---
name: fluidsim
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

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.

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.

## Required workflow

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.

Stop if physical assumptions, units, boundary conditions, forcing semantics,
resolution criteria, resource limits, or acceptance criteria are missing.

## Version and installation

As verified on 2026-07-23:

- 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`.

Prefer a project lock:

```bash
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
```

For an isolated disposable environment:

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

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.

MPI is optional and native:

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

Those packages still require a compatible MPI runtime and FFTW development
libraries. The optional native plugins are:

- `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.

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 [installation](references/installation.md) for system dependencies, MPI ABI,
HDF5-MPI, backend discovery, and verification.

## API snapshot

Use direct, versioned imports:

```python
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
```

Important 0.9 corrections:

- 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`.

`ParamContainer` rejects undeclared attributes. Always generate defaults from the
selected `Simul` class and inspect them before changing values. See
[parameters](references/parameters.md).

## Solvers

Primary Cartesian CFD keys and imports:

```python
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
```

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

## Forcing and time advancement

Forcing is solver-specific. A current normalized random example is:

```python
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"
```

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.

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

## Outputs, loading, and restart

For read-only analysis:

```python
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` uses a coarse operator and disables saving/online plotting.
For a state-bearing object:

```python
from fluidsim import load_state_phys_file

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

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

## Scientific acceptance gate

Before interpreting results, require:

- 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.

Never label a run “DNS,” “converged,” “validated,” “steady,” or “physically
correct” from parameter values or plots alone.

## Bundled local tools

All tools emit strict JSON, reject URLs/traversal/symlinks, enforce hard bounds,
use no network or subprocess, and never launch a simulation:

```bash
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
```

The HDF5 tools lazily require `h5py`, inspect bounded metadata/hyperslabs, and
never follow external links or load full field arrays.

## References

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

## 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.