FastAPI / Rust / River 2D Unsteady Flow

Rustで計算し、FastAPIで受け渡す
計算APIデモ

Pythonによる計算処理ではなく、Rust製の計算エンジンで簡易2次元河川不定流を実行し、 FastAPIがJSON入力・JSON出力の橋渡しを行う構成例です。 Web画面、curl、JavaScriptフロントエンドから同じ計算APIを呼び出せます。

ソースを見る API入出力を見る デモ一覧へ戻る
FastAPIとRustの計算API構成図

Overview

FastAPIは入口、Rustは計算エンジン

このデモでは、FastAPIがHTTPリクエストを受け取り、入力JSONをRust CLIへ標準入力で渡します。 Rust側は簡易2次元河川不定流計算を実行し、ハイドログラフ、水深分布、流速分布をJSONで返します。 Python側を薄く保つことで、Web APIとして扱いやすくしながら、計算部をRustで高速化・単体テスト化しやすくします。

Rustで数値計算

水深・流速・ハイドログラフの計算はRustのCLIが担当します。FastAPI側では重い計算を行わず、JSONの受け渡しに徹します。

FastAPIでWeb API化

ブラウザ、curl、JavaScriptフロントエンドからPOSTできるようにし、社内ツールやデモサイトから同じ計算エンジンを呼び出せます。

Docker Composeで動かせる構成

RustをビルドするAPIコンテナと、デモサイトを配信するNginxコンテナをComposeでまとめて起動できます。

River 2D Model

簡易2次元河川不定流計算

サンプル計算では、矩形格子上に河道・堤防・簡易破堤部を作り、上流端から時間変化する流入ハイドログラフを与えます。 セル間の水面勾配とManning式からフラックスを求め、水深を時間更新する簡略モデルです。

厳密な実務ソルバーではありません。API化の考え方、Rust連携、入出力JSON、可視化結果の確認を目的にしたデモです。

簡易2次元河川不定流モデルの処理フロー
FastAPIから受け取った条件をRustで計算し、結果JSONとして返す流れです。

Input

入力データ

  • 格子数 nx, ny と格子間隔 dx, dy
  • 計算時間刻み dt とステップ数 steps
  • Manning粗度係数、河床勾配、初期水深
  • 上流流入ハイドログラフの基底流量・ピーク流量・ピーク時刻
  • 簡易破堤位置、出力間隔、表示用の流速上限

Output

出力結果

  • 上流流入量・下流端流出量のハイドログラフ
  • 最大水深マップ、最終水深マップ
  • 最終流速分布マップ
  • ピーク流量、最大水深、浸水面積などのサマリーJSON

Demo Result Figures

Rust計算エンジンのサンプル結果図

APIレスポンスに含まれるハイドログラフ、水深、流速、地形・水面情報を、デモサイト掲載用に図化したものです。 実運用では、このJSONをフロントエンド側で可視化する構成にできます。

FastAPIとRustを用いた河川2D不定流デモのハイドログラフ
1. 流入・流出ハイドログラフ 上流流入量と下流端流出量を時系列で比較し、計算APIの応答に含める代表的な結果を確認します。
最大水深分布図
2. 最大水深分布 河道から右岸側へ越流・拡散する様子を、最大水深の平面分布として表示します。
最終流速分布図
3. 最終流速分布 計算終了時刻の流速分布を表示し、河道部・破堤部・氾濫域の流れの違いを確認します。
河床高と最終水面コンター図
4. 河床と水面コンター 簡易地形と最終水面コンターを重ね、API入力条件と計算結果の関係を確認します。

Request JSON

API入力例

POST /api/river2d/run に送るJSON例です。

sample_request.jsonJSON

sample_request.json をダウンロード

読み込み中...

Response JSON

API応答例

実際のAPIでは2次元配列の水深・流速マップも返します。ここではページ表示用に要約しています。

sample_response_summary.jsonJSON

sample_response_summary.json をダウンロード

読み込み中...

Run

ローカル実行手順

Rust計算エンジンをビルドしてから、FastAPIを起動します。 Docker Composeを使う場合は、Rustビルド、FastAPI起動、静的デモサイト配信、NginxからAPIへのプロキシをまとめて起動できます。

Docker Composeで起動

# プロジェクト直下で実行
cp .env.example .env   # 任意。ポート変更しない場合は省略可

docker compose up --build

ブラウザ確認

# デモサイト
http://localhost:8080/software/fastapi-demo/

# FastAPI Swagger UI
http://localhost:8080/docs

# FastAPIへ直接アクセス
http://localhost:8000/

API呼び出し

curl -X POST http://localhost:8080/api/river2d/run \
  -H "Content-Type: application/json" \
  --data-binary @public/demo-data/fastapi-rust/data/sample_request.json

停止

docker compose down

# イメージも削除する場合
docker compose down --rmi local

Source Sample

FastAPI・Rustソースサンプル

FastAPIはAPIとブラウザ確認画面、Rustは2次元不定流の簡易計算を担当します。 Docker Compose設定、Nginxプロキシ設定、疎通確認スクリプトも同梱しています。

api/fastapi_rust_river_api.pyFastAPI / Python

fastapi_rust_river_api.py をダウンロード

読み込み中...
rust/river2d_core/src/main.rsRust

main.rs をダウンロード

読み込み中...
compose.yamlDocker Compose

compose.yaml をダウンロード

読み込み中...

References

公式リンク・マニュアル

このデモはFastAPIをAPI層、Rustを計算コアとして分ける構成です。実装時はFastAPIのOpenAPI自動生成、Rust / Cargoのビルド・ドキュメント、Docker Composeの運用方法を確認します。

FastAPI Documentation The Rust Book The Cargo Book Docker Compose Documentation

Note

実務適用時の注意

このデモは「FastAPIで受け渡し、Rustで計算する」構成を説明するための簡易モデルです。 実務の河川不定流解析として使う場合は、境界条件、CFL条件、ウェット・ドライ処理、地形補正、 河道・堤防データの取り込み、観測水位・流量による検証、保存則の厳密性を追加検討してください。