Matrices

Calling this from Scala? L11 — Matrices shows the API’s shape — the two carriers, the parser’s structural dispatch, and decompositions that answer a row. This page is the reference.

import it.grypho.scala.leonardo.core.*
import it.grypho.scala.leonardo.scalar.*
import it.grypho.scala.leonardo.matrix.*
import it.grypho.scala.leonardo.parser.Parser

val env = new Environment()

Constructing a matrix

_Matrix.ofRows accepts row vectors as Vector[_Expression] varargs:

// 2×2 identity matrix
val I2 = _Matrix.ofRows(
  Vector(_Number(1.0), _Number(0.0)),
  Vector(_Number(0.0), _Number(1.0))
)
I2.toString
// res0: String = "[[1.0, 0.0], [0.0, 1.0]]"

The parser accepts the same structure as a [[…], […]] literal:

Parser.parse("[[1, 0], [0, 1]]").get.toString
// res1: String = "[[1.0, 0.0], [0.0, 1.0]]"

A row vector uses double brackets: [[1, 2, 3]].

Element types

Matrix elements can be arbitrary expressions — variables, functions, even functionals. The matrix is symbolic until every element reduces to a number:

val x = _Variable("x")
val symM = _Matrix.ofRows(
  Vector(x,                        Sin(x)),
  Vector(Power(x, _Number(2.0)),   _Number(1.0))
)
symM.toString
// res2: String = "[[x, sin(x)], [(x ^ 2.0), 1.0]]"

Evaluate with x = 1:

val envX = new Environment(5, Map("x" -> _Number(1.0)))
// envX: Environment = it.grypho.scala.leonardo.core.Environment@344d770b
symM.eval(envX)
// res3: Either[_Expression, _Value] = Right([[1.0, 0.84147], [1.0, 1.0]])

Arithmetic

Standard +, *, scalar multiplication, transpose, determinant and inverse work on both symbolic and concrete matrices:

val A = Parser.parse("[[1, 2], [3, 4]]").get
val B = Parser.parse("[[5, 6], [7, 8]]").get
// A + B
MatSum(A, B).eval(env)
// res4: Either[_Expression, _Value] = Right([[6.0, 8.0], [10.0, 12.0]])
// A * B
MatProduct(A, B).eval(env)
// res5: Either[_Expression, _Value] = Right([[19.0, 22.0], [43.0, 50.0]])
// 2 * A
MatScale(_Number(2.0), A).eval(env)
// res6: Either[_Expression, _Value] = Right([[2.0, 4.0], [6.0, 8.0]])
// Aᵀ
Transpose(A).eval(env)
// res7: Either[_Expression, _Value] = Right([[1.0, 3.0], [2.0, 4.0]])
// det(A) — a scalar result (LU decomposition with partial pivoting on dense values)
Determinant(A).eval(env)
// res8: Either[_Expression, _Value] = Right(_Number(-2.0))
// inv(A) — the inverse matrix (Gauss–Jordan elimination); 1/A and M/N parse to this too
Inverse(A).eval(env)
// res9: Either[_Expression, _Value] = Right([[-2.0, 1.0], [1.5, -0.5]])

det(A) reduces to a scalar _Number; a non-square or (for the inverse) singular matrix has no result and stays symbolic, the same x/0 contract used elsewhere. The reciprocal spellings 1 / A and M / N (= M · N⁻¹) route through the same Inverse node. Small symbolic matrices expand by cofactors (determinant) and adjugate/det (inverse). Algorithm references: LU decomposition, Gauss–Jordan elimination.

Products, trace and norms

dot(u, v) is the number Σ uᵢvᵢ of two rows or columns of one length, in any mix — where transpose(u) * v is a 1×1 matrix, which does not add to a number. It takes no conjugate, so a complex vector stays unevaluated rather than meeting one convention or the other. cross(u, v) is the right-handed product of two 3-vectors, in the first one’s shape:

Parser.parse("dot([[1], [2], [3]], [[4], [5], [6]])").get.eval(env)
// res10: Either[_Expression, _Value] = Right(_Number(32.0))
Parser.parse("cross([[1], [0], [0]], [[0], [1], [0]])").get.eval(env)
// res11: Either[_Expression, _Value] = Right([[0.0], [0.0], [1.0]])

trace(A) sums a square matrix’s diagonal, and equals the sum of its eigenvalues:

