🥮 mooncakes.io
README

#symmatrices

CAIMEOX/symbit/symmatrices is the public import path for this package.

Dense, sparse, and symbolic matrix objects together with linear algebra, matrix-expression construction, and decomposition utilities.

#When To Use This Package

  • Import CAIMEOX/symbit/symmatrices directly when your code depends on this package's subsystem-specific types or algorithms.
  • Prefer this package over the root facade when you want the focused API surface listed below rather than a convenience wrapper.

#Key Public Entry Points

  • block_diag
  • block_diag_matrix_expr
  • block_matrix
  • block_matrix_expr
  • casoratian
  • diag
  • eye
  • gram_schmidt

#Related Packages

  • CAIMEOX/symbit/symcore
  • CAIMEOX/symbit/sympolys

#
EigenValueMult

source
type EigenValueMult = (
Expr, Int)

#
EigenVectData

source

#
Expr

source

Core symbolic expression tree used across Symbit.

Current Limits:
  • symcore defines structure and canonical construction, not the full mathematical behavior of every subsystem.
  • textual mathematics should go through symparse rather than raw head construction.
  • several higher-level object families are easier to use through their own package front doors.

#
MatrixError

source
pub(all) suberror MatrixError {
  ShapeError(String)
  ValueError(String)
  NonSquareMatrixError(String)
  SingularMatrixError(String)
  IndexError(String)
} derive(Eq, 
Debug)

Matrix package errors aligned with the common SymPy matrix failure modes.

  • Does: Groups the front-door errors raised by dense, sparse, symbolic, and exact matrix operations.
  • Input: Error constructors carry one explanatory String.
  • Returns: A MatrixError value.
  • Limits: Lower-level arithmetic failures are usually translated into one of these variants instead of being exposed directly.
impl Show for MatrixError

#
Matrix

source
#alias(ImmutableDenseMatrix)
#alias(MutableMatrix)
#alias(MutableDenseMatrix)
#alias(ImmutableMatrix)
pub struct Matrix {
  rows : Int
  cols : Int
  data : Array[Array[
Expr]]
}

Dense symbolic matrix values and structural operations.

Current Limits:
  • This file covers dense construction and reshaping front doors only.
  • Decompositions and exact linear algebra live in other symmatrices files.
impl Add for Matrix
impl Mul for Matrix
impl Show for Matrix
impl Sub for Matrix

#
Matrix::adjugate

source
fn Matrix::adjugate(self : Matrix) -> Matrix raise MatrixError

Compute the adjugate matrix.

  • Does: Transposes the cofactor matrix.
  • Input: A square dense Matrix.
  • Returns: A dense Matrix of the same shape.
  • Limits: Propagates the same square-matrix requirement as cofactor_matrix().

#
Matrix::applyfunc

source

#
Matrix::as_immutable

source
fn Matrix::as_immutable(self : Matrix) -> Matrix

Return an immutable-style copy of a dense matrix.

  • Does: Clones the matrix while preserving its current entries.
  • Input: A dense Matrix.
  • Returns: Another Matrix with the same shape and entries.
  • Limits: This is a compatibility front door; it does not freeze or alias the original value.

#
Matrix::as_mutable

source
fn Matrix::as_mutable(self : Matrix) -> Matrix

Return a mutable-style copy of a dense matrix.

  • Does: Clones the matrix so callers can keep editing the returned value.
  • Input: A dense Matrix.
  • Returns: Another Matrix with the same shape and entries.
  • Limits: This package uses value semantics, so the original matrix is never mutated in place.

#
Matrix::charpoly

source

Compute the characteristic polynomial as an expression.

  • Does: Returns det(x*I - A) in a normalized symbolic form.
  • Input: A square dense Matrix and an optional polynomial variable Expr.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. Some matrices fall back to determinant expansion instead of an exact polynomial-domain path.

#
Matrix::charpoly_expr

source

Characteristic-polynomial and eigen-structure front doors for dense matrices.

Current Limits:
  • Exact algebraic paths cover many common cases but not every dense symbolic matrix.
  • Hard cases can still return unevaluated radicals or raise ValueError when a basis cannot be assembled.

#
Matrix::cholesky

source
fn Matrix::cholesky(self : Matrix) -> Matrix raise MatrixError

Compute a Cholesky factorization.

  • Does: Returns a lower-triangular matrix L such that L * L.T matches the input on supported inputs.
  • Input: A square dense Matrix.
  • Returns: A lower-triangular dense Matrix.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. This front door does not prove positive definiteness before taking square roots.

#
Matrix::cofactor

source
fn Matrix::cofactor(self : Matrix, row : Int, col : Int) -> 
Expr raise MatrixError

Compute one cofactor.

  • Does: Multiplies the selected minor by the alternating sign (-1)^(row + col).
  • Input: A Matrix, a row index, and a column index.
  • Returns: One symbolic Expr.
  • Limits: Propagates index and determinant errors from minor().

#
Matrix::cofactor_matrix

source
fn Matrix::cofactor_matrix(self : Matrix) -> Matrix raise MatrixError

Compute the cofactor matrix.

  • Does: Replaces each entry with its cofactor.
  • Input: A square dense Matrix.
  • Returns: A dense Matrix of the same shape.
  • Limits: Raises MatrixError::NonSquareMatrixError when the matrix is not square.

#
Matrix::col

source
fn Matrix::col(self : Matrix, col : Int) -> Array[
Expr] raise MatrixError

Extract a full column as expressions.

  • Does: Clones one column from the dense matrix.
  • Input: A Matrix and a column index. Negative indices count from the end.
  • Returns: Array[Expr] for that column.
  • Limits: Raises MatrixError::IndexError when the column index is out of range.

#
Matrix::col_del

source
fn Matrix::col_del(self : Matrix, col : Int) -> Matrix raise MatrixError

#
Matrix::col_insert

source
fn Matrix::col_insert(self : Matrix, pos : Int, other : Matrix) -> Matrix raise MatrixError

#
Matrix::col_join

source
fn Matrix::col_join(self : Matrix, other : Matrix) -> Matrix raise MatrixError

#
Matrix::columnspace

source

Return a basis for the column space.

  • Does: Selects the pivot columns from the original matrix.
  • Input: Any dense Matrix.
  • Returns: Array[Array[Expr]], one basis vector per column.
  • Limits: Uses pivot detection from rref(), so symbolic pivot choices follow the same heuristics.

#
Matrix::copy

source
fn Matrix::copy(self : Matrix) -> Matrix

#
Matrix::det

source

Compute the determinant of a square matrix.

  • Does: Uses exact rational, numeric, or symbolic elimination to compute the determinant.
  • Input: A square dense Matrix.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. Symbolic paths may keep expressions unevaluated instead of fully simplifying them.

test "det computes the determinant of a dense matrix" {
  let m = @symmatrices.matrix([
    [@symcore.int(1), @symcore.int(2)],
    [@symcore.int(3), @symcore.int(4)],
  ])
  inspect(@symprint.pretty_string(m.det()), content="-2")
}

#
Matrix::diagonal

source
fn Matrix::diagonal(self : Matrix, k? : Int) -> Array[
Expr]

