fluidsim

FluidSim

将 FluidSim 0.9.0 用作以 Python 定义的数值求解器框架，尤其适用于周期笛卡尔伪谱 CFD。上游 FluidSim 采用 CeCILL-2.1 许可证；MIT 前置元数据中的许可证仅适用于此技能。

此技能不会将运行完成、时间步稳定、图表平滑或程序正常退出视为数值收敛或物理有效性的证据。

必需工作流

1. 说明方程、单位或无量纲化方式、几何形状、边界条件、初始条件、强迫项、观测量和验收标准。
2. 选择经过验证的求解器，并检查其生成的默认参数。
3. 创建严格的 JSON 计划，明确限定 CPU、RAM、磁盘、运行时长、输出文件、时间步长、CFL、分辨率和去混叠范围。
4. 运行随附的验证器和资源估算器。
5. 生成并审查试运行脚本。除非使用明确的配置 ID 确认执行，否则脚本不会执行任何操作。
6. 运行一次极小规模的串行试运行。检查预算、散度／约束、谱尾部、CFL／时间步历史记录和输出增长情况。
7. 分别细化网格和时间步长。检查守恒／预算残差和观测量敏感性。
8. 仅在此之后准备特定站点的 MPI 作业。绝不自动提交或启动 MPI。
9. 保存配置、脚本、uv.lock、软件包／平台／后端版本、日志、输出清单、校验和及重启沿袭信息。

如果缺少物理假设、单位、边界条件、强迫项语义、分辨率标准、资源限制或验收标准，请停止。

版本与安装

截至 2026-07-23 已验证：

• PyPI 最新稳定版：fluidsim==0.9.0（2025-12-04）。
• 软件包元数据要求 Python >=3.11，并列出 Python 3.11–3.14。
• 创建伪谱参数需要 FluidFFT；在冒烟测试中可以导入基础版 fluidsim，但安装 fft extra 之前，ns2d.create_default_params() 会失败。
• 此处测试的当前配套版本：fluidfft==0.4.5 和 pyFFTW==0.15.1。

优先使用项目锁文件：

uv init --python 3.11
uv add "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"
uv lock
uv sync --frozen

对于隔离的一次性环境：

uv venv --python 3.11
uv pip install "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"

项目锁文件是可复现性记录；仅指定直接依赖的版本并不能锁定所有传递依赖制品。请勿在不兼容的平台或 MPI ABI 之间复用锁文件。

MPI 是可选的原生组件：

uv add "mpi4py==4.1.2" "fluidfft-mpi-with-fftw==0.0.1" "fluidfft-fftwmpi==0.0.1"
uv lock

这些软件包仍然需要兼容的 MPI 运行时和 FFTW 开发库。可选的原生插件包括：

• fluidfft-fftw==0.0.1：串行 fft2d.with_fftw1d、fft2d.with_fftw2d、fft3d.with_fftw3d。
• fluidfft-mpi-with-fftw==0.0.1：MPI fft2d.mpi_with_fftw1d、fft3d.mpi_with_fftw1d。
• fluidfft-fftwmpi==0.0.1：支持 MPI 的 FFTW fft2d.mpi_with_fftwmpi2d、fft3d.mpi_with_fftwmpi3d。
• fluidfft-p3dfft==0.0.1：fft3d.mpi_with_p3dfft；需要 P3DFFT。
• FluidFFT 还声明了 PFFT 和 P3DFFT extras；请针对目标集群审查并锁定其原生依赖栈。

FluidFFT 的文档曾提及 cuFFT，但 FluidFFT 0.4.5 的软件包元数据未声明 CUDA extra 或已安装的 GPU 插件，其 CUDA 安装页面也尚未完成。不要声称支持 GPU 加速，也不要将无关的 CUDA wheel 安装为 FluidSim 后端。请将 GPU 工作视为需要单独验证的源码级实验性集成。

请参阅安装，了解系统依赖、MPI ABI、HDF5-MPI、后端发现和验证。

API 快照

使用直接的版本化导入：

from fluidsim.solvers.ns2d.solver import Simul

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 32
params.oper.Lx = params.oper.Ly = 2 * 3.141592653589793
params.oper.coef_dealiasing = 2 / 3
params.time_stepping.USE_CFL = True
params.time_stepping.cfl_coef = 0.5
params.time_stepping.deltat0 = 0.001
params.time_stepping.deltat_max = 0.01
params.time_stepping.t_end = 0.1
params.time_stepping.max_elapsed = "00:05:00"
params.init_fields.type = "noise"
params.init_fields.noise.velo_max = 0.01
params.output.HAS_TO_SAVE = False
params.output.ONLINE_PLOT_OK = False

0.9 版的重要修正：

• CFL 字段：params.time_stepping.cfl_coef，而非 CFL。
• 时间相关强迫： params.forcing.tcrandom.time_correlation，而非扁平字段 tcrandom_time_correlation。
• NS2D 默认初始类型包括 constant、noise、jet、dipole、 from_file、from_simul 和 in_script；不要为 每个求解器臆造一个通用列表。
• 输出状态文件默认为 state_phys_t*.nc；频谱使用 spectra1D.h5/spectra2D.h5；标量平均值因求解器而异，使用 spatial_means.txt 或 JSON Lines 格式。
• params.output.sub_directory 是相对于 FLUIDSIM_PATH 的路径。

ParamContainer 会拒绝未声明的属性。始终根据所选 Simul 类生成默认值， 并在修改前检查这些默认值。参见 参数。

求解器

主要的笛卡尔 CFD 键和导入：

