Axiomize

Axiomize

经得起现实检验的可复现科学建模。 Axiomize 将模糊的想法转化为明确且有版本记录的数学模型，通过量纲和数值验证，并导出其他人多年后仍能重新运行的工件。

这不是数值方法库。相关项目请访问 scientific-computing-system。Axiomize 是建模层：强制使用单位、采用有版本记录的 Model IR，并导出为 SBML、CellML 和 Modelica。MCP 服务为 axiomize mcp。

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

当前软件包版本：1.14.2。PyPI 提供 1.14.2；npm 提供 1.14.1。各注册表的可用情况记录在 docs/documentation.md 中；上方徽章为实时数据，且具有权威性。

文档：furox-art.github.io/axiomize · 更新日志：CHANGELOG.md · 路线图：ROADMAP.md · 安全：SECURITY.md · 贡献指南：CONTRIBUTING.md · 行为准则：CODE_OF_CONDUCT.md · 引用：CITATION.cff

为什么

我受够了那些存在于 Jupyter 笔记本中、也终结于 Jupyter 笔记本中的科学模型。

有人编写了一个精妙的模拟程序，它在自己的机器上运行正常；后来此人毕业或换了工作，六个月后就没人能运行它了。依赖项出了问题，数据不见了，而所谓的“文档”只是一个有 47 个单元格、没有任何说明的笔记本。

Axiomize 强制将模型编写为明确、有版本记录且可测试的代码，而不是探索性意大利面条代码。每项假设都有书面记录。每个参数都带有单位。每项结果都包含足够的溯源信息，让其他人能在另一台机器上复现。

适用对象

如果你是……	从这里开始
需要在评审中为结果辩护的科学家	为什么 和示例集
需要估算容量、可靠性或库存的工程师	CLI 快速入门 和 axiomize solve / axiomize fit
正在构建一个应当依据数字而非感觉进行推理的 Agent	axiomize capabilities，然后查看 MCP 或 REST
需要复现或审计他人已发表模型的人	axiomize model --action numerical-verify 和可移植导出

不适合：如果你想要的是无法检查其假设的黑盒预测器，或者需要引擎在没有人在环的情况下替你提出科学主张。

安装

pip install axiomize

可选扩展：运行 pip install "axiomize[full]"，以使用 PyMC/JAX 贝叶斯抽样。

playground 扩展会安装 gradio 和 pandas，但不包含 UI：playground/app.py 不在 wheel 或 sdist 中，因此仅运行 pip install "axiomize[playground]" 只会安装依赖项，却没有可运行的内容。要使用它，请从代码库获取该文件：

git clone https://github.com/Furox-Art/axiomize
pip install "axiomize[playground]"
python axiomize/playground/app.py

五分钟掌握 Python

声明模型，然后让 Axiomize 检查它。单位是必填项，因此量纲错误会明确报出，而不会产生毫无意义的数字。以下代码块是 examples/quickstart_sir.py 中的模型，逐字段对应。

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']['backend']} / {result['solver']['method']}")
print(f"days:   {result['time']}")
print(f"infected: {[round(v, 3) for v in result['states']['I']]}")
print(f"checks: {result['validation']['status']} ({len(result['validation']['checks'])} of them)")

实际输出，与运行 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

每条命令都会输出可通过管道传递的 JSON。

# 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 的输出：

=== 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

离开参考模型后，最重要的两个标志是 --input-json（作为文件提供的 Model IR 请求）和 --approve-heavy（授权执行重复的细化运行）：

# 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

其中所有内容的分步说明及请求文件见 docs/quickstart.md。

功能概览

引擎由 68 个公共模块组成，通过四种接口提供。本 README 列出了完整的 CLI，以及两个服务的概况；各模块的详细信息请参阅 docs/integrations.md。

控制台脚本（8 个）

