Python API · Submodule

alkahest.ansatz

Ansatz families — structured conjecture generation for search loops.

P2 item 1 — see docs/mdbook/src/ansatz.md.

Stage 1 of an autoresearch loop is generate: propose a structured family of candidate objects ("every polynomial of degree ≤ 3 in x and y", "a Padé approximant of type (2, 2)", "a quadratic Lyapunov candidate"), then either sweep it numerically or solve for the coefficients that make some residual vanish. Agents hand-roll this constantly, and the hand-rolled version is usually wrong in one of three specific ways:

it loses the distinction between an unknown coefficient and an independent variable, so the follow-up substitution solves for the wrong thing;
it assumes the first m sample points give m independent equations, which is false exactly when the family is degenerate — the interesting case;
it never substitutes the fitted answer back, so a fit that only satisfies the sampled constraints is reported as if it satisfied the identity.

This module is that plumbing, done once. Ansatz keeps the unknowns and the variables apart; fit() over-samples and reads the rank off the reduced row echelon form rather than assuming independence; and fit(..., certify="residual") — the default — substitutes the solution back and only reports "exactly_verified" when the residual provably normalises to zero.

Honesty invariants

Solving may be heuristic; checking is exact. The linear system is built by collocation (probing the residual at sample points), which is a sufficient condition for identical vanishing only for polynomial residuals of bounded degree. So the fit is never trusted on its own: it is substituted back and normalised. A solution that normalises to zero is verification["status"] == "exactly_verified"; one that does not is returned intact but labelled "numerically_checked", with the surviving residual stated in verification["residual"]. There is no status meaning "solved".

Inconsistent is a result, not a malfunction. When no member of the family can satisfy the constraints, fit() raises AnsatzError E-ANSATZ-003. For a loop that is a closed branch — a positive finding worth recording — in the same spirit as a non-elementarity verdict from integrate().

Underdetermined is also a result. When the rank is below the number of unknowns, the members that work form a positive-dimensional family. That is often the answer the loop wanted, so AnsatzSolution.free returns the free parameters rather than picking an arbitrary member of the space.

Quick start

Python

>>> import alkahest as ak
>>> from alkahest.ansatz import polynomial, fit
>>> pool = ak.ExprPool()
>>> x = pool.symbol("x")
>>> A = polynomial(pool, [x], degree=2)
>>> len(A.unknowns)
3
>>> target = x**2 - pool.integer(3) * x + pool.integer(2)
>>> sol = fit(A, A.expr - target)
>>> sol.status
'exactly_verified'
>>> sol.rank, sol.free
(3, ())

Everything here is pure Python composed from primitives that are already fast in Rust (Matrix.rref, simplify, subs), so it works in a build without the groebner feature — see fit() for the one path that needs it, and refuses rather than degrading when it is absent.

class

class ansatz.Ansatz

alkahest.ansatz

#Honesty invariants

#Quick start

Honesty invariants

Quick start