npm package: @lightjs-forge/lmath
Description: ![Version](https://img.shields.io/badge/version-1.0.0-blue) ![License](https://img.shields.io/badge/license-MIT-green)
Author: Eduardo Amorim Pereira
Latest version: 0.1.0

# LMath – The Ultimate Mathematics Library for JavaScript/Node.js

![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)

LMath is a **comprehensive, modular, and high-performance** mathematics library for JavaScript and Node.js. It covers everything from basic arithmetic to advanced calculus, linear algebra, statistics, complex numbers, differential equations, and numerical methods. Designed with **clarity, extensibility, and educational value** in mind, LMath is perfect for students, researchers, and developers who need powerful mathematical tools.

---

## ✨ Features

- **100% Pure JavaScript** – Works in Node.js and browsers (with bundlers).
- **Modular Architecture** – Import only what you need.
- **High Precision** – BigInt support for large integers, rational numbers, and complex arithmetic.
- **Comprehensive Coverage** – Over 500 functions across multiple domains:
  - ➕ **Arithmetic** – Basic operations, number theory, combinatorics, sequences.
  - 🧮 **Algebra** – Vectors, matrices, linear systems, decompositions (LU, QR, SVD, Cholesky), eigenvalues.
  - 📈 **Calculus** – Limits, derivatives, integrals (multiple methods), ODEs, PDEs, series.
  - 📊 **Statistics** – Descriptive statistics, probability distributions, hypothesis tests, regression.
  - 🌀 **Complex Numbers** – Full complex arithmetic, trig, hyperbolic, roots, exponentials.
  - 🔢 **Number Theory** – Primes, GCD/LCM, modular arithmetic, arithmetic functions.
  - 🔬 **Numerical Methods** – Root finding, optimization, numerical integration, FFT.
  - 🎲 **Random Numbers** – Multiple PRNGs (Xorshift, Mersenne Twister), distributions, sampling.

- **Well Documented** – Every function includes JSDoc comments with examples.
- **Tested** – Extensive test suite covering edge cases.

---

## 📦 Installation

```bash
npm install lmath
```

Or include directly in HTML (using a CDN):

```html
<script src="https://cdn.jsdelivr.net/npm/lmath/dist/lmath.min.js"></script>
```

---

## 🚀 Quick Start

```javascript
// Import the whole library
const lmath = require('lmath');

// Or import specific modules
const { add, mul, sqrt } = require('lmath/core/arithmetic');
const { solveLinear, eigen } = require('lmath/core/linearAlgebra');
const { normalPDF, correlation } = require('lmath/core/statistics');
const { Complex, rk4 } = require('lmath/advanced');

// Basic arithmetic
console.log(add(5, 3));                // 8
console.log(sqrt(16));                  // 4
console.log(factorial(5));              // 120

// Linear algebra
const A = [[1, 2], [3, 4]];
const b = [5, 6];
console.log(solveLinear(A, b));         // [-4, 4.5]
console.log(det(A));                     // -2

// Statistics
const data = [2, 4, 4, 4, 5, 5, 7, 9];
console.log(mean(data));                 // 5
console.log(stdDev(data));               // 2.138
console.log(correlation([1,2,3], [2,4,6])); // 1.0

// Complex numbers
const z1 = new Complex(3, 4);
const z2 = new Complex(1, -2);
console.log(z1.mul(z2).toString());     // "11 - 2i"

// Differential equations
const f = (x, y) => y;                   // dy/dx = y
const sol = rk4(f, 0, 1, 2, 100);
console.log(sol[sol.length-1].y);        // ≈ 7.389 (e^2)
```

---

## 📚 Module Overview

LMath is organized into three main directories:

### 📁 core/ – Essential, everyday math

Module Description Key Functions
arithmetic.js Basic operations, number theory, combinatorics add, gcd, factorial, isPrime, fibonacci, binomial
algebra.js Vectors, matrices, linear algebra dotProduct, matrixMul, det, inv, eigen
calculus.js Derivatives, integrals, ODEs, series derivative, integral, rk4, taylorSeries
linearAlgebra.js Extended linear algebra lu, qr, svd, cholesky, conjugateGradient
complex.js Complex numbers Complex class with all operations
statistics.js Statistics and probability mean, variance, normalPDF, correlation, tTest

### 📁 advanced/ – Specialized topics

| Module | Description Key | Functions |
----------------------------------------
differentialEquations.js,  ODE solvers, BVP, PDEs rk4, rkf45, shootingMethod, heatEquation

### 📁 utils/ – Utilities and helpers

Module Description Key Functions
random.js Random number generation normal, poisson, shuffle, uuidv4
constants.js Mathematical, physical, astronomical constants PI, E, G, C, SOLAR_MASS, GOLDEN_RATIO

---



## 🧪 Testing

Run the test suite:

```bash
npm test
```

Tests cover all modules with edge cases and performance benchmarks.

---

## 🤝 Contributing

Contributions are welcome! Please follow the contribution guidelines.

1. Fork the repository.
2. Create a feature branch.
3. Write tests for new functionality.
4. Submit a pull request.

---

##📄 License

LMath is MIT licensed. © 2026 Eduardo Amorim Pereira.

---

🙏 Acknowledgments

· Inspired by NumPy, SciPy, Math.js, and Python's math module.
· Thanks to the open-source community for providing foundational algorithms and ideas.

---

## 🚀 What's Next?

We're constantly expanding LMath. Planned future modules include:

· Machine Learning – Basic algorithms (linear regression, k-means, neural networks)
· Graph Theory – Dijkstra, Floyd–Warshall, spanning trees
· Quantum Computing – Simulated quantum gates and algorithms
· Fractals – Mandelbrot, Julia sets, L-systems

Stay tuned!