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

npm install js-generalized-numbers

Or clone directly from GitHub:

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

🚀 Quick Start

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

Number Type Formats

| 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 |

Core Functions

add(a, b)

Adds two numbers/matrices of compatible types.

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.

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.

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

toString(a)

Converts any number type to a readable string representation.

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.

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).

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

isEqual(a, b)

Checks equality with epsilon tolerance (1e-16).

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

RoundToNearest(a)

Rounds to nearest with 10 decimal precision.

RoundToNearest(3.14159265358979);  // 3.1415926536

collapse(a)

Reduces complex types to simpler forms when possible.

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

Matrix-Specific Functions

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.

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

🔬 Type Detection

The library provides type-checking functions:

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: [email protected]
• 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