Numbers.js

A comprehensive JavaScript library for working with various number systems and division algebras including Complex Numbers, Quaternions, Dual Numbers, Split Numbers, and Matrices.

🌟 Features

- Multiple Number Systems
- ℝ (Real Numbers)
- ℂ (Complex Numbers)
- ℍ (Quaternions)
- Dual Numbers
- Split Numbers
- Matrix operations
- Parallel Pairs

- Core Operations
- Addition and multiplication for all number types
- Matrix operations (add, multiply, inverse, Kronecker product)
- Hermitian conjugate
- Type detection and automatic type handling
- Precision rounding and comparison

📦 Installation

``bash
npm install js-generalized-numbers
`

Or clone directly from GitHub:

`bash
git clone https://github.com/coreality-dev/js-generalized-numbers.git
`

🚀 Quick Start

`javascript
import { add, mul, toString } from 'js-generalized-numbers';

// Complex numbers: [-1, real, imaginary]
const c1 = [-1, 3, 4]; // 3 + 4i
const c2 = [-1, 1, 2]; // 1 + 2i

const sum = add(c1, c2);
console.log(toString(sum)); // "4+6i"

const product = mul(c1, c2);
console.log(toString(product)); // "-5+10i"

// Quaternions: [2, w, x, y, z]
const q1 = [2, 1, 0, 1, 0]; // 1 + j
const q2 = [2, 0, 1, 0, 0]; // i

const qProduct = mul(q1, q2);
console.log(toString(qProduct)); // "i+k"

// Matrices: [3, [[array]]]
const m1 = [3, [[1, 2], [3, 4]]];
const m2 = [3, [[5, 6], [7, 8]]];

const mProduct = mul(m1, m2);
console.log(toString(mProduct));
`

📖 Documentation

$3

| Type | Format | Example |
|------|--------|---------|
| Real | number | 42 |
| Complex | [-1, real, imag] | [-1, 3, 4] → 3+4i |
| Dual | [0, real, dual] | [0, 2, 1] → 2+ε |
| Split | [1, real, split] | [1, 3, 2] → 3±2 |
| Quaternion | [2, w, x, y, z] | [2, 1, 2, 3, 4] → 1+2i+3j+4k |
| Matrix | [3, [[...]]] | [3, [[1,2],[3,4]]] |
| Pair | [4, a, b] | [4, m1, m2] → m1⊕m2 |

$3

#### add(a, b)
Adds two numbers/matrices of compatible types.

`javascript
add(5, 3); // 8
add([-1, 1, 2], [-1, 3, 4]); // [-1, 4, 6] (complex addition)
`

#### mul(a, b)
Multiplies two numbers/matrices of compatible types.

`javascript
mul(5, 3); // 15
mul([-1, 1, 2], [-1, 3, 4]); // [-1, -5, 10] (complex multiplication)
`

#### inv(a)
Computes the inverse of a number or matrix.

`javascript
inv(2); // 0.5
inv([-1, 3, 4]); // Complex inverse
`

#### toString(a)
Converts any number type to a readable string representation.

`javascript
toString([-1, 3, 4]); // "3+4i"
toString([2, 1, 2, 3, 4]); // "1+2i+3j+4k"
`

#### kron(a, b)
Computes the Kronecker (tensor) product of two matrices.

`javascript
const m1 = [3, [[1, 2], [3, 4]]];
const m2 = [3, [[0, 5], [6, 7]]];
const result = kron(m1, m2);
`

#### hcon(a)
Computes the Hermitian conjugate (conjugate transpose).

`javascript
hcon([-1, 3, 4]); // [-1, 3, -4] (complex conjugate)
`

#### isEqual(a, b)
Checks equality with epsilon tolerance (1e-16).

`javascript
isEqual(0.1 + 0.2, 0.3); // true
`

#### RoundToNearest(a)
Rounds to nearest with 10 decimal precision.

`javascript
RoundToNearest(3.14159265358979); // 3.1415926536
`

#### collapse(a)
Reduces complex types to simpler forms when possible.

`javascript
collapse([-1, 5, 0]); // 5 (complex with no imaginary part)
`

$3

#### matInv(a)
Computes the inverse of a square matrix (Real, Complex, or Quaternion entries).

Note: Uses Souriau's algorithm. For better numerical stability, consider Gauss-Jordan elimination for production use.

`javascript
const m = [3, [[1, 2], [3, 4]]];
const mInv = matInv(m);
`

🔬 Type Detection

The library provides type-checking functions:

`javascript
isReal(x) // Check if number is real
isComplex(x) // Check if complex number
isDual(x) // Check if dual number
isSplit(x) // Check if split number
isQuat(x) // Check if quaternion
isMat(x) // Check if matrix
isPair(x) // Check if parallel pair
`

🎯 Use Cases

- Computer Graphics: Quaternion rotations
- Physics Simulations: Complex number wave functions
- Automatic Differentiation: Dual numbers for derivatives
- Linear Algebra: Matrix operations
- Signal Processing: Complex number transformations

⚠️ Limitations

- Matrix inverse uses Souriau's algorithm which can be slow and numerically unstable for large matrices
- No input validation for matrix dimensions
- Limited to basic operations (no eigenvalues, SVD, etc.)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details

👤 Author

Fabrice PFAFF
- Email: fabrice.pfaff@coreality.cc
- Website: https://coreality.cc/

🙏 Acknowledgments

- Inspired by various mathematical libraries
- References:
- fast-complex
- Quaternion.js
- matrix-js

📚 Version History

- v2.00 (November 2024) - Complete rewrite with expanded functionality