#
Matrix::diagonalize

source
fn Matrix::diagonalize(self : Matrix, reals_only? : Bool) -> (Matrix, Matrix) raise MatrixError

Diagonalize a matrix when a full eigenbasis is available.

  • Does: Returns the modal matrix P and diagonal matrix D such that A = P * D * P^-1.
  • Input: A square dense Matrix and an optional reals_only flag.
  • Returns: (P, D) as dense matrices.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs and MatrixError::ValueError when the matrix is not diagonalizable with the currently available eigenbasis. reals_only is accepted for API compatibility but is not enforced here.

#
Matrix::echelon_form

source
fn Matrix::echelon_form(self : Matrix) -> Matrix

Compute an echelon form of a matrix.

  • Does: Performs elimination without normalizing pivots to one.
  • Input: Any dense Matrix.
  • Returns: A dense Matrix in echelon form.
  • Limits: This front door does not report pivot columns; use echelon_form_with_pivots when callers need them.

#
Matrix::echelon_form_with_pivots

source
fn Matrix::echelon_form_with_pivots(self : Matrix) -> (Matrix, Array[Int])

#
Matrix::eigenvals

source
fn Matrix::eigenvals(self : Matrix) -> Array[(
Expr, Int)] raise MatrixError

Compute eigenvalues and algebraic multiplicities.

  • Does: Uses diagonal shortcuts, low-dimensional closed forms, exact eigen paths, or roots of the characteristic polynomial.
  • Input: A square dense Matrix.
  • Returns: Array[(Expr, Int)], one pair per distinct eigenvalue.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. Returned eigenvalues may stay symbolic or radical-based rather than being numerically approximated.

#
Matrix::eigenvects

source

Compute eigenvalues, multiplicities, and eigenvector bases.

  • Does: Computes eigenvalues first, then builds a nullspace basis for each eigenspace unless an exact higher-dimensional path is available.
  • Input: A square dense Matrix.
  • Returns: Array[(Expr, Int, Array[Array[Expr]])].
  • Limits: Bases can be incomplete when the exact algebraic path fails on difficult matrices, in which case downstream front doors such as diagonalize may raise ValueError.

#
Matrix::equals

source
fn Matrix::equals(self : Matrix, other : Matrix) -> Bool

#
Matrix::evalf

source
fn Matrix::evalf(self : Matrix, prec? : Int) -> Matrix

Numerically evaluate every entry of a dense matrix.

  • Does: Calls @symcore.evalf on each entry with the requested precision.
  • Input: A dense Matrix and optional binary precision prec.
  • Returns: A dense Matrix whose entries are numeric expressions when evaluation succeeds.
  • Limits: Non-numeric subexpressions can remain symbolic if evalf cannot reduce them further.

#
Matrix::extract

source
fn Matrix::extract(self : Matrix, row_indices : Array[Int], col_indices : Array[Int]) -> Matrix raise MatrixError

Select a submatrix by row and column index lists.

  • Does: Builds a new matrix from the requested row and column positions, preserving order and duplicates.
  • Input: A Matrix, row_indices, and col_indices. Indices may be negative.
  • Returns: A new dense Matrix.
  • Limits: Raises MatrixError::IndexError when any requested index is out of range.

#
Matrix::getitem

source
fn Matrix::getitem(self : Matrix, row : Int, col : Int) -> 
Expr raise MatrixError

Read a single matrix entry.

  • Does: Returns the expression stored at (row, col).
  • Input: A Matrix plus row and column indices. Negative indices count from the end.
  • Returns: The selected Expr.
  • Limits: Raises MatrixError::IndexError when either index falls outside the matrix bounds.

#
Matrix::inv

source
fn Matrix::inv(self : Matrix) -> Matrix raise MatrixError

Compute the inverse of a square matrix.

  • Does: Chooses an exact or numeric elimination path and returns the matrix inverse.
  • Input: A square dense Matrix.
  • Returns: A dense Matrix whose product with the input is the identity when the input is invertible.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs and MatrixError::SingularMatrixError for singular matrices.

test "inv computes a dense matrix inverse" {
  let m = @symmatrices.matrix([
    [@symcore.int(1), @symcore.int(2)],
    [@symcore.int(3), @symcore.int(4)],
  ])
  inspect(m.inv().to_string(), content="Matrix([[-2, 1], [3/2, -1/2]])")
}

#
Matrix::is_diagonal

source
fn Matrix::is_diagonal(self : Matrix) -> Bool

#
Matrix::is_diagonalizable

source
fn Matrix::is_diagonalizable(self : Matrix) -> Bool

Decide whether a matrix is diagonalizable over the currently computed eigenbasis.

  • Does: Checks whether the total number of eigenvectors equals the matrix size.
  • Input: Any dense Matrix.
  • Returns: Bool.
  • Limits: Non-square matrices return false. A false result can also reflect current eigenbasis limitations, not only mathematical non-diagonalizability.

#
Matrix::is_echelon

source
fn Matrix::is_echelon(self : Matrix) -> Bool

#
Matrix::is_lower

source
fn Matrix::is_lower(self : Matrix) -> Bool

#
Matrix::is_square

source
fn Matrix::is_square(self : Matrix) -> Bool

#
Matrix::is_symmetric

source
fn Matrix::is_symmetric(self : Matrix) -> Bool

#
Matrix::is_upper

source
fn Matrix::is_upper(self : Matrix) -> Bool

#
Matrix::is_zero_matrix

source
fn Matrix::is_zero_matrix(self : Matrix) -> Bool

#
Matrix::jordan_cells

source
fn Matrix::jordan_cells(self : Matrix) -> Array[Matrix] raise MatrixError

Return Jordan blocks for the matrix.

  • Does: Computes the Jordan-chain decomposition and materializes each Jordan block as a dense matrix.
  • Input: A square dense Matrix.
  • Returns: Array[Matrix], one block per Jordan chain.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs and may raise ValueError when a full Jordan chain basis cannot be recovered.

#
Matrix::jordan_form

source
fn Matrix::jordan_form(self : Matrix, calc_transform? : Bool) -> (Matrix, Matrix) raise MatrixError

Compute the Jordan form and optionally the similarity transform.

  • Does: Builds Jordan blocks from Jordan chains and, when requested, also returns the change-of-basis matrix.
  • Input: A square dense Matrix and an optional calc_transform flag.
  • Returns: (P, J) where J is the Jordan form and P is the similarity transform when requested.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs and MatrixError::ValueError when a full Jordan basis cannot be assembled. When calc_transform=false, the first result is eye(self.rows).

#
Matrix::latex

source
fn Matrix::latex(self : Matrix, settings? : 
LatexSettings) -> String

#
Matrix::ldl

source
fn Matrix::ldl(self : Matrix) -> (Matrix, Matrix) raise MatrixError

Compute an LDL decomposition.

  • Does: Returns matrices L and D such that self = L * D * L.T on supported inputs.
  • Input: A square dense Matrix.
  • Returns: (L, D) where L has unit diagonal and D is diagonal.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. This front door does not validate definiteness or symmetry up front.

#
Matrix::lower_triangular_solve

