Docs  /  Matrix quotient, powers, and roots

Matrix quotient, powers, and roots

_AlgebraKernel (MathAlgebra) extends scalar arithmetic to square matrices: quotient (division), integer/real powers, square root, inverse square root, logarithm, cube root, and exponential. Commands live under algebra …; Lua globals are registered by _MathAlgebraFeatures::RegisterLuaGlobals.

Brainstorm → API map

Idea Meaning API Algorithm notes
Quotient (right) (A / B = A B^{-1}) MatrixRightDivide Solve (X B = A) via ((B^\top \backslash A^\top)^\top)
Quotient (left) (A \backslash B = A^{-1} B) MatrixLeftDivide Column-wise SolveLinear
Integer exponent (A^n), (n \in \mathbb{Z}) MatrixPowerInt Binary exponentiation; (n<0) uses inverse
Real exponent (A^p) MatrixPower Near-integers → int path; else (\mathrm{expm}(p\,\mathrm{logm}(A)))
Square root (S^2 = A) MatrixSqrt Denman–Beavers iteration
Inv. square root (A^{-1/2}) MatrixInvSqrt Denman–Beavers (Z) iterate (fallback: inv of sqrt)
Logarithm Inverse of expm MatrixLog Inverse scaling-and-squaring + Mercator series
Cube root (A^{1/3}) MatrixCbrt Real power (1/3)
Exponential (e^A) MatrixExp Taylor series (existing)

Domain / caveats

  • Operations assume small dense real square matrices (college / control / ODE scale).
  • Sqrt / invsqrt / log / fractional powers work best for SPD matrices or matrices with no eigenvalues on the non-positive real axis. Failure returns false.
  • Principal real branch only (no complex Schur form).
  • Residual checks reject diverged iterations.
Operation Status
Hadamard (elementwise) /, ^, √ Not separate API (trivial on entries)
Matrix cosine / sine / sinh / cosh Compose via MatrixExp if needed
Fractional roots (A^{1/k}) Use MatrixPower(A, 1.0/k)
Pseudoinverse quotient Use LeastSquares / normal equations
Schur–Parlett f(A) Future enhancement for non-SPD

Typed commands

algebra mdemo              # full matrix-arithmetic smoke demo
algebra rdiv [n A.. B..]   # right divide A/B  (default SPD demo)
algebra ldiv [n A.. B..]   # left divide  A\B
algebra pow  [n p A..]     # A^p  (default A=[4,1;1,3], p from args)
algebra sqrt [n A..]       # matrix square root
algebra invsqrt [n A..]
algebra logm [n A..]
algebra cbrt [n A..]       # default diag(8,27)
algebra expm a11 a12 a21 a22   # existing 2×2 Taylor expm

Flat packing matches algebra eig: n then row-major n² entries. For rdiv/ldiv, pack A then B (each n² values).

Lua

Global Args Returns
ai_algebra_msqrt matrix nested table or nil, err
ai_algebra_mpow matrix, p nested table
ai_algebra_mrdiv A, B nested table
ai_algebra_mldiv A, B nested table
ai_algebra_mlog matrix nested table
ai_algebra_mcbrt matrix nested table
ai_algebra_minvsqrt matrix nested table
ai_algebra_mexpm matrix [, terms] nested table

Matrix args: nested {{row},{row}} or flat {n, a11, …, ann}.

local S, err = ai_algebra_msqrt({{4,1},{1,3}})
local P = ai_algebra_mpow({{4,0},{0,9}}, 0.5)
local Q = ai_algebra_mrdiv({{4,1},{1,3}}, {{2,0},{0,2}})

Self-test

algebra mdemo

Unit coverage: tests/suite_math_extensions.cpp (via tests/run_math_tests.ps1).

Files

  • MathAlgebra.hpp / MathAlgebra.cpp — kernel
  • MathAlgebraFeatures.cpp — algebra verbs + Lua
  • GuiDashboard.cpp — mdemo / sqrtm / logm buttons
Generated from the project markdown docs on 2026-07-24. This is a static, self-contained site.