tellurium

Tellurium 反応速度実験

使用する場面

このスキルは、ローカルモデルから得られる決定論的な反応ネットワークの軌跡と、独立したパラメータ条件に使用します。ヘルパーは SBML の一貫性チェック、CVODE 積分、および実際の COMBINE アーカイブのリプレイを実行します。記録されていないノートブックの状態を引き渡すのではなく、各条件の正確な SBML と SED-ML 実験をエクスポートします。

ランタイム

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 を設定できます。ヘルパーによってプロットウィンドウが開かれることはありません。

固定された 6 つのリリースは、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 秒まで実行します。 スキルディレクトリから、インタープリターを上記で作成した環境に向けます。

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 のアルゴリズムとパラメーター定義