source
fn Matrix::lower_triangular_solve(self : Matrix, rhs : Matrix) -> Matrix raise MatrixError

Solve a lower-triangular linear system.

  • Does: Performs forward substitution on self * X = rhs.
  • Input: A square lower-triangular left-hand-side Matrix and a right-hand-side Matrix with the same row count.
  • Returns: A dense Matrix solution.
  • Limits: Raises MatrixError::ShapeError when the left-hand side is not square or the row counts do not match. Callers must ensure the diagonal is invertible.

#
Matrix::lu

source
fn Matrix::lu(self : Matrix) -> (Matrix, Matrix, Array[(Int, Int)]) raise MatrixError

Compute an LU decomposition with recorded row swaps.

  • Does: Factors the matrix into L, U, and the sequence of row swaps applied during elimination.
  • Input: A square dense Matrix.
  • Returns: (L, U, swaps) where L has unit diagonal and swaps records permutation steps.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. Zero pivots are skipped rather than forcing a full pivoting strategy.

#
Matrix::minor

source
fn Matrix::minor(self : Matrix, row : Int, col : Int) -> 
Expr raise MatrixError

Compute one matrix minor.

  • Does: Takes the determinant of the submatrix formed by removing one row and one column.
  • Input: A Matrix, a row index, and a column index.
  • Returns: One symbolic Expr.
  • Limits: Propagates index and determinant errors from minor_submatrix() and det().

#
Matrix::minor_submatrix

source
fn Matrix::minor_submatrix(self : Matrix, row : Int, col : Int) -> Matrix raise MatrixError

Build the minor submatrix for one position.

  • Does: Deletes the requested row and column from the matrix.
  • Input: A Matrix, a row index, and a column index.
  • Returns: A smaller dense Matrix.
  • Limits: Raises MatrixError::IndexError when either index is out of range.

#
Matrix::nnz

source
fn Matrix::nnz(self : Matrix) -> Int

#
Matrix::nullspace

source

Return a basis for the nullspace.

  • Does: Solves the homogeneous system self * x = 0 from the reduced row echelon form.
  • Input: Any dense Matrix.
  • Returns: Array[Array[Expr]], one basis vector per free variable.
  • Limits: Returns an empty array when the nullspace is trivial.

#
Matrix::qr

source
fn Matrix::qr(self : Matrix) -> (Matrix, Matrix) raise MatrixError

Compute a QR decomposition.

  • Does: Runs a Gram-Schmidt style factorization and returns Q and R.
  • Input: Any dense Matrix.
  • Returns: (Q, R) with Q shaped like the input columns and R upper triangular.
  • Limits: Zero columns can leave unevaluated square roots or divisions in symbolic mode; empty matrices return zero-shaped factors.

#
Matrix::rank

source
fn Matrix::rank(self : Matrix) -> Int

Compute the rank of a matrix.

  • Does: Counts pivot columns in the reduced row echelon form.
  • Input: Any dense Matrix.
  • Returns: An Int rank.
  • Limits: Uses rref() internally, so symbolic expressions follow the same pivot heuristics as that front door.

#
Matrix::reshape

source
fn Matrix::reshape(self : Matrix, rows : Int, cols : Int) -> Matrix raise MatrixError

Reshape a dense matrix without changing entry order.

  • Does: Reinterprets the current row-major entry sequence with a new shape.
  • Input: A Matrix and target rows and cols.
  • Returns: A new Matrix with the requested shape.
  • Limits: Raises MatrixError::ShapeError when the new shape is negative or changes the total number of entries.

#
Matrix::row

source
fn Matrix::row(self : Matrix, row : Int) -> Array[
Expr] raise MatrixError

Extract a full row as expressions.

  • Does: Clones one row from the dense matrix.
  • Input: A Matrix and a row index. Negative indices count from the end.
  • Returns: Array[Expr] for that row.
  • Limits: Raises MatrixError::IndexError when the row index is out of range.

#
Matrix::row_del

source
fn Matrix::row_del(self : Matrix, row : Int) -> Matrix raise MatrixError

#
Matrix::row_insert

source
fn Matrix::row_insert(self : Matrix, pos : Int, other : Matrix) -> Matrix raise MatrixError

#
Matrix::row_join

source
fn Matrix::row_join(self : Matrix, other : Matrix) -> Matrix raise MatrixError

#
Matrix::rowspace

source

Return a basis for the row space.

  • Does: Extracts the nonzero rows of the reduced row echelon form.
  • Input: Any dense Matrix.
  • Returns: Array[Array[Expr]], one basis vector per row.
  • Limits: Basis vectors are returned in echelon order, not normalized to any additional canonical form.

#
Matrix::rref

source
fn Matrix::rref(self : Matrix) -> (Matrix, Array[Int])

Compute the reduced row echelon form of a matrix.

  • Does: Returns the row-reduced form together with the pivot column indices.
  • Input: Any dense Matrix.
  • Returns: (reduced_matrix, pivots) where pivots lists pivot columns in ascending order.
  • Limits: Numeric matrices use a floating elimination path; symbolic matrices use exact expression elimination and may return unsimplified expressions.

test "rref reports pivot columns" {
  let m = @symmatrices.matrix([
    [@symcore.int(1), @symcore.int(2)],
    [@symcore.int(2), @symcore.int(4)],
  ])
  let (_, pivots) = m.rref()
  debug_inspect(pivots, content="[0]")
}

#
Matrix::rref_rhs

source
fn Matrix::rref_rhs(self : Matrix, rhs : Matrix) -> (Matrix, Matrix) raise MatrixError

#
Matrix::scalar_mul

source
fn Matrix::scalar_mul(self : Matrix, scalar : 
Expr) -> Matrix raise MatrixError

#
Matrix::setitem

source
fn Matrix::setitem(self : Matrix, row : Int, col : Int, value : 
Expr) -> Matrix raise MatrixError

Return a copy of the matrix with one entry replaced.

  • Does: Clones the matrix, writes value into (row, col), and returns the new matrix.
  • Input: A Matrix, row index, column index, and replacement Expr. Negative indices count from the end.
  • Returns: A new Matrix with the same shape.
  • Limits: Raises MatrixError::IndexError when either index falls outside the matrix bounds.

#
Matrix::shape

source
fn Matrix::shape(self : Matrix) -> (Int, Int)

Return the matrix shape.

  • Does: Reports the number of rows and columns stored in the dense matrix.
  • Input: A Matrix.
  • Returns: A pair (rows, cols).
  • Limits: This is metadata only; it never validates contents.

#
Matrix::simplify

source
fn Matrix::simplify(self : Matrix) -> Matrix raise MatrixError

#
Matrix::solve

source
fn Matrix::solve(self : Matrix, rhs : Matrix) -> Matrix raise MatrixError

Solve a square linear system A * X = rhs.

  • Does: Solves the system with an exact or LU-based path depending on the matrix data.
  • Input: A square left-hand-side Matrix and a right-hand-side Matrix with the same row count.
  • Returns: A dense Matrix solution with self.cols rows and rhs.cols columns.
  • Limits: Raises MatrixError::ShapeError when the row counts do not match, MatrixError::NonSquareMatrixError when the left-hand side is not square, and MatrixError::SingularMatrixError for singular systems.

