alterlab-fluidsim

FluidSim

概述

FluidSim 是一个面向对象的 Python 框架，用于高性能计算流体动力学（CFD）模拟。它使用基于 FFT 的伪谱方法，为周期域方程提供求解器，性能可媲美 Fortran/C++，同时保留 Python 的易用性。

何时使用此技能

当用户希望使用 FluidSim 运行或分析周期域伪谱 CFD 时，请使用此技能，包括：二维/三维 Navier-Stokes 湍流、分层流或旋转流、浅水动力学、能谱和空间平均、参数扫描，或在集群上运行 MPI。

不适用的场景

场景	改用
对已记录的时间序列进行机器学习（异常检测、分类、预测）	alterlab-aeon
海洋或大气场的遥感/卫星反演	alterlab-geomaster
将完成的作业脚本提交到 SLURM 或云端 GPU 队列	alterlab-remote-compute
离散事件或排队模拟，而非基于 PDE 的 CFD	alterlab-simpy

主要优势：

• 多种求解器：二维/三维 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. 运行模拟

标准工作流包含五个步骤：

步骤 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. 可用求解器

根据物理问题选择求解器：

二维 Navier-Stokes（ns2d）：二维湍流、涡旋动力学

from fluidsim.solvers.ns2d.solver import Simul

三维 Navier-Stokes（ns3d）：三维湍流、真实流动

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()

高级可视化：在 ParaView 或 VisIt 中打开 state_phys_t*.nc 文件进行三维可视化。

详细的分析工作流、参数研究分析和数据导出请参阅 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

Taylor-Green 涡验证

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 套件。