# matrix — linear-algebra adapter pack

Linear algebra capability pack — pure JavaScript, zero dependencies. Matrix operations: create/validate, identity, zeros, add, subtract, multiply (matrix product), scalarMultiply, transpose...


Pure JavaScript linear algebra for the Leumas adapter engine. **Zero npm dependencies** — Node
built-ins only. Every routine is a plain, deterministic function over arrays of numbers, so the pack
loads and runs anywhere with no native binaries.

A matrix is a rectangular array-of-rows (`[[1,2],[3,4]]`); a vector is a flat numeric array
(`[1,2,3]`). Inputs coerce loosely: a matrix or vector may arrive as a JSON string, and vectors also
accept CSV / space-delimited strings. Ragged, empty, or non-numeric inputs throw a `TypeError`.

Each tool takes ONE args object (an HTTP POST body maps 1:1) and returns a plain JSON-serializable
result. Pass `options.precision` (an integer) to round display values to N decimals.

## Tools (20)

### Matrix construction
- **create** `{ values }` — validate raw rows into a rectangular matrix; reports rows/cols/square.
- **identity** `{ n }` — the n×n identity matrix.
- **zeros** `{ rows, cols? }` — a zero matrix (square when `cols` omitted).

### Matrix arithmetic
- **add** `{ a, b }` — element-wise A + B (same shape).
- **subtract** `{ a, b }` — element-wise A − B (same shape).
- **multiply** `{ a, b }` — matrix product A·B (A.cols must equal B.rows).
- **scalarMultiply** `{ a, scalar }` — scale every entry by a scalar.
- **transpose** `{ a }` — swap rows and columns.

### Decomposition-free analysis
- **determinant** `{ a }` — determinant of a square matrix (forward elimination); flags `singular`.
- **inverse** `{ a }` — inverse via Gauss-Jordan; returns `{ singular:true, matrix:null }` when non-invertible.
- **trace** `{ a }` — sum of the main diagonal (square).
- **rank** `{ a }` — number of linearly independent rows (nonzero pivots); flags `fullRank`.
- **gaussianElimination** `{ a }` — row-reduce to upper-triangular; exposes `pivots`, `rank`, `rowSwaps`.
- **isSymmetric** `{ a, options.tolerance? }` — true if A equals its transpose within a tolerance.

### Solvers
- **solve** `{ a, b }` — solve **Ax = b** via Gaussian elimination with partial pivoting +
  back-substitution. `b` is a vector (or n×1 matrix). Returns `{ singular:true, solution:null }` for
  systems with no unique solution.

### Vectors
- **dot** `{ a, b }` — dot / inner product of two equal-length vectors.
- **cross** `{ a, b }` — cross product of two 3-D vectors (right-handed) + its magnitude.
- **vectorAdd** `{ a, b }` — element-wise vector addition.
- **magnitude** `{ a }` — Euclidean (L2) length.
- **normalize** `{ a }` — unit vector in the same direction (throws on the zero vector).

## Usage

```js
import matrix from './index.js';

matrix.adapters.multiply({ a: [[1, 2], [3, 4]], b: [[5, 6], [7, 8]] });
// { rows: 2, cols: 2, matrix: [[19, 22], [43, 50]] }

matrix.adapters.solve({ a: [[2, 1], [1, 3]], b: [3, 5] });
// { singular: false, solution: [0.8, 1.4] }

matrix.adapters.determinant({ a: "[[1,2,3],[4,5,6],[7,8,10]]" });
// { n: 3, determinant: -3, singular: false }

matrix.adapters.normalize({ a: [3, 4] });
// { unit: [0.6, 0.8], magnitude: 5 }
```

## Numerical notes
- Forward elimination uses **partial pivoting** (largest-magnitude pivot per column) for stability.
- A pivot with `|value| < 1e-10` is treated as zero → the matrix is reported **singular** rather than
  dividing by ~0. `determinant`, `inverse`, `solve`, and `rank` all share this row-reduction core.
- Rounding normalizes `-0` to `0`.

## DRY boundary
This pack is **real linear algebra over 2-D matrices + n-D vectors**, and deliberately does not
overlap its neighbours:

- **`numbers`** owns 1-D **series analytics** — running average, percentile insights, anomaly
  detection, normalize/scale, weighted scoring. Those are statistics over a list of samples, not
  matrix algebra. No tool is duplicated here.
- **`a-transformation`**'s `vector.*` adapters own only **dot-product and L2 norm** as generic
  data-type transforms. Those stay there. Here `dot` / `magnitude` are part of a *complete* vector
  toolkit (`add`, `cross`, `normalize`, …) that the matrix solvers build on — same math, different
  purpose (an algebra kit vs. a transformation registry entry).
- **`array`** owns structural array operations (chunk / flatten / unique / rotate / merge-join).
  Those are not numeric algebra and are not reimplemented here.


---
Source: shared/engines/adapters/domain/matrix/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/matrix