fluidsim · diff
git:20260611.1b8fae3 to v1.1
206 added, 268 removed. Audit A to A.
---
name: fluidsim
- description: Framework for computational fluid dynamics simulations using Python. Use when running fluid dynamics simulations including Navier-Stokes equations (2D/3D), shallow water equations, stratified flows, or when analyzing turbulence, vortex dynamics, or geophysical flows. Provides pseudospectral methods with FFT, HPC support, and comprehensive output analysis.
- license: CeCILL FREE SOFTWARE LICENSE AGREEMENT
- metadata: {"version": "1.0", "skill-author": "K-Dense Inc."}
+ description: Plan, configure, inspect, restart, and analyze bounded FluidSim computational-fluid-dynamics simulations with explicit numerical-validity and HPC safety checks. Use for FluidSim solver selection, parameter review, FFT/MPI setup, output diagnostics, or restart compatibility.
+ license: MIT
+ compatibility: Bundled CLIs require Python 3.11+ and use the standard library; HDF5/netCDF4 metadata tools lazily use h5py when available. Simulation examples target fluidsim 0.9.0, fluidfft 0.4.5, and pyFFTW 0.15.1. MPI/native FFT use requires a site-compatible MPI implementation, development headers, FFTW/PFFT/P3DFFT libraries, compilers, and an approved scheduler workflow. No GPU backend is assumed.
+ allowed-tools:
+ - Read
+ - Write
+ - Bash
+ - Glob
+ - Python
+ metadata:
+ version: "1.1"
+ skill-author: "K-Dense Inc."
+ last-reviewed: "2026-07-23"
---
# FluidSim
- ## Overview
-
- FluidSim is an object-oriented Python framework for high-performance computational fluid dynamics (CFD) simulations. It provides solvers for periodic-domain equations using pseudospectral methods with FFT, delivering performance comparable to Fortran/C++ while maintaining Python's ease of use.
+ Use FluidSim 0.9.0 as a framework for Python-defined numerical solvers, especially
+ periodic Cartesian pseudospectral CFD. Upstream FluidSim is CeCILL-2.1; the MIT
+ frontmatter license applies only to this skill.
- **Key strengths**:
- - Multiple solvers: 2D/3D Navier-Stokes, shallow water, stratified flows
- - High performance: Pythran/Transonic compilation, MPI parallelization
- - Complete workflow: Parameter configuration, simulation execution, output analysis
- - Interactive analysis: Python-based post-processing and visualization
+ This skill does **not** treat a completed run, a stable time step, a smooth plot,
+ or a closed program exit as evidence of numerical convergence or physical
+ validity.
- ## Core Capabilities
+ ## Required workflow
- ### 1. Installation and Setup
+ 1. State equations, units or nondimensionalization, geometry, boundaries,
+ initial conditions, forcing, observables, and acceptance criteria.
+ 2. Select a verified solver and inspect its generated default parameters.
+ 3. Create a strict JSON plan with explicit CPU, RAM, disk, wall-time, output-file,
+ timestep, CFL, resolution, and dealiasing bounds.
+ 4. Run the bundled validator and resource estimator.
+ 5. Generate and review a dry-run script. It does nothing unless executed with an
+ explicit config-ID acknowledgement.
+ 6. Run one tiny serial pilot. Inspect budgets, divergence/constraints, spectral
+ tails, CFL/time-step history, and output growth.
+ 7. Refine grid and time step independently. Check conservation/budget residuals
+ and observable sensitivity.
+ 8. Only then prepare a site-specific MPI job. Never submit or launch MPI
+ automatically.
+ 9. Preserve config, script, `uv.lock`, package/platform/backend versions, logs,
+ output inventory, checksums, and restart lineage.
- Install fluidsim using uv with appropriate feature flags:
+ Stop if physical assumptions, units, boundary conditions, forcing semantics,
+ resolution criteria, resource limits, or acceptance criteria are missing.
- ```bash
- # Basic installation
- uv pip install fluidsim
+ ## Version and installation
- # With FFT support (required for most solvers)
- uv pip install "fluidsim[fft]"
+ As verified on 2026-07-23:
- # With MPI for parallel computing
- uv pip install "fluidsim[fft,mpi]"
- ```
+ - Latest stable PyPI release: `fluidsim==0.9.0` (2025-12-04).
+ - Package metadata requires Python `>=3.11` and lists Python 3.11–3.14.
+ - Pseudospectral parameter creation needs FluidFFT; bare `fluidsim` imported in
+ the smoke test, but `ns2d.create_default_params()` failed until the `fft` extra
+ was installed.
+ - Current companion versions tested here: `fluidfft==0.4.5` and
+ `pyFFTW==0.15.1`.
- Set environment variables for output directories (optional):
+ Prefer a project lock:
```bash
- export FLUIDSIM_PATH=/path/to/simulation/outputs
- export FLUIDDYN_PATH_SCRATCH=/path/to/working/directory
+ 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
```
- No API keys or authentication required.
-
- See `references/installation.md` for complete installation instructions and environment configuration.
+ For an isolated disposable environment:
- ### 2. Running Simulations
+ ```bash
+ uv venv --python 3.11
+ uv pip install "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"
+ ```
- Standard workflow consists of five steps:
+ The project lock is the reproducibility record; direct pins alone do not freeze
+ all transitive artifacts. Do not reuse a lock across incompatible platforms or
+ MPI ABIs.
- **Step 1**: Import solver
- ```python
- from fluidsim.solvers.ns2d.solver import Simul
- ```
+ MPI is optional and native:
- **Step 2**: Create and configure parameters
- ```python
- 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"
+ ```bash
+ uv add "mpi4py==4.1.2" "fluidfft-mpi-with-fftw==0.0.1" "fluidfft-fftwmpi==0.0.1"
+ uv lock
```
- **Step 3**: Instantiate simulation
- ```python
- sim = Simul(params)
- ```
+ Those packages still require a compatible MPI runtime and FFTW development
+ libraries. The optional native plugins are:
- **Step 4**: Execute
- ```python
- sim.time_stepping.start()
- ```
+ - `fluidfft-fftw==0.0.1`: sequential
+ `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-enabled FFTW
+ `fft2d.mpi_with_fftwmpi2d`, `fft3d.mpi_with_fftwmpi3d`.
+ - `fluidfft-p3dfft==0.0.1`: `fft3d.mpi_with_p3dfft`; requires P3DFFT.
+ - FluidFFT also declares PFFT and P3DFFT extras; audit and pin their native
+ stacks for the target cluster.
- **Step 5**: Analyze results
- ```python
- sim.output.phys_fields.plot("vorticity")
- sim.output.spatial_means.plot()
- ```
+ FluidFFT documents cuFFT historically, but FluidFFT 0.4.5 declares no CUDA extra
+ or installed GPU plugin in its package metadata, and its CUDA installation page
+ is unfinished. Do not claim GPU acceleration or install an unrelated CUDA wheel
+ as a FluidSim backend. Treat GPU work as source-level experimental integration
+ requiring separate validation.
- See `references/simulation_workflow.md` for complete examples, restarting simulations, and cluster deployment.
+ See [installation](references/installation.md) for system dependencies, MPI ABI,
+ HDF5-MPI, backend discovery, and verification.
- ### 3. Available Solvers
+ ## API snapshot
- Choose solver based on physical problem:
+ Use direct, versioned imports:
- **2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics
```python
from fluidsim.solvers.ns2d.solver import Simul
- ```
- **3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows
- ```python
- from fluidsim.solvers.ns3d.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
```
- **Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows
- ```python
- from fluidsim.solvers.ns2d.strat.solver import Simul
- params.N = 1.0 # Brunt-Väisälä frequency
- ```
+ Important 0.9 corrections:
- **Shallow water** (`sw1l`): Geophysical flows, rotating systems
- ```python
- from fluidsim.solvers.sw1l.solver import Simul
- params.f = 1.0 # Coriolis parameter
- ```
+ - CFL field: `params.time_stepping.cfl_coef`, not `CFL`.
+ - Time-correlated forcing:
+ `params.forcing.tcrandom.time_correlation`, not a flat
+ `tcrandom_time_correlation`.
+ - NS2D default initial types include `constant`, `noise`, `jet`, `dipole`,
+ `from_file`, `from_simul`, and `in_script`; do not invent a universal list for
+ every solver.
+ - Output state files default to `state_phys_t*.nc`; spectra use
+ `spectra1D.h5`/`spectra2D.h5`; scalar means are solver-dependent
+ `spatial_means.txt` or JSON-lines.
+ - `params.output.sub_directory` is relative under `FLUIDSIM_PATH`.
- See `references/solvers.md` for complete solver list and selection guidance.
+ `ParamContainer` rejects undeclared attributes. Always generate defaults from the
+ selected `Simul` class and inspect them before changing values. See
+ [parameters](references/parameters.md).
- ### 4. Parameter Configuration
+ ## Solvers
- Parameters are organized hierarchically and accessed via dot notation:
+ Primary Cartesian CFD keys and imports:
- **Domain and resolution**:
```python
- params.oper.nx = 256 # grid points
- params.oper.Lx = 2 * pi # domain size
+ 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
```
- **Physical parameters**:
- ```python
- params.nu_2 = 1e-3 # viscosity
- params.nu_4 = 0 # hyperviscosity (optional)
- ```
+ The 0.9 registry also includes `plate2d`, `sw1l` variants, `waves2d`, 1D models,
+ 0D models, spherical solvers, and framework adapters. Availability in the
+ registry does not make a solver appropriate for a scientific question. Verify
+ equations, variables, geometry, boundaries, and diagnostics in the solver
+ source. See [solvers](references/solvers.md).
- **Time stepping**:
- ```python
- params.time_stepping.t_end = 10.0
- params.time_stepping.USE_CFL = True # adaptive time step
- params.time_stepping.CFL = 0.5
- ```
+ ## Forcing and time advancement
- **Initial conditions**:
- ```python
- params.init_fields.type = "noise" # or "dipole", "vortex", "from_file", "in_script"
- ```
+ Forcing is solver-specific. A current normalized random example is:
- **Output settings**:
```python
- 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
+ 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"
```
- The Parameters object raises `AttributeError` for typos, preventing silent configuration errors.
+ Record the forced variable, normalization definition, wave-number band, random
+ seed/state, injection target, and measured injection. FluidSim 0.9 saves state
+ parameters for restart; 0.8.6 fixed time-correlated forcing restart behavior.
- See `references/parameters.md` for comprehensive parameter documentation.
+ Available pseudospectral schemes include Euler/RK2 phase-shift variants,
+ `RK2_trapezoid`, and `RK4`. A named order does not establish accuracy. Check CFL,
+ fast-wave/diffusive limits, `deltat_max`, and time-step refinement. See
+ [advanced features](references/advanced_features.md).
- ### 5. Output and Analysis
+ ## Outputs, loading, and restart
- FluidSim produces multiple output types automatically saved during simulation:
+ For read-only analysis:
- **Physical fields**: Velocity, vorticity in HDF5 format
```python
- sim.output.phys_fields.plot("vorticity")
- sim.output.phys_fields.plot("vx")
- ```
+ from fluidsim import load_sim_for_plot
- **Spatial means**: Time series of volume-averaged quantities
- ```python
+ sim = load_sim_for_plot("run-directory", hide_stdout=True)
sim.output.spatial_means.plot()
- ```
-
- **Spectra**: Energy and enstrophy spectra
- ```python
sim.output.spectra.plot1d()
- sim.output.spectra.plot2d()
- ```
-
- **Load previous simulations**:
- ```python
- from fluidsim import load_sim_for_plot
- sim = load_sim_for_plot("simulation_dir")
- sim.output.phys_fields.plot()
- ```
-
- **Advanced visualization**: Open `.h5` files in ParaView or VisIt for 3D visualization.
-
- See `references/output_analysis.md` for detailed analysis workflows, parametric study analysis, and data export.
-
- ### 6. Advanced Features
-
- **Custom forcing**: Maintain turbulence or drive specific dynamics
- ```python
- params.forcing.enable = True
- params.forcing.type = "tcrandom" # time-correlated random forcing
- params.forcing.forcing_rate = 1.0
- ```
-
- **Custom initial conditions**: Define fields in script
- ```python
- 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 parallelization**: Run on multiple processors
- ```bash
- mpirun -np 8 python simulation_script.py
- ```
-
- **Parametric studies**: Run multiple simulations with different parameters
- ```python
- 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()
+ sim.output.phys_fields.plot(time=1.0)
```
- See `references/advanced_features.md` for forcing types, custom solvers, cluster submission, and performance optimization.
-
- ## Common Use Cases
-
- ### 2D Turbulence Study
+ `load_sim_for_plot` uses a coarse operator and disables saving/online plotting.
+ For a state-bearing object:
```python
- 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()
+ from fluidsim import load_state_phys_file
- # Analyze energy cascade
- sim.output.spectra.plot1d(tmin=30.0, tmax=50.0)
+ sim = load_state_phys_file("run-directory", t_approx="last")
```
- ### Stratified Flow Simulation
-
- ```python
- from fluidsim.solvers.ns2d.strat.solver import Simul
-
- params = Simul.create_default_params()
- params.oper.nx = params.oper.ny = 256
- params.N = 2.0 # stratification strength
- params.nu_2 = 5e-4
- params.time_stepping.t_end = 20.0
+ For a controlled restart, prefer `load_for_restart` or first run
+ `fluidsim-restart --only-check`. Do not use `--modify-params` with untrusted text:
+ the upstream CLI executes Python code supplied to that option. This skill's
+ generator never emits it. Verify solver, grid/domain, state variables, versions,
+ forcing state, checksum, target time, output destination, and resource bounds.
+ Resolution changes require the dedicated reviewed workflow, not a silent grid
+ edit. See [simulation workflow](references/simulation_workflow.md) and
+ [output analysis](references/output_analysis.md).
- # Initialize with dense layer
- 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()
+ ## Scientific acceptance gate
- sim.time_stepping.start()
- sim.output.phys_fields.plot("b")
- ```
+ Before interpreting results, require:
- ### High-Resolution 3D Simulation with MPI
+ - Explicit dimensional units or a complete nondimensionalization map.
+ - Correct equations, periodic geometry/boundaries, initial state, forcing, and
+ diagnostic definitions.
+ - Resolution and dealiasing evidence: spectra/tails, resolved gradients, and
+ solver-appropriate small-scale criteria.
+ - Timestep evidence: CFL history, fastest-wave and dissipative limits, and
+ smaller-step comparison.
+ - Conservation and budget checks including forcing, dissipation, transfers, and
+ residuals.
+ - Grid/time refinement with uncertainty or sensitivity for reported
+ observables.
+ - Comparison to an analytical solution, manufactured solution, benchmark, or
+ independently reproduced result where appropriate.
+ - Complete provenance and restart lineage.
- ```python
- from fluidsim.solvers.ns3d.solver import Simul
+ Never label a run “DNS,” “converged,” “validated,” “steady,” or “physically
+ correct” from parameter values or plots alone.
- 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"
+ ## Bundled local tools
- sim = Simul(params)
- sim.time_stepping.start()
- ```
+ All tools emit strict JSON, reject URLs/traversal/symlinks, enforce hard bounds,
+ use no network or subprocess, and never launch a simulation:
- Run with:
```bash
- mpirun -np 64 python script.py
- ```
-
- ### Taylor-Green Vortex Validation
-
- ```python
- 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()
-
- # Validate energy decay
- df = sim.output.spatial_means.load()
- # Compare with analytical solution
+ 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
```
- ## Quick Reference
-
- **Import solver**: `from fluidsim.solvers.ns2d.solver import Simul`
-
- **Create parameters**: `params = Simul.create_default_params()`
-
- **Set resolution**: `params.oper.nx = params.oper.ny = 256`
-
- **Set viscosity**: `params.nu_2 = 1e-3`
-
- **Set end time**: `params.time_stepping.t_end = 10.0`
-
- **Run simulation**: `sim = Simul(params); sim.time_stepping.start()`
-
- **Plot results**: `sim.output.phys_fields.plot("vorticity")`
-
- **Load simulation**: `sim = load_sim_for_plot("path/to/sim")`
+ The HDF5 tools lazily require `h5py`, inspect bounded metadata/hyperslabs, and
+ never follow external links or load full field arrays.
- ## Resources
+ ## References
- **Documentation**: https://fluidsim.readthedocs.io/
+ - [Installation and FFT/MPI backends](references/installation.md)
+ - [Solver registry and selection](references/solvers.md)
+ - [Simulation, pilot, and restart workflow](references/simulation_workflow.md)
+ - [Verified parameter surface](references/parameters.md)
+ - [Output, plotting, and budget analysis](references/output_analysis.md)
+ - [Forcing, operators, MPI, and migrations](references/advanced_features.md)
- **Reference files**:
- - `references/installation.md`: Complete installation instructions
- - `references/solvers.md`: Available solvers and selection guide
- - `references/simulation_workflow.md`: Detailed workflow examples
- - `references/parameters.md`: Comprehensive parameter documentation
- - `references/output_analysis.md`: Output types and analysis methods
- - `references/advanced_features.md`: Forcing, MPI, parametric studies, custom solvers
+ ## Dated upstream basis
+ Verified 2026-07-23 against
+ [PyPI 0.9.0](https://pypi.org/project/fluidsim/),
+ [FluidSim 0.9 docs](https://fluidsim.readthedocs.io/en/latest/),
+ [release notes](https://fluidsim.readthedocs.io/en/latest/changes.html),
+ [official source mirror](https://github.com/fluiddyn/fluidsim),
+ [FluidFFT 0.4.5 docs](https://fluidfft.readthedocs.io/en/latest/), and the
+ primary FluidSim ([DOI 10.5334/jors.239](https://doi.org/10.5334/jors.239))
+ and FluidFFT ([DOI 10.5334/jors.238](https://doi.org/10.5334/jors.238))
+ papers. API claims use official docs/source; method/performance claims in the
+ references are scoped to the cited primary papers and their benchmark setups.