Parser.parse("trace([[2, 1], [1, 3]])").get.eval(env)
// res12: Either[_Expression, _Value] = Right(_Number(5.0))

size(A) is the row [[rows, cols]], so r, c := size(A) at the prompt names both, and size(A, 1) / size(A, 2) give one dimension; a number is a 1×1 matrix:

Parser.parse("size([[1, 2, 3], [4, 5, 6]])").get.eval(env)
// res13: Either[_Expression, _Value] = Right([[2.0, 3.0]])
Parser.parse("size([[1, 2, 3], [4, 5, 6]], 2)").get.eval(env)
// res14: Either[_Expression, _Value] = Right(_Number(3.0))

norm(x) and norm(x, kind) read the operand’s shape (MATLAB’s rule): a row or a column is a vector, anything else a matrix. The default is the 2-norm either way — for a matrix the largest singular value, which the vector 2-norm equals on a column — and kind is 1, 2, inf or fro, or for a vector any p ≥ 1. On a vector 1 and inf are the sum and the largest modulus; on a matrix the largest column and row sums:

Parser.parse("norm([[3], [4]])").get.eval(env)
// res15: Either[_Expression, _Value] = Right(_Number(5.0))
Parser.parse("norm([[1, -2], [-3, 4]], 1)").get.eval(env)
// res16: Either[_Expression, _Value] = Right(_Number(6.0))
Parser.parse("norm([[1, -2], [-3, 4]], inf)").get.eval(env)
// res17: Either[_Expression, _Value] = Right(_Number(7.0))
Parser.parse("norm([[1, -2], [-3, 4]])").get.eval(env)
// res18: Either[_Expression, _Value] = Right(_Number(5.4649857042190435))

All four stay exact on exact cells, surds of one radical included: norm([[2], [3]]) is √13 and norm([[√2], [1]], 1) is 1 + √2; a 2-norm whose sum of squares is not rational takes its root at the working precision, and the matrix 2-norm demotes, as svd does. Symbolic cells give a symbolic answer, except the max-norm and a matrix’s operator norms, which stay unevaluated. A Double 2-norm is scaled by its largest entry before squaring, so norm([[1e200], [1e200]]) is not an overflow.

Dense evaluation

When all elements reduce to numbers the result is a _MatrixValue — a dense row-major Array[Double]. The multiply kernel is block-tiled for cache efficiency and runs in parallel above a 2¹⁶-element work threshold:

MatProduct(A, B).eval(env) match {
  case Right(m: _MatrixValue) => m.toVector
  case other                  => other
}
// res19: Object & Equals = Vector(19.0, 22.0, 43.0, 50.0)

Calculus on matrices

derive, simplify, and expand distribute element-wise over _Matrix nodes (the _ElementWise marker enables this without domain-specific cases):

val exprM = _Matrix.ofRows(
  Vector(Power(x, _Number(2.0)),  Sin(x)),
  Vector(Exp(x),                  _Number(1.0))
)
derive(exprM, x).toString
// res20: String = "[[(2.0 * x), cos(x)], [exp(x), 0.0]]"

Matrix products do not distribute automatically under differentiation — they need the product rule applied explicitly.

Functions on matrices

Scalar functions (sin, exp, ln, …) applied to a matrix distribute element-wise. This works for a dense value and for a symbolic matrix alike — numeric cells fold, free-variable cells stay as f(cell) until bound:

// exp over a symbolic matrix: exp(x) stays symbolic, exp(0) folds to 1.0
Exp(_Matrix.ofRows(Vector(x, _Number(0.0)))).eval(env) match {
  case Left(m)  => m.toString
  case Right(v) => v.toString
}
// res21: String = "[[exp(x), 1.0]]"

Binding the free variables lets the whole matrix collapse to a dense value:

Exp(_Matrix.ofRows(Vector(x, _Number(0.0)))).eval(envX) match {
  case Right(v) => v.toString
  case Left(m)  => m.toString
}
// res22: String = "[[2.71828, 1.0]]"

Decompositions

Each decomposition returns its factors bundled as a 1×n row of matrices, so one indexing mechanism (at(result, 1, k), or tuple assignment in the REPL) serves them all:

Call Result Algorithm
lu(A) [[L, U, P]], P·A = L·U LU decomposition with partial pivoting; over the rationals for an exact A, where a singular matrix factors too (a zero on U’s diagonal)
qr(A) [[Q, R]], A = Q·R QR decomposition by modified Gram–Schmidt; dependent columns stay unevaluated, since that refusal is the rank test regress relies on
eigen(A) [[λ₁, …, λₙ]] QR algorithm: balancing, Hessenberg reduction and the Francis double shift; complex pairs come back as _Complex; sorted by real part, then imaginary part, as tfpoles sorts its roots
eig(A) [[V, D]], A·V = V·D Eigendecomposition: eigenvector columns and the diagonal eigenvalue matrix; a repeated eigenvalue gets independent eigenvectors when its eigenspace allows, and a defective matrix stays symbolic
jordan(A) [[P, J]], A = P·J·P⁻¹ Jordan normal form: exact, Jordan blocks included, for an exact matrix whose eigenvalues are all rational (eigenvalues ascending, blocks by decreasing size, the 1s above the diagonal); otherwise the diagonal case, and a defective numeric matrix stays symbolic, since a numeric Jordan block is not computable
Parser.parse("eigen([[2, 1], [1, 2]])").get.eval(env).toExpression.toString
// res23: String = "[[1.0, 3.0]]"
Parser.parse("lu([[4, 3], [6, 3]])").get.eval(env).toExpression.toString
// res24: String = "[[[[1.0, 0.0], [0.66667, 1.0]], [[6.0, 3.0], [0.0, 1.0]], [[0.0, 1.0], [1.0, 0.0]]]]"

Matrix exponential

expm(A) computes e^A — the matrix exponential, a different operation from the integer power A^n. It uses scaling and squaring with a degree-13 Padé approximant, which is why it also works for defective matrices — input the eigendecomposition route has no basis for:

// nilpotent: the series terminates, so the result is exact
Parser.parse("expm([[0, 1], [0, 0]])").get.eval(env).toExpression.toString
// res25: String = "[[1.0, 1.0], [0.0, 1.0]]"
// a rotation generator exponentiates to the rotation matrix
Parser.parse("expm([[0, -1], [1, 0]])").get.eval(env).toExpression.toString
// res26: String = "[[0.5403, -0.84147], [0.84147, 0.5403]]"

Cholesky factorisation

chol(A) returns the lower-triangular L with a positive diagonal and A = L·Lᵀ — the Cholesky factorisation of a symmetric positive-definite matrix. Like expm it is a single matrix, not a row, so chol(A) * x is an ordinary matrix product.

Parser.parse("chol([[4, 2], [2, 3]])").get.eval(env).toExpression.toString
// res27: String = "[[2.0, 0.0], [1.0, 1.41421]]"

Its refusal is as useful as its answer: a matrix that is not symmetric, or not positive definite (indefinite, negative definite, or singular), stays unevaluated — the cheapest test there is that a quadratic form is strictly convex. An asymmetric matrix is never factored from one triangle, which would answer for a different matrix. Both tests are relative to the matrix’s largest entry, so rescaling A never changes the verdict:

// indefinite: the eigenvalues are 3 and -1
Parser.parse("chol([[1, 2], [2, 1]])").get.eval(env).toExpression.toString
// res28: String = "chol([[1.0, 2.0], [2.0, 1.0]])"

In exact mode the factor is exact even when a pivot’s square root is irrational: each column of L carries a single root, so the factor is made of surds — chol([[4, 2], [2, 3]]) is [[2, 0], [1, √2]] — and L·Lᵀ gives back A exactly. det, inv, lu and A^n likewise stay exact on a matrix whose surds share one root, and read two different roots at the working precision.

Singular values: svd, pinv, rank, cond, nullspace, orth

svd(A) returns the row [[U, S, V]] with A = U·S·Vᵀ — the singular value decomposition, the singular values on S’s diagonal, largest first. By default it is the economy form: with k = min(m, n), U is m×k, S k×k and V n×k, everything a computation multiplies with. svd(A, full) completes U and V to square orthogonal matrices (and S to m×n), so the extra columns span the left null space and the null space; full is a word of that slot only, not a reserved name. Like lu, the factors bind by tuple assignment: U, S, V := svd(A).

Parser.parse("svd([[3, 0], [4, 5]])").get.eval(env).toExpression.toString
// res29: String = "[[[[0.31623, 0.94868], [0.94868, -0.31623]], [[6.7082, 0.0], [0.0, 2.23607]], [[0.70711, 0.70711], [0.70711, -0.70711]]]]"