test "solve returns the dense solution matrix" {
  let lhs = @symmatrices.matrix([
    [@symcore.int(2), @symcore.int(1)],
    [@symcore.int(1), @symcore.int(3)],
  ])
  let rhs = @symmatrices.matrix([[@symcore.int(1)], [@symcore.int(2)]])
  inspect(lhs.solve(rhs).to_string(), content="Matrix([[1/5], [3/5]])")
}

#
Matrix::to_list

source

Convert a dense matrix into nested row arrays.

  • Does: Clones the internal grid so callers can inspect or reuse row-major data safely.
  • Input: A Matrix.
  • Returns: Array[Array[Expr]] in row-major order.
  • Limits: The returned arrays are copies, so later edits do not mutate the original matrix.

#
Matrix::to_sparse

source
fn Matrix::to_sparse(self : Matrix) -> SparseMatrix

Convert a dense matrix into sparse DOK form.

  • Does: Drops zero entries and stores the remaining coordinates explicitly.
  • Input: A dense Matrix.
  • Returns: A SparseMatrix.
  • Limits: Zero detection depends on the current symbolic zero predicate.

#
Matrix::todod

source
fn Matrix::todod(self : Matrix) -> Map[Int, Map[Int, 
Expr]]

#
Matrix::todok

source
fn Matrix::todok(self : Matrix) -> Map[(Int, Int), 
Expr]

#
Matrix::tolist

source

#
Matrix::trace

source

Compute the trace of a dense matrix.

  • Does: Adds the main-diagonal entries.
  • Input: A square Matrix.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::NonSquareMatrixError when the matrix is not square.

#
Matrix::transpose

source
fn Matrix::transpose(self : Matrix) -> Matrix raise MatrixError

Transpose a dense matrix.

  • Does: Swaps rows and columns and returns the transposed matrix.
  • Input: A Matrix.
  • Returns: A new Matrix of shape (cols, rows).
  • Limits: Raises MatrixError only if zero-matrix allocation for the output shape fails.

#
Matrix::upper_triangular_solve

source
fn Matrix::upper_triangular_solve(self : Matrix, rhs : Matrix) -> Matrix raise MatrixError

Solve an upper-triangular linear system.

  • Does: Performs backward substitution on self * X = rhs.
  • Input: A square upper-triangular left-hand-side Matrix and a right-hand-side Matrix with the same row count.
  • Returns: A dense Matrix solution.
  • Limits: Raises MatrixError::ShapeError when the left-hand side is not square or the row counts do not match. Callers must ensure the diagonal is invertible.

#
Matrix::vec

source
fn Matrix::vec(self : Matrix) -> Matrix raise MatrixError

#
MatrixExpr

source
pub enum MatrixExpr {
  Concrete(Matrix)
  Symbol(String, Int, Int)
  Identity(Int)
  Zero(Int, Int)
  Add(Array[MatrixExpr])
  Mul(Array[MatrixExpr])
  BlockDiag(Array[MatrixExpr])
  Block(Array[Array[MatrixExpr]])
  Transpose(MatrixExpr)
  Inverse(MatrixExpr)
  Pow(MatrixExpr, Int)
}

Symbolic matrix expression nodes and front doors.

Current Limits:
  • This layer models symbolic matrix syntax but only evaluates operations implemented in symmatrices.
  • Unsupported symbolic rewrites stay unevaluated instead of introducing a separate assumption system.

  • Does: Represents symbolic matrix syntax such as symbols, products, sums, block layouts, transpose, inverse, and integer powers.
  • Input: Each variant stores matrix metadata or child MatrixExpr nodes.
  • Returns: One MatrixExpr tree.
  • Limits: This is a syntax layer, not a full theorem prover; semantically equivalent matrix expressions can remain structurally different until a caller evaluates or collapses them.
impl Show for MatrixExpr

#
MatrixExpr::as_explicit

source
fn MatrixExpr::as_explicit(self : MatrixExpr, env : Map[String, Matrix]) -> Matrix raise MatrixError

Convert a symbolic matrix expression into an explicit dense matrix.

  • Does: Alias of eval, intended for callers that want a fully explicit matrix result.
  • Input: A MatrixExpr and symbol environment.
  • Returns: A dense Matrix.
  • Limits: Propagates the same evaluation errors as eval.

#
MatrixExpr::block_collapse

source
fn MatrixExpr::block_collapse(self : MatrixExpr) -> MatrixExpr

Collapse block-oriented symbolic wrappers where local rewrites are available.

  • Does: Recursively simplifies nested block, block-diagonal, identity, transpose, inverse, and product forms.
  • Input: Any MatrixExpr.
  • Returns: A simplified MatrixExpr.
  • Limits: This is not a full symbolic canonicalizer; many semantically equivalent expressions remain structurally different.

#
MatrixExpr::doit

source
fn MatrixExpr::doit(self : MatrixExpr, env : Map[String, Matrix]) -> Matrix raise MatrixError

Evaluate a symbolic matrix expression eagerly.

  • Does: Alias of eval.
  • Input: A MatrixExpr and symbol environment.
  • Returns: A dense Matrix.
  • Limits: Propagates the same evaluation errors as eval.

#
MatrixExpr::eval

source
fn MatrixExpr::eval(self : MatrixExpr, env : Map[String, Matrix]) -> Matrix raise MatrixError

Evaluate a symbolic matrix expression against a binding environment.

  • Does: Replaces symbolic matrices from env and executes supported matrix operations to produce a concrete dense matrix.
  • Input: A MatrixExpr and Map[String, Matrix] environment for symbol bindings.
  • Returns: A dense Matrix.
  • Limits: Raises MatrixError::ValueError for missing symbol bindings and shape-related matrix errors when an operation cannot be evaluated.

#
MatrixExpr::latex

source

#
MatrixExpr::shape

source
fn MatrixExpr::shape(self : MatrixExpr) -> (Int, Int) raise MatrixError

Compute the shape of a symbolic matrix expression.

  • Does: Checks the structural dimensions implied by the expression tree.
  • Input: Any MatrixExpr.
  • Returns: A pair (rows, cols).
  • Limits: Raises MatrixError::ShapeError when add/mul/block layouts are inconsistent.

#
SparseMatrix

source
#alias(ImmutableSparseMatrix)
#alias(MutableSparseMatrix)
pub struct SparseMatrix {
  rows : Int
  cols : Int
  entries : Map[(Int, Int), 
Expr]
}

Sparse symbolic matrices stored in dictionary-of-keys form.

Current Limits:
  • Most structural front doors stay sparse, but several decomposition paths return dense matrices.
  • This file focuses on DOK-style sparse values rather than a separate symbolic matrix-expression layer.
impl Add for SparseMatrix
impl Mul for SparseMatrix
impl Sub for SparseMatrix

#
SparseMatrix::applyfunc

source

Apply a function to each stored sparse entry.

  • Does: Maps f over explicitly stored entries and drops results that simplify to zero.
  • Input: A SparseMatrix and a function (Expr) -> Expr.
  • Returns: A SparseMatrix.
  • Limits: Implicit zero entries are not passed through f.

