Skip to content
Research Agent Skillsby Kalaris Labs
Install
Physical Sciencesv1.2AdaptedMIT

fluidsim

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.

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill fluidsim
uvx (Python tool runner)
uvx research-agent-skills install fluidsim

Documentation & Instructions

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

Solvers

Primary Cartesian CFD keys and imports:

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.

Forcing and time advancement

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

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.

Outputs, loading, and restart

For read-only analysis:

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:

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 and output analysis.

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:

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

Dated upstream basis

Verified 2026-07-23 against PyPI 0.9.0, FluidSim 0.9 docs, release notes, official source mirror, FluidFFT 0.4.5 docs, and the primary FluidSim (DOI 10.5334/jors.239) and FluidFFT (DOI 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.

Agent operating procedure

  1. Check the environment. Confirm library versions, units, coordinate systems and data formats (FITS, CIF, HDF5, netCDF).
  2. Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
  3. Run a small version first. Run on a small grid, region or subset and check physical plausibility.
  4. Execute the full task using the instructions and references above.
  5. Validate the result. Check units and dimensional consistency, conservation laws or known limits, and numerical convergence.
  6. Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
If this happens Do this
Results violate known physical limits Check units, boundary conditions and solver tolerances before reporting.
A function, flag or endpoint in these instructions is missing in the installed version Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API.
A required input, identifier or parameter is ambiguous Ask the user, or state the assumption explicitly before running.

Integrity rules

  • Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
  • Report uncertainties and numerical tolerances with every quantitative result.
  • Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
  • Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.

Related skills

  • pylabrobot: Develop and review PyLabRobot lab-automation resources, liquid-handling plans, offline simulations, and supported-device integrations.

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects fluidsim for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “I need to run a 2D turbulence sim with fluidsim, 256x256 periodic box. Can you set it up safely?”

    expects Asks for or states equations, units/nondimensionalization, forcing, observables, and acceptance criteria. Selects a solver (e.g. ns2d), inspects generated default params, builds a bounded JSON plan (CPU/RAM/disk/wall-time, CFL, resolution), runs the validator and estimator, and proposes a tiny serial pilot. Does not launch the run.

  • should trigger

    “I have a run in ~/runs/ns2d_forced_512/ with state_phys_t*.nc files and spectra1D.h5. I tried `params.time_stepping.CFL = 0.5` and got an AttributeError from ParamContainer when restarting with a modified script. I want to restart to t=200 on 8 MPI ranks on our cluster. What's wrong and how do I restart safely?”

    expects Explains that the 0.9 field is `cfl_coef`, not `CFL`, and that ParamContainer rejects undeclared attributes. Recommends `load_for_restart` or `fluidsim-restart --only-check`, and checking solver, grid, versions, forcing state, checksums, target time and output destination. Warns not to use `--modify-params` with untrusted text. Prepares but does not submit the MPI job. Does not call the restart converged or validated.

  • should trigger

    “I'm simulating forced 3D homogeneous turbulence on a periodic cube in Python, and my collaborators want to know if our 128^3 spectral run is resolved enough to call it DNS. What should I check, and can you look at the output files?”

    expects Refuses to label it DNS from parameters or plots alone. Requires spectral tail and dealiasing evidence, small-scale resolution criteria, CFL and time-step history, budget/dissipation residuals, and grid and time refinement. Inspects outputs with the bounded read-only tools. Reports uncertainty and provenance.

Near misses (2)

  • near miss

    “I have a bunch of FITS images of a galaxy cluster and want to run source extraction and photometry. Which Python tools should I use?”

    expects Recognizes this as astronomy image processing, unrelated to FluidSim pseudospectral CFD. It should not use the fluidsim skill and should use an astronomy or photometry tool, such as astropy or photutils, if one is available.

  • near miss

    “Write me an OpenFOAM case for lid-driven cavity flow with simpleFoam and a blockMesh file.”

    expects Recognizes that OpenFOAM finite-volume cases are outside FluidSim's periodic pseudospectral Python framework. It does not apply the fluidsim skill and answers from OpenFOAM knowledge, or says it has no matching skill.