The kernel is one-sided Jacobi, which works on A’s columns and never forms AᵀA (that would square the condition number), and its answer is certified: a decomposition that does not reconstruct A with orthonormal U and V stays unevaluated. An exact matrix is decomposed in Double, as lu and qr are; a symbolic one stays symbolic.

Three answers are read off the singular values. rank(A) counts those above 0.5·10⁻ᵖ·σ_max at session precision p — the tolerance of = applied to the spectrum, and relative to the largest singular value, so rescaling A never changes its rank; rank(A, tol) takes a tolerance in [0, 1), relative in the same way. pinv(A) is the Moore–Penrose pseudo-inverse, inverting exactly the singular values rank counts, so a rank-deficient matrix is not amplified by rounding:

Parser.parse("rank([[1, 2], [2, 4]])").get.eval(env).toExpression.toString
// res30: String = "1.0"
Parser.parse("pinv([[1, 2], [2, 4]])").get.eval(env).toExpression.toString
// res31: String = "[[0.04, 0.08], [0.08, 0.16]]"

cond(A) is the 2-norm condition number σ_max/σ_min, and inf for a singular matrix. It takes a different cut-off from rank, on purpose: it reports how close to singular A is, so it stays finite until the smallest singular value is lost in rounding (max(m, n)·ε·σ_max).

Parser.parse("cond([[1, 0], [0, 0.001]])").get.eval(env).toExpression.toString
// res32: String = "1000.0"

Two bases are read off the same decomposition, at the same rank. nullspace(A) returns an orthonormal basis of the null space {x : A·x = 0} as the columns of an n×(n − rank) matrix, and orth(A) an orthonormal basis of the range as an m×rank one; both take rank’s optional tolerance, so size(nullspace(A), 2) + size(orth(A), 2) = n always holds. A subspace with no basis — the null space of a full-column-rank matrix, the range of the zero matrix — answers false, since a matrix cannot have zero columns. A basis is unique only up to rotation, so check one by what it does, not by its entries:

Parser.parse("nullspace([[1, 2, 3], [2, 4, 6], [1, 0, 1]])").get.eval(env).toExpression.toString
// res33: String = "[[0.57735], [0.57735], [-0.57735]]"
Parser.parse("nullspace([[1, 0], [0, 1]])").get.eval(env).toExpression.toString
// res34: String = "false"

The decomposition is bounded by max(m, n)·min(m, n)² ≤ 10⁷ — a 200×200 or a 1000×100 matrix — checked before any work; past it the call stays unevaluated and the REPL says why.

Block matrices

hcat and vcat join any number of blocks side by side and stacked, blkdiag puts them on the diagonal, repmat(A, m, n) tiles one, kron(A, B) is the Kronecker product, and ones(m, n) is the all-ones counterpart of zeros:

Parser.parse("blkdiag([[1]], [[2, 3], [4, 5]])").get.eval(env).toExpression.toString
// res35: String = "[[1.0, 0.0, 0.0], [0.0, 2.0, 3.0], [0.0, 4.0, 5.0]]"
Parser.parse("kron(eye(2), [[1, 2]])").get.eval(env).toExpression.toString
// res36: String = "[[1.0, 2.0, 0.0, 0.0], [0.0, 0.0, 1.0, 2.0]]"

submatrix(A, r0, r1, c0, c1) slices rows r0..r1 and columns c0..c1, 1-based and inclusive — the convention at(A, i, j) uses, so the 1×1 slice submatrix(A, i, i, j, j) holds exactly at(A, i, j):

Parser.parse("submatrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]], 2, 3, 1, 2)").get.eval(env).toExpression.toString
// res37: String = "[[4.0, 5.0], [7.0, 8.0]]"

All of them rearrange cells through one shared assembly, so they work unchanged on numeric, exact and symbolic matrices. In hcat, vcat, blkdiag and kron a number counts as a 1×1 block; a name with no value yet is never guessed to be one, since it might later be bound to a matrix of any shape, so the call waits:

Parser.parse("hcat(1, [[2]])").get.eval(env).toExpression.toString
// res38: String = "[[1.0, 2.0]]"
Parser.parse("hcat(x, [[2]])").get.eval(env).toExpression.toString
// res39: String = "hcat(x, [[2.0]])"

Blocks that do not conform, and indices out of range or not whole, leave the call unevaluated; a result above a million cells is refused before anything is built.


This site uses Just the Docs, a documentation theme for Jekyll.