Error handling

Alkahest uses a structured exception hierarchy. Every error carries a stable diagnostic code, a human-readable message, an optional source span, and an optional remediation hint.

Exception hierarchy

AlkahestError (base)
├── ConversionError   (E-POLY-*)   — expression → polynomial/rational conversion
├── DomainError       (E-DOMAIN-*) — mathematical side conditions violated
├── DiffError         (E-DIFF-*)   — differentiation failed
├── IntegrationError  (E-INT-*)    — integration failed
├── MatrixError       (E-MAT-*)    — matrix shape / singularity / undecidable determinant
│   ├── LinearAlgebraError (E-LINALG-*) — elimination, decompositions, canonical forms
│   └── EigenError         (E-EIGEN-*)  — eigenvalues, eigenvectors, Jordan form
├── CadError          (E-CAD-*)    — real quantifier elimination, see [Positivity](./positivity.md#decide-refuses-rather-than-guessing)
├── OdeError          (E-ODE-*)    — every ODE engine: construction, dsolve, dsolve_system, series_solve, numeric
├── TransformError    (E-TRANSFORM-*) — Laplace / Fourier / Z transforms and their inverses
├── AsymptoticError   (E-ASYMPT-*) — asymptotic expansion at infinity
├── FpsError          (E-FPS-*)    — formal power series
├── DaeError          (E-DAE-*)    — DAE structural analysis
├── SolverError       (E-SOLVE-*)  — polynomial system solving
├── JitError          (E-JIT-*)    — LLVM/JIT codegen
├── CudaError         (E-CUDA-*)   — NVPTX compile, kernel launch, or driver, see [GPU support](./gpu.md)
├── PoolError         (E-POOL-*)   — ExprPool misuse
├── AnsatzError       (E-ANSATZ-*) — ansatz family construction or fitting, see [Ansatz families](./ansatz.md)
├── CrossCheckError   (E-XCHECK-*) — cross-CAS check could not be posed, see [Cross-CAS testing](./crosscheck.md)
├── SmtError          (E-SMT-*)    — SMT-LIB export, solver run, or model lift, see [SMT bridge](./smt.md)
├── VectorError       (E-VEC-*)    — vector calculus over an orthogonal chart, see below
├── QuaternionError   (E-QUAT-*)   — quaternion algebra and rotations, see below
├── UnitError         (E-UNIT-*)   — units and dimensional analysis, see [Units](./units.md)
├── ControlsError     (E-CTRL-*)   — transfer functions, state space, Lyapunov / Riccati, see [Controls](./controls.md)
├── SpecialFunctionError (E-SPECFN-*) — orthogonal polynomials, Y_lm, 3j/6j/Clebsch–Gordan, Bessel/zeta/polylog, see [Orthogonal polynomials](./orthopoly.md) and [Bessel, Airy, zeta](./specfun.md)
├── NcError           (E-NC-*)     — noncommutative algebra, see [Noncommutative algebra](./noncommutative.md)
├── ProbabilityError  (E-PROB-*)   — distributions, expectations, generating functions, entropy, see below
├── GroupError        (E-GRP-*)    — permutation groups: orbits, Schreier–Sims, membership
├── FunctionFieldError (E-FFLD-*) — divisors, Pic⁰ and Riemann–Roch on algebraic curves, see below
├── ThetaError        (E-THETA-*)  — Riemann theta, modular and Weierstrass functions as rigorous enclosures
└── BudgetExceededError (E-BUDGET-*) — budget/cancellation trip, see [Budgets](./budgets.md)

Error attributes

Every exception instance exposes:

There is no .message. The human-readable description is str(e), which carries the code, the message and the remediation on separate lines; e.args[0] is the same string. Branch on .code, print str(e).

import alkahest
from alkahest import ExprPool, UniPoly, ConversionError

pool = ExprPool()
x = pool.symbol("x")

try:
    # sin(x) cannot be represented as a polynomial
    p = UniPoly.from_symbolic(alkahest.sin(x), x)
except ConversionError as e:
    print(e.code)          # E-POLY-006
    print(str(e))          # "[E-POLY-006] function 'sin' cannot appear in a polynomial
                           #  Remediation: not a polynomial; wrap in the function only
                           #  after rational reduction"
    print(e.remediation)   # "not a polynomial; wrap in the function only after
                           #  rational reduction"

Common errors and remediations

ConversionError (E-POLY-*)

Raised when an expression cannot be converted to a polynomial or rational function.

DomainError (E-DOMAIN-*)

Raised when a mathematical side condition is violated.

IntegrationError (E-INT-*)

SolverError (E-SOLVE-*)

PslqError (E-PSLQ-*)

Raised by alkahest.guess_relation, the augmented-lattice integer-relation heuristic, and reported without an exception by alkahest.relation_confidence.

E-PSLQ-004 and E-PSLQ-005 are raised from Python (alkahest.guess_relation), so they are not in the Rust REGISTRY; both are subclasses of PslqError and are caught by except alkahest.PslqError. The two are deliberately distinct: 004 is a statement about how much precision the inputs carry, 005 is a statement about the relation itself and does not depend on precision at all.

PrimaryDecompositionError (E-IDEAL-*)

Refusals: when Alkahest declines to answer

A refusal is not a malfunction. These codes all mean “I could not establish this, and the alternative to saying so is a confident wrong answer” — the outcome an unattended loop must record as undecided, never as a negative result.

E-SERIES-003 and E-SERIES-004 travel out of band for the same reason (SeriesError is exhaustive) but are wired into the bindings: series returns SeriesError::InvalidOrder with calculus::series::take_series_refusal() pending, and the Python layer raises SeriesError with .code == "E-SERIES-003" / "E-SERIES-004" — or BudgetExceededError when a budget was what stopped it. SeriesRefusal::cause() distinguishes the two in Rust.

E-SERIES-005 and E-SERIES-006 come from a different type — calculus::puiseux::PuiseuxError, which is #[non_exhaustive] from birth and so needs no out-of-band channel — but they raise the same Python SeriesError, because puiseux_series is the series engine widened rather than a new subsystem, and except SeriesError should keep covering both entry points. A budget trip inside puiseux_series raises BudgetExceededError, not E-SERIES-003: “raise your budget” and “this expansion does not close” are different problems.

A removable singularity is not in that list, because it is no longer refused: series puts the expression over a common denominator and divides the two power series rather than substituting the expansion point into a quotient, so sin(x)/x gives 1 − x²/6 + O(x⁴) and 1/sin(x) gives x⁻¹ + x/6 + O(x). E-SERIES-004 is what is left when that does not apply.

E-EIGEN-008 travels out of band on the same arrangement: EigenError and LinearAlgebraError are exhaustive, so the refusal is returned inside UnsupportedIrreducibleDegree — whose text now states the disjunction it covers — with matrix::take_spectrum_refusal() pending, and the Python bindings raise EigenError / LinearAlgebraError carrying .code == "E-EIGEN-008" and the offending λ list.

E-IDEAL-005, E-IDEAL-006 and E-SOLVE-004 are new in 3.8 and travel out of band: PrimaryDecompositionError and SolverError are public exhaustive enums that cannot gain a variant in a patch release, so the refusal is returned inside an existing variant and the real code is available from ideal::take_ideal_refusal() / solver::regular_chains::take_triangularize_refusal(). The Python bindings consult both, so radical and primary_decomposition raise AlkahestError with .code == "E-IDEAL-005" / "E-IDEAL-006", and triangularize raises SolverError with .code == "E-SOLVE-004". AlkahestError subclasses ValueError, so code that catches ValueError is unaffected.

E-SOLVE-005 uses the same channel for the same reason: solve returns SolverError::NotPolynomial with solver::take_undefined_equation() pending, and the Python binding raises SolverError with .code == "E-SOLVE-005". It means the equation’s denominator vanishes identically, so it is not a rational function of anything and there is no solution set to report — distinct from E-SOLVE-001, which means the equation is a perfectly good function that is merely not polynomial or rational in the declared unknowns.

The takers are consuming, which is what keeps the carrier variant honest: a genuinely non-polynomial equation still reports E-SOLVE-001, because no refusal is pending for it. Both readings of the shared variant stay distinguishable.

The three-valued zero test behind E-LINALG-010 / E-MAT-004 is new in 3.8. Before it, “could not prove det ≠ 0” was silently read as “det = 0”, and Matrix.nullspace() returned a confident wrong basis for any 2×2 with a symbolic determinant.

import alkahest as ak

pool = ak.ExprPool()
a = pool.symbol("a")
zero, one = pool.integer(0), pool.integer(1)

# `mystery` has no evaluation rule, so its vanishing is genuinely undecidable.
opaque = pool.func("mystery", [a])
m = ak.Matrix([[opaque, zero], [zero, one]])

try:
    m.inverse()
except ak.MatrixError as e:
    print(e.code)          # E-MAT-004
    print(e.remediation)   # substitute concrete values for the parameters

try:
    ak.Matrix([[opaque, zero], [zero, zero]]).nullspace()
except ak.LinearAlgebraError as e:
    print(e.code)          # E-LINALG-010

LinearAlgebraError and EigenError are both subclasses of MatrixError, so except ak.MatrixError catches all three families; catch the subclass when you want to distinguish them. Note that eigenvects() raises EigenError — with code E-LINALG-010, because the code identifies what could not be decided, not which wrapper it surfaced through.

Catching errors by code

For programmatic error handling:

try:
    result = alkahest.integrate(expr, x)
except alkahest.AlkahestError as e:
    if e.code.startswith("E-INT-"):
        print(f"Integration failed: {e.remediation}")
    else:
        raise

Error taxonomy

Every error is classified on two independent axes: subsystem (determines the code prefix and exception class) and cause (informs the remediation hint).

Subsystem axis

Some registry codes are Rust-side only and have no Python entry point that raises them today: E-LOGIC-001 (LogicError), E-NFM-* (NormalFormError), E-DIFFALG-* (DiffAlgError) and E-HOLO-060…064 (DiffTelescopingError). E-EVAL-* has no class of its own — the bindings surface it as DomainError, E-EVAL-009 being “undefined at this point”, which is a verdict. E-POLY-008 … E-POLY-010 belong to FactorError rather than ConversionError, which shares the prefix.

scripts/check_error_codes.py checks that this table names every prefix in the Rust REGISTRY, so a new subsystem cannot land undocumented.

Transforms: a table gap is not a refuted hypothesis

E-TRANSFORM-* covers three tables under one prefix and one class — Laplace (00x), Fourier (01x), Z (10x) — the way E-ODE-* covers five ODE engines under OdeError. The number says which table and which failure; a caller who wants only one of them filters on the code.

The split that matters is not between the tables but inside each of them:

“Not in the table yet” and “no such transform exists” are opposite instructions. The first says rewrite the input or wait for a wider table; the second says stop looking. Before 3.10 all of these arrived as a bare ValueError with no .code at all, so telling them apart meant matching English prose.

A symbolic parameter is reported as neither. θ(t−a) with a symbolic a cannot be decided, so the hypothesis a ≥ 0 is recorded rather than assumed or refused. It is not a field on the returned value — these functions return a bare Expr, and there is nowhere in band to hang a hypothesis — so read it from the thread-local experimental.transform_side_conditions(), which describes the most recent laplace_transform, inverse_laplace_transform, fourier_transform, inverse_fourier_transform or inverse_z_transform on this thread whether it returned or raised:

import alkahest as ak
from alkahest import experimental as ex

pool = ak.ExprPool()
t, s = pool.symbol("t"), pool.symbol("s")

# A literal negative edge: refuted, and nothing to find.
theta = pool.func("heaviside", [t + pool.integer(1)])
try:
    ex.laplace_transform(theta, t, s)
except ak.TransformError as e:
    print(e.code)          # E-TRANSFORM-004
    print(e.remediation)   # "the unilateral transform integrates over t ≥ 0 only, ..."

# The control: shift it the other way and the rule applies.
ex.laplace_transform(pool.func("heaviside", [t - pool.integer(1)]), t, s)

# Undecidable: answered, with the hypothesis stated out of band.
a = pool.symbol("a")
ex.laplace_transform(pool.func("heaviside", [t - a]), t, s)   # e^{-a·s}/s
print(ex.transform_side_conditions())                          # ['a ∈ NonNegative']

An empty list means every branch taken was forced by the input, not that none was taken.

Probability: four ways not to answer

E-PROB-* is one prefix over one class, and the six numbers exist because “there is no closed form”, “this integrator could not find one”, “the quantity does not exist” and “one was found and is not trustworthy” call for four different next steps. Collapsing them would send a caller looking for a better integrator when the integral diverges.

Two of these are the reason the surface exists at all. moment_generating_function for a LogNormal raises E-PROB-006: E[e^{tX}] is +inf for every t > 0, and a CAS that completes the square anyway hands back a clean closed form that is the value of no integral. And M_X(t) = lambda/(lambda − t) for an Exponential holds only on t < lambda — outside that strip the expression is still finite, still plausible and still wrong — so a decidable argument outside the strip raises E-PROB-006 and an undecidable one publishes the condition on experimental.prob_side_conditions().

import alkahest as ak
from alkahest import experimental as ex

pool = ak.ExprPool()
t, lam = pool.symbol("t"), pool.symbol("lam")

ex.Exponential(lam).moment_generating_function(t)   # lam/(lam - t)
print(ex.prob_side_conditions())
# the convergence strip and the parameter constraint: ['lam - t > 0', 'lam > 0']

try:
    ex.LogNormal(pool.integer(0), pool.integer(1)).moment_generating_function(t)
except ak.ProbabilityError as e:
    print(e.code)        # E-PROB-006

prob_side_conditions() is the same out-of-band channel as transform_side_conditions(), for the same reason: the return value is an Expr, so a conditional answer and a theorem look identical at the call site unless the hypotheses are published somewhere. A law whose MGF is entire leaves the list empty — so empty means checked, not unexamined.

Vector calculus and quaternions

alkahest.experimental’s rigid-body layer refuses in three places where a clean, plausible number is available, and that is the point of each of them.

The vector Laplacian is a fourth trap without an error code, because there is a right answer: experimental.vector_laplacian is ∇(∇·F) − ∇×(∇×F), which equals the componentwise scalar Laplacian in Cartesian coordinates only. Applying experimental.laplacian to each physical component of a cylindrical or spherical field silently drops the terms that come from the basis turning — ∇²(φ̂) is −φ̂/ρ², not 0.

E-RESIDUE-005 is raised only at the Python boundary — the Rust residue takes an already-parsed point and cannot reach that state — so it is deliberately absent from alkahest-core’s REGISTRY, on the same footing as E-SMT-001/003/004 in alkahest/smt.py and E-BATCH-001 in alkahest/_batch.py. It exists because residue(f, z, a) with a symbolic a reads perfectly well and used to escape as a bare AttributeError naming an attribute of the implementation, which is not an AlkahestError and so was invisible to except ak.AlkahestError.

Three of these describe outcomes that are results rather than malfunctions, and the wording of each is deliberate. E-ANSATZ-003 means no member of this family satisfies the constraints — for a search loop that is a closed branch worth recording, not a failure. E-XCHECK-002 means no oracle is installed, and exists so that a missing oracle can never be mistaken for agreement. E-SMT-003 refuses a model containing an algebraic number that cannot be lifted exactly, rather than truncating it to a float — a float witness recorded as an exact one is precisely the silent-error shape these subsystems exist to prevent.

E-CERT-* — certificate policy

This one is unusual: the computation succeeded. What is missing is the machine-checkable evidence, so it is a policy failure rather than a mathematical one. It is raised only when you ask for it, by alkahest.require_certificate(result), by alkahest.to_lean(result) (which never returns an empty string), or ambiently inside with alkahest.context(require_certificate=True):. The remediation names the blocking rewrite rules where they can be identified.

import alkahest as ak

p = ak.ExprPool()
x = p.symbol("x")

with ak.context(require_certificate=True):
    ak.diff(ak.sin(x), x)              # fine — certifies
    ak.diff(ak.log(ak.sin(x)), x)      # raises E-CERT-001

Cause axis

1. User-input — the expression or argument is outside the supported fragment. Always has a remediation; carries a span once parsing lands.
2. Domain — input is syntactically fine but violates a mathematical side condition. Remediation is “substitute a different value,” not “reformulate.”
3. Unsupported — the operation is not implemented for this case. Must name the missing capability so users can file a feature request.
4. Resource/environment — CUDA device absent, out-of-memory, JIT target mismatch, pool closed. Typically no span; remediation references the environment, not the expression.
5. Internal invariant — a bug. Should never reach users in release; in debug it carries a backtrace. Use E-INTERNAL-001.

Adding a new error code

1. Does it fit an existing subsystem? Add a variant and a code one higher than the current max for that prefix.
2. Does it name a new subsystem? Add a prefix, a class, and an entry in REGISTRY in the same PR. Do not reuse prefixes across unrelated subsystems. 2b. One code, one meaning. Two AlkahestError impls under the same prefix must not return the same number. REGISTRY’s no_duplicate_codes test cannot catch this — it only sees the registry, and the colliding impl is typically the one that never got registered. scripts/check_error_codes.py compares the impls themselves and fails on any code claimed by two of them; a genuine alias (the same fact reported by two types that share a Python class) goes in its DELIBERATE_ALIASES with the reason.
3. Write the remediation before the message — if you cannot say what the user should do, the taxonomy is telling you this is an internal bug, not a user error.

Users match on subsystem (the exception class); triagers filter on cause (the code suffix and remediation text).

Function fields: what is modelled

Stabilizer codes: the (x | z) convention

E-STAB-* has thirteen numbers and only one of them is about running out of room. The rest exist because the commonest failure in this area is not a resource limit — it is a set of generators that looks like a stabilizer code, type-checks like a stabilizer code, and is not one.

Everything in this layer writes a Pauli operator as 2n bits in (x | z) layout: the first n are the X exponents, the last n the Z exponents, with

    ⟨(x₁ | z₁), (x₂ | z₂)⟩  =  x₁·z₂ + z₁·x₂     (mod 2)

and two Paulis commuting exactly when that vanishes. The (z | x) layout is also in use in the literature. A check matrix transcribed from a paper that uses it produces generators that commute, have the right rank, and encode a different code — and no error at all. There is nothing this library can do about that except say so loudly, which is why the convention is repeated at the top of every module in the layer. If a code comes out with the right n and k and the wrong distance, suspect the layout before suspecting the search.

Three of the codes deserve to be read apart from the rest:

The last one is the reason minimum_distance() does not return an int. A Distance carries .value and .exact, and the upper-bound path sets .exact to False. A caller that stores .value in a field named d has thrown away the one fact that made the number safe to publish.

E-FFLD-* is one prefix over one class, and the eleven numbers exist because the honest answer to most function-field questions, in most of the space of possible inputs, is not this implementation.

The implemented class is

    K = ℚ(x)[y] / (y² − a(x)),    a squarefree,  deg a = 2g + 1 odd,

with divisors supported on ℚ-rational places — the degree-one points (α, β) with α, β ∈ ℚ, plus the single place at infinity. That is not a convenience boundary. The divisor class group here is Cantor arithmetic on Mumford pairs, reached through the code the algebraic integrator already uses (integrate::algebraic::jacobian_torsion, coates), and that code measures every class against one rational place at infinity. An even-degree (“real”) model has two, and n > 2 has no Mumford representation at all.

The last row is the one worth dwelling on. div(u) derives the multiplicity at infinity from deg div(u) = 0 and then checks it against v_∞(p + qy) = min(−2 deg p, −deg a − 2 deg q), which is exact on the odd-degree model because the two candidates differ in parity. Riemann–Roch checks its dimension against dim ≥ deg D + 1 − g and, above the canonical degree, against the equality. Neither check can fire on valid input; both exist so that a wrong answer arrives as E-FFLD-011 rather than as a divisor.

Certified coding bounds

delsarte_lp_bound(n, d, q) returns an upper bound on A_q(n, d) — the largest possible size of any code (linear or not) of length n over an alphabet of size q with minimum distance at least d. Every step is exact rational arithmetic, but exactness alone is not what makes the number trustworthy: a solver that stopped early would report a bound that is too small, and a bound that is too small silently rules out codes that exist.

So the number is read off the dual programme and comes with the multipliers that prove it. DelsarteBound.certificate() is a vector y ≥ 0 satisfying Σ_k y_k K_k(i) ≤ −1 for every i in d..=n; from that alone, with no reference to this implementation, |C| ≤ 1 + Σ_k y_k K_k(0) for every such code. DelsarteBound.verify_certificate() re-checks it from scratch, and the constructor refuses with E-CODE-007 rather than returning a bound whose certificate did not pass. A caller who does not trust this crate can re-verify the certificate with nothing but a Krawtchouk evaluator.

This is the plain Delsarte programme. Schrijver’s semidefinite strengthening and the extra inequalities that beat it on specific (n, d) are not implemented: what is returned is always a valid upper bound, not always the tightest one known.