Axiomize

Axiomize

Reproducible scientific modeling that survives contact with reality. Axiomize turns a vague idea into an explicit, versioned mathematical model, validates it dimensionally and numerically, and exports an artifact someone else can re-run years from now.

This is not the numerical-methods library. That door is scientific-computing-system. Axiomize is the modeling layer: mandatory units, a versioned Model IR, and export to SBML, CellML, and Modelica. The MCP server is axiomize mcp.

mcp-name: io.github.Furox-Art/axiomize

Current package line: 1.14.3. PyPI and npm both serve 1.14.2. Per-registry availability is tracked in docs/documentation.md; the badges above are live and authoritative.

Documentation: [furox-art.github.io/axiomize](https://furox-art.github.io/axiomize/) · Changelog: [CHANGELOG.md](CHANGELOG.md) · Roadmap: [ROADMAP.md](ROADMAP.md) · Security: [SECURITY.md](SECURITY.md) · Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · Cite: [CITATION.cff](CITATION.cff)

Why

I got tired of scientific models that live in Jupyter notebooks and die there.

Someone writes a beautiful simulation, it works on their machine, they graduate or change jobs, and six months later nobody can run it. The dependencies are broken, the data is missing, and the "documentation" is a 47-cell notebook with no explanation.

Axiomize forces models to be explicit, versioned, testable code instead of exploratory spaghetti. Every assumption is written down. Every parameter carries a unit. Every result carries enough provenance that another person, on another machine, can reproduce it.

Who it is for

Not a fit: if you want a black-box predictor with no inspectable assumptions, or if you need the engine to make scientific claims for you without a human in the loop.

Install

pip install axiomize

Optional extras: pip install "axiomize[full]" for PyMC/JAX Bayesian sampling.

The playground extra installs gradio and pandas but ships no UI: playground/app.py is not in the wheel or the sdist, so pip install "axiomize[playground]" alone leaves you with dependencies and nothing to run. To use it, get the file from the repository:

git clone https://github.com/Furox-Art/axiomize

pip install "axiomize[playground]" python axiomize/playground/app.py

Python in five minutes

Declare the model, then let Axiomize check it. Units are mandatory, so dimensional mistakes fail loudly instead of producing a meaningless number. This block is the model in examples/quickstart_sir.py, field for field.

from axiomize.general_engine import simulate_model

from axiomize.model_ir import ModelIR

model = ModelIR.from_dict({ "schema_version": "1.0", "name": "sir-outbreak", "domain": "epidemiology", "family": "ode", "independent_variable": "t", "independent_unit": "day", "variables": [ {"name": "S", "unit": "person", "initial": 990.0, "bounds": [0.0, None]}, {"name": "I", "unit": "person", "initial": 10.0, "bounds": [0.0, None]}, ], "parameters": [ {"name": "beta", "unit": "1/day", "value": 0.3, "bounds": [0.0, None]}, {"name": "gamma", "unit": "1/day", "value": 0.1, "bounds": [0.0, None]}, {"name": "N", "unit": "persons", "value": 1000.0}, ], "equations": [ {"target": "S", "expression": "-beta*I*S/N", "kind": "derivative"}, {"target": "I", "expression": "beta*I*S/N - gamma*I", "kind": "derivative"}, ], "constraints": [ {"name": "cases_nonnegative", "expression": "I", "relation": "ge", "threshold": 0.0, "scientific_basis": "case counts cannot be negative"}, ], "assumptions": ["closed population of 1000", "homogeneous mixing"], })

result = simulate_model(model, t_span=(0.0, 30.0), points=4) print(f"status: {result['status']}") print(f"solver: {result'solver'} / {result'solver'}") print(f"days: {result['time']}") print(f"infected: {round(v, 3) for v in result['states']}") print(f"checks: {result'validation'} ({len(result'validation')} of them)")

Real output, and byte-identical to python examples/quickstart_sir.py:

status: PASS

solver: scipy / DOP853 days: [0.0, 10.0, 20.0, 30.0] infected: [10.0, 65.393, 239.869, 290.024] checks: PASS (25 of them)

CLI in five minutes

Every command prints JSON you can pipe.

# What is actually installed, and is it usable? Backends report honestly.

axiomize capabilities

Clarify a vague idea before any numbers get committed.

axiomize intake "Reduce traffic congestion in a mid-size city"

Check a model against closed-form theory, not just vibes.

axiomize-validate --model sir --beta 0.3 --gamma 0.1

axiomize-validate output on those inputs:

=== SIR validation ===

horizon = 180 days (final-size theory is the t->infinity limit) R0 = 3.000 (outbreak) Peak infected = 300,465 at day 61.4 Final size (simulated) = 0.9404 Final size (theory) = 0.9405 Theory match = True

--- sanity checks --- population_conserved PASS compartments_nonnegative PASS R_monotonic_increase PASS

The two flags that matter once you leave the reference model are --input-json (the Model IR request as a file) and --approve-heavy (authorizes repeated refinement runs):

# Without --approve-heavy the study is refused rather than run silently.

axiomize model --action numerical-verify --input-json request.json

status: APPROVAL_REQUIRED, study: solver_tolerance_refinement

axiomize model --action numerical-verify --input-json request.json --approve-heavy

status: PASS, uncertainty_separation.numerical: 6.6100987239990846e-11

Step-by-step versions of all of this, with the request files, are in docs/quickstart.md.

Surface map

The engine is 44 importable names (22 modules plus 22 subpackages) behind four interfaces. This README names the whole CLI and the shape of the two servers; the per-module detail belongs in docs/integrations.md.

Console scripts (8)

axiomize subcommands (14)

intake · policy · model · clean-data · compare-runs · solve · fit · validate · tools · capabilities · reproduce · benchmark · serve · mcp

tools and capabilities report backend availability; policy reports what the agent is allowed to spend; reproduce and compare-runs work on stored run directories.

axiomize model --action (16)

MCP and REST

The MCP server exposes 35 tools named axiomize. . Sixteen are axiomize.model_* and follow the model --action values with two differences: axiomize.model_visualize has no CLI action counterpart, and experiment-design is exposed as axiomize.experiment_design rather than a model_* tool. The other nineteen names (intake, solve, simulate, fit_model, validate, cross_validate, sensitivity_analysis, uncertainty_analysis, falsify, compare_models, experiment_design, clean_data, compare_runs, inspect_run, reproduce, get_capabilities, list_tools, select_tools, workflow_policy) cover the surrounding workflow. Enumerate them rather than trusting a list:

axiomize mcp        # stdio transport; send tools/list over stdin

The REST server serves 30 route handlers (26 POST, plus GET /tools, /capabilities, /workflow-policy and /runs/{id}) under a /v1 prefix, on loopback by default:

axiomize serve --port 8765

curl -s http://127.0.0.1:8765/v1/capabilities

Both surfaces are larger than any README can enumerate honestly, which is why the naming convention matters more than the list. Both counts come from the installed handlers.

Model export formats

axiomize model --action export --input-json request.json dispatches on the "format" field. What actually returns PASS for a given model:

LaTeX is not in this dispatch chain. latex, tex and pdf raise ValueError: format must be json, python, yaml, sbml, or cellml. Use axiomize-to-latex on a written report instead.

Content in the repository