CFD FastAPI Server

將 2D 翼型空氣動力分析包裝成一般 FastAPI HTTP API，讓前端、腳本或其他服務可以直接呼叫完整的「幾何 → 網格 → 求解 → 後處理 → 視覺化」流程。

Client ──▶ FastAPI Server ──▶ aerosandbox / NeuralFoil / SU2
                              └─▶ Cp 分布 / 極曲線 / dashboard / artifact downloads

功能

API	功能
POST /api/geometry/airfoil	從 NACA 4/5 位數代碼生成翼型座標 (.dat)
POST /api/meshes/2d	生成 2D 網格，支援 placeholder 與 SU2/Gmsh
POST /api/solver/run	執行 NeuralFoil，或提交非同步 SU2 求解
GET /api/solver/results/{job_id}	查詢 job 狀態；完成後回傳 CL / CD / CM / Cpmin / 轉捩點
POST /api/workflow/airfoil	一次完成 geometry -> mesh -> solver；SU2 只提交背景求解
POST /api/visualizations	生成視覺化 artifact metadata
GET /artifacts/{artifact_id}	在瀏覽器 inline 預覽視覺化圖檔
GET /artifacts/{artifact_id}/download	下載視覺化圖檔
/mcp/	Streamable HTTP MCP endpoint，提供同一套 CFD workflow tools

視覺化模式

plot_kind	內容
summary	翼型形狀 + 結果數字
cp	沿翼型表面真 Cp 分布
polar	CL/CD vs alpha 雙軸極曲線
drag_polar	CL vs CD 拖力極曲線
mesh	網格預覽圖
dashboard	綜合 dashboard 與網格預覽
mach	馬赫數分佈圖 (SU2)
pressure	壓力分佈圖 (SU2)

POST /api/visualizations 會回傳：

{
  "status": "success",
  "summary": "...",
  "artifact": {
    "artifact_id": "vis_abc123",
    "filename": "dashboard_vis_abc123.jpg",
    "mimeType": "image/jpeg",
    "size_bytes": 170868
  }
}

圖檔不直接塞進 JSON body，而是落地成 artifact。用回傳的 artifact_id 組 GET /artifacts/{artifact_id} 在瀏覽器預覽，或組 GET /artifacts/{artifact_id}/download 下載。

HTTP API 只回傳資源 id，不回傳伺服器端檔案路徑。手動流程請依序傳遞 geometry_id、mesh_id、job_id、artifact_id。

SU2 求解是非同步工作。POST /api/solver/run 或 POST /api/workflow/airfoil 使用 solver_backend="su2" 時會回傳 status: "submitted" 與 job_id；之後用 GET /api/solver/results/{job_id} 輪詢，直到狀態變成 converged 或 failed。NeuralFoil surrogate 仍同步回傳結果。

快速開始

環境需求

• Python 3.11+
• uv

本機啟動

uv sync
uv run python -m cfd_server

啟動後可用：

• Swagger UI: http://localhost:8765/docs
• OpenAPI: http://localhost:8765/openapi.json
• Health check: http://localhost:8765/healthz
• MCP endpoint: http://localhost:8765/mcp/

執行測試

uv run --group dev pytest

Docker

docker build -t cfd-server:su2-local .
docker run --rm -p 8765:8765 -v "$PWD/jobs:/app/jobs" cfd-server:su2-local

檢查 SU2 與 Gmsh：

docker run --rm cfd-server:su2-local SU2_CFD --help
docker run --rm cfd-server:su2-local gmsh --version

Docker Compose

docker compose up --build cfd-server

API 範例

建立翼型

curl -X POST http://localhost:8765/api/geometry/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "chord_length": 1.0,
    "n_points_per_side": 180,
    "normalize_geometry": true
  }'

一鍵工作流

curl -X POST http://localhost:8765/api/workflow/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "velocity": 30.0,
    "angle_of_attack": 5.0,
    "solver_backend": "neuralfoil"
  }'

SU2 一鍵工作流會先產生 SU2/Gmsh mesh，然後提交背景求解：

curl -X POST http://localhost:8765/api/workflow/airfoil \
  -H "content-type: application/json" \
  -d '{
    "naca_code": "0012",
    "velocity": 30.0,
    "angle_of_attack": 5.0,
    "mesh_format": "su2",
    "solver_backend": "su2",
    "max_iterations": 500
  }'

查詢背景求解：

curl http://localhost:8765/api/solver/results/06936164e5a7

視覺化

curl -X POST http://localhost:8765/api/visualizations \
  -H "content-type: application/json" \
  -d '{
    "job_id": "06936164e5a7",
    "plot_kind": "dashboard",
    "image_format": "jpeg"
  }'

MCP

這個服務現在同時提供 Streamable HTTP MCP，直接重用現有 service layer，不需要另外維護第二套 CFD 邏輯。

MCP tools:

• generate_airfoil_geometry
• generate_2d_mesh
• run_cfd_solver
• check_solver_results
• run_airfoil_workflow
• visualize_cfd_results
• get_visualization_artifact

本機啟動 HTTP + MCP：

uv run python -m cfd_server

用 MCP Inspector 連線：

npx -y @modelcontextprotocol/inspector

連到：

http://localhost:8765/mcp/

如果你要用 stdio 模式直接跑 MCP server：

uv run python -m cfd_server.app.interfaces.mcp.server

測試

• tests/conftest.py: 共用 FastAPI TestClient 與 workflow fixture
• tests/test_http_workflow.py: 幾何、網格、求解、結果查詢、路由註冊
• tests/test_async_su2_solver.py: SU2 非同步提交與狀態轉換
• tests/test_visualization_artifacts.py: artifact metadata 與落地檔案
• tests/test_artifact_download.py: artifact HTTP download endpoint
• tests/test_su2_config.py: SU2 config 單元測試

專案結構

cfd-server/
├── cfd_server/
│   ├── __main__.py
│   ├── app/
│   │   ├── interfaces/
│   │   │   └── http/        # FastAPI app, routers, request schemas
│   │   └── services/        # workflow / visualization service layer
│   ├── server.py            # 相容 wrapper
│   ├── core/
│   ├── mesh/
│   ├── solvers/
│   ├── visualization/
│   └── models/
├── tests/
├── pyproject.toml
├── Dockerfile
└── README.md