{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/matrix",
  "slug": "adapters/domain/matrix",
  "kind": "capabilities",
  "bucket": "package",
  "title": "matrix — linear-algebra adapter pack",
  "name": "matrix",
  "eyebrow": "linear-algebra adapter pack",
  "chip": null,
  "summary": "Linear algebra capability pack — pure JavaScript, zero dependencies. Matrix operations: create/validate, identity, zeros, add, subtract, multiply (matrix product), scalarMultiply, transpose...",
  "keywords": [
    "matrix",
    "zeros",
    "subtract",
    "scalarmultiply",
    "determinant",
    "leumas matrix",
    "gaussianelimination",
    "pivoting"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# matrix — linear-algebra adapter pack\n\nPure JavaScript linear algebra for the Leumas adapter engine. **Zero npm dependencies** — Node\nbuilt-ins only. Every routine is a plain, deterministic function over arrays of numbers, so the pack\nloads and runs anywhere with no native binaries.\n\nA matrix is a rectangular array-of-rows (`[[1,2],[3,4]]`); a vector is a flat numeric array\n(`[1,2,3]`). Inputs coerce loosely: a matrix or vector may arrive as a JSON string, and vectors also\naccept CSV / space-delimited strings. Ragged, empty, or non-numeric inputs throw a `TypeError`.\n\nEach tool takes ONE args object (an HTTP POST body maps 1:1) and returns a plain JSON-serializable\nresult. Pass `options.precision` (an integer) to round display values to N decimals.\n\n## Tools (20)\n\n### Matrix construction\n- **create** `{ values }` — validate raw rows into a rectangular matrix; reports rows/cols/square.\n- **identity** `{ n }` — the n×n identity matrix.\n- **zeros** `{ rows, cols? }` — a zero matrix (square when `cols` omitted).\n\n### Matrix arithmetic\n- **add** `{ a, b }` — element-wise A + B (same shape).\n- **subtract** `{ a, b }` — element-wise A − B (same shape).\n- **multiply** `{ a, b }` — matrix product A·B (A.cols must equal B.rows).\n- **scalarMultiply** `{ a, scalar }` — scale every entry by a scalar.\n- **transpose** `{ a }` — swap rows and columns.\n\n### Decomposition-free analysis\n- **determinant** `{ a }` — determinant of a square matrix (forward elimination); flags `singular`.\n- **inverse** `{ a }` — inverse via Gauss-Jordan; returns `{ singular:true, matrix:null }` when non-invertible.\n- **trace** `{ a }` — sum of the main diagonal (square).\n- **rank** `{ a }` — number of linearly independent rows (nonzero pivots); flags `fullRank`.\n- **gaussianElimination** `{ a }` — row-reduce to upper-triangular; exposes `pivots`, `rank`, `rowSwaps`.\n- **isSymmetric** `{ a, options.tolerance? }` — true if A equals its transpose within a tolerance.\n\n### Solvers\n- **solve** `{ a, b }` — solve **Ax = b** via Gaussian elimination with partial pivoting +\n  back-substitution. `b` is a vector (or n×1 matrix). Returns `{ singular:true, solution:null }` for\n  systems with no unique solution.\n\n### Vectors\n- **dot** `{ a, b }` — dot / inner product of two equal-length vectors.\n- **cross** `{ a, b }` — cross product of two 3-D vectors (right-handed) + its magnitude.\n- **vectorAdd** `{ a, b }` — element-wise vector addition.\n- **magnitude** `{ a }` — Euclidean (L2) length.\n- **normalize** `{ a }` — unit vector in the same direction (throws on the zero vector).\n\n## Usage\n\n```js\nimport matrix from './index.js';\n\nmatrix.adapters.multiply({ a: [[1, 2], [3, 4]], b: [[5, 6], [7, 8]] });\n// { rows: 2, cols: 2, matrix: [[19, 22], [43, 50]] }\n\nmatrix.adapters.solve({ a: [[2, 1], [1, 3]], b: [3, 5] });\n// { singular: false, solution: [0.8, 1.4] }\n\nmatrix.adapters.determinant({ a: \"[[1,2,3],[4,5,6],[7,8,10]]\" });\n// { n: 3, determinant: -3, singular: false }\n\nmatrix.adapters.normalize({ a: [3, 4] });\n// { unit: [0.6, 0.8], magnitude: 5 }\n```\n\n## Numerical notes\n- Forward elimination uses **partial pivoting** (largest-magnitude pivot per column) for stability.\n- A pivot with `|value| < 1e-10` is treated as zero → the matrix is reported **singular** rather than\n  dividing by ~0. `determinant`, `inverse`, `solve`, and `rank` all share this row-reduction core.\n- Rounding normalizes `-0` to `0`.\n\n## DRY boundary\nThis pack is **real linear algebra over 2-D matrices + n-D vectors**, and deliberately does not\noverlap its neighbours:\n\n- **`numbers`** owns 1-D **series analytics** — running average, percentile insights, anomaly\n  detection, normalize/scale, weighted scoring. Those are statistics over a list of samples, not\n  matrix algebra. No tool is duplicated here.\n- **`a-transformation`**'s `vector.*` adapters own only **dot-product and L2 norm** as generic\n  data-type transforms. Those stay there. Here `dot` / `magnitude` are part of a *complete* vector\n  toolkit (`add`, `cross`, `normalize`, …) that the matrix solvers build on — same math, different\n  purpose (an algebra kit vs. a transformation registry entry).\n- **`array`** owns structural array operations (chunk / flatten / unique / rotate / merge-join).\n  Those are not numeric algebra and are not reimplemented here.\n",
  "source": {
    "path": "shared/engines/adapters/domain/matrix/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 4601,
    "hash": "ddd93a064cfafdaa5c3e9d8ca56013ab83e74b75"
  },
  "urls": {
    "html": "/p/adapters/domain/matrix",
    "json": "/docs/adapters/domain/matrix.json",
    "md": "/docs/adapters/domain/matrix.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}