/fluidsim

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:
    skill-author: K-Dense Inc.

FluidSim

Routing Boundary

Use this skill only for FluidSim or explicit CFD workflows such as Navier-Stokes, turbulence, shallow-water, stratified-flow, or pseudospectral fluid simulations. Do not use it for CSS fluid layouts, responsive design, generic Python simulation, generic PDE solving, or non-FluidSim numerical physics work.

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.

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

Core Capabilities

1. Installation and Setup

Install fluidsim using uv with appropriate feature flags:

# Basic installation
uv uv pip install fluidsim

# With FFT support (required for most solvers)
uv uv pip install "fluidsim[fft]"

# With MPI for parallel computing
uv uv pip install "fluidsim[fft,mpi]"

Set environment variables for output directories (optional):

export FLUIDSIM_PATH=/path/to/simulation/outputs
export FLUIDDYN_PATH_SCRATCH=/path/to/working/directory

No API keys or authentication required.

See `references/installation.md` for complete installation instructions and environment configuration.

2. Running Simulations

Standard workflow consists of five steps:

**Step 1**: Import solver

from fluidsim.solvers.ns2d.solver import Simul

**Step 2**: Create and configure parameters

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"

**Step 3**: Instantiate simulation

sim = Simul(params)

**Step 4**: Execute

sim.time_stepping.start()

**Step 5**: Analyze results

sim.output.phys_fields.plot("vorticity")
sim.output.spatial_means.plot()

See `references/simulation_workflow.md` for complete examples, restarting simulations, and cluster deployment.

3. Available Solvers

Choose solver based on physical problem:

**2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics

from fluidsim.solvers.ns2d.solver import Simul

**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows

from fluidsim.solvers.ns3d.solver import Simul

**Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows

from fluidsim.solvers.ns2d.strat.solver import Simul
params.N = 1.0  # Brunt-Väisälä frequency

**Shallow water** (`sw1l`): Geophysical flows, rotating systems

from fluidsim.solvers.sw1l.solver import Simul
params.f = 1.0  # Coriolis parameter

See `references/solvers.md` for complete solver list and selection guidance.

4. Parameter Configuration

Parameters are organized hierarchically and accessed via dot notation:

**Domain and resolution**:

params.oper.nx = 256  # grid points
params.oper.Lx = 2 * pi  # domain size

**Physical parameters**:

params.nu_2 = 1e-3  # viscosity
params.nu_4 = 0     # hyperviscosity (optional)

**Time stepping**:

params.time_stepping.t_end = 10.0
params.time_stepping.USE_CFL = True  # adaptive time step
params.time_stepping.CFL = 0.5

**Initial conditions**:

params.init_fields.type = "noise"  # or "dipole", "vortex", "from_file", "in_script"

**Output settings**:

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

The Parameters object raises `AttributeError` for typos, preventing silent configuration errors.

See `references/parameters.md` for comprehensive parameter documentation.

5. Output and Analysis

FluidSim produces multiple output types automatically saved during simulation:

**Physical fields**: Velocity, vorticity in HDF5 format

sim.output.phys_fields.plot("vorticity")
sim.output.phys_fields.plot("vx")

**Spatial means**: Time series of volume-averaged quantities

sim.output.spatial_means.plot()

**Spectra**: Energy and enstrophy spectra

sim.output.spectra.plot1d()
sim.output.spectra.plot2d()

**Load previous simulations**:

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

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

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 processor