Exact mathematics. Built from first principles.
By Umutcan EDIZASLAN
Python 3.11+ · Dependency-free core · v0.9.0 alpha
Releases / Guide / Changes / Example / MIT license
MathForge is a pure-Python library for exact mathematics. It computes with integers, rationals and exact algebraic numbers, never with floating point, and an independent checker confirms each answer before you see it. The evidence travels with the result, so anyone can check it again later.
- Exact. Rationals, real algebraic numbers, exact complex numbers and exact
interval sets. Even
0.1parses as1/10. - Independently checked. Each operation pairs a producer with an independent checker, and a value is returned only after the checker accepts it.
- Re-verifiable. Structured results carry their request and evidence as
mathematical JSON.
mf.verifychecks a stored document again, without trusting the code that produced it. - Bounded. Every computation runs under a budget. Running out is an explicit error, never a wrong answer or a false "no solution".
- Dependency-free. The core is plain Python 3.11–3.14. An optional MCP server lets AI agents use it.
v0.9 adds 65 operations, from 103 to 168, and opens five new areas: equations, sets, decimal digits, vectors and plane geometry. Every new operation is checked by its own independent checker, and its result re-verifies from its JSON.
| Area | New operations |
|---|---|
| Number theory | powmod, multiplicative_order, primitive_root, legendre_symbol, jacobi_symbol, sqrt_mod, next_prime, prev_prime, linear_diophantine, quadratic_continued_fraction, convergents, pell_fundamental, moebius, divisor_sigma, integer_nth_root, discrete_log, two_squares |
| Algebra | count_real_roots, complex_roots, interpolate, denest_sqrt, sturm_sequence, cyclotomic_polynomial |
| Equations and sets | solve_abs, solve_sqrt, set_union, set_intersection, set_difference, set_complement, set_symmetric_difference |
| Decimal digits and approximation | digits, rational_approximation |
| Sums and series | sum_polynomial, geometric_sum, geometric_series, polynomial_geometric_series, series_coefficients, residue |
| Integrals | trig_power_antiderivative, trig_power_integral |
| Linear algebra | matrix_power (also Matrix ** k), eigenvectors, definiteness, gram_schmidt, hermite_normal_form, smith_normal_form |
| Vectors and geometry | dot, cross, projection, triple_product, distance, polygon_area, line_intersection, orientation, convex_hull |
| Statistics and counting | correlation, linear_regression, quantile, mode, stationary_distribution, fisher_exact, partitions, derangements, bell, stirling1 |
import mathforge as mf
Q = mf.Rational
x = mf.symbol("x")
F = lambda text: mf.parse_function(text, symbols={"x": x})
assert mf.ntheory.pell_fundamental(61) == (1766319049, 226153980)
assert mf.render_text(mf.equations.solve_abs(F("abs(x - 1) + abs(x + 2)"), F("3"), x)) == "[-2, 1]"
assert mf.render_text(mf.numeric.digits(mf.sqrt(2), 20)) == "1.41421356237309504880..."
assert mf.render_text(mf.integrals.trig_power_integral(F("sin(x)^2"), x, 0, 1)) == "pi/2"
assert mf.linalg.matrix_power(mf.Matrix(((1, 1), (1, 0))), 10) == mf.Matrix(((89, 55), (55, 34)))
assert mf.geometry.polygon_area(mf.Matrix(((0, 0), (4, 0), (0, 3)))) == Q(6)
assert mf.numeric.rational_approximation(mf.sqrt(2), 100) == Q(140, 99)
assert mf.linalg.smith_normal_form(mf.Matrix(((2, 4), (6, 8)))) == (2, 4)
result = mf.operations.eigenvectors(mf.Matrix(((2, 1), (1, 2))))
assert mf.verify(mf.loads(mf.dumps(result))).verifiedA question outside an operation's rules, such as the complex roots of x³ − 2, is
deferred with a reason rather than guessed. Of the 167 natural requests in the
probe scoreboard (tools/check_probes.py), 133 now get a verified answer, up
from 88 in v0.8, and none a wrong one. The MCP server gains three area tools,
mathforge.equations, mathforge.geometry and mathforge.numeric, for 40 in
all.
Every v0.8 operation keeps its name, signature and result, and v1–v6 documents
keep their bytes and verdicts. Matrix * Matrix still raises InvalidInput; its
message now points to @.
Known limitations: each operation documents the input sizes that fit the default
budget, and larger inputs end as resource_limit_exceeded, never as a wrong
value. integer_gcd and integer_lcm on integers of thousands of bits, and
solve_system, keep the costs that v0.8 documented.
See the v0.9 mathematics guide, the area guide, the complete executable example and the changelog. v0.8.0, the speed release, made exact computation many times cheaper; its figures are in the performance notes.
Install the wheel from the v0.9.0 release:
python -m pip install https://github.com/U-C4N/MathForge/releases/download/v0.9.0/mathforge-0.9.0-py3-none-any.whlFrom a local checkout, use python -m pip install -e . instead. Then:
import mathforge as mf
x = mf.symbol("x", domain=mf.Reals)
problem = mf.parse_problem("x^2 - 2 = 0", symbols={"x": x})
result = mf.solve(problem, for_=x)
print(mf.render_text(result.solution_set))
print(mf.to_latex(result.solution_set))
assert mf.verify(result).verified
assert mf.parse_expression("0.1", symbols={}) == mf.Rational(1, 10)Every example in this README runs as written: tools/check_docs.py executes
them with their assertions.
roots = mf.real_roots(x**3 - x, x) # -1, 0, 1 with multiplicities
rf = mf.rational_function(x**2 - 1, x - 1, variable=x)
assert mf.solve(mf.Eq(rf, 2), for_=x).outcome is mf.Outcome.NO_SOLUTION
assert mf.integrate(x**2, x, 0, 1) == mf.Rational(1, 3)
assert mf.det(mf.Matrix(((1, 2), (3, 4)))) == mf.Rational(-2)Full workflow · Linear systems · Rational inequalities
y = mf.symbol("y")
f = x**2*y + y**3
assert mf.gradient(f, (x, y)) == (2*x*y, x**2 + 3*y**2)
assert mf.hessian(f, (x, y)) == ((2*y, 2*x), (2*x, 6*y))
assert mf.verify(mf.operations.jacobian((f, x*y), (x, y))).verifiedJacobian and Hessian values are immutable tuples of expression rows. The
existing Matrix type remains rational-valued. See the
multivariate guide.
f = mf.parse_expression("((x-1)*(x^2+2))/(x*(x-1))", symbols={"x": x})
analysis_result = mf.operations.analyze_function(f, x)
analysis = analysis_result.unwrap()
assert not analysis.domain.contains(0) and not analysis.domain.contains(1)
assert [(p.point, p.kind) for p in analysis.excluded_points] == [
(mf.Rational(0), "pole"), (mf.Rational(1), "hole")]
assert mf.limit(f, x, 1) == mf.LimitValue("finite", mf.Rational(3))
assert mf.limit(f, x, 0).kind == "does_not_exist"
assert mf.verify(analysis_result).verified
print(mf.render_text(analysis))The hole at x=1 remains excluded even though its limit is 3. The two-sided
limit at x=0 does not exist because its one-sided limits have opposite signs.
See the function analysis guide and the
complete executable example.
import mathforge as mf
x = mf.symbol("x")
factors = mf.factor(mf.Polynomial.from_expression(x**4 + 4, x))
assert len(factors.factors) == 2
alpha = mf.RealAlgebraicRoot((-2, 0, 0, 1), 0)
assert mf.algebraic(alpha**3) == mf.Rational(2)
assert mf.evaluate_algebraic(x**3, {x: alpha}) == mf.Rational(2)
assert mf.integrate(x, x, 0, mf.sqrt(2)) == mf.Rational(1)
assert mf.verify(mf.operations.charpoly(mf.Matrix(((0, 2), (1, 0))), x)).verifiedRead the exact algebra guide for polynomial domains, certificates and explicit real algebraic arithmetic.
import mathforge as mf
from mathforge import functions as fn
x = mf.symbol("x")
f = mf.real_function(fn.sin(x)/fn.as_real_expr(x), (x,))
result = mf.operations.function_limit(f, x, 0)
assert result.unwrap().value == fn.as_real_expr(1)
assert mf.verify(mf.loads(mf.dumps(result))).verified
assert mf.expectation(mf.discrete_uniform((1, 2, 3, 4, 5, 6))) == mf.Rational(7, 2)
assert mf.complex_pow(mf.ComplexAlgebraic(0, 1), 2) == mf.ComplexAlgebraic(-1, 0)See the v0.7 mathematics guide for domains, supported families and API examples.
MathForge includes an optional MCP server. Install it into the environment your MCP client uses:
python -m pip install -e ".[mcp]"
mathforge-mcpThe process speaks MCP on stdin/stdout, not an interactive terminal prompt. It
offers 40 tools: the thirty curated tools of v0.7, area tools that run an
operation of their areas by name, and mathforge.catalog, which finds operations
and the arguments they take. The base install has no runtime dependencies; the
mcp extra installs the official MCP SDK and its dependencies. There is no API
key or HTTP server.
See client configuration and tool inputs, the user guide, and API reference.
Each operation has a producer, which computes, and a checker, which confirms.
A checker confirms the answer another way, usually by examining evidence
instead of repeating the computation: a Bézout identity for a gcd, a modular
certificate for a determinant, a prime certificate for a factorization,
truncated power series for a Taylor polynomial. The checkers in
mathforge.certify share no code with the producers beyond a small trusted
layer of arithmetic. CI runs tools/check_layering.py, which fails if a checker
could reach producer code, even through chained imports. Verification is
algorithmic, not formal proof.
MathForge implements its own exact arithmetic with finite computation budgets.
It covers real polynomial roots, rational equations and inequalities, exact
linear algebra, polynomial factorization and real algebraic numbers,
multivariate derivatives, limits and analysis of rational functions, real
elementary functions, exact integration of rational functions and of powers of
sine and cosine, power series, sums, residues, complex algebra, number theory,
equations with absolute values and square roots, interval sets, exact decimal
digits and best rational approximations, integer lattices (Hermite and Smith
forms), vectors, plane geometry and convex hulls, combinatorics, probability and
statistics, including Markov chains and Fisher's exact test. A formal
RationalPrimitive certifies an antiderivative identity; general LogRootSum
point evaluation is outside scope. Improper integrals, complex roots beyond
irreducible factors of degree two, symbolic matrices, approximate numerical
output and remote HTTP serving are outside this alpha.
| Version | Date | Highlights |
|---|---|---|
| 0.9.0 | 2026-11-14 | More mathematics: 65 new operations in number theory, algebra, equations, sets, decimal digits, series, integrals, linear algebra, vectors, geometry, statistics and counting; three new MCP area tools |
| 0.8.0 | 2026-10-21 | The speed release: exact kernels with independent checkers, a lean value path, area modules, mathematical JSON v6, MCP area tools and continued fractions |
| 0.7.0 | 2026-10-14 | Real elementary functions, exact integration, complex algebra, number theory, combinatorics, probability, statistics and JSON v5 |
| 0.6.0 | 2026-10-14 | Complete polynomial factorization, resultants, real algebraic arithmetic, characteristic polynomials, real eigenvalues and JSON v4 |
| 0.5.0 | 2026-10-14 | Multivariate derivatives, gradients, Jacobians and Hessians; faster root isolation and RREF |
| 0.4.0 | 2026-10-11 | Exact limits of rational functions and complete function analysis, JSON v3 |
| 0.3.0 | 2026-10-10 | Math-text parsing, exact text and LaTeX rendering, the optional MCP server |
| 0.2.0 | 2026-10-09 | Polynomials, real roots, rational equations and inequalities, matrices and JSON v2 |
| 0.1.0 | 2026-10-08 | First public alpha: the exact rational core |
The changelog has the details of each release.
python -m unittest discover -s tests -v
python tools/check_docs.py
python -m pip install -r requirements-dev.txt
python -m build
python tools/check_distribution.pyCore tests use Python's standard library. Protocol tests use the optional MCP
SDK. Build, schema, typing and the seeded SymPy comparison suite are development
dependencies. Distribution checks validate both base and MCP-extra
installations. Public documentation/ is tracked and included in the sdist;
docs/ remains local working material and is excluded from Git and release
packages.
MathForge is released under the MIT license.