/fluidsim

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.2"
  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:

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:

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:

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:

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.