Alkahest

Alkahest is a high-performance computer algebra system built for both humans and agents. It is especially well suited for autoresearch agents doing work in pure and applied mathematics. Available as a Python package or a Rust crate.

[!IMPORTANT] Alkahest is in beta. The API is still moving, and — despite the verification machinery described below — it will contain bugs, including answers that are wrong without saying so. Treat a result that matters as unverified until you have checked it: read the derivation log, export the Lean certificate where one is available, or cross-check against an independent source. tests/silent_errors/ measures how often the library returns a confident wrong answer rather than refusing; that rate is not zero for inputs nobody has tried yet. Please report what you find.

The main stack is: Rust kernel → FLINT/Arb (polynomials, ball arithmetic) → egglog + colored e-graphs (simplification) → Cranelift/LLVM JIT + MLIR (native and GPU codegen) → PyO3 → Python

Highlights

• Verifiable by construction. Every computation produces a derivation log; a meaningful subset can export Lean 4 proofs for independent verification.
• 520× faster than SymPy on trig-identity simplification — and 77× faster than Mathematica on the same task (cross-CAS report).
• ~40× faster than SymPy on 2-variable quadratic systems, via FLINT-backed polynomial arithmetic and a compiled F4 core (solving guide).
• GPU codegen is a routine operation, not a research project — 16.2× over the CPU JIT on a 1M-point polynomial evaluation (NVPTX sm_86, RTX 3090). Requires a source build with --features cuda; the PyPI wheel has no GPU support (GPU guide).
• A trained RL environment. GRPO against the CAS verifier moved Qwen2.5-1.5B-Instruct from 11.7% → 15.1% on elementary integrals (+29% relative) with no stored reference answers — the CAS grades every rollout, including honest refusal on non-elementary integrands.
• Built for agent loops. String entry point (ak.parse), per-candidate Budgets, batched *_many fan-out, and compact JSON envelopes for cheap logging.
• No silent performance cliffs. Expr, UniPoly, MultiPoly, ArbBall and friends are explicit representations; conversion between them is always an opt-in call.

---

Install

Python 3.9–3.13:

pip install alkahest
pip install "alkahest[rl]"   # RL environments; Python >= 3.10

Rust users: alkahest-cas = "2" — see Rust crate.

Default wheels are batteries-included: e-graph simplification, the Gröbner solver (so alkahest.solve, Diophantine, and homotopy work out of the box), the pure-Rust Cranelift CPU JIT with no system LLVM required, and parallel — the Rayon-backed multi-core paths (numpy_eval_par, simplify_par, parallel F4 reduction, sharded ExprPool). They do not include the LLVM JIT; for that, use a PyTorch-style opt-in +jit / +full Linux wheel from GitHub Releases, not the default PyPI resolver path.

Install matrix (default vs opt-in wheels)

Probe your environment after install: alkahest.capabilities()["features"] and alkahest.jit_is_available().

Artifact	Where	OS / arch (CI)	Python	Cranelift JIT	LLVM JIT	parallel
Default (pip install alkahest)	PyPI	Linux manylinux x86_64; macOS arm64; Windows x86_64	3.9–3.13	yes	no	yes
+jit (X.Y.Z+jit)	GitHub Releases only	Linux x86_64	3.9–3.13	no	yes	yes
+full (X.Y.Z+full)	GitHub Releases only	Linux x86_64	3.9–3.13	yes	yes	yes

parallel ships in the default PyPI wheel on all three platforms, so numpy_eval_par and simplify_par really do use multiple cores out of the box. Its state is still worth checking rather than assuming, because it is the one feature whose absence is silent: those entry points exist in every build and fall back to numpy_eval / simplify — same correct answer, no speedup, no warning — if you are on a source build that did not enable it.

import alkahest as ak
ak.capabilities()["features"]["parallel"]   # True on wheels; source builds need --features parallel

macOS / Windows: default PyPI wheels include Cranelift JIT and parallel. +jit and +full are not built in CI (LLVM / MSYS2 constraints); use building from source with --features jit on those platforms if you need the LLVM backend.

Linux LLVM wheels vendor LLVM and related .so files under site-packages/alkahest.libs/. If import alkahest fails with a missing libffi-*.so or libLLVM-*.so, prepend that directory to LD_LIBRARY_PATH.

Opt-in Linux wheels: +jit and +full (PyTorch-style)

Why a separate index or direct wheel URL: feature-heavy wheels use a PEP 440 local version (for example 3.12.0+jit or 3.12.0+full). Those builds must not be mixed into the main PyPI project’s simple API for the same reason PyTorch publishes CUDA wheels on download.pytorch.org: otherwise pip install alkahest could resolve a +jit / +full build as “newer” than 3.12.0 and pull LLVM (or a much larger binary) when you wanted the default wheel.

