alterlab-fluidsim

FluidSim

概要

FluidSim は、高性能な数値流体力学（CFD）シミュレーション向けのオブジェクト指向 Python フレームワークです。FFT を用いた擬スペクトル法で周期領域の方程式を解くソルバーを提供し、Python の使いやすさを保ちながら Fortran/C++ に匹敵する性能を実現します。

このスキルを使用する場面

ユーザーが FluidSim を使って、周期領域における擬スペクトル CFD を実行または解析したい場合に使用します。対象には、2D/3D Navier-Stokes 乱流、成層流や回転流、浅水流のダイナミクス、エネルギースペクトルと空間平均、パラメトリックスイープ、クラスターでの MPI 実行が含まれます。

対象外

シナリオ	代わりに使用
すでに記録された時系列データを対象とした ML（異常検知、分類、予測）	alterlab-aeon
海洋または大気の場のリモートセンシング／衛星検索	alterlab-geomaster
完成したジョブスクリプトを SLURM またはクラウド GPU キューに送信する	alterlab-remote-compute
PDE ベースの CFD ではなく、離散イベントまたは待ち行列シミュレーション	alterlab-simpy

主な強み：

• 複数のソルバー：2D/3D Navier-Stokes、浅水流、成層流
• 高性能：Pythran/Transonic コンパイル、MPI 並列化
• 完全なワークフロー：パラメーター設定、シミュレーション実行、出力解析
• 対話型解析：Python ベースの後処理と可視化

主な機能

1. インストールとセットアップ

適切な機能フラグを指定し、uv を使って fluidsim をインストールします。

# Basic installation
uv pip install fluidsim

# With FFT support (required for most solvers)
uv pip install "fluidsim[fft]"

# With MPI for parallel computing
uv pip install "fluidsim[fft,mpi]"

出力ディレクトリ用の環境変数を設定します（任意）。

export FLUIDSIM_PATH=/path/to/simulation/outputs
export FLUIDDYN_PATH_SCRATCH=/path/to/working/directory

API キーや認証は不要です。

インストール手順と環境設定の全容については、references/installation.md を参照してください。

2. シミュレーションの実行

標準的なワークフローは、次の 5 つのステップで構成されます。

ステップ 1：ソルバーをインポートする

from fluidsim.solvers.ns2d.solver import Simul

ステップ 2：パラメーターを作成して設定する

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 256
params.oper.Lx = params.oper.Ly = 2 * 3.14159
params.nu_2 = 1e-3
params.time_stepping.t_end = 10.0
params.init_fields.type = "noise"

ステップ 3：シミュレーションをインスタンス化する

sim = Simul(params)

ステップ 4：実行する

sim.time_stepping.start()

ステップ 5：結果を解析する

sim.output.phys_fields.plot("rot")
sim.output.spatial_means.plot()

具体例、シミュレーションの再開、クラスターへのデプロイについては、references/simulation_workflow.md を参照してください。

3. 利用可能なソルバー

物理的な問題に応じてソルバーを選択します。

2D Navier-Stokes（ns2d）：2D 乱流、渦のダイナミクス

from fluidsim.solvers.ns2d.solver import Simul

3D Navier-Stokes（ns3d）：3D 乱流、現実的な流れ

from fluidsim.solvers.ns3d.solver import Simul

成層流（ns2d.strat、ns3d.strat）：海洋・大気の流れ

from fluidsim.solvers.ns2d.strat.solver import Simul
params.N = 1.0  # Brunt-Väisälä frequency

浅水流（sw1l）：地球物理学的な流れ、回転系

from fluidsim.solvers.sw1l.solver import Simul
params.f = 1.0  # Coriolis parameter

ソルバーの一覧と選択の指針については、references/solvers.md を参照してください。

4. パラメーター設定

パラメーターは階層構造で整理されており、ドット記法でアクセスします。

領域と解像度：

params.oper.nx = 256  # grid points
params.oper.Lx = 2 * pi  # domain size

物理パラメーター：

params.nu_2 = 1e-3  # viscosity
params.nu_4 = 0     # hyperviscosity (optional)

時間積分：

params.time_stepping.t_end = 10.0
params.time_stepping.USE_CFL = True  # adaptive time step
params.time_stepping.cfl_coef = 0.5

初期条件：

params.init_fields.type = "noise"  # or "dipole", "jet", "constant", "from_file", "from_simul", "in_script"

出力設定：

params.output.periods_save.phys_fields = 1.0  # save every 1.0 time units
params.output.periods_save.spectra = 0.5
params.output.periods_save.spatial_means = 0.1

Parameters オブジェクトは入力ミスに対して AttributeError を発生させるため、設定ミスを見逃すことがありません。

パラメーターの詳細なドキュメントについては、references/parameters.md を参照してください。

5. 出力と解析

FluidSim は複数の種類の出力を生成し、シミュレーション中に自動で保存します。

物理場：速度と渦度は state_phys_t*.nc（NetCDF-4/HDF5）として保存されます。 ns2d のキーは ux、uy、rot で、ns2d.strat では b も含まれます。

sim.output.phys_fields.plot("rot")
sim.output.phys_fields.plot("ux")

空間平均：体積平均量の時系列

sim.output.spatial_means.plot()

スペクトル：エネルギースペクトルとエンストロフィースペクトル

sim.output.spectra.plot1d()
sim.output.spectra.plot2d()

以前のシミュレーションを読み込む：

from fluidsim import load_sim_for_plot
sim = load_sim_for_plot("simulation_dir")
sim.output.phys_fields.plot()

高度な可視化：3D 可視化には、state_phys_t*.nc ファイルを ParaView または VisIt で開きます。

