A reliable Python library for numerically evaluating mathematical expressions in MathJSON format. Perfect for applications that need to safely execute user-provided formulas, calculate dynamic equations, or process mathematical data.
What is MathJSON? MathJSON represents mathematical expressions as JSON arrays, like ["Add", 1, 2, 3] for 1+2+3. This format is safe, structured, and easy to generate programmatically.
Coming from 1.x? Version 2 changed Log's meaning — see Migrating from 1.x.
- Use Cases
- Installation
- Quick Start
- Supported Operations
- Restricting Available Functions
- Error Handling
- Migrating from 1.x
- Testing
- Community
- Contributing
- Related Projects
The core pattern: if your Python backend accepts user-provided datapoints and user-provided math to apply to them, mathjson-solver is the engine for that — it evaluates the formula without needing to trust either the formula's author or the data's source. A survey platform is a natural fit: a survey and its "calculated answers" both come from the same untrusted party (the survey builder), the calculation runs against whatever the respondent enters, and the result has to be safe to compute no matter what either of them contains. The same shape covers pricing rules, scoring algorithms, and scientific or medical calculators wherever the formula itself isn't fixed at development time — our showcase example is a breast-cancer risk calculator implementing the Gail model, numerical integration included, entirely in MathJSON.
- Dynamic Formulas: Let users create custom calculations in web applications
- Scientific Computing: Evaluate mathematical models with variable parameters
- Business Logic: Process complex pricing rules or scoring algorithms
- Data Processing: Apply mathematical transformations to datasets
- Health Applications: Calculate medical scores, dosages, or risk assessments
pip install mathjson-solverRequirements: Python 3.10+
Optional:
pip install mathjson-solver[integration](installs numpy; only required forTrapezoidalIntegrate)pip install mathjson-solver[regex](installs google-re2; only required forRegExp/IsMatch/StringMatch/StringMatchAll)pip install mathjson-solver[special-functions](installs scipy; required forBesselJ/BesselY/BesselI/BesselK,AiryAi/AiryBi/AiryAiPrime/AiryBiPrime,Zeta,GammaRegularized,BetaRegularized, andCDF/QuantileonBinomialDistribution/PoissonDistribution)
Combine any of these by separating them with commas in one pip install, e.g. pip install mathjson-solver[integration,regex,special-functions] for all three at once.
from mathjson_solver import create_solver, MathJSONException
# Define variables and create solver
parameters = {"x": 2, "y": 3}
solver = create_solver(parameters)
# Evaluate expressions
basic_math = solver(["Add", "x", "y", 4])
print(basic_math) # 9 (because 2+3+4=9)
# More complex expressions
result = solver(["Multiply", ["Add", "x", 1], ["Subtract", "y", 1]])
print(result) # 6 (because (2+1) * (3-1) = 6)
# Handle errors gracefully
try:
solver(["Divide", 1, 0])
except MathJSONException as e:
print(f"Math error: {e}")
# Math error: Problem in Divide. ['Divide', 1, 0]. division by zeroThink Functional: MathJSON Solver embraces functional programming principles. Instead of writing loops and modifying variables, you compose expressions that transform data. Functions like Map, Reduce, and Filter let you process arrays elegantly, while immutable operations ensure predictable, side-effect-free calculations. Don't worry if you're new to functional programming — the examples will guide you naturally into this powerful paradigm.
# Functional approach: transform data with expressions
solver(["Map", ["Array", 1, 2, 3, 4], ["Multiply"], 2]) # [2, 4, 6, 8]
solver(["Reduce", ["Array", 1, 2, 3, 4], 0, ["Add", "acc", "item"],
["Variable", "acc"], ["Variable", "item"], ["Variable", "i"]]) # 10
# CortexJS-style forms also work: a lambda via Function, and a 2-argument Reduce
solver(["Map", ["Array", 1, 2, 3, 4], ["Function", ["Multiply", "_", 2]]]) # [2, 4, 6, 8]
solver(["Reduce", ["Array", 1, 2, 3, 4], ["Add"]]) # 10338 MathJSON constructs across arithmetic, trigonometry, logarithms, comparisons, logic and sets, statistics and probability distributions, functional programming (Map/Reduce/Filter), arrays and collections, control flow, strings and RE2-backed pattern matching, date/time, number theory, special functions (Bessel/Airy/Gamma/elliptic-integral/hypergeometric families), combinatorics, and structural introspection.
["Add", 1, 2, ["Multiply", 3, 4]] # 15
["CDF", ["NormalDistribution", 0, 1], 1.96] # 0.975 (z-score to percentile)
["Reduce", ["Array", 1, 2, 3, 4], ["Add"]] # 10
["StringMatch", "patient-042", "[0-9]+"] # "042" at position 9-11
["FactorInteger", 360] # [[2,3], [3,2], [5,1]] (2³·3²·5)Three optional extras unlock specific functions — see Installation above: regex (RE2-backed pattern matching), integration (TrapezoidalIntegrate), special-functions (Bessel/Airy/Zeta/regularized gamma and beta, plus CDF/Quantile on the two discrete probability distributions).
View the complete function reference with examples →
Pass blacklist to disable specific constructs for a solver instance — useful when evaluating expressions from a source you don't fully trust, or when your deployment simply doesn't want certain functions exposed:
solver = create_solver(parameters, blacklist=["PowerSet", "Permutations", "Combinations", "CartesianProduct"])
solver(["PowerSet", ["Array", 1, 2, 3]])
# Raises: MathJSONException: Problem in PowerSet. [...]. 'PowerSet' has been disabled in this solver instance.
solver(["Add", 1, 2]) # unaffected constructs still work: 3.0This is an access-policy control, not a resource limiter. Blacklisting a construct stops it from running at all; it doesn't make an enabled construct safe against pathological input. In particular, the enumeration functions (PowerSet, Permutations, Combinations, CartesianProduct) have no built-in output-size limit — ["PowerSet", ["Range", 30]] will try to materialize over a billion subsets if you let it run. If you're evaluating expressions from an untrusted source, blacklist any construct whose worst-case cost you haven't reasoned about, rather than assuming everything implemented is safe by default for every threat model.
A blacklisted name that isn't an actual construct (a typo, for instance) is silently ignored rather than rejected — blacklist isn't validated against the list of implemented constructs.
MathJSON Solver raises MathJSONException for invalid expressions or mathematical errors:
from mathjson_solver import create_solver, MathJSONException
solver = create_solver({})
# Handle specific math errors
try:
result = solver(["Sqrt", -1]) # Invalid: square root of negative
except MathJSONException as e:
print(f"Cannot evaluate: {e}")
# Handle malformed expressions
try:
result = solver(["UnknownFunction", 1, 2])
except MathJSONException as e:
print(f"Unsupported operation: {e}")Version 2 introduced a breaking change:
Logis now log base 10 instead of natural log (see CHANGELOG.md). Bugfix releases for the 1.x line continue on the1.xbranch.
Version 2.0.0's only breaking change is Log: pre-2.0.0 it was always natural log, ["Log", x] == math.log(x). From 2.0.0 on it matches CortexJS — ["Log", x] is log base 10, ["Log", x, b] is log base b — and natural log moved to Ln.
If you have existing expressions built for 1.x and don't want to hand-edit every Log node just to pick up functions added in 2.x (Product, the CortexJS forms of If/Map/Filter/Reduce, the new aliases, etc.), pass legacy_v1=True when creating the solver. It rewrites every ["Log", x] to ["Ln", x] before evaluating, so old expressions keep producing the same results without modification:
solver = create_solver(parameters, legacy_v1=True)
solver(["Log", 8]) # 2.0794... (natural log, matching pre-2.0.0 behavior)You can also run the rewrite yourself and inspect or store the translated expression:
from mathjson_solver import translate_v1_mathjson
translate_v1_mathjson(["Add", ["Log", 8], 1]) # ["Add", ["Ln", 8], 1]legacy_v1=True only affects Log. Every other 1.x expression already evaluates identically on 2.x without any translation.
Install development dependencies and run tests:
# Install pytest if not already installed
pip install pytest
# Run tests from project directory
pytest
# Run with coverage
pytest --cov=mathjson_solver- Questions & Discussion: GitHub Issues
- Bug Reports & Feature Requests: GitHub Issues
- Documentation: Complete Function Reference
We welcome contributions! Please feel free to:
- Report bugs or request features via GitHub Issues
- Submit pull requests with improvements
We also created londec — evaluate tree-structured conditions against an ordered history of events. It uses mathjson-solver internally.
mathjson-tree-builder is a fully compatible frontend counterpart — a framework-agnostic, click-to-build editor for authoring MathJSON expressions in the browser.
This library implements the MathJSON format as defined by the CortexJS Compute Engine. Since 2.0.0, mathjson-solver has been steering towards greater compatibility with CortexJS's calling conventions and function set — while remaining an independent Python implementation, not a port or dependency of CortexJS.
Scope: mathjson-solver targets compatibility with CortexJS's array-form calling conventions and standard function names — not the full Compute Engine, which is a symbolic CAS.
Made with ❤️ by Longenesis