Docker + Fortran + Rust + Python + MLflow でつくる共通シミュレーション実行基盤 r003 ― MLflowでRunを比較・検証する
はじめに
r001では、Rust APIからFortranの数値計算を呼び出し、結果をMLflowのRunへ記録するところまで作りました。
r002では、そのRunをWeb画面から選択し、最大流動深と堆積範囲をOpenLayersで表示できるようにしました。
ここまでで「計算して、結果を見る」ことはできます。しかし、条件を少しずつ変えて計算を繰り返すようになると、それだけでは足りなくなります。
例えば、土石流の流速や堆積率を変えて10回計算したとします。Run一覧だけでは、どの条件を変更し、結果がどの程度変化し、どの計算が確認済みなのかを把握しづらくなります。
そこでr003では、実DEMへの対応よりも先に、MLflowのRunを比較・検証する機能を追加しました。
今回扱うのは、次の3点です。
- 計算が終わったら、格子や収支の検査を自動で行う。
- その検査結果を、元のMLflow Runへ記録する。
- 2つのRunを選び、条件・指標・地図を並べて比較する。
Fortran側の数値計算やr002のmanifest.jsonは変更しません。新しい処理はPython、Rust API、Web画面へ追加します。
1. r002とr003の違い
r002では、1つのRunを選択すると結果地図が表示されました。
r003では、その後ろに「検証」と「比較」の処理を追加します。
重要なのは、検証処理をFortranへ入れないことです。
Fortranは従来どおり計算に専念させます。計算結果の点検はPythonで行い、MLflowへ記録する処理はRust Workerが担当します。
| 構成要素 | r003での役割 |
|---|---|
| Fortran | 最大流動深などの数値計算。r002から変更なし |
| Python | 後処理に加え、自動検証と実行物ハッシュの取得 |
| Rust | Run実行、MLflowとの連携、比較API |
| MLflow | Runの条件、指標、品質判定、成果物を保存 |
| OpenLayers | Run A/Bを並べて地図表示 |
この分離なら、後から別のSolverを追加するときも、品質基準をそのSolver用に追加する形へ発展させられます。ただし、今回のr003が対応するSolverはDebris Flowのサンプルだけです。
2. 計算が終わったら自動検証する
r002の後処理は、次の成果物を生成していました。
result/
├── result.json
└── map/
├── manifest.json
├── terrain.png
├── max_depth.png
└── deposition_area.geojson
r003ではresult/validation.jsonを追加します。
result/
├── result.json
├── validation.json # 今回追加
└── map/
├── manifest.json
├── terrain.png
├── max_depth.png
└── deposition_area.geojson
新しいpython/validate_run.pyでは、次の内容を確認しています。
| 確認項目 | 具体的な検証 |
|---|---|
| 入力・結果ファイル | Run条件、正規化入力、結果JSON、manifestの存在 |
| 格子 | nx・ny、セルサイズ、CSV配列の形状 |
| 数値 | NaN・Inf、負値の有無 |
| 最大流動深 | 各セルの最大流動深が最終流動深以上か |
| 地図定義 | extentと格子サイズ、必須レイヤーの整合 |
| 水・土砂量収支 | 設定した誤差閾値を超えていないか |
| 出力サマリ | CSVの最大値と結果指標の整合 |
検証結果は、例えば次のようになります。
{
"schema_version": "r003-validation-v1",
"status": "PASS",
"criteria_version": "r003-criteria-v1",
"metrics": {
"validation_passed_checks": 18.0,
"validation_total_checks": 18.0,
"validation_pass_rate": 1.0
}
}
実際のvalidation.jsonには、各項目のPASS / FAIL、チェック時の値、閾値、ファイルのSHA-256なども保存されます。
判定基準はJSONに分離する
config/validation/debris_flow.jsonの内容を抜粋します。
{
"schema_version": "r003-criteria-v1",
"solver": "debris_flow",
"mass_balance_error_abs_max": 0.001,
"negative_tolerance": 1e-10,
"maximum_final_depth_tolerance": 1e-8
}
ここで設定している0.001という値は、今回の合成格子サンプルを検証するための例です。実際の河川計算や土石流解析へ、そのまま適用することは想定していません。
数値計算の検証基準には、対象現象と数値モデルに応じた根拠が必要です。r003では、その基準をソースに埋め込まず、外から定義できるようにした点が重要です。
3. 実行成功と、品質検証の合格は別にする
今回は、ここを分けて考えることにしました。
例えばFortranが最後まで計算し、ファイルを正常に生成したとします。しかし、その結果の収支誤差が設定した閾値を超えていた場合、「計算の実行」は成功していますが、「結果の品質確認」は不合格です。
これをMLflowでは、次のように記録します。
| 内容 | 記録場所 | 値の例 |
|---|---|---|
| 実行状態 | Run info / sim.status
|
FINISHED / completed
|
| 品質判定 | sim.validation.status |
PASS / FAIL
|
| 合格項目数 | Metric | validation_passed_checks=18 |
| 検証項目数 | Metric | validation_total_checks=18 |
| 収支誤差絶対値 | Metric | validation_mass_balance_abs=2.95e-6 |
| 検証詳細 | Artifact | result/validation.json |
こうしておけば、計算できなかったRunと、計算できたが品質上の問題が残るRunを区別できます。
なお、CSVに異常値が含まれるなどしてr002の後処理が失敗した場合は、これまでどおりRunをFAILEDとします。validation.jsonは後処理が完了したRunについて生成されます。
4. 再現性のためにハッシュを残す
条件を変えて多数の計算を行うと、パラメータだけでなく、使用した実行ファイルや前後処理コードの違いも影響します。
そのためr003では、次のSHA-256を記録するようにしました。
Run
├── request/run.json → sim.request.sha256
├── input/normalized.json → sim.input.sha256
├── Fortran実行バイナリ → sim.solver.sha256
├── Python後処理コード → sim.adapter.sha256
└── 検証ルールJSON → sim.validation.rules.sha256
例えば、同じ計算条件でもFortran実行ファイルのハッシュが違えば、同一の実行環境とは言えません。
ただし、SHA-256が一致することだけで計算の完全な再現性が保証されるわけではありません。コンパイラ、OS、CPU/GPU環境、使用ライブラリなどの記録は今後の課題です。
5. Rust APIにRun比較を追加する
r002には次のAPIがありました。
POST /api/v1/runs
GET /api/v1/runs
GET /api/v1/runs/{run_id}
GET /api/v1/runs/{run_id}/map/manifest
GET /api/v1/runs/{run_id}/map/{asset}
r003では、この2つを追加します。
GET /api/v1/runs/{run_id}/validation
GET /api/v1/runs/compare?run_a={A}&run_b={B}
/validationはresult/validation.jsonを返します。以前のr002 Runにはまだこのファイルがないため、その場合は404となり、画面では「未評価」と表示します。
/compareは、MLflowへ登録されているParametersとMetricsを取得し、差分表を返します。
{
"schema_version": "r003-compare-v1",
"metrics": [
{
"key": "max_deposition",
"a": 0.0141826735,
"b": 0.017374125403,
"delta_b_minus_a": 0.003191451903
}
]
}
これは説明用に主要フィールドを抜粋したものです。実際のAPIではほかのMetricsと入力パラメータの差、比較条件の注意も返します。
重要なのは、数値の差を出すことと、意味のある比較かどうかを判断することを分けることです。
今回は同じSolver、同じ格子、同じ計算ケース、同じ座標範囲かを確認します。違いがあれば警告を表示します。たとえ数値が近くても、計算条件や指標の定義が違えば、そのまま良し悪しを判断できないためです。
6. OpenLayersの比較画面を追加する
r002の3列レイアウトを引き継いでいます。
左側でRun Aを選び、別のRunをBに設定すると、中央に2つの地図を並べて表示します。右側には、検証状況とMetricsの差分表を追加しました。
図3は画面構成を説明するイメージ図です。 図中の地形・色分け・数値・差分地図は説明用の例であり、r003の実行結果ではありません。r003で実装しているのは2つの地図の並列表示とMetricsの差分表で、画素単位の差分地図やRMSEの自動計算ではありません。
地図の表示方法はr002と同じです。
Run A/Bを選択
↓
各Runのmanifest.jsonを取得
↓
terrain.png / max_depth.png
↓
deposition_area.geojson
↓
OpenLayersで2枚の地図を表示
今回の地図は、まだSIM:LOCALの合成格子です。また、2つの地図の画素単位の差分画像は作成していません。今回は条件・指標の比較と、目視での地図比較までに限定しています。
7. Docker Composeの構成は変えない
新しいコンテナは増やしていません。
Browser :8080
↓
Nginx / OpenLayers
↓ /api/
Rust API :8000
├── MLflow :5000
└── Queue / Worker
↓
Python前処理
↓
Fortran Solver
↓
Python後処理
↓
Python自動検証 ← r003追加
↓
MLflow記録
compose.yamlでは、r002のMLflowデータと実行結果を引き続き使用できるように、プロジェクト名をsimulation_platform_r002へ固定しています。
ただし、r002を-pなどで別のプロジェクト名として起動していた場合は、その名前に合わせる必要があります。更新前にはデータベースと保存ボリュームをバックアップしてください。
MLflowのExperiment名も、今回はdebris-flow-r002のままにしています。既存Runと新しいRunを同じ一覧で扱うためです。
8. 実行してみる
r003のソースファイル一式はZIPにまとめ、次のURLに置いています。ダウンロードして、実行やコードの確認に活用してください。
これまでのr002の配布形式と同様に、非公開Fortranソースは含めず、r002で配布済みの実行バイナリを利用しています。
unzip simulation_platform_r003.zip
cd simulation_platform_r003
docker compose up -d --build
起動後のアクセス先はこれまでと同じです。
Web http://localhost:8080
Rust API http://localhost:8000
MLflow http://localhost:5000
比較用の2件を登録します。
bash scripts/run_compare_samples.sh
Run Aはr002と同じ設定です。Run Bは次の2項目だけを変えています。
{
"flow_speed_ms": 1.2,
"deposition_rate": 0.0012
}
このJSONはnumerics内の変更値だけの抜粋です。完全なリクエストはsamples/debris_flow_run_b.jsonを参照してください。
Run IDが表示され、両Runの検証が完了したらWebを開きます。
9. サンプルで確認した結果
今回、r002で使っていたFortran実行バイナリを使い、Python前処理・Fortran計算・Python後処理・Python自動検証までをローカルで実行しました。
| 項目 | Run A | Run B |
|---|---|---|
| 最大流動深(m) | 0.15837372 | 0.15837372 |
| 最大堆積厚(m) | 0.01418267 | 0.01737413 |
| 最大流速(m/s) | 1.0 | 1.2 |
| 収支誤差 | 2.95×10⁻⁶ | 2.56×10⁻⁶ |
| 自動検証 | PASS(18/18) | PASS(18/18) |
パラメータを変えた結果、堆積厚と流速に違いが出ています。ただし、ここで見ているのは2つの計算結果の差であって、観測値に近いかどうかではありません。
Pythonの単体テストは6件PASSし、JavaScriptの構文検査もPASSしました。
なお、この作業環境にはRustとDockerの実行環境がないため、Rustのビルド、Vite本番ビルド、Docker Composeを通したWeb画面までの統合試験は未実施です。実機ではZIP内のVALIDATION.mdに沿って確認してください。
10. r002の古いRunも検証できるようにした
既存のr002 Runが同じMLflowデータベースと/workボリュームに残っている場合、保存済みの結果から検証レポートを作成できます。
bash scripts/backfill_validation.sh <RUN_ID>
この処理では、既存のRun IDは変更しません。評価結果のMetricsとTagsを同じRunへ追加します。
注意点として、過去のRunの当時のSolverバイナリを再現したわけではありません。保存済みの結果を現在の品質ルールで判定するだけなので、過去の実行バイナリのSHA-256を後付けで推測することはしていません。
11. 今回のポイント
MLflowにはもともとRun比較や検索の機能があります。今回はそれを置き換えるために別のDBを作ったわけではありません。
Web側にはシミュレーションの地図があり、Rust側にはRunの実行制御があります。MLflow側に計算条件や評価指標が集約されているなら、それらを利用して比較画面を作れるということです。
今回も役割を混ぜないようにしました。
Fortran
計算する
Python
結果を変換・検証する
MLflow
計算条件・評価結果・成果物を記録する
Rust
実行要求とRunの比較情報を配信する
OpenLayers
2つの計算結果を表示する
r003で一番変わったのは、結果を保存するだけでなく、品質判定と比較の情報を次の検討に使える形で残せるようになったことです。
12. 次のステップ
次は、結果の比較から一歩進めて、条件を自動的に変えながら計算する仕組みを検討します。
例えば、同じ入力地形で流速・堆積率などを変更して複数Runを作り、ある評価指標を小さくする設定を探索します。この部分にはOptunaなどを使えます。
ただし、最適化する指標を何にするかは重要です。観測値がある場合は観測値との誤差を使えますが、今回の合成サンプルでは物理現象への精度を評価できません。r004では、まず合成的な目的関数で実行管理の仕組みを検証し、その後に実データへ進める予定です。
実DEM・GeoTIFF・COG・PostGISへの対応、複数SolverのRegistry化は、共通基盤を拡張する別の段階として扱います。



