FluidSim

FluidSim

概述

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

核心优势：

• 多种求解器：2D/3D Navier-Stokes、浅水方程、分层流
• 高性能：Pythran/Transonic 编译、MPI 并行化
• 完整工作流：参数配置、模拟执行、输出分析
• 交互式分析：基于 Python 的后处理和可视化

核心能力

1. 安装与配置

使用 uv 安装 fluidsim，并添加适当的功能标志：

# 基础安装
uv pip install fluidsim

# 包含 FFT 支持（大多数求解器必需）
uv pip install "fluidsim[fft]"

# 包含 MPI 以支持并行计算
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("vorticity")
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ä 频率

浅水方程 (sw1l)：地球物理流、旋转系统

from fluidsim.solvers.sw1l.solver import Simul
params.f = 1.0  # 科里奥利参数

详见 references/solvers.md 获取完整求解器列表和选择指南。

4. 参数配置

参数按层次组织，通过点号表示法访问：

域和分辨率：

params.oper.nx = 256  # 网格点数
params.oper.Lx = 2 * pi  # 域大小

物理参数：

params.nu_2 = 1e-3  # 粘性系数
params.nu_4 = 0     # 超粘性（可选）

时间步进：

params.time_stepping.t_end = 10.0
params.time_stepping.USE_CFL = True  # 自适应时间步长
params.time_stepping.CFL = 0.5

初始条件：

params.init_fields.type = "noise"  # 或 "dipole", "vortex", "from_file", "in_script"

输出设置：

params.output.periods_save.phys_fields = 1.0  # 每 1.0 时间单位保存一次
params.output.periods_save.spectra = 0.5
params.output.periods_save.spatial_means = 0.1

Parameters 对象会对拼写错误抛出 AttributeError，防止配置错误被静默忽略。

详见 references/parameters.md 获取全面的参数文档。

5. 输出与分析

FluidSim 在模拟过程中自动产生多种输出类型：

物理场：HDF5 格式的速度、涡量

sim.output.phys_fields.plot("vorticity")
sim.output.phys_fields.plot("vx")

空间平均值：体积平均量的时间序列

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 中打开 .h5 文件进行 3D 可视化。

详见 references/output_analysis.md 获取详细分析工作流、参数化研究分析和数据导出。

6. 高级特性

自定义强迫：维持湍流或驱动特定动力学

params.forcing.enable = True
params.forcing.type = "tcrandom"  # 时间相关随机强迫
params.forcing.forcing_rate = 1.0

自定义初始条件：在脚本中定义场

params.init_fields.type = "in_script"
sim = Simul(params)
X, Y = sim.oper.get_XY_loc()
vx = sim.state.state_phys.get_var("vx")
vx[:] = sin(X) * cos(Y)
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()

# 分析能量级串
sim.output.spectra.plot1d(tmin=30.0, tmax=50.0)

分层流模拟

from fluidsim.solvers.ns2d.strat.solver import Simul

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 256
params.N = 2.0  # 分层强度
params.nu_2 = 5e-4
params.time_stepping.t_end = 20.0

# 用密集层初始化
params.init_fields.type = "in_script"
sim = Simul(params)
X, Y = sim.oper.get_XY_loc()
b = sim.state.state_phys.get_var("b")
b[:] = exp(-((X - 3.14)**2 + (Y - 3.14)**2) / 0.5)
sim.state.statephys_from_statespect()

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

高分辨率 3D 模拟（使用 MPI）

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.get_XY_loc()
vx = sim.state.state_phys.get_var("vx")
vy = sim.state.state_phys.get_var("vy")
vx[:] = np.sin(X) * np.cos(Y)
vy[:] = -np.cos(X) * np.sin(Y)
sim.state.statephys_from_statespect()

sim.time_stepping.start()

# 验证能量衰减
df = sim.output.spatial_means.load()
# 与解析解比较

快速参考

导入求解器：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("vorticity")

加载模拟：sim = load_sim_for_plot("path/to/sim")

资源

文档：https://fluidsim.readthedocs.io/

参考文件：

• references/installation.md：完整安装说明
• references/solvers.md：可用求解器和选择指南
• references/simulation_workflow.md：详细工作流示例
• references/parameters.md：全面参数文档
• references/output_analysis.md：输出类型和分析方法
• references/advanced_features.md：强迫、MPI、参数化研究、自定义求解器