tellurium

Tellurium 动力学实验

何时使用

当需要从本地模型获得确定性反应网络轨迹和独立参数条件时，使用本技能。该辅助工具会执行 SBML 一致性检查、CVODE 积分以及实际的 COMBINE 归档重放。它会导出每个条件的精确 SBML 和 SED-ML 实验，而不是交出一个未记录的 notebook 状态。

运行时

uv venv --python 3.11 kinetic-env
uv pip install --python kinetic-env/bin/python tellurium==2.2.13.1 libroadrunner==2.10.0 \
  antimony==3.2.0 python-libsbml==5.21.2 python-libsedml==2.0.34 python-libcombine==0.2.20

完整工作流在 macOS ARM64 上使用这些包运行。它使用 libSEDML 构建 SED-ML，并使用 Tellurium/libCombine 创建归档；本辅助工具不需要 PhraSEDML。无头运行可以设置 MPLBACKEND=Agg。该辅助工具不会打开绘图窗口。

这六个固定版本已于 2026-10-01 根据官方 PyPI 元数据重新核对。RoadRunner 的文档站点仍显示旧版本横幅；下面的求解器设置也已根据已发布的 2.10.0 源码和已安装的原生运行时进行核对。

工作流

1. 检查所提供模型的区室、物种、初始条件、边界物种、反应、参数定义以及规则/事件。识别科学问题，并区分机理动力学模型与通量平衡重建。记录源模型、版本以及任何文献参数；不要将示例模型视为已经过实验校准。
2. 在解释轨迹之前检查单位。SBML 反应速率具有量/时间单位；物种可能具有浓度或量语义。在固定体积的一级模型中，k*A*cell 将浓度依赖关系转换为量/时间。该辅助工具会检查 SBML 一致性并保留所有警告，包括未定义单位。未定义单位会报告为空/无法确定，而不会静默假定为 SI。
3. 按照 references/experiments.md 中描述的 JSON 格式选择浓度输出和实验。时间值使用模型自身的时间单位。经过测试的辅助工具会为 hasOnlySubstanceUnits=false 的物种输出浓度；它拒绝仅量的选择，以避免在 SED-ML 重放期间改变其含义。零维区室和速率规则模型也会被拒绝；后者需要单独的容差工作流，因为 RoadRunner 2.10.0 对标量容差的排序可能与状态不同。
4. 运行基线和所需的恒定全局参数变更。每个场景都从全新的 SBML 模型开始，因此先前的最终浓度不会泄漏到下一个条件中。对物种初始值、区室体积、赋值规则或时变输入的更改需要显式修改模型并进行相应测试；它们不是隐藏在此辅助工具中的参数变更。
5. 检查有限输出、符号、相关守恒关系和时间尺度。当科学解释依赖于微小差异时，通过在更严格容差下重复运行来检查求解器敏感性。平滑曲线或零归档重放误差并不能证明模型有效性或参数可辨识性。切勿裁剪负浓度来掩盖求解器或模型问题。
6. 在 report.json 中查看 COMBINE 重放比较、模型警告和单位。该辅助工具会重放其生成的归档，并将每个选定值与直接轨迹进行比较。交付归档、报告、源模型、实验配置和 CSV 曲线。

运行可执行参考示例

assets/first-order.ant 定义了在恒定 1-L 隔室中的封闭反应 A → B，初始 A=1、B=0 mol/L，k=0.2 每秒。 assets/experiment.json 运行基线和 k=0.4 每秒，时间从 0 到 10 s。 从 skill 目录中，将解释器指向上方创建的环境：

MPLBACKEND=Agg kinetic-env/bin/python scripts/kinetic_experiment.py \
  --model assets/first-order.ant --format antimony --experiment assets/experiment.json \
  --output kinetic-reference

# The SBML branch was also exercised; replace these filenames with actual user inputs.
MPLBACKEND=Agg kinetic-env/bin/python scripts/kinetic_experiment.py \
  --model model.xml --format sbml --experiment experiment.json --output kinetic-analysis

输出目录必须是新的。该参考示例已执行，包括 Antimony 到 SBML 的转换、libSBML 检查、两次直接积分、SED-ML 创建和 COMBINE 重放。两种条件都与解析解 A(t)=exp(-k*t)、B(t)=1-A(t) 在 2e-8 绝对/相对容差内匹配；A+B 在 1e-10 内守恒，且在测试的栈上归档重放与直接输出完全一致。 额外检查使用 5-L 隔室和 10 mol（2 mol/L）的初始量，将每个 SED-ML 物种 XPath 对照其实际 SBML 文件进行解析，并验证求解器容差缩放。 这验证了这个受控示例；任意 SBML 包、事件、延迟或随机模型不在这些测试的覆盖范围内。

产物

文件	内容
baseline.csv、其他情景 CSV	时间和选定的浓度，物种表头带方括号
model_<scenario>.xml	两条执行路径所使用的完全独立的 SBML 条件
experiment.sedml	均匀时间过程、CVODE/容差、模型、任务和输出选择
experiment.omex	这些 SBML 文件加上主 SED-ML 和归档清单
report.json	版本、输入/归档校验和、参数、单位、验证发现、初始状态容差向量、最低浓度和重放差异

报告中的 libSEDML 发现是解析诊断。成功执行和相等性提供了额外证据，表明这个生成的均匀过程实验在 Tellurium 中有效；它们并不证明每个 SED-ML 特性或每个模拟器的兼容性。

在 RoadRunner 2.10.0 中，JSON absolute_tolerance 值是状态/量容差的标量调整因子，不是统一的浓度误差界限。归档将该含义记录为 KISAO:0000571；查看 initial_state_absolute_tolerances 以及 references/experiments.md 中的详细说明。声明的 SBML XPath 命名空间以及显式的刚性/均匀输出设置可防止成功的 Tellurium 重放掩盖缺失的归档上下文。

主要参考

• Tellurium 模型加载和导出方法
• Antimony 单位和反应语义
• Tellurium SED-ML 实现
• SED-ML Level 1 Version 3 规范
• RoadRunner 2.10.0 CVODE 实现
• KiSAO 算法和参数定义