詳細な解析ワークフロー、パラメトリックスタディの解析、データのエクスポートについては、references/output_analysis.md を参照してください。

6. 高度な機能

カスタム強制：乱流を維持したり、特定のダイナミクスを駆動したりします

params.forcing.enable = True
params.forcing.type = "tcrandom"  # time-correlated random forcing
params.forcing.forcing_rate = 1.0

カスタム初期条件：スクリプトで場を定義します

params.init_fields.type = "in_script"
sim = Simul(params)
X, Y = sim.oper.XX, sim.oper.YY  # local physical grid
rot = np.sin(X) * np.sin(Y)          # ns2d evolves the vorticity "rot"
sim.state.init_from_rotfft(sim.oper.fft2(rot))  # sets rot_fft and derives ux, uy
sim.time_stepping.start()

MPI 並列化：複数のプロセッサーで実行します

mpirun -np 8 python simulation_script.py

パラメトリックスタディ：異なるパラメーターで複数のシミュレーションを実行します

for nu in [1e-3, 5e-4, 1e-4]:
    params = Simul.create_default_params()
    params.nu_2 = nu
    params.output.sub_directory = f"nu{nu}"
    sim = Simul(params)
    sim.time_stepping.start()

強制の種類、カスタムソルバー、クラスターへのジョブ投入、性能最適化については、references/advanced_features.md を参照してください。

一般的なユースケース

2D 乱流の研究

from fluidsim.solvers.ns2d.solver import Simul
from math import pi

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 512
params.oper.Lx = params.oper.Ly = 2 * pi
params.nu_2 = 1e-4
params.time_stepping.t_end = 50.0
params.time_stepping.USE_CFL = True
params.init_fields.type = "noise"
params.output.periods_save.phys_fields = 5.0
params.output.periods_save.spectra = 1.0

sim = Simul(params)
sim.time_stepping.start()

# Analyze energy cascade
sim.output.spectra.plot1d(tmin=30.0, tmax=50.0)

成層流シミュレーション

from fluidsim.solvers.ns2d.strat.solver import Simul
import numpy as np

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 256
params.N = 2.0  # stratification strength (Brunt-Vaisala frequency)
params.nu_2 = 5e-4
params.time_stepping.t_end = 20.0

# Initialize with dense layer
params.init_fields.type = "in_script"
sim = Simul(params)
X, Y = sim.oper.XX, sim.oper.YY  # local physical grid
b = sim.state.state_phys.get_var("b")
b[:] = np.exp(-((X - 3.14)**2 + (Y - 3.14)**2) / 0.5)
# Sync spectral state FROM the physical field just set (not the reverse)
sim.state.statespect_from_statephys()

sim.time_stepping.start()
sim.output.phys_fields.plot("b")

MPI を使用した高解像度 3D シミュレーション

from fluidsim.solvers.ns3d.solver import Simul

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = params.oper.nz = 512
params.nu_2 = 1e-5
params.time_stepping.t_end = 10.0
params.init_fields.type = "noise"

sim = Simul(params)
sim.time_stepping.start()

次のコマンドで実行します：

mpirun -np 64 python script.py

テイラー・グリーン渦の検証

from fluidsim.solvers.ns2d.solver import Simul
import numpy as np
from math import pi

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 128
params.oper.Lx = params.oper.Ly = 2 * pi
params.nu_2 = 1e-3
params.time_stepping.t_end = 10.0
params.init_fields.type = "in_script"

sim = Simul(params)
X, Y = sim.oper.XX, sim.oper.YY  # local physical grid
ux = np.sin(X) * np.cos(Y)
uy = -np.cos(X) * np.sin(Y)
rot = 2 * np.sin(X) * np.sin(Y)   # vorticity d(uy)/dx - d(ux)/dy
# Set the physical state, then compute the spectral state FROM it
# ns2d keys are ux, uy, rot; the solver's spectral state is rot_fft, which
# statespect_from_statephys computes from `rot` — so rot must be set too
sim.state.init_statephys_from(ux=ux, uy=uy, rot=rot)
sim.state.statespect_from_statephys()

sim.time_stepping.start()

# Validate energy decay. spatial_means.load() returns a dict of numpy
# arrays keyed by "t", "E", etc. (NOT a pandas DataFrame).
data = sim.output.spatial_means.load()
t, E = data["t"], data["E"]
# Compare E(t) decay with the analytical Taylor-Green solution

クイックリファレンス

ソルバーをインポート：from fluidsim.solvers.ns2d.solver import Simul

パラメーターを作成：params = Simul.create_default_params()

解像度を設定：params.oper.nx = params.oper.ny = 256

粘性を設定：params.nu_2 = 1e-3

終了時間を設定：params.time_stepping.t_end = 10.0

シミュレーションを実行：sim = Simul(params); sim.time_stepping.start()

結果をプロット：sim.output.phys_fields.plot("rot")

シミュレーションを読み込み：sim = load_sim_for_plot("path/to/sim")

リソース

ドキュメント：https://fluidsim.readthedocs.io/ （fluidsim 0.9.0、Python ≥ 3.11 で検証済み）

リファレンスファイル：

• references/installation.md：インストール手順の完全版
• references/solvers.md：利用可能なソルバーと選択ガイド
• references/simulation_workflow.md：ワークフローの詳細な例
• references/parameters.md：パラメーターの包括的なドキュメント
• references/output_analysis.md：出力の種類と解析方法
• references/advanced_features.md：強制、MPI、パラメトリックスタディ、カスタムソルバー

AlterLab Academic Skills スイートの一部です。