matrix — linear-algebra adapter pack

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

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.