#
SparseMatrix::as_immutable

source
fn SparseMatrix::as_immutable(self : SparseMatrix) -> SparseMatrix

Return an immutable-style copy of a sparse matrix.

  • Does: Clones the sparse entry dictionary while preserving the stored sparsity pattern.
  • Input: A SparseMatrix.
  • Returns: Another SparseMatrix with the same shape and stored entries.
  • Limits: This is a compatibility front door; it does not freeze or alias the original value.

#
SparseMatrix::as_mutable

source
fn SparseMatrix::as_mutable(self : SparseMatrix) -> SparseMatrix

Return a mutable-style copy of a sparse matrix.

  • Does: Clones the sparse entry dictionary so callers can keep editing the returned value.
  • Input: A SparseMatrix.
  • Returns: Another SparseMatrix with the same shape and stored entries.
  • Limits: This package uses value semantics, so the original sparse matrix is never mutated in place.

#
SparseMatrix::cholesky

source
fn SparseMatrix::cholesky(self : SparseMatrix) -> Matrix raise MatrixError

#
SparseMatrix::col_del

source
fn SparseMatrix::col_del(self : SparseMatrix, pos : Int) -> SparseMatrix raise MatrixError

#
SparseMatrix::col_insert

source
fn SparseMatrix::col_insert(self : SparseMatrix, pos : Int, other : SparseMatrix) -> SparseMatrix raise MatrixError

#
SparseMatrix::col_join

source
fn SparseMatrix::col_join(self : SparseMatrix, other : SparseMatrix) -> SparseMatrix raise MatrixError

#
SparseMatrix::col_list

source

#
SparseMatrix::columnspace

source

#
SparseMatrix::copy

source

Clone a sparse matrix.

  • Does: Returns a sparse matrix with copied metadata and entries.
  • Input: A SparseMatrix.
  • Returns: Another SparseMatrix.
  • Limits: Equivalent to as_mutable() for this value-semantic API.

#
SparseMatrix::det

source

Compute the determinant of a sparse square matrix.

  • Does: Uses diagonal shortcuts when available and otherwise delegates to dense determinant computation.
  • Input: A square SparseMatrix.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::NonSquareMatrixError for non-square inputs. General sparse determinants currently fall back to dense evaluation.

#
SparseMatrix::echelon_form

source
fn SparseMatrix::echelon_form(self : SparseMatrix) -> Matrix

#
SparseMatrix::eigenvals

source

#
SparseMatrix::eigenvects

source

#
SparseMatrix::equals

source
fn SparseMatrix::equals(self : SparseMatrix, other : SparseMatrix) -> Bool

Compare two sparse matrices by value.

  • Does: Checks whether both matrices have the same shape and the same explicit entries.
  • Input: Two SparseMatrix values.
  • Returns: Bool.
  • Limits: Comparison is delegated through dense equality, so semantically equal but differently simplified expressions may compare unequal.

#
SparseMatrix::evalf

source
fn SparseMatrix::evalf(self : SparseMatrix, prec? : Int) -> Matrix

Numerically evaluate every entry of a sparse matrix.

  • Does: Converts the sparse matrix to dense form and then applies dense evalf.
  • Input: A SparseMatrix and optional binary precision prec.
  • Returns: A dense Matrix.
  • Limits: The return type is dense, so sparsity is not preserved.

#
SparseMatrix::extract

source
fn SparseMatrix::extract(self : SparseMatrix, row_ids : Array[Int], col_ids : Array[Int]) -> SparseMatrix raise MatrixError

Extract a sparse submatrix by row and column index lists.

  • Does: Reindexes the selected rows and columns into a new sparse matrix.
  • Input: A SparseMatrix, row_ids, and col_ids. Indices may be negative.
  • Returns: A new SparseMatrix.
  • Limits: Raises MatrixError::IndexError when any requested index is out of range.

#
SparseMatrix::getitem

source
fn SparseMatrix::getitem(self : SparseMatrix, row : Int, col : Int) -> 
Expr raise MatrixError

Read one sparse matrix entry.

  • Does: Returns the stored expression at (row, col) or symbolic zero if the coordinate is absent.
  • Input: A SparseMatrix, row index, and column index. Negative indices count from the end.
  • Returns: An Expr.
  • Limits: Raises MatrixError::IndexError when either index falls outside the matrix bounds.

#
SparseMatrix::inv

source
fn SparseMatrix::inv(self : SparseMatrix) -> Matrix raise MatrixError

Compute the inverse of a sparse square matrix.

  • Does: Delegates through the dense inverse path.
  • Input: A square SparseMatrix.
  • Returns: A dense Matrix.
  • Limits: Raises MatrixError::NonSquareMatrixError or MatrixError::SingularMatrixError under the same conditions as dense inversion, and it does not preserve sparsity in the return type.

#
SparseMatrix::is_diagonal

source
fn SparseMatrix::is_diagonal(self : SparseMatrix) -> Bool

#
SparseMatrix::is_lower

source
fn SparseMatrix::is_lower(self : SparseMatrix) -> Bool

#
SparseMatrix::is_symmetric

source
fn SparseMatrix::is_symmetric(self : SparseMatrix) -> Bool

#
SparseMatrix::is_upper

source
fn SparseMatrix::is_upper(self : SparseMatrix) -> Bool

#
SparseMatrix::is_zero_matrix

source
fn SparseMatrix::is_zero_matrix(self : SparseMatrix) -> Bool

Check whether the sparse matrix stores only zeros.

  • Does: Tests whether there are no explicit nonzero entries.
  • Input: A SparseMatrix.
  • Returns: Bool.
  • Limits: This is structural and assumes explicit zeros were removed on construction.

#
SparseMatrix::jordan_form

source
fn SparseMatrix::jordan_form(self : SparseMatrix, calc_transform? : Bool) -> (Matrix, Matrix) raise MatrixError

#
SparseMatrix::latex

source

#
SparseMatrix::ldl

source
fn SparseMatrix::ldl(self : SparseMatrix) -> (Matrix, Matrix) raise MatrixError

#
SparseMatrix::lower_triangular_solve

source
fn SparseMatrix::lower_triangular_solve(self : SparseMatrix, rhs : Matrix) -> Matrix raise MatrixError

#
SparseMatrix::lu

source
fn SparseMatrix::lu(self : SparseMatrix) -> (Matrix, Matrix, Array[(Int, Int)]) raise MatrixError

#
SparseMatrix::nnz

source
fn SparseMatrix::nnz(self : SparseMatrix) -> Int

Count stored nonzero entries.

  • Does: Reports how many entries are currently present in the sparse dictionary.
  • Input: A SparseMatrix.
  • Returns: An Int.
  • Limits: This is structural sparsity only; mathematically equivalent but unsimplified zeros are excluded at construction time.

#
SparseMatrix::nullspace

source

#
SparseMatrix::qr

source

#
SparseMatrix::rank

source
fn SparseMatrix::rank(self : SparseMatrix) -> Int

