# Equation operators > Differential and symbolic operators available inside equation blocks. > Generated by `sema doc` from the compiler's authoritative native-signature registry. # equation operators Differential operators available inside `equation:` blocks (LANGUAGE §5.28) — not `math.` members. # rounding ## `floor(value) -> int | rational | float | list | tuple | Tensor | Sym | Approx` Greatest-integer rounding, applied recursively to numeric containers. - domain: finite exact/float scalars, symbolic expressions, same-evaluation Approx evidence, recursively numeric list/tuple, rank-1/rank-2 dense-real Tensor, or Embedding coerced to rank-1 Tensor; at most 1,000,000 visited values and nesting depth 128; rank-0/higher-rank tensors, non-finite lanes, and non-numeric containers fail typed - shape: elementwise - returns: `int | rational | float | list | tuple | Tensor | Sym | Approx` - example: `floor(7 / 2)` ## `ceil(value) -> int | rational | float | list | tuple | Tensor | Sym | Approx` Least-integer rounding, applied recursively to numeric containers. - domain: finite exact/float scalars, symbolic expressions, same-evaluation Approx evidence, recursively numeric list/tuple, rank-1/rank-2 dense-real Tensor, or Embedding coerced to rank-1 Tensor; at most 1,000,000 visited values and nesting depth 128; rank-0/higher-rank tensors, non-finite lanes, and non-numeric containers fail typed - shape: elementwise - returns: `int | rational | float | list | tuple | Tensor | Sym | Approx` - example: `ceil(-7 / 2)` ## `round(value) -> int | rational | float | list | tuple | Tensor | Sym | Approx` Nearest-integer round-half-to-even, applied recursively to numeric containers. - domain: finite exact/float scalars, symbolic expressions, same-evaluation Approx evidence, recursively numeric list/tuple, rank-1/rank-2 dense-real Tensor, or Embedding coerced to rank-1 Tensor; at most 1,000,000 visited values and nesting depth 128; rank-0/higher-rank tensors, non-finite lanes, and non-numeric containers fail typed - shape: elementwise - returns: `int | rational | float | list | tuple | Tensor | Sym | Approx` - example: `round(5 / 2)` ## `trunc(value) -> int | rational | float | list | tuple | Tensor | Sym | Approx` Round toward zero, applied recursively to numeric containers. - domain: finite exact/float scalars, symbolic expressions, same-evaluation Approx evidence, recursively numeric list/tuple, rank-1/rank-2 dense-real Tensor, or Embedding coerced to rank-1 Tensor; at most 1,000,000 visited values and nesting depth 128; rank-0/higher-rank tensors, non-finite lanes, and non-numeric containers fail typed - shape: elementwise - returns: `int | rational | float | list | tuple | Tensor | Sym | Approx` - example: `trunc(-7 / 2)` ## `fract(value) -> int | rational | float | list | tuple | Tensor | Sym | Approx` Signed fractional part x - trunc(x), applied recursively to numeric containers. - domain: finite exact/float scalars, symbolic expressions, same-evaluation Approx evidence, recursively numeric list/tuple, rank-1/rank-2 dense-real Tensor, or Embedding coerced to rank-1 Tensor; at most 1,000,000 visited values and nesting depth 128; rank-0/higher-rank tensors, non-finite lanes, and non-numeric containers fail typed - shape: elementwise - returns: `int | rational | float | list | tuple | Tensor | Sym | Approx` - example: `fract(-7 / 2)` # symbolic ## `cancel(expression) -> tuple[Sym, list[Sym]]` Condition-aware cancellation returning the simplified expression and every required real-domain condition. - domain: bounded real symbolic expressions with explicit representable side conditions - shape: symbolic - returns: `tuple[Sym, list[Sym]]` - example: `cancel("x" / "x")` ## `integrate(expression, variable, lower?, upper?) -> tuple[Sym, list[Sym]]` Exact conditional antiderivative, or exact definite integral when lower and upper bounds are provided. - domain: bounded exact rational-power fragment; optional exact bounds must satisfy every side condition - shape: symbolic - returns: `tuple[Sym, list[Sym]]` - example: `integrate("x"^2, "x")` ## `limit(expression, variable, point, side?) -> tuple[Sym, list[Sym]]` Exact rational-function limit with explicit one-sided pole behavior, source-domain conditions, and typed unknown/unsupported results. - domain: bounded exact univariate rational function at an exact finite point; side is both, left, or right - shape: symbolic - returns: `tuple[Sym, list[Sym]]` - example: `limit(("x"^2 - 1) / ("x" - 1), "x", 1)` ## `series(expression, variable, point, order) -> tuple[Sym, list[Sym]]` Exact Taylor polynomial through the requested order with source-domain conditions; the omitted remainder is O((x-point)^(order+1)). - domain: bounded exact univariate rational Taylor series at an exact finite point, order 0..=12; Laurent poles unsupported - shape: symbolic - returns: `tuple[Sym, list[Sym]]` - example: `series(1 / (1 - "x"), "x", 0, 3)` # number_theory ## `is_prime(value) -> bool` Deterministic bounded primality predicate; larger integers return typed NotImplemented. - domain: exact non-negative integer through 2^32-1; deterministic bounded trial division - shape: scalar - returns: `bool` - example: `is_prime(104729)` ## `factorint(value) -> list[tuple[int, int]]` Exact prime factorization as sorted (prime, exponent) pairs; zero and negatives fail typed. - domain: exact positive integer through 2^32-1; deterministic bounded trial division - shape: constructor - returns: `list[tuple[int, int]]` - example: `factorint(360)` ## `next_prime(value) -> int` Least prime strictly greater than value under a bounded deterministic candidate search. - domain: exact non-negative integer through 2^32-1; result must remain inside the bounded profile - shape: scalar - returns: `int` - example: `next_prime(100)` ## `prev_prime(value) -> int` Greatest prime strictly less than value; integers <= 2 fail with DomainError. - domain: exact integer in 3..=2^32-1; deterministic bounded candidate search - shape: scalar - returns: `int` - example: `prev_prime(100)` ## `totient(value) -> int` Exact Euler totient; zero, negatives, and integers above the bounded profile fail typed. - domain: exact positive integer through 2^32-1; deterministic bounded factorization - shape: scalar - returns: `int` - example: `totient(36)` ## `divisors(value) -> list[int]` All positive divisors in strictly increasing canonical order. - domain: exact positive integer through 2^32-1; deterministic bounded factorization - shape: constructor - returns: `list[int]` - example: `divisors(36)` ## `divisor_count(value) -> int` Exact count of positive divisors from the canonical prime factorization. - domain: exact positive integer through 2^32-1; deterministic bounded factorization - shape: scalar - returns: `int` - example: `divisor_count(360)` ## `mobius(value) -> int` Exact Möbius function in {-1, 0, 1}; repeated prime factors map to zero. - domain: exact positive integer through 2^32-1; deterministic bounded factorization - shape: scalar - returns: `int` - example: `mobius(30)` ## `mod_inverse(value, modulus) -> int` Canonical modular inverse in 0..modulus via bounded extended Euclid. - domain: exact integers under the 16,384-bit ceiling, modulus >= 2, and gcd(value, modulus) = 1 - shape: scalar - returns: `int` - example: `mod_inverse(-3, 11)` ## `crt(moduli, residues) -> tuple[int, int]` Generalized Chinese remainder merge returning the least nonnegative solution and LCM modulus; consistent non-coprime systems are supported. - domain: equal-length exact integer lists with 0..=256 positive moduli and a consistent generalized CRT system; combined modulus <= 16,384 bits - shape: constructor - returns: `tuple[int, int]` - example: `crt([3, 5, 7], [2, 3, 2])` ## `chinese_remainder(moduli, residues) -> tuple[int, int]` Alias of crt, returning the canonical solution and combined modulus. - domain: equal-length exact integer lists with 0..=256 positive moduli and a consistent generalized CRT system; combined modulus <= 16,384 bits - shape: constructor - returns: `tuple[int, int]` - example: `chinese_remainder([6, 8], [4, 4])` ## `prime_nth(index) -> int` The index-th prime, 1-indexed (prime_nth(1) = 2), from a preflighted deterministic sieve. - domain: exact integer index in 1..=100,000; deterministic bounded sieve - shape: scalar - returns: `int` - example: `prime_nth(25)` ## `prime(index) -> int` Alias of prime_nth. - domain: exact integer index in 1..=100,000; deterministic bounded sieve - shape: scalar - returns: `int` - example: `prime(25)` ## `prime_count(value) -> int` Exact prime-counting function pi(value) over the bounded sieve profile. - domain: exact non-negative integer through 2,000,000; deterministic bounded sieve - shape: scalar - returns: `int` - example: `prime_count(100)` ## `primepi(value) -> int` Alias of prime_count. - domain: exact non-negative integer through 2,000,000; deterministic bounded sieve - shape: scalar - returns: `int` - example: `primepi(541)` # interpolation ## `interpolate(xs, ys, x) -> int | rational | float` Evaluate the unique degree <= n-1 interpolating polynomial (Newton form) at the query point; duplicate knots and non-finite values fail typed. - domain: 1..=64 distinct knots with equal-length values and a scalar query; all-exact inputs stay exact under the 16,384-bit ceiling, any float input evaluates in strict finite f64 - shape: reduction - returns: `int | rational | float` - example: `interpolate([0, 1, 2], [1, 3, 7], 4)` ## `polynomial_interpolate(xs, ys) -> list[int | rational | float]` Ascending monomial coefficients (exactly one per sample point) of the unique interpolating polynomial; entry i multiplies x^i and trailing zeros are kept. - domain: 1..=64 distinct knots with equal-length values; all-exact inputs stay exact under the 16,384-bit ceiling, any float input evaluates in strict finite f64 - shape: constructor - returns: `list[int | rational | float]` - example: `polynomial_interpolate([0, 1, 2], [1, 3, 7])` # formal ## `prove_bezout(left, right) -> ProofResult` Produce and independently replay an exact ZZ certificate that left*x + right*y equals the canonical nonnegative gcd. Results expose typed certificate_data and a domain-separated SHA-256 proof_ref while retaining legacy certificate text and legacy_proof_ref for migration; unsupported bounds return Unknown. - domain: exact integers of at most 4,096 bits; producer and independent checker each allow at most 10,000 Euclidean steps - shape: constructor - returns: `ProofResult` - example: `prove_bezout(-240, 46)` ## `verify_bezout(left, right, gcd, left_coefficient, right_coefficient) -> ProofResult` Independently replay caller-supplied certificate fields; corruption and resource bounds return Unknown and can never forge an accepted proof. - domain: caller-supplied v1/ZZ Bézout fields, each at most 4,096 bits; independent checker allows at most 10,000 Euclidean steps - shape: constructor - returns: `ProofResult` - example: `verify_bezout(-240, 46, 2, 9, 47)` # statistics ## `expectation(values) -> float` Empirical expectation, identical to the bounded population mean. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `expectation([1.0, 2.0, 3.0])` ## `E(values) -> float` Alias of expectation. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `E([1.0, 2.0, 3.0])` ## `mean(values) -> float` Population mean using scaled compensated accumulation. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `mean([1.0, 2.0, 3.0])` ## `variance(values) -> float` Population variance with ddof=0 using a two-pass scaled centered moment. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `variance([1.0, 2.0, 3.0])` ## `Var(values) -> float` Alias of population variance. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `Var([1.0, 2.0, 3.0])` ## `std(values) -> float` Population standard deviation with ddof=0. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `std([1.0, 2.0, 3.0])` ## `covariance(left, right) -> float` Population covariance with ddof=0 over equal-length samples. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `covariance([1.0, 2.0], [2.0, 4.0])` ## `Cov(left, right) -> float` Alias of population covariance. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `Cov([1.0, 2.0], [2.0, 4.0])` ## `correlation(left, right) -> float` Pearson population correlation; zero-variance samples fail typed. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `correlation([1.0, 2.0], [2.0, 4.0])` ## `Corr(left, right) -> float` Alias of Pearson population correlation. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `Corr([1.0, 2.0], [2.0, 4.0])` ## `entropy(values) -> float` Shannon entropy in nats over a strict probability simplex. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `entropy([0.25, 0.75])` ## `H(values) -> float` Alias of Shannon entropy in nats. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `H([0.25, 0.75])` ## `cross_entropy(left, right) -> float` Cross entropy in nats under a strict finite-result simplex contract. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `cross_entropy([0.25, 0.75], [0.5, 0.5])` ## `kl_divergence(left, right) -> float` Kullback-Leibler divergence in nats under a strict finite-result simplex contract. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `kl_divergence([0.25, 0.75], [0.5, 0.5])` ## `D_KL(left, right) -> float` Alias of Kullback-Leibler divergence in nats. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `D_KL([0.25, 0.75], [0.5, 0.5])` ## `js_divergence(left, right) -> float` Symmetric Jensen-Shannon divergence in nats. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `js_divergence([0.25, 0.75], [0.5, 0.5])` ## `JS(left, right) -> float` Alias of Jensen-Shannon divergence in nats. - domain: 1..=1,000,000 finite real values in flat lists, tuples, or rank-1 vectors; population statistics use ddof=0; information statistics require strict simplexes and return nats - shape: reduction - returns: `float` - example: `JS([0.25, 0.75], [0.5, 0.5])` # transforms ## `convolution(left, right) -> Vec` Deterministic rank-1 full linear convolution with compensated accumulation and typed resource/nonfinite failures. - domain: two non-empty finite real lists, tuples, or rank-1 vectors whose full output has at most 1,000,000 elements and direct work at most 10,000,000 multiply-adds - shape: contraction - returns: `Vec` - example: `convolve([1.0, 2.0], [3.0, 4.0])` ## `convolve(left, right) -> Vec` Deterministic rank-1 full linear convolution with compensated accumulation and typed resource/nonfinite failures. - domain: two non-empty finite real lists, tuples, or rank-1 vectors whose full output has at most 1,000,000 elements and direct work at most 10,000,000 multiply-adds - shape: contraction - returns: `Vec` - example: `convolve([1.0, 2.0], [3.0, 4.0])` ## `cross_correlation(left, right) -> Vec` Deterministic rank-1 full cross-correlation in ascending lag order with compensated accumulation and typed resource/nonfinite failures. - domain: two non-empty finite real lists, tuples, or rank-1 vectors whose full lag output has at most 1,000,000 elements and direct work at most 10,000,000 multiply-adds - shape: contraction - returns: `Vec` - example: `correlate([1.0, 2.0, 3.0], [4.0, 5.0])` ## `correlate(left, right) -> Vec` Deterministic rank-1 full cross-correlation in ascending lag order with compensated accumulation and typed resource/nonfinite failures. - domain: two non-empty finite real lists, tuples, or rank-1 vectors whose full lag output has at most 1,000,000 elements and direct work at most 10,000,000 multiply-adds - shape: contraction - returns: `Vec` - example: `correlate([1.0, 2.0, 3.0], [4.0, 5.0])` # distributions ## `normal_pdf(x, loc, scale) -> float` Normal probability density; finite tail underflow returns canonical +0.0. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_pdf(1.0, 0.0, 1.0)` ## `normal_logpdf(x, loc, scale) -> float` Normal log-density computed directly without taking the logarithm of an underflowed density. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_logpdf(1.0, 0.0, 1.0)` ## `normal_cdf(x, loc, scale) -> float` Normal cumulative distribution with stable finite-tail evaluation and closed [0, 1] saturation. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_cdf(1.0, 0.0, 1.0)` ## `normal_sf(x, loc, scale) -> float` Normal survival function evaluated directly rather than as 1 - cdf, preserving upper-tail precision. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_sf(1.0, 0.0, 1.0)` ## `normal_logcdf(x, loc, scale) -> float` Normal log-CDF evaluated directly with stable lower-tail precision. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_logcdf(1.0, 0.0, 1.0)` ## `normal_logsf(x, loc, scale) -> float` Normal log-survival evaluated directly with stable upper-tail precision. - domain: finite real x and loc with finite scale > 0; scalar only; pdf may underflow to +0.0, cdf/sf may saturate within [0, 1], and unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_logsf(1.0, 0.0, 1.0)` ## `normal_ppf(p, loc, scale) -> float` Normal quantile for a strict interior probability, with location and scale transformation. - domain: finite real p, loc, and scale with 0 < p < 1 and scale > 0; scalar only; unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_ppf(0.975, 0.0, 1.0)` ## `normal_logppf(log_p, loc, scale) -> float` Normal quantile from a strict negative log-probability, preserving underflowed and near-one probabilities. - domain: finite real log_p, loc, and scale with log_p < 0 and scale > 0; scalar only; unrepresentable results fail typed - shape: scalar - returns: `float` - example: `normal_logppf(-800.0, 0.0, 1.0)` # numerics ## `ode_rk45(rhs, t0, y0, t1, rtol, atol, max_steps) -> tuple[Approx[Vec], int, int]` Dormand-Prince 5(4) integration returning (Approx(final_state), accepted_steps, rejected_steps); stiffness, events, dense output, DAE, and PDE are unsupported. - domain: finite dense real state of dimension 1..=256, finite rtol > 0, atol >= 0, and max_steps in 1..=1,000,000; explicit non-stiff systems only - shape: time evolution - returns: `tuple[Approx[Vec], int, int]` - example: `ode_rk45(ode_rhs, 0.0, [1.0], 1.0, 1e-9, 1e-12, 10000)` # optimization ## `linear_program(objective, coefficients, rhs, max_iterations?) -> LinearProgramResult` Deterministic two-phase dense-real simplex with Bland pivots; returns Optimal, Infeasible, Unbounded, IterationLimit, or NumericalFailure plus optional incumbent and primal residual. - domain: finite dense real standard form max c·x subject to A x <= b and x >= 0; 1..=64 variables, 1..=128 constraints, bounded tableau and 1..=100,000 iterations - shape: optimization - returns: `LinearProgramResult` - example: `linear_program([3.0, 2.0], [[1.0, 1.0], [1.0, 0.0], [0.0, 1.0]], [4.0, 2.0, 3.0])` ## `lp(objective, coefficients, rhs, max_iterations?) -> LinearProgramResult` Alias of linear_program with identical status, residual, bounds, and deterministic two-phase simplex semantics. - domain: alias of linear_program over the same bounded finite dense-real standard form - shape: optimization - returns: `LinearProgramResult` - example: `lp([1.0], [[1.0]], [2.0])` # linalg ## `det(matrix) -> float` Determinant via checked partial-pivot LU; singular matrices return 0.0. - domain: finite non-empty square dense real matrix within the bounded LU work profile - shape: reduction - returns: `float` - example: `det([[1.0, 2.0], [3.0, 4.0]])` ## `solve(matrix, rhs) -> Vec[float | complex]` Solve A x = b with checked LU, conditioning, and residual validation; any complex operand promotes the real side exactly and returns a complex vector. - domain: finite non-singular square dense real or complex matrix and equal-length vector; complex operands use the checked complex LU with the shared residual gate - shape: contraction - returns: `Vec[float | complex]` - example: `solve([[2.0, 0.0], [0.0, 4.0]], [2.0, 8.0])` ## `inv(matrix) -> Matrix` Checked dense matrix inverse with condition and residual validation. - domain: finite non-singular square dense real matrix within the bounded LU work profile - shape: decomposition - returns: `Matrix` - example: `inv([[4.0, 7.0], [2.0, 6.0]])` ## `qr(matrix) -> tuple[Matrix, Matrix]` Checked Householder QR decomposition returning (Q, R). - domain: finite non-empty dense real matrix within the bounded Householder work profile - shape: decomposition - returns: `tuple[Matrix, Matrix]` - example: `qr([[1.0, 0.0], [0.0, 2.0]])` ## `svd(matrix) -> tuple[Matrix, Vec, Matrix]` Reduced singular-value decomposition returning (U, descending singular values, Vt) with reconstruction and orthogonality checks. - domain: finite nonempty rank-2 dense real matrix; reduced outputs and bounded scale-normalized one-sided Jacobi work - shape: decomposition - returns: `tuple[Matrix, Vec, Matrix]` - example: `svd([[3.0, 0.0], [0.0, 2.0]])` ## `pseudoinverse(matrix) -> Matrix` Moore-Penrose pseudoinverse derived from the checked reduced SVD with the public rank cutoff. - domain: finite nonempty rank-2 dense real matrix; SVD cutoff s_max * max(rows, cols) * f64::EPSILON; output shape cols x rows; bounded derived work - shape: decomposition - returns: `Matrix` - example: `pinv([[1.0, 0.0], [0.0, 2.0]])` ## `pinv(matrix) -> Matrix` Moore-Penrose pseudoinverse derived from the checked reduced SVD with the public rank cutoff. - domain: finite nonempty rank-2 dense real matrix; SVD cutoff s_max * max(rows, cols) * f64::EPSILON; output shape cols x rows; bounded derived work - shape: decomposition - returns: `Matrix` - example: `pinv([[1.0, 0.0], [0.0, 2.0]])` ## `least_squares(matrix, rhs) -> tuple[Vec, float, int, Vec]` Minimum-norm SVD least-squares result as (solution, residual norm, numerical rank, singular values), with a normal-equation self-check. - domain: finite nonempty rank-2 dense real matrix and finite right-hand side of length rows; same SVD cutoff as rank/pinv; bounded derived work - shape: decomposition - returns: `tuple[Vec, float, int, Vec]` - example: `lstsq([[1.0], [1.0]], [1.0, 2.0])` ## `lstsq(matrix, rhs) -> tuple[Vec, float, int, Vec]` Minimum-norm SVD least-squares result as (solution, residual norm, numerical rank, singular values), with a normal-equation self-check. - domain: finite nonempty rank-2 dense real matrix and finite right-hand side of length rows; same SVD cutoff as rank/pinv; bounded derived work - shape: decomposition - returns: `tuple[Vec, float, int, Vec]` - example: `lstsq([[1.0], [1.0]], [1.0, 2.0])` ## `condition_number(matrix) -> float` Spectral condition number from checked singular values; infinity explicitly represents numerical rank deficiency. - domain: finite nonempty rank-2 dense real matrix; spectral 2-norm condition using the public SVD cutoff; numerically rank-deficient matrices return infinity - shape: reduction - returns: `float` - example: `cond([[1.0, 0.0], [0.0, 2.0]])` ## `cond(matrix) -> float` Spectral condition number from checked singular values; infinity explicitly represents numerical rank deficiency. - domain: finite nonempty rank-2 dense real matrix; spectral 2-norm condition using the public SVD cutoff; numerically rank-deficient matrices return infinity - shape: reduction - returns: `float` - example: `cond([[1.0, 0.0], [0.0, 2.0]])` ## `rank(matrix) -> int` Scale-relative numerical matrix rank using the same singular values as svd. - domain: same finite nonempty reduced-SVD domain; threshold s_max * max(rows, cols) * f64::EPSILON - shape: reduction - returns: `int` - example: `rank([[1e-12]])` ## `eigh(matrix) -> tuple[Vec, Matrix]` Symmetric eigendecomposition with ascending eigenvalues and normalized eigenvectors. - domain: finite symmetric non-empty square dense real matrix within the bounded Jacobi profile - shape: decomposition - returns: `tuple[Vec, Matrix]` - example: `eigh([[2.0, 1.0], [1.0, 2.0]])` ## `matmul(a, b) -> Matrix[float | complex]` Strict matrix-matrix product over dense real or complex operands; the result dtype follows the operands. - domain: finite nonempty rank-2 dense real or complex matrices with agreeing inner dimensions; mixed operands promote the real side exactly; checked finite accumulation under exact element/work ceilings - shape: contraction - returns: `Matrix[float | complex]` - example: `matmul([[1.0, 2.0], [3.0, 4.0]], [[1.0, 0.0], [0.0, 1.0]])` ## `matvec(a, x) -> Vec[float | complex]` Strict matrix-vector product over dense real or complex operands; the result dtype follows the operands. - domain: finite nonempty rank-2 dense real or complex matrix and length-matching rank-1 vector; mixed operands promote the real side exactly; checked finite accumulation under exact work ceilings - shape: contraction - returns: `Vec[float | complex]` - example: `matvec([[1.0, 0.0], [0.0, 2.0]], [3.0, 4.0])` # sparse_linalg ## `sparse(rows, cols, row_indices, col_indices, values) -> SparseMatrix` Validated CSR construction from COO triplets; duplicates are a typed ShapeError, never silently summed. Exits equations as a tagged inspectable record. - domain: COO triplets over a nonempty shape: in-bounds indices, finite f64 values, no duplicate coordinates, and exact shape/nnz ceilings; canonicalized to sorted CSR - shape: constructor - returns: `SparseMatrix` - example: `sparse(2, 2, [0, 1], [0, 1], [1.0, 2.0])` ## `sparse.matmul(matrix, operand) -> Vec | Matrix` Sparse-dense product with checked finite accumulation: a vector operand yields a vector, a dense matrix operand a dense matrix. - domain: CSR matrix times a dense real vector or matrix under preflighted nnz-work and result-size ceilings; sparse or complex right operands are typed refusals - shape: contraction - returns: `Vec | Matrix` - example: `sparse.matmul(sparse(2, 2, [0, 1], [0, 1], [1.0, 2.0]), [3.0, 4.0])` ## `sparse.solve(matrix, rhs) -> Vec` Solve sparse A x = b via an explicitly bounded densification ceiling; never a silent dense fallback beyond it. - domain: square CSR system solved by documented bounded densification (rows*cols <= 16384) through the checked dense LU with its conditioning and residual gates; larger systems are a typed ResourceLimit - shape: contraction - returns: `Vec` - example: `sparse.solve(sparse(2, 2, [0, 1], [0, 1], [2.0, 4.0]), [2.0, 8.0])` # equation ## `jvp(target, tangent) -> float | Vec` Forward-mode Jacobian-vector product without materializing the Jacobian; variables are ordered lexicographically. - domain: scalar or flat vector target over >=1 sorted free real scalar variable; one-dimensional finite real tangent of exactly matching length (bounded forward work) - shape: differential - returns: `float | Vec` - example: `jvp([x^2, x * y], [1.0, -0.5])` ## `jacobian(target) -> Matrix` Jacobian matrix ∂f_i/∂x_j via forward-mode dual numbers. - domain: vector-valued expression over free scalar variables (bounded seed/work) - shape: differential - returns: `Matrix` - example: `jacobian([x^2, x * y])` ## `hessian(target) -> Matrix` Hessian matrix via central differences of the exact dual gradient. - domain: scalar expression with >= 1 free variable (bounded cubic work) - shape: differential - returns: `Matrix` - example: `hessian(x^2 + y^2)`