There is no pip install alkahest[jit] / alkahest[full] that swaps the native extension: pip extras only add Python dependencies, not alternate binaries for the same wheel slot.

Until a dedicated PEP 503 simple index is published, tagged releases attach Linux linux_x86_64 wheels on GitHub Releases (CI builds them on ubuntu-22.04, not the manylinux image used for default wheels). Pick the .whl whose tags match your Python (cp311, etc.) and linux_x86_64.

Local version	Cargo features	When to use
(default PyPI)	egraph groebner cranelift parallel	Cranelift CPU JIT and multi-core paths on all published platforms; no system LLVM.
+jit	egraph groebner jit parallel	LLVM CPU JIT instead of Cranelift (Linux only in CI; larger than default).
+full	egraph groebner jit cranelift parallel	The only wheel carrying both JIT backends, and a strict superset of the default wheel. Pick it over +jit if you want LLVM and Cranelift in one build.

Direct-install examples (adjust tag and filename after checking the release assets):

pip install "https://github.com/alkahest-cas/alkahest/releases/download/v3.12.0/alkahest-3.12.0+full-cp311-cp311-manylinux_2_38_x86_64.whl"
pip install "https://github.com/alkahest-cas/alkahest/releases/download/v3.12.0/alkahest-3.12.0+jit-cp311-cp311-manylinux_2_38_x86_64.whl"

These wheels vendor LLVM (for JIT) and related .so files under site-packages/alkahest.libs/. If import alkahest fails with a missing libffi-*.so or libLLVM-*.so, prepend that directory to LD_LIBRARY_PATH (or install matching system packages). Release CI uses the same LD_LIBRARY_PATH step when smoke-testing wheels.

If your client chokes on + in the URL, use percent-encoding (3.12.0%2Bfull in the filename segment).

After installing the default wheel, alkahest.jit_is_available() is True (Cranelift). After +jit it is also True (LLVM, in place of Cranelift); +full carries both backends. Gröbner-backed APIs such as alkahest.solve are available in all wheels since groebner became a default feature.

See the install matrix for per-platform coverage.

Target layout (roadmap): a small extra index URL (PEP 503) hosting only +jit / +full wheels, mirroring PyTorch’s --extra-index-url workflow:

pip install 'alkahest==3.12.0+full' --extra-index-url https://EXAMPLE/alkahest-extras/simple

From source

Required to enable optional features (jit, cuda) or for development. The groebner and egraph features are already built into default wheels; a source build inherits them automatically. cranelift and parallel are not Cargo defaults, so a source build that omits them gets a wheel weaker than PyPI's — pass --features "parallel egraph cranelift groebner" to match it. Prerequisites:

• Rust stable ≥ 1.76 and nightly:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  rustup toolchain install nightly
  

• uv (recommended Python tool manager): curl -LsSf https://astral.sh/uv/install.sh | sh