Compute the rank of a sparse matrix.

  • Does: Counts pivot columns in the reduced row echelon form.
  • Input: Any SparseMatrix.
  • Returns: An Int rank.
  • Limits: This front door materializes dense row data during elimination.

#
SparseMatrix::reshape

source
fn SparseMatrix::reshape(self : SparseMatrix, rows : Int, cols : Int) -> SparseMatrix raise MatrixError

Reshape a sparse matrix without densifying it.

  • Does: Reinterprets each stored coordinate in row-major order under a new shape.
  • Input: A SparseMatrix and target rows and cols.
  • Returns: A new SparseMatrix.
  • Limits: Raises MatrixError::ShapeError when the new shape is negative or changes the total number of entries.

#
SparseMatrix::row_del

source
fn SparseMatrix::row_del(self : SparseMatrix, pos : Int) -> SparseMatrix raise MatrixError

#
SparseMatrix::row_insert

source
fn SparseMatrix::row_insert(self : SparseMatrix, pos : Int, other : SparseMatrix) -> SparseMatrix raise MatrixError

#
SparseMatrix::row_join

source
fn SparseMatrix::row_join(self : SparseMatrix, other : SparseMatrix) -> SparseMatrix raise MatrixError

#
SparseMatrix::row_list

source

#
SparseMatrix::rowspace

source

#
SparseMatrix::rref

source
fn SparseMatrix::rref(self : SparseMatrix) -> (Matrix, Array[Int])

#
SparseMatrix::scalar_multiply

source

Multiply every stored sparse entry by a scalar.

  • Does: Scales all explicit entries and drops any that simplify to zero.
  • Input: A SparseMatrix and one scalar Expr.
  • Returns: A SparseMatrix.
  • Limits: Raises any construction errors from sparse_matrix() if the rebuilt sparse value becomes invalid.

#
SparseMatrix::setitem

source
fn SparseMatrix::setitem(self : SparseMatrix, row : Int, col : Int, value : 
Expr) -> SparseMatrix raise MatrixError

Return a copy of the sparse matrix with one entry replaced.

  • Does: Writes value into (row, col) and removes the key entirely when value is zero.
  • Input: A SparseMatrix, row index, column index, and replacement Expr. Negative indices count from the end.
  • Returns: A new SparseMatrix.
  • Limits: Raises MatrixError::IndexError when either index falls outside the matrix bounds.

#
SparseMatrix::shape

source
fn SparseMatrix::shape(self : SparseMatrix) -> (Int, Int)

Return the sparse matrix shape.

  • Does: Reports the number of rows and columns.
  • Input: A SparseMatrix.
  • Returns: A pair (rows, cols).
  • Limits: This is metadata only.

#
SparseMatrix::solve

source
fn SparseMatrix::solve(self : SparseMatrix, rhs : Matrix) -> Matrix raise MatrixError

Solve a sparse linear system A * X = rhs.

  • Does: Solves the system using sparse LU where possible and falls back through dense-style triangular solves.
  • Input: A square left-hand-side SparseMatrix and a dense right-hand-side Matrix with matching row count.
  • Returns: A dense Matrix solution.
  • Limits: Raises shape and singularity errors under the same conditions as dense solve, and the result is returned as a dense matrix.

#
SparseMatrix::solve_least_squares

source
fn SparseMatrix::solve_least_squares(self : SparseMatrix, rhs : Matrix) -> Matrix raise MatrixError

#
SparseMatrix::to_dense

source
fn SparseMatrix::to_dense(self : SparseMatrix) -> Matrix

Convert a sparse matrix into a dense matrix.

  • Does: Materializes all missing entries as symbolic zero and returns a dense grid.
  • Input: A SparseMatrix.
  • Returns: A dense Matrix.
  • Limits: Large sparse matrices can allocate large dense outputs.

#
SparseMatrix::to_list

source

#
SparseMatrix::todok

source

Convert a sparse matrix to dictionary-of-keys form.

  • Does: Clones the underlying (row, col) -> Expr map.
  • Input: A SparseMatrix.
  • Returns: Map[(Int, Int), Expr].
  • Limits: The returned map contains only stored nonzero entries.

#
SparseMatrix::tolist

source

#
SparseMatrix::trace

source

Compute the trace of a sparse matrix.

  • Does: Adds the explicitly stored diagonal entries and treats missing ones as zero.
  • Input: A square SparseMatrix.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::NonSquareMatrixError when the matrix is not square.

#
SparseMatrix::transpose

source
fn SparseMatrix::transpose(self : SparseMatrix) -> SparseMatrix

Transpose a sparse matrix.

  • Does: Swaps row and column coordinates while preserving stored nonzero values.
  • Input: A SparseMatrix.
  • Returns: A transposed SparseMatrix.
  • Limits: The sparsity pattern is rewritten structurally; no additional simplification is performed.

#
SparseMatrix::upper_triangular_solve

source
fn SparseMatrix::upper_triangular_solve(self : SparseMatrix, rhs : Matrix) -> Matrix raise MatrixError

#
block_diag

source
fn block_diag(blocks : Array[Matrix]) -> Matrix raise MatrixError

Block assembly front doors for dense matrices.

Current Limits:
  • These helpers only materialize explicit dense block layouts.
  • They do not preserve symbolic block structure; use MatrixExpr for unevaluated block syntax.

Assemble a block-diagonal dense matrix.

  • Does: Places each block on the main block diagonal and fills all off-diagonal regions with exact zero.
  • Input: An Array[Matrix] whose items can have different shapes.
  • Returns: One dense Matrix whose shape is the sum of all block heights and widths.
  • Limits: Raises any MatrixError emitted by the delegated dense zero-matrix construction.

#
block_diag_matrix_expr

source
fn block_diag_matrix_expr(items : Array[MatrixExpr]) -> MatrixExpr

Convenience alias for matrix_expr_block_diag.

  • Does: Delegates to matrix_expr_block_diag.
  • Input: An Array[MatrixExpr].
  • Returns: A MatrixExpr.
  • Limits: Empty input still becomes a 0 x 0 zero expression.

#
block_matrix

source
fn block_matrix(rows : Array[Array[Matrix]]) -> Matrix raise MatrixError

Assemble a dense block matrix from a rectangular grid of blocks.

  • Does: Concatenates the provided blocks into one dense matrix after checking row-wise heights and column-wise widths.
  • Input: Array[Array[Matrix]] describing a rectangular block grid.
  • Returns: One dense Matrix.
  • Limits: Raises MatrixError::ShapeError when the block grid is jagged or when blocks disagree on a shared row height or column width.

#
block_matrix_expr

source
fn block_matrix_expr(rows : Array[Array[MatrixExpr]]) -> MatrixExpr

Convenience alias for matrix_expr_block.

  • Does: Delegates to matrix_expr_block.
  • Input: Rows of block expressions.
  • Returns: A MatrixExpr.
  • Limits: Block-layout validation is still deferred to shape() or eval().

#
casoratian

source

Compute the Casoratian determinant of sequences.

  • Does: Substitutes consecutive values into the sequences, builds the resulting matrix, and returns its determinant.
  • Input: An array of sequence expressions, a symbolic index n, and optional zero to choose between zero-based and shifted evaluation.
  • Returns: One symbolic Expr.
  • Limits: Raises MatrixError::ValueError when n is not a symbol.