命令	功能
axiomize	主 CLI。包含以下 14 个子命令。
axiomize-validate	对三个参考模型 sir、gillespie、queue 进行闭式理论检查
axiomize-fit	使用 time,value CSV 对 sir 或 logistic 进行校准；--selftest 会运行内置检查
axiomize-csv-check	检查观测文件的数据质量：缺失、重复项，以及通过修正 z 分数检测异常值
axiomize-benchmark	根据 benchmarks/ideas.json 中的案例对生成的报告进行评分
axiomize-to-latex	将标准化报告转换为 LaTeX，可选使用 --pdf。这是项目中唯一的 LaTeX 路径；它不是模型导出格式。
axiomize-index-reports	根据目录中的报告重建 reports/INDEX.md
axiomize-sweep	并行参数扫描（--job sweep、--job mc）

axiomize 子命令（14 个）

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

tools 和 capabilities 会报告后端的可用情况；policy 会报告 Agent 可使用的资源额度；reproduce 和 compare-runs 用于处理已存储的运行目录。

axiomize model --action（16 个）

类别	值
模型生命周期	plan · validate · simulate · fit · compare · repair · export
分析	stability · validity · discover · experiment-design · uncertainty · bifurcation
验证	numerical-verify · stop-check · surrogate

MCP 和 REST

MCP 服务提供 35 个工具，名称为 axiomize.<verb>。axiomize.model_* 与上方的 model --action 值对应；未加前缀的名称（solve、fit_model、cross_validate、 sensitivity_analysis、uncertainty_analysis、falsify、compare_models、intake、 workflow_policy、clean_data、compare_runs、experiment_design、inspect_run、 reproduce、get_capabilities、list_tools、select_tools）涵盖相关工作流。请枚举工具，而不要只依赖列表：

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

REST 服务在 /v1 前缀下提供 30 个路由处理程序（26 个 POST，另有 GET /tools、/capabilities、 /workflow-policy 和 /runs/{id}），默认绑定到回环地址：

axiomize serve --port 8765
curl -s http://127.0.0.1:8765/v1/capabilities

这两个接口的规模都超出了 README 能如实列举的范围，因此命名惯例比列表更重要。两个计数均来自已安装的处理程序。

模型导出格式

axiomize model --action export --input-json request.json 根据 "format" 字段进行分派。对于给定模型，哪些格式实际会返回 PASS：

格式	状态	说明
json	是	规范模型 IR，键已排序
python	是	可重新运行的脚本，会重新导入 IR
yaml	是	需要 PyYAML；否则返回 TOOL_UNAVAILABLE
ipynb	是	nbformat 4 笔记本
sbml-l3v2	是	SBML Level 3 Version 2 Core
modelica	是	Modelica 3.6 文本
portable-bundle	是	axiomize.portable-bundle.v1，包含基于规范 IR 计算的 SHA-256
graphml	有条件	需要带有 metadata.network 的 family: network IR
causal-dot	有条件	需要带有识别元数据的 family: causal IR
cellml-2.0	有条件	对受支持的单位返回 PASS；对于不会重新解释的单位，会返回并指出其名称的 ADAPTER_REQUIRED
sbml、cellml	否	无版本别名会按设计返回 ADAPTER_REQUIRED

LaTeX 不在此分派链中。latex、tex 和 pdf 会引发 ValueError: format must be json, python, yaml, sbml, or cellml。对于已撰写的报告，请改用 axiomize-to-latex。

仓库中的内容

内容	位置	数量
领域包	packs/	12
视角透镜	skills/axiomize/perspectives/	15
报告模板	skills/axiomize/templates/	5
完整示例	examples/	18 个 .md + quickstart_sir.py
MCP 注册表清单	server.json	1

MCP 注册表会读取 server.json，以发布 axiomize mcp；其中的 mcp-name 行 也会重复显示在本 README 顶部，供抓取该信息的客户端使用。

采用路径

1. 先用你已经认可的内容试用。 使用 axiomize-validate 重建一个你信任的模型。如果引擎与一个你能够证明正确的结果不一致，请就此止步并 提交问题。
2. 将一个实际问题转为 Model IR。 明确声明单位和约束。量纲检查最先体现出价值。
3. 为高成本步骤设置门槛。 离散化模型族会返回 APPROVAL_REQUIRED，直到你通过 --approve-heavy。批准仅授权计算，绝不会禁用资源上限。
4. 导出可移植内容。 axiomize model --action export 会输出规范 IR JSON， 并为受支持的模型输出 SBML、CellML 或 Modelica，因此产物不会因这个库而失效。
5. 将其纳入评审流程。 将导出的 IR 和验证记录与结果一同提交，而不只是提交图表。