• LLVM 21: apt install llvm-21 libllvm21 llvm-21-dev / brew install llvm@21 (apt install llvm-21-dev needs the upstream repository on Debian/Ubuntu (apt.llvm.org; Ubuntu 24.04's own universe stops at 19) — https://apt.llvm.org/llvm.sh 21 sets it up. Fedora/RHEL 10 ship it as llvm-devel.)

• FLINT ≥ 3.3 (≥ 3.4 for Riemann theta; pulls in GMP and MPFR). Many distribution packages are older — Ubuntu 24.04's libflint-dev is 3.0.1, Debian 12's is 2.9 — and build.rs refuses them with a message saying so; on such systems build FLINT from its release tarball into a prefix (see No root? below). Packages: apt install libflint-dev (Debian/Ubuntu, if new enough) · dnf install flint-devel (Fedora/RHEL) · pacman -S flint (Arch) · brew install flint (macOS) · pacman -S mingw-w64-ucrt-x86_64-flint (MSYS2 UCRT64 shell; MSYS2 no longer ships a MINGW64 FLINT — set MSYS2_PREFIX if FLINT lives elsewhere) · conda install -c conda-forge libflint

  FLINT is mandatory, not optional. There is no FLINT-free source build: UniPoly is a FLINT polynomial, and factorization, resultants, Hermite/Smith normal forms and number_theory all call FLINT directly, with no pure-Rust fallback. The flint3 Cargo feature selects which FLINT version's API to call; it does not make the dependency optional. build.rs fails fast with an install hint when it cannot find FLINT, rather than letting the build die at link time.

  No root? Build FLINT into a user-local prefix and point the build at it — no system package needed:

  FLINT_LIB_DIR=$PREFIX/lib FLINT_INCLUDE_DIR=$PREFIX/include \
    maturin develop --manifest-path alkahest-py/Cargo.toml --release --features "parallel egraph cranelift groebner"
  # then at run time: export LD_LIBRARY_PATH=$PREFIX/lib   (DYLD_LIBRARY_PATH on macOS)
  

  Both variables are also used for FLINT version detection, so a locally built FLINT 3 is recognised as FLINT 3. bypasses the presence probe if FLINT is reachable by a route it does not cover. If you do not need a source build at all, the prebuilt PyPI wheels already have FLINT linked in.

# Install dev tools (maturin, pytest, ruff, ty, …) without building the Rust extension:
uv sync --no-install-project --group dev
# Build and install the extension into the project venv:
uv run maturin develop --manifest-path alkahest-py/Cargo.toml --release --features "parallel egraph jit groebner"

Without uv, install maturin directly and run the same develop command:

pip install maturin
maturin develop --manifest-path alkahest-py/Cargo.toml --release --features "parallel egraph jit groebner"

Optional Cargo features: parallel (sharded pool + parallel F4 + numpy_eval_par), egraph (vendored egglog backend; default in PyPI wheels), groebner (Gröbner solver + Diophantine + homotopy; default in both the Rust crate and PyPI wheels), system-gmp (rug links the system GMP/MPFR that FLINT uses; default in PyPI wheels, opt-in for source builds — needs GMP ≥ 6.3 / MPFR ≥ 4.2, see the GMP prerequisite above), cranelift (pure-Rust Tier-1 JIT), jit (LLVM JIT), cuda (NVPTX codegen — needs LLVM 21 with the NVPTX target; adds compile_cuda), groebner-cuda (CUDA Macaulay-matrix kernel — needs only cudarc, and is a Rust-crate entry point that no Python call reaches). Neither GPU feature is in any published wheel: see the GPU guide.

Rust crate

alkahest-cas is also published on crates.io (docs.rs) for use directly from Rust without a Python runtime:

[dependencies]
alkahest-cas = "3"

# groebner is included by default; add other optional features as needed:
# alkahest-cas = { version = "3", features = ["parallel", "egraph"] }

System prerequisites (same libraries as the Python build — must be present before cargo build):

# Debian / Ubuntu
sudo apt-get install -y libflint-dev libgmp-dev libmpfr-dev

# macOS (with `system-gmp`, also export CPATH / LIBRARY_PATH for the gmp and mpfr kegs — see above)
brew install flint

With GMP ≥ 6.3 and MPFR ≥ 4.2 you can add features = ["system-gmp"] so rug shares FLINT's libgmp instead of compiling a bundled one (see the GMP prerequisite above).

The jit feature additionally requires LLVM 21 dev headers (apt install llvm-21-dev / brew install llvm@21). A self-contained runnable example is in examples/rust_quickstart/.

---

Quick start

import alkahest as ak

caps = ak.capabilities()  # groebner, jit, egraph, parallel
pool = ak.ExprPool()
x = pool.symbol("x")

# Python int literals work in arithmetic (pool still required for symbols)
expr = x**2 + 1

# Differentiation with derivation log
result = ak.diff(ak.sin(expr), x)
print(result.value)   # 2*x*cos(x^2 + 1)
print(result.steps)   # list of rewrite steps

# Integration
r = ak.integrate(ak.exp(x), x)
print(r.value)        # exp(x)

# Simplification — use simplify_trig for sin²+cos², not the catch-all simplify
s = ak.simplify(x + 0)
print(s.value)        # x
print(ak.simplify_trig(ak.sin(x)**2 + ak.cos(x)**2).value)  # 1

# JIT-compile to native code (interpreter fallback when caps["jit"] is False)
f = ak.compile_expr(x**2 + 1, [x])
print(f([3.0]))       # 10.0

# String entry point for agents / notebooks (bindings optional)
e = ak.parse("sin(x)^2 + cos(x)^2", pool, {"x": x})
print(ak.simplify_trig(e).value)  # 1

Partial fractions, definite integration, and Lean certificates:

import alkahest as ak

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

f = 1 / (x**2 - pool.integer(1))
print(ak.apart(f, x))  # partial fractions over ℚ

r = ak.integrate(x**2, x, pool.integer(0), pool.integer(1))  # ∫₀¹ x² dx = 1/3
print(r.value)
print(r.certificate)  # Lean 4 proof term when available

More runnable examples live in examples/ — polynomials, Risch integration, Lean certificates, agent workflows, and more.

---

Features

Area	What you get	Entry points
Calculus	Differentiation, Risch integration (definite and indefinite), limits, series expansion, residues	diff · integrate · limit · series · residue
Simplification	Rule engine plus e-graph saturation, with domain-specific passes instead of one catch-all	simplify · simplify_trig · simplify_log_exp · simplify_egraph
Polynomials	FLINT-backed univariate and multivariate arithmetic, factorization over ℤ and 𝔽ₚ, sparse GCD and interpolation, resultants, partial fractions	UniPoly.factor_z · factor_univariate_mod_p · gcd_sparse · resultant · apart · cancel
Solving	Gröbner bases (F4), triangular decomposition, primary decomposition, real root isolation via CAD, numerical fallback	solve · real_roots · triangularize · cad_project · primary_decomposition · solve_numerical
Sums and products	Gosper and Zeilberger creative telescoping, WZ pair verification, linear recurrence solving	sum_indefinite · sum_definite · zeilberger · verify_wz_pair · rsolve
Linear algebra	Symbolic matrices, eigenvalues and eigenvectors, Jacobians, Routh–Hurwitz stability

Full listing in the Python API reference.

---

Expression representations

Type	Description
Expr	Generic hash-consed symbolic expression
UniPoly	Dense univariate polynomial (FLINT-backed)
MultiPoly	Sparse multivariate polynomial over ℤ
MultiPolyFp	Sparse multivariate polynomial over 𝔽ₚ (modular arithmetic)
RationalFunction	Quotient of polynomials with GCD normalization
ArbBall	Real interval with rigorous error bounds (Arb)

Representation types are explicit — no silent performance cliffs. Conversion between them is always an opt-in call (UniPoly.from_symbolic(...), etc.).

---

Result objects

Most transforming operations (diff, simplify, integrate, sum_*, …) return a DerivedResult with:

• .value — the result expression
• .steps — derivation log (list of rewrite rules applied)
• .certificate — Lean 4 proof term, when available
• .to_dict() / .to_json() — versioned machine-parseable envelope; use mode="compact" in agent loops

Exceptions: limit returns a bare Expr, and series returns a Series (with its own .polynomial / .order fields). Use .value only on DerivedResult.

Search plumbing (agent loops)

Need	Entry point
Bound one candidate	Budget + context(budget=…) → BudgetExceededError (E-BUDGET-*)
Fan out without aborting	batch_map / integrate_many / simplify_many / diff_many
Compact logs	DerivedResult.to_dict(mode="compact")
Session provenance	alkahest.research claim graphs
Propose and fit a parametric family	alkahest.ansatz
Differential-test against another CAS	alkahest.crosscheck
Hand off a discrete / mixed int-real subproblem	alkahest.smt

Docs: Autoresearch / agent loops.

---

Modules for autoresearch loops

Three submodules new in 3.8, aimed at unattended search. Each has its own chapter in the documentation site.

Module	What it does
alkahest.ansatz	Parametric families with named unknown coefficients — polynomial, rational, exponential_polynomial, linear_combination, quadratic_form — plus fit (solve for the coefficients from a residual, with a verification status), enumerate_family, and certify_nonneg. This is the "guess the shape, let the CAS pin the constants" loop, done once instead of re-improvised per problem.
alkahest.crosscheck	Differential testing against an external CAS. check(op, …) runs one comparison through a ladder of increasingly semantic rungs (syntactic → normalised → numeric → invariant) and reports agree / diverge / incomparable / unavailable; sweep() generates a seeded corpus of them; run_frozen_corpus() replays the pinned cases. A missing oracle is reported as unavailable, never as agreement.
alkahest.smt	SMT-LIB 2 export (to_smtlib) and a bridge to z3 / cvc5 (solve, supported, solvers). A sat model is lifted to exact rationals and substituted back and checked in-process; an unsat is reported as externally_asserted and is deliberately not counted as machine-checked. Algebraic-number witnesses are refused (E-SMT-003) rather than truncated to floats.

import alkahest as ak

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

# Fit an ansatz
from alkahest.ansatz import polynomial, fit
A = polynomial(pool, [x], degree=2)
sol = fit(A, A.expr - (x**2 - pool.integer(3) * x + pool.integer(2)))
print(sol.expr, sol.status)          # (2 + x^2 + (x * -3))  exactly_verified

# Cross-check a result against SymPy
print(ak.crosscheck.check("integrate", x**2, x).outcome)     # 'agree'

# Ask whether the SMT route applies before paying for it
print(ak.smt.supported(pool.gt(x, pool.integer(0))).recommendation)   # 'prefer_in_tree'

---

Known limits

Alkahest is meant to be run unattended, so the limits are documented as prominently as the features. These are properties of the design, not open bugs — write the loop around them.

• ExprPool never reclaims. The expression arena is append-only: no clear, no refcount, no GC. The only way to free interned nodes is to drop the whole pool, and every Expr / Matrix / DerivedResult holds a strong reference to its pool, so keeping one result keeps everything. Growth is roughly 115 bytes per node and linear forever (~2–3.5 KB per integrate call) while per-call latency stays flat — so a long-running loop on one pool dies by OOM with no slowdown to warn you first. Use one pool per problem and carry to_dict() envelopes, not live Expr handles. Details.
• wall_ms is cooperative and its granularity is one primitive operation. A call stops at the first checkpoint after the deadline. Past a certain degree that operation is a FLINT call, which no cooperative mechanism can interrupt — a 300 ms budget on a degree-62 integrand returns after ~2 s. Only an OS-level timeout goes below that.
• run_with_wall_fallback does not bound wall time for an uncooperative callee. It joins its worker before raising, so it returns when the callee returns: run_with_wall_fallback(time.sleep, 3.0, budget=Budget(wall_ms=50)) raises after 3000 ms. It exists to turn a silent truncation into a coded error, not to contain an unknown callee. integrate and limit are the engines that honour the cooperative budget throughout, so they are the ones that can be cancelled while already running. The other heavy entry points (simplify, diff, solve, factor_z, matrix operations, …) also release the GIL, so a thread pool overlaps them — but releasing the GIL does not make them cancellable.
• decide refuses rather than answering in cases it cannot establish. It covers polynomial bodies in ≤ 2 real variables with a ≤ 2-quantifier prefix, and inside that fragment it raises E-CAD-001 when the only candidate solutions sit at an irrational boundary point that rational sampling cannot test. Same for linear algebra: an entry or determinant whose vanishing is undecidable gives E-LINALG-010 / E-MAT-004 instead of a guessed branch. A refusal means undecided, not false — a search loop that records it as a negative result closes a branch it never explored.
• can emit casus-irreducibilis cube roots. These are correct under Alkahest's real cube-root convention — refuses them honestly and returns an unbounded ball — but a principal-branch evaluator (SymPy, NumPy) returns a confident number that is an eigenvalue. Evaluate inside Alkahest before exporting a radical expression to another tool. .

---

Reinforcement learning

alkahest.rl exposes verifiable RL environments backed by the CAS. The core layer (alkahest.rl.core) is trainer-agnostic; domain environments live under alkahest.rl.envs.* and optionally integrate with Prime Intellect Verifiers.

pip install "alkahest[rl]"   # Python ≥ 3.10; adds verifiers + datasets

from alkahest.rl.envs.integration import IntegrationVerifier, load_environment

verifier = IntegrationVerifier()
# reward = verifier.verify(model_output, {"f_expr": f, "is_elementary": True, "pool": pool})

env = load_environment(difficulty_tier=0, n_train=1000, n_eval=100, adaptive=True)

Component	Description
IntegrationVerifier	Layered check: symbolic diff → e-graph → interval spot checks; rewards honest refusal on NonElementary integrands
load_environment()	Returns a verifiers.SingleTurnEnv with Risch-tier curriculum
recipes/verl_integration_reward.py	Drop-in reward for veRL

Environments Hub: alkahest/alkahest-symbolic-integration — install with prime env install alkahest/alkahest-symbolic-integration. Publish updates from python/alkahest/rl/envs/integration/ with prime env push. Full checklist in the RL guide.

---

Documentation and further reading

• Documentation site — full API reference and user guide
• ARCHITECTURE.md — crates, directory layout, and key files
• ROADMAP.md — planned milestones
• CONTRIBUTING.md — Rust vs Python layer guide
• TESTING.md — property-based testing, fuzzing, sanitizers, CI tiers
• BENCHMARKS.md — criterion and Python benchmark suites
• examples/ — runnable end-to-end examples
• demo-playground/ — notebook UI, agent chat, and demo recording stack (the hosted playground is the WASM build of it)
• LICENSE — Apache 2.0 license

---

Stability

Alkahest follows semantic versioning from 1.0. The stable surface is everything re-exported from alkahest_cas::stable (Rust) and alkahest.__all__ (Python). Experimental APIs live under alkahest_cas::experimental and alkahest.experimental and may change in minor releases.