#
diag

source
fn diag(values : Array[
Expr], rows? : Int?, cols? : Int?) -> Matrix raise MatrixError

Build a diagonal matrix from a list of entries.

  • Does: Places the given values on the main diagonal and fills all other entries with zero.
  • Input: A diagonal value array plus optional row and column counts.
  • Returns: A dense Matrix whose diagonal is populated up to the shortest of values.length(), rows, and cols.
  • Limits: Raises MatrixError::ShapeError when the delegated zero matrix construction rejects the requested dimensions.

#
eye

source
fn eye(n : Int) -> Matrix raise MatrixError

Build an identity matrix.

  • Does: Creates a square matrix with ones on the diagonal and zeros elsewhere.
  • Input: A non-negative matrix size n.
  • Returns: An n x n dense Matrix.
  • Limits: Raises MatrixError::ShapeError when n is negative.

test "eye builds an identity matrix" {
  let ident = @symmatrices.eye(3)
  inspect(
    ident.to_string(),
    content="Matrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]])",
  )
}

#
gram_schmidt

source
fn gram_schmidt(vectors : Array[Matrix], orthonormal? : Bool) -> Array[Matrix] raise MatrixError

Orthogonalize or orthonormalize a list of vectors.

  • Does: Runs Gram-Schmidt on row or column vectors and optionally normalizes the resulting basis.
  • Input: Array[Matrix] where each matrix must be a row or column vector, plus optional orthonormal.
  • Returns: Array[Matrix] in column-vector form.
  • Limits: Raises MatrixError::ShapeError when an input is not a vector and MatrixError::SingularMatrixError when the vectors are linearly dependent.

#
hessian

source

Build a Hessian matrix, optionally augmented with constraint gradients.

  • Does: Places first derivatives of constraints around the border and second derivatives of f in the lower-right block.
  • Input: One scalar expression f, a variable list, and an optional constraint list.
  • Returns: A dense Matrix.
  • Limits: Constraint handling follows the bordered-Hessian layout only; it does not solve optimization problems by itself.

#
hstack

source
fn hstack(parts : Array[Matrix]) -> Matrix raise MatrixError

Concatenate dense matrices horizontally.

  • Does: Joins matrices side-by-side in their existing row order.
  • Input: A non-empty Array[Matrix] whose members all have the same row count.
  • Returns: A new dense Matrix with summed column count.
  • Limits: Raises MatrixError::ShapeError when row counts differ. Returns 0 x 0 for an empty input list.

test "hstack joins matrices side by side" {
  let left = @symmatrices.eye(2)
  let right = @symmatrices.ones(2, cols=Some(1))
  inspect(
    @symmatrices.hstack([left, right]).to_string(),
    content="Matrix([[1, 0, 1], [0, 1, 1]])",
  )
}

#
identity_expr

source
fn identity_expr(n : Int) -> MatrixExpr

Create a symbolic identity matrix expression.

  • Does: Builds an identity-node placeholder.
  • Input: A single size n.
  • Returns: MatrixExpr::Identity(n).
  • Limits: This front door does not validate that n is non-negative.

#
jordan_cell

source
fn jordan_cell(eigenval : 
Expr, n : Int) -> Matrix raise MatrixError

Build a Jordan block.

  • Does: Creates an n x n dense matrix with eigenval on the diagonal and ones on the superdiagonal.
  • Input: One eigenvalue expression and a non-negative block size.
  • Returns: A dense Matrix.
  • Limits: Raises MatrixError::ShapeError when n is negative.

#
mat_add

source
fn mat_add(items : Array[MatrixExpr]) -> MatrixExpr

Convenience alias for matrix_expr_add.

  • Does: Delegates to matrix_expr_add.
  • Input: An Array[MatrixExpr].
  • Returns: A simplified MatrixExpr.
  • Limits: Incompatible shapes are still detected later by shape() or eval().

#
mat_mul

source
fn mat_mul(items : Array[MatrixExpr]) -> MatrixExpr

Convenience alias for matrix_expr_mul.

  • Does: Delegates to matrix_expr_mul.
  • Input: An Array[MatrixExpr].
  • Returns: A simplified MatrixExpr.
  • Limits: Incompatible dimensions are still detected later by shape() or eval().

#
matrix

source

Build a dense matrix from nested rows.

  • Does: Validates row widths and stores a cloned rectangular grid of expressions.
  • Input: An array of rows where each row is an Array[Expr].
  • Returns: A Matrix whose shape matches the input grid, or an empty 0 x 0 matrix for [].
  • Limits: Raises MatrixError::ShapeError when rows have inconsistent lengths.

test "matrix builds a rectangular dense value" {
  let m = @symmatrices.matrix([
    [@symcore.int(1), @symcore.int(2)],
    [@symcore.int(3), @symcore.int(4)],
  ])
  guard m.shape() == (2, 2) else { fail("unexpected dense matrix shape") }
  inspect(m.to_string(), content="Matrix([[1, 2], [3, 4]])")
}

#
matrix_expr

source
fn matrix_expr(m : Matrix) -> MatrixExpr

Lift a concrete dense matrix into the symbolic matrix expression layer.

  • Does: Wraps a Matrix as MatrixExpr::Concrete.
  • Input: A dense Matrix.
  • Returns: A MatrixExpr.
  • Limits: This is a structural wrapper only; it does not copy or simplify entries beyond the underlying value semantics.

#
matrix_expr_add

source
fn matrix_expr_add(items : Array[MatrixExpr]) -> MatrixExpr

Build a symbolic matrix sum.

  • Does: Flattens nested adds, drops symbolic zero terms, and eagerly combines concrete and block-diagonal operands when possible.
  • Input: An Array[MatrixExpr].
  • Returns: A simplified MatrixExpr.
  • Limits: If shapes are inconsistent, the expression may stay unevaluated until callers ask for shape() or eval().

#
matrix_expr_block

source
fn matrix_expr_block(rows : Array[Array[MatrixExpr]]) -> MatrixExpr

Build a symbolic block matrix expression.

  • Does: Stores the block layout directly, or unwraps a 1 x 1 block grid back into its only entry.
  • Input: Rows of block expressions.
  • Returns: A MatrixExpr.
  • Limits: Rectangularity and block-shape compatibility are validated later by shape() or eval().

#
matrix_expr_block_diag

source
fn matrix_expr_block_diag(items : Array[MatrixExpr]) -> MatrixExpr

Build a symbolic block-diagonal expression.

  • Does: Flattens nested block-diagonal nodes and preserves the remaining pieces structurally.
  • Input: An Array[MatrixExpr].
  • Returns: A simplified MatrixExpr.
  • Limits: Empty input returns a 0 x 0 zero expression.

#
matrix_expr_inverse

source
fn matrix_expr_inverse(expr : MatrixExpr) -> MatrixExpr

Invert a symbolic matrix expression.

  • Does: Simplifies inverse-on-inverse, inverse-of-transpose, inverse-of-products, and a small set of block patterns.
  • Input: Any MatrixExpr.
  • Returns: A MatrixExpr.
  • Limits: General block-matrix inversion is not expanded here; unsupported cases remain as Inverse(...).