实际功能

• 验证量纲一致性，确保你不会把米加到秒上
• 拒绝模拟未通过这些检查的模型：执行时会进行与 axiomize model --action validate 相同的 验证；如果不匹配，会抛出携带失败检查项的 ModelDimensionMismatch，而不是返回数值
• 将科学约束作为有名称、有依据的检查项强制执行，而不是只写在说明文字中
• 在声称结果收敛之前，将数值误差与随机变异分开处理
• 比较候选模型族，并记录选择某个模型族的原因
• 导出为 JSON、Python、YAML、笔记本、SBML Level 3、CellML 2.0、Modelica、GraphML、 Graphviz DOT 和 SHA-256 可移植包；有关哪些格式有条件限制，请参阅格式表 。数值和单位往返转换后位级精确；测试套件会对此进行断言，而不是仅凭假设
• 通过独立流程 axiomize-to-latex 将已撰写的报告转换为 LaTeX
• 维护经过完整性检查的运行日志，以便在使用存储的结果前验证其有效性

诚实的局限

• 它无法让糟糕的模型变好，只会让糟糕的模型明确暴露问题。
• 贝叶斯采样需要 full extra（PyMC/JAX）；FEM 需要 FEniCS/DOLFINx。两者均会报告为不可用，而不会悄悄替换。
• 基准测试结果在盲测中评估报告的结构，而非建模正确性。只有附带脚本、案例集和提交哈希的表格可复现；较早的几轮结果仅作为历史记录保留，无法重新运行。
• 示例使用标记为 lit. / data / est. 的说明性参数范围。示例均未引用外部来源，因此请将这些数字视为阅读材料，而非有文献依据的结果。
• 生成代码的执行和定理的详细推导都不受操作系统沙箱保护。请参阅 SECURITY.md。

文档

• 快速入门和工作流：furox-art.github.io/axiomize
• 示例：示例画廊，或查看 examples/ 中的 19 个文件
• 领域包（各领域适用的视角）： packs/domain-packs.md
• Agent 集成（MCP、REST、CLI）：docs/integrations.md
• 可移植导出格式：docs/portable-export.md
• 信任边界和报告：SECURITY.md、docs/security.md
• Agent 技能包：skills/axiomize/SKILL.md，以及 15 个视角镜头

供应链

PyPI 版本发布时附带 PEP 740 证明：wheel 和 sdist 都提供 Sigstore bundle，通过 release.yml、pypi 环境标明 Furox-Art/axiomize，且每个证明中的摘要都与您下载的文件相符。您可以在安装前进行确认。

npm 版本没有证明：尚未注册 npm 可信发布者，因此 npm tarball 只能验证摘要。当前 npm shim（1.14.1）没有构建证明：

npm view [email protected] dist.integrity   # pin this; npm ci enforces it from a lockfile

有三件不同的事很容易混淆。PEP 740 证明表示某个构建工作流为这个确切的文件摘要签了名。**npm dist.signatures只表示注册表没有篡改自己的元数据——每个 npm 版本都有这些签名，无论使用 token 还是 OIDC，它们都不代表构建来源。dist.integrity / digests.sha256**表示您拿到的字节与已发布的字节相同，但不说明是谁构建的。

目前，诚实的建议是按摘要固定版本。注册 npm 可信发布者（所有者 Furox-Art、仓库 axiomize、工作流 release.yml、环境 npm）即可弥补 npm 的缺口；PyPI 的可信发布者已经注册。验证命令、PyPI 单文件端点的格式，以及这三项分别能证明什么，详见 docs/documentation.md；CI 会在每次运行时针对两个注册表重新检查该文档中的来源声明。

npm

npx axiomize 可以运行，并会转发到 python -m axiomize.cli，因此需要 Python，并且底层需要运行 pip install axiomize；它不是独立二进制文件。npm 1.12.2 已发布但无法使用（index.js 存在语法错误）；1.12.4 是首个可正常运行的版本。

许可证

MIT。随意使用、折腾和修复。