from fluidsim.solvers.ns2d.solver import Simul       # ns2d
from fluidsim.solvers.ns2d.bouss.solver import Simul # ns2d.bouss
from fluidsim.solvers.ns2d.strat.solver import Simul # ns2d.strat
from fluidsim.solvers.ns3d.solver import Simul       # ns3d
from fluidsim.solvers.ns3d.bouss.solver import Simul # ns3d.bouss
from fluidsim.solvers.ns3d.strat.solver import Simul # ns3d.strat

0.9 版注册表还包含 plate2d、sw1l 变体、waves2d、1D 模型、 0D 模型、球面求解器和框架适配器。求解器出现在注册表中，并不意味着它 适用于某个科学问题。请在求解器源代码中核实方程、变量、几何、边界条件和 诊断项。参见求解器。

强迫与时间推进

强迫因求解器而异。当前规范化随机示例如下：

params.forcing.enable = True
params.forcing.type = "tcrandom"
params.forcing.forcing_rate = 1.0
params.forcing.nkmin_forcing = 4
params.forcing.nkmax_forcing = 5
params.forcing.tcrandom.time_correlation = "based_on_forcing_rate"

记录受强迫的变量、规范化定义、波数区间、随机种子/状态、注入目标和实测 注入量。FluidSim 0.9 会保存状态参数以供重启；0.8.6 修复了时间相关强迫 的重启行为。

可用的伪谱格式包括 Euler/RK2 相移变体、 RK2_trapezoid 和 RK4。标示的阶数并不能证明精度。请检查 CFL、 快波/扩散限制、deltat_max 和时间步细化。参见 高级功能。

输出、加载与重启

对于只读分析：

from fluidsim import load_sim_for_plot

sim = load_sim_for_plot("run-directory", hide_stdout=True)
sim.output.spatial_means.plot()
sim.output.spectra.plot1d()
sim.output.phys_fields.plot(time=1.0)

load_sim_for_plot 使用粗粒度算子，并禁用保存和在线绘图。 对于包含状态的对象：

from fluidsim import load_state_phys_file

sim = load_state_phys_file("run-directory", t_approx="last")

如需受控重启，优先使用 load_for_restart，或先运行 fluidsim-restart --only-check。不要对不可信文本使用 --modify-params：上游 CLI 会执行传入该选项的 Python 代码。本技能的 生成器绝不会输出此选项。请核实求解器、网格/区域、状态变量、版本、强迫 状态、校验和、目标时间、输出目标和资源限制。更改分辨率必须使用经过审查的 专用工作流，不得悄然修改网格。参见 模拟工作流和 输出分析。

科学验收关卡

解释结果之前，必须满足以下要求：

• 明确给出有量纲单位，或提供完整的无量纲化映射。
• 方程、周期性几何/边界条件、初始状态、强迫和诊断定义均正确。
• 提供分辨率和去混叠证据：频谱/尾部、已解析梯度，以及适用于该求解器的小尺度判据。
• 提供时间步证据：CFL 历史、最快波和耗散限制，以及更小时间步的对比。
• 检查守恒量和收支，包括强迫、耗散、传递和残差。
• 对所报告的观测量进行网格/时间细化，并评估不确定性或敏感性。
• 在适当情况下，与解析解、制造解、基准测试或独立复现的结果进行比较。
• 提供完整的溯源信息和重启沿袭记录。

绝不能仅凭参数值或图表，就将一次运行标记为“DNS”“已收敛”“已验证”“稳态” 或“物理上正确”。

随附的本地工具

所有工具均输出严格的 JSON，拒绝 URL/路径遍历/符号链接，强制执行硬性限制， 不使用网络或子进程，也绝不启动模拟：

python3 scripts/solver_config_validator.py --example
python3 scripts/solver_config_validator.py --config config.json
python3 scripts/grid_resource_estimator.py --config config.json
python3 scripts/simulation_dry_run.py --config config.json --output run.py
python3 scripts/output_inventory.py --path run-directory
python3 scripts/budget_summary.py --path run-directory
python3 scripts/restart_compatibility.py --source state.nc --target-config config.json

HDF5 工具会按需要求 h5py，检查有界元数据/超切片，并且绝不跟随外部链接 或加载完整场数组。

参考资料

• 安装以及 FFT/MPI 后端
• 求解器注册表与选择
• 模拟、试运行与重启工作流
• 已验证的参数范围
• 输出、绘图与预算分析
• 强迫项、算子、MPI 与迁移

上游资料基准日期

已于 2026-07-23 对照以下资料验证： PyPI 0.9.0， FluidSim 0.9 文档， 发行说明， 官方源码镜像， FluidFFT 0.4.5 文档，以及 FluidSim (DOI 10.5334/jors.239) 和 FluidFFT (DOI 10.5334/jors.238) 的主要论文。API 相关声明依据官方文档/源码；参考资料中的方法和性能声明仅适用于所引用的主要论文及其基准测试设置。

Agent 操作流程

1. 检查环境。 确认库版本、单位、坐标系和数据格式（FITS、CIF、HDF5、netCDF）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 在较小网格、区域或子集上运行，并检查物理合理性。
4. 使用上述说明和参考资料 执行完整任务。
5. 验证结果。 检查单位和量纲一致性、守恒定律或已知极限，以及数值收敛性。
6. 汇报。 说明运行内容（版本、命令、参数）、检查内容及仍不确定之处。

如果发生这种情况	请这样做
结果违反已知物理极限	汇报前检查单位、边界条件和求解器容差。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自己的文档（help()、--help、官方文档），调整操作并告知用户。切勿编造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 每个定量结果都应报告不确定性和数值容差。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 涉及费用、占用共享 GPU 或云配额、处理个人或患者数据，或无法撤销的操作前，请先征求同意。

相关技能

• pylabrobot：开发和审查 PyLabRobot 实验室自动化资源、液体处理方案、离线模拟和受支持设备的集成。