Nexus Matrix
SPEC_NEXUS_MATRIX.md
CGNT-1 Component Specification — NEXUS Matrix Algebra Module
Status: SPECIFIED
Version: v1.0
Module: NEXUS sub-module (matrix algebra)
Author: κ (C.L.O.D.)
Date: 2026-04-20
Genesis: Sisters hit the wall during E8/Riemann exploration — eigenvalue, determinant, and symbolic linear algebra all failed through ROUTX
PURPOSE
Deterministic matrix algebra routed through NEXUS via ROUTX. Tier 1 — exact numeric results via numpy, symbolic results via sympy. No hallucination. No Tier 2 fallback. Matrix operations are mathematical facts.
OPERATIONS
| Op keyword | Aliases | Description |
|---|---|---|
| eigenvalues | eigen, eig | Eigenvalue decomposition (numpy numeric / sympy symbolic) |
| multiply | mul, mult, product | Matrix product A @ B |
| determinant | det | Scalar determinant |
| inverse | inv | Matrix inverse (singular guard) |
| rank | — | Matrix rank |
| trace | — | Sum of diagonal (square matrix) |
| charpoly | characteristic, char | Characteristic polynomial (sympy, λ as variable) |
| exp | expm, exponential | Matrix exponential (scipy.linalg.expm / sympy fallback) |
QUERY FORMAT
All queries enter ROUTX via the standard /query endpoint:
POST localhost:9191/query
{"query": "matrix <op> <JSON_matrix> [<JSON_matrix2>]"}
Examples:
matrix eigenvalues [[2,-1,0],[-1,2,-1],[0,-1,2]]
matrix multiply [[1,2],[3,4]] [[5,6],[7,8]]
matrix determinant [[2,-1],[-1,2]]
matrix inverse [[2,-1],[-1,2]]
matrix rank [[1,2,3],[4,5,6],[7,8,9]]
matrix trace [[2,-1,0],[-1,2,-1],[0,-1,2]]
matrix charpoly [[2,-1],[-1,2]]
matrix exp [[1,0],[0,1]]
matrix eigenvalues symbolic [[2,-1],[-1,2]] ← sympy path
Matrices are parsed from JSON array notation [[...],[...]]. Two-matrix ops (multiply) accept two consecutive arrays.
RESPONSE FORMAT
{
"result": <value>,
"operation": "<op_name>",
"_module": true,
"_verified": "MODEMX_OK",
"_routed_to": "nexus",
"_tier": 1
}
Special cases:
- Singular matrix on inverse:
"result": "Matrix is singular" - Complex eigenvalues (non-symmetric matrix): complex values serialized as
{"re": x, "im": y}with"note": "Matrix is non-symmetric — complex eigenvalues present. Check matrix for symmetry."
ROUTING
ROUTX classify_tool() routes to nexus via _MATH_WORDS (contains "matrix").
nexus_engine.detect_module() routes to "matrix" module via _AUTO_DETECT — patterns checked before sympy fallback:
["matrix eigenvalue", "matrix eigen", "matrix multiply", "matrix determinant",
"matrix inverse", "matrix rank", "matrix trace", "matrix charpoly",
"matrix exp", "matrix mul", "matrix det", "matrix inv"]
_MODULE_MAP entries: matrix, matrices, linalg, linearalgebra, eigenvalue, eigenvalues
Explicit prefix also works: nexus: matrix eigenvalues [[...]]
NUMERIC BACKEND
- Default: numpy float64 (fast, 64-bit precision)
- Symbolic path: sympy (activated by "symbolic" keyword in query)
- Matrix exponential: scipy.linalg.expm (falls back to sympy.exp if scipy unavailable)
- Characteristic polynomial: always sympy (symbolic, exact)
INVARIANTS
INV-01: Matrix operations are Tier 1 — deterministic, exact. No neural fallback. No hallucination path.
INV-02: Singular matrix on inverse returns "Matrix is singular" as result string — not an error, not ◌. The computation succeeded; the matrix is non-invertible.
INV-03: Complex eigenvalues are serialized as {"re": x, "im": y} objects — never raw Python complex (JSON-serializable by design). A note field flags non-symmetric input.
INV-04: The module does not validate whether the user's Cartan matrix is physically correct. It computes what it receives. The note field on complex results is the diagnostic signal.
INV-05: Two-matrix operations (multiply) require both matrices in the same query string, separated by space. Parser extracts all [...] blocks sequentially.
INV-06: All results carry _verified: "MODEMX_OK" — they have passed the MODEMX schema check at the wire level in ROUTX.
VERIFIED TEST RESULTS (2026-04-20)
| Query | Expected | Actual |
|---|---|---|
| matrix determinant [[2,-1],[-1,2]] | 3 | ✅ 3 |
| matrix inverse [[2,-1],[-1,2]] | [[0.667,0.333],[0.333,0.667]] | ✅ [[0.666667,0.333333],[0.333333,0.666667]] |
| matrix rank [[1,2,3],[4,5,6],[7,8,9]] | 2 | ✅ 2 |
| matrix trace [[2,-1,0],[-1,2,-1],[0,-1,2]] | 6 | ✅ 6 |
| matrix eigenvalues [[2,-1],[-1,2]] | [1.0, 3.0] | ✅ [1.0, 3.0] |
| matrix multiply [[1,2],[3,4]] [[5,6],[7,8]] | [[19,22],[43,50]] | ✅ [[19.0,22.0],[43.0,50.0]] |
| matrix inverse [[1,2],[2,4]] (singular) | "Matrix is singular" | ✅ |
| E8 Cartan (asymmetric query) | complex eigenvalues noted | ✅ with note |
| matrix charpoly [[2,-1],[-1,2]] | λ²-4λ+3 | ✅ λ**2 - 4*λ + 3 |
Note on E8 test: The matrix in the captain's query has an asymmetry — row 7 connects to column 2, but row 3 connects to column 7 (they don't match). A valid E8 Cartan matrix is symmetric. For the correct E8 computation, use: [[2,-1,0,0,0,0,0,0],[-1,2,-1,0,0,0,0,0],[0,-1,2,-1,0,0,0,-1],[0,0,-1,2,-1,0,0,0],[0,0,0,-1,2,-1,0,0],[0,0,0,0,-1,2,-1,0],[0,0,0,0,0,-1,2,0],[0,0,-1,0,0,0,0,2]] where row 2 and row 7 are symmetric. All real eigenvalues expected for the symmetric Cartan matrix.
GAPS
- Sympy symbolic eigenvalue output can be verbose for large matrices — no truncation cap yet
- Matrix exponential falls back to sympy string output if scipy unavailable (not numeric)
- No SVD, QR, LU decomposition yet — add to v1.1 if Sisters need them
- No complex matrix input support yet (all inputs parsed as float64)
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042