Alkahest

PyPI • crates.io • Docs • Website • RL environment • Demo

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.

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().

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.10.0+jit or 3.10.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.10.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.

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

pip install "https://github.com/alkahest-cas/alkahest/releases/download/v3.10.0/alkahest-3.10.0+full-cp311-cp311-linux_x86_64.whl"
pip install "https://github.com/alkahest-cas/alkahest/releases/download/v3.10.0/alkahest-3.10.0+jit-cp311-cp311-linux_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.10.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.10.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-x86_64-flint (MSYS2) · 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. ALKAHEST_SKIP_FLINT_CHECK=1 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.

• GMP and MPFR (headers + libraries; FLINT's own dependencies): apt install libgmp-dev libmpfr-dev · dnf install gmp-devel mpfr-devel · Homebrew and MSYS2 get them with flint.

  By default rug gets its own bundled, statically linked GMP/MPFR compiled from source, which works with any distribution's packages. The opt-in system-gmp feature (which every PyPI wheel is built with) links rug against the system libraries FLINT uses instead, so the process has one GMP (which is what lets Budget(max_bytes=...) see FLINT's bignums) and nothing is compiled from GMP source. It needs GMP ≥ 6.3 and MPFR ≥ 4.2 (Ubuntu 24.04, Debian 13, Fedora, Homebrew, MSYS2; not Ubuntu 22.04 / Debian 12, and not *-windows-msvc). Its probe runs a bare cc … -lgmp, so the libraries must be on the compiler's default search path:

  • Homebrew: export CPATH=$(brew --prefix gmp)/include:$(brew --prefix mpfr)/include LIBRARY_PATH=$(brew --prefix gmp)/lib:$(brew --prefix mpfr)/lib
  • User-local prefix: the same two variables pointing at $PREFIX/include / $PREFIX/lib (plus LD_LIBRARY_PATH at run time); build FLINT against that prefix too (./configure --with-gmp=$PREFIX --with-mpfr=$PREFIX) so there really is only one.

# 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

Full listing in the Python API reference.

Expression representations

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)

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.

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.
• Matrix.eigenvals() can emit casus-irreducibilis cube roots. These are correct under Alkahest's real cube-root convention — eval_expr refuses them honestly and interval_eval returns an unbounded ball — but a principal-branch evaluator (SymPy, NumPy) returns a confident number that is not an eigenvalue. Evaluate inside Alkahest before exporting a radical expression to another tool. Details.

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)

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.