#
matrix_expr_mul

source
fn matrix_expr_mul(items : Array[MatrixExpr]) -> MatrixExpr

Build a symbolic matrix product.

  • Does: Flattens nested products, removes identities, folds adjacent concrete factors, and performs a small amount of inverse/power cancellation.
  • Input: An Array[MatrixExpr].
  • Returns: A simplified MatrixExpr.
  • Limits: Incompatible dimensions are not rejected here unless they are needed for a zero or identity shortcut; callers should use shape() or eval() for strict checking.

#
matrix_expr_pow

source
fn matrix_expr_pow(expr : MatrixExpr, exp : Int) -> MatrixExpr

Raise a symbolic matrix expression to an integer power.

  • Does: Simplifies identity, zero, transpose, inverse, and nested-power cases for integer exponents.
  • Input: A MatrixExpr and an integer exponent.
  • Returns: A MatrixExpr.
  • Limits: Non-square inputs are only rejected when the zero-power shortcut needs the shape; other invalid powers can stay unevaluated until eval().

#
matrix_expr_transpose

source
fn matrix_expr_transpose(expr : MatrixExpr) -> MatrixExpr

Transpose a symbolic matrix expression.

  • Does: Pushes transpose through supported nodes and simplifies double-transpose cases.
  • Input: Any MatrixExpr.
  • Returns: A MatrixExpr.
  • Limits: Unsupported rewrites remain as explicit Transpose(...) nodes.

#
matrix_from_flat

source
fn matrix_from_flat(rows : Int, cols : Int, values : Array[
Expr]) -> Matrix raise MatrixError

Build a dense matrix from a flat row-major array.

  • Does: Splits a flat value buffer into rows * cols entries and delegates to matrix.
  • Input: Non-negative rows, non-negative cols, and a flat Array[Expr].
  • Returns: A Matrix with the requested shape.
  • Limits: Raises MatrixError::ShapeError when dimensions are negative or the flat buffer length does not match rows * cols.

#
matrix_multiply_elementwise

source
fn matrix_multiply_elementwise(lhs : Matrix, rhs : Matrix) -> Matrix raise MatrixError

#
matrix_symbol

source
fn matrix_symbol(name : String, rows : Int, cols : Int) -> MatrixExpr

Create a symbolic matrix placeholder with a fixed shape.

  • Does: Builds a MatrixExpr::Symbol node that can later be evaluated with an environment.
  • Input: A symbol name plus row and column counts.
  • Returns: A symbolic MatrixExpr.
  • Limits: Shape metadata is trusted as given; negative dimensions are not rejected here.

#
ones

source
fn ones(rows : Int, cols? : Int?) -> Matrix raise MatrixError

Build a one-filled dense matrix.

  • Does: Creates a dense matrix whose entries are all exact symbolic one.
  • Input: A required row count and an optional column count. When cols is omitted, it builds a square matrix.
  • Returns: A Matrix of shape (rows, cols) or (rows, rows).
  • Limits: Raises MatrixError::ShapeError when either dimension is negative.

#
rot_axis1

source
fn rot_axis1(theta : 
Expr) -> Matrix raise MatrixError

Build the right-handed rotation matrix around the first axis.

  • Does: Returns the symbolic 3 x 3 rotation matrix using sin(theta) and cos(theta).
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
rot_axis2

source
fn rot_axis2(theta : 
Expr) -> Matrix raise MatrixError

Build the right-handed rotation matrix around the second axis.

  • Does: Returns the symbolic 3 x 3 rotation matrix using sin(theta) and cos(theta).
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
rot_axis3

source
fn rot_axis3(theta : 
Expr) -> Matrix raise MatrixError

Build the right-handed rotation matrix around the third axis.

  • Does: Returns the symbolic 3 x 3 rotation matrix using sin(theta) and cos(theta).
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
rot_ccw_axis1

source
fn rot_ccw_axis1(theta : 
Expr) -> Matrix raise MatrixError

Build the counter-clockwise rotation matrix around the first axis.

  • Does: Returns the symbolic 3 x 3 matrix with the opposite sign convention from rot_axis1.
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
rot_ccw_axis2

source
fn rot_ccw_axis2(theta : 
Expr) -> Matrix raise MatrixError

Build the counter-clockwise rotation matrix around the second axis.

  • Does: Returns the symbolic 3 x 3 matrix with the opposite sign convention from rot_axis2.
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
rot_ccw_axis3

source
fn rot_ccw_axis3(theta : 
Expr) -> Matrix raise MatrixError

Build the counter-clockwise rotation matrix around the third axis.

  • Does: Returns the symbolic 3 x 3 matrix with the opposite sign convention from rot_axis3.
  • Input: One angle expression theta.
  • Returns: A dense Matrix.
  • Limits: Propagates any matrix-construction error from the underlying dense front door.

#
sparse_matrix

source
fn sparse_matrix(rows : Int, cols : Int, entries : Map[(Int, Int), 
Expr]) -> SparseMatrix raise MatrixError

Build a sparse matrix from explicit nonzero entries.

  • Does: Validates the declared shape, drops explicit zero values, and stores the remaining entries in DOK form.
  • Input: Row count, column count, and a Map[(Int, Int), Expr] of entries.
  • Returns: A SparseMatrix.
  • Limits: Raises MatrixError::ShapeError for negative dimensions and MatrixError::IndexError when any stored coordinate lies outside the declared shape.

#
vstack

source
fn vstack(parts : Array[Matrix]) -> Matrix raise MatrixError

Concatenate dense matrices vertically.

  • Does: Stacks matrices top-to-bottom in their existing row order.
  • Input: A non-empty Array[Matrix] whose members all have the same column count.
  • Returns: A new dense Matrix with summed row count.
  • Limits: Raises MatrixError::ShapeError when column counts differ. Returns 0 x 0 for an empty input list.

#
wronskian

source

Compute the Wronskian determinant.

  • Does: Builds the derivative tower of the given functions and returns the determinant of the resulting matrix.
  • Input: An array of expressions and a differentiation variable.
  • Returns: One symbolic Expr.
  • Limits: Raises any matrix or differentiation errors from the underlying dense and calculus front doors.

#
zero_matrix_expr

source
fn zero_matrix_expr(rows : Int, cols : Int) -> MatrixExpr

Create a symbolic zero matrix expression.

  • Does: Builds a zero-matrix placeholder with explicit shape.
  • Input: Row and column counts.
  • Returns: MatrixExpr::Zero(rows, cols).
  • Limits: This front door does not validate that the provided dimensions are non-negative.

#
zeros

source
fn zeros(rows : Int, cols? : Int?) -> Matrix raise MatrixError

Build a zero-filled dense matrix.

  • Does: Creates a dense matrix whose entries are all exact symbolic zero.
  • Input: A required row count and an optional column count. When cols is omitted, it builds a square matrix.
  • Returns: A Matrix of shape (rows, cols) or (rows, rows).
  • Limits: Raises MatrixError::ShapeError when either dimension is negative.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io