fluidsim

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

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

```bash
# 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):

```bash
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
```python
from fluidsim.solvers.ns2d.solver import Simul
```

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

**Step 3**: Instantiate simulation
```python
sim = Simul(params)
```

**Step 4**: Execute
```python
sim.time_stepping.start()
```

**Step 5**: Analyze results
```python
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
```python
from fluidsim.solvers.ns2d.solver import Simul
```

**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows
```python
from fluidsim.solvers.ns3d.solver import Simul
```

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

**Shallow water** (`sw1l`): Geophysical flows, rotating systems
```python
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**:
```python
params.oper.nx = 256  # grid points
params.oper.Lx = 2 * pi  # domain size
```

**Physical parameters**:
```python
params.nu_2 = 1e-3  # viscosity
params.nu_4 = 0     # hyperviscosity (optional)
```

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

**Initial conditions**:
```python
params.init_fields.type = "noise"  # or "dipole", "vortex", "from_file", "in_script"
```

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

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
```python
sim.output.phys_fields.plot("vorticity")
sim.output.phys_fields.plot("vx")
```

**Spatial means**: Time series of volume-averaged quantities
```python
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()
```

See `references/advanced_features.md` for forcing types, custom solvers, cluster submission, and performance optimization.

## Common Use Cases

### 2D Turbulence Study

```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()

# Analyze energy cascade
sim.output.spectra.plot1d(tmin=30.0, tmax=50.0)
```

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

# 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()

sim.time_stepping.start()
sim.output.phys_fields.plot("b")
```

### High-Resolution 3D Simulation with MPI

```python
from fluidsim.solvers.ns3d.solver import Simul

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"

sim = Simul(params)
sim.time_stepping.start()
```

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

## 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")`

## Resources

**Documentation**: https://fluidsim.readthedocs.io/

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

{
  "format": "aiskill/v1",
  "skill": {
    "name": "fluidsim",
    "slug": "fluidsim",
    "version": "1.0.0",
    "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.",
    "category": "Research",
    "tags": [
      "research-science",
      "python"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "CECILL FREE SOFTWARE LICENSE AGREEMENT"
  },
  "prompts": {
    "system": "# FluidSim\r\n\r\n## Overview\r\n\r\nFluidSim 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.\r\n\r\n**Key strengths**:\r\n- Multiple solvers: 2D/3D Navier-Stokes, shallow water, stratified flows\r\n- High performance: Pythran/Transonic compilation, MPI parallelization\r\n- Complete workflow: Parameter configuration, simulation execution, output analysis\r\n- Interactive analysis: Python-based post-processing and visualization\r\n\r\n## Core Capabilities\r\n\r\n### 1. Installation and Setup\r\n\r\nInstall fluidsim using uv with appropriate feature flags:\r\n\r\n```bash\r\n# Basic installation\r\nuv uv pip install fluidsim\r\n\r\n# With FFT support (required for most solvers)\r\nuv uv pip install \"fluidsim[fft]\"\r\n\r\n# With MPI for parallel computing\r\nuv uv pip install \"fluidsim[fft,mpi]\"\r\n```\r\n\r\nSet environment variables for output directories (optional):\r\n\r\n```bash\r\nexport FLUIDSIM_PATH=/path/to/simulation/outputs\r\nexport FLUIDDYN_PATH_SCRATCH=/path/to/working/directory\r\n```\r\n\r\nNo API keys or authentication required.\r\n\r\nSee `references/installation.md` for complete installation instructions and environment configuration.\r\n\r\n### 2. Running Simulations\r\n\r\nStandard workflow consists of five steps:\r\n\r\n**Step 1**: Import solver\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\n```\r\n\r\n**Step 2**: Create and configure parameters\r\n```python\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 256\r\nparams.oper.Lx = params.oper.Ly = 2 * 3.14159\r\nparams.nu_2 = 1e-3\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"noise\"\r\n```\r\n\r\n**Step 3**: Instantiate simulation\r\n```python\r\nsim = Simul(params)\r\n```\r\n\r\n**Step 4**: Execute\r\n```python\r\nsim.time_stepping.start()\r\n```\r\n\r\n**Step 5**: Analyze results\r\n```python\r\nsim.output.phys_fields.plot(\"vorticity\")\r\nsim.output.spatial_means.plot()\r\n```\r\n\r\nSee `references/simulation_workflow.md` for complete examples, restarting simulations, and cluster deployment.\r\n\r\n### 3. Available Solvers\r\n\r\nChoose solver based on physical problem:\r\n\r\n**2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\n```\r\n\r\n**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows\r\n```python\r\nfrom fluidsim.solvers.ns3d.solver import Simul\r\n```\r\n\r\n**Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows\r\n```python\r\nfrom fluidsim.solvers.ns2d.strat.solver import Simul\r\nparams.N = 1.0  # Brunt-Väisälä frequency\r\n```\r\n\r\n**Shallow water** (`sw1l`): Geophysical flows, rotating systems\r\n```python\r\nfrom fluidsim.solvers.sw1l.solver import Simul\r\nparams.f = 1.0  # Coriolis parameter\r\n```\r\n\r\nSee `references/solvers.md` for complete solver list and selection guidance.\r\n\r\n### 4. Parameter Configuration\r\n\r\nParameters are organized hierarchically and accessed via dot notation:\r\n\r\n**Domain and resolution**:\r\n```python\r\nparams.oper.nx = 256  # grid points\r\nparams.oper.Lx = 2 * pi  # domain size\r\n```\r\n\r\n**Physical parameters**:\r\n```python\r\nparams.nu_2 = 1e-3  # viscosity\r\nparams.nu_4 = 0     # hyperviscosity (optional)\r\n```\r\n\r\n**Time stepping**:\r\n```python\r\nparams.time_stepping.t_end = 10.0\r\nparams.time_stepping.USE_CFL = True  # adaptive time step\r\nparams.time_stepping.CFL = 0.5\r\n```\r\n\r\n**Initial conditions**:\r\n```python\r\nparams.init_fields.type = \"noise\"  # or \"dipole\", \"vortex\", \"from_file\", \"in_script\"\r\n```\r\n\r\n**Output settings**:\r\n```python\r\nparams.output.periods_save.phys_fields = 1.0  # save every 1.0 time units\r\nparams.output.periods_save.spectra = 0.5\r\nparams.output.periods_save.spatial_means = 0.1\r\n```\r\n\r\nThe Parameters object raises `AttributeError` for typos, preventing silent configuration errors.\r\n\r\nSee `references/parameters.md` for comprehensive parameter documentation.\r\n\r\n### 5. Output and Analysis\r\n\r\nFluidSim produces multiple output types automatically saved during simulation:\r\n\r\n**Physical fields**: Velocity, vorticity in HDF5 format\r\n```python\r\nsim.output.phys_fields.plot(\"vorticity\")\r\nsim.output.phys_fields.plot(\"vx\")\r\n```\r\n\r\n**Spatial means**: Time series of volume-averaged quantities\r\n```python\r\nsim.output.spatial_means.plot()\r\n```\r\n\r\n**Spectra**: Energy and enstrophy spectra\r\n```python\r\nsim.output.spectra.plot1d()\r\nsim.output.spectra.plot2d()\r\n```\r\n\r\n**Load previous simulations**:\r\n```python\r\nfrom fluidsim import load_sim_for_plot\r\nsim = load_sim_for_plot(\"simulation_dir\")\r\nsim.output.phys_fields.plot()\r\n```\r\n\r\n**Advanced visualization**: Open `.h5` files in ParaView or VisIt for 3D visualization.\r\n\r\nSee `references/output_analysis.md` for detailed analysis workflows, parametric study analysis, and data export.\r\n\r\n### 6. Advanced Features\r\n\r\n**Custom forcing**: Maintain turbulence or drive specific dynamics\r\n```python\r\nparams.forcing.enable = True\r\nparams.forcing.type = \"tcrandom\"  # time-correlated random forcing\r\nparams.forcing.forcing_rate = 1.0\r\n```\r\n\r\n**Custom initial conditions**: Define fields in script\r\n```python\r\nparams.init_fields.type = \"in_script\"\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nvx = sim.state.state_phys.get_var(\"vx\")\r\nvx[:] = sin(X) * cos(Y)\r\nsim.time_stepping.start()\r\n```\r\n\r\n**MPI parallelization**: Run on multiple processors\r\n```bash\r\nmpirun -np 8 python simulation_script.py\r\n```\r\n\r\n**Parametric studies**: Run multiple simulations with different parameters\r\n```python\r\nfor nu in [1e-3, 5e-4, 1e-4]:\r\n    params = Simul.create_default_params()\r\n    params.nu_2 = nu\r\n    params.output.sub_directory = f\"nu{nu}\"\r\n    sim = Simul(params)\r\n    sim.time_stepping.start()\r\n```\r\n\r\nSee `references/advanced_features.md` for forcing types, custom solvers, cluster submission, and performance optimization.\r\n\r\n## Common Use Cases\r\n\r\n### 2D Turbulence Study\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\nfrom math import pi\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 512\r\nparams.oper.Lx = params.oper.Ly = 2 * pi\r\nparams.nu_2 = 1e-4\r\nparams.time_stepping.t_end = 50.0\r\nparams.time_stepping.USE_CFL = True\r\nparams.init_fields.type = \"noise\"\r\nparams.output.periods_save.phys_fields = 5.0\r\nparams.output.periods_save.spectra = 1.0\r\n\r\nsim = Simul(params)\r\nsim.time_stepping.start()\r\n\r\n# Analyze energy cascade\r\nsim.output.spectra.plot1d(tmin=30.0, tmax=50.0)\r\n```\r\n\r\n### Stratified Flow Simulation\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.strat.solver import Simul\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 256\r\nparams.N = 2.0  # stratification strength\r\nparams.nu_2 = 5e-4\r\nparams.time_stepping.t_end = 20.0\r\n\r\n# Initialize with dense layer\r\nparams.init_fields.type = \"in_script\"\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nb = sim.state.state_phys.get_var(\"b\")\r\nb[:] = exp(-((X - 3.14)**2 + (Y - 3.14)**2) / 0.5)\r\nsim.state.statephys_from_statespect()\r\n\r\nsim.time_stepping.start()\r\nsim.output.phys_fields.plot(\"b\")\r\n```\r\n\r\n### High-Resolution 3D Simulation with MPI\r\n\r\n```python\r\nfrom fluidsim.solvers.ns3d.solver import Simul\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = params.oper.nz = 512\r\nparams.nu_2 = 1e-5\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"noise\"\r\n\r\nsim = Simul(params)\r\nsim.time_stepping.start()\r\n```\r\n\r\nRun with:\r\n```bash\r\nmpirun -np 64 python script.py\r\n```\r\n\r\n### Taylor-Green Vortex Validation\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\nimport numpy as np\r\nfrom math import pi\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 128\r\nparams.oper.Lx = params.oper.Ly = 2 * pi\r\nparams.nu_2 = 1e-3\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"in_script\"\r\n\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nvx = sim.state.state_phys.get_var(\"vx\")\r\nvy = sim.state.state_phys.get_var(\"vy\")\r\nvx[:] = np.sin(X) * np.cos(Y)\r\nvy[:] = -np.cos(X) * np.sin(Y)\r\nsim.state.statephys_from_statespect()\r\n\r\nsim.time_stepping.start()\r\n\r\n# Validate energy decay\r\ndf = sim.output.spatial_means.load()\r\n# Compare with analytical solution\r\n```\r\n\r\n## Quick Reference\r\n\r\n**Import solver**: `from fluidsim.solvers.ns2d.solver import Simul`\r\n\r\n**Create parameters**: `params = Simul.create_default_params()`\r\n\r\n**Set resolution**: `params.oper.nx = params.oper.ny = 256`\r\n\r\n**Set viscosity**: `params.nu_2 = 1e-3`\r\n\r\n**Set end time**: `params.time_stepping.t_end = 10.0`\r\n\r\n**Run simulation**: `sim = Simul(params); sim.time_stepping.start()`\r\n\r\n**Plot results**: `sim.output.phys_fields.plot(\"vorticity\")`\r\n\r\n**Load simulation**: `sim = load_sim_for_plot(\"path/to/sim\")`\r\n\r\n## Resources\r\n\r\n**Documentation**: https://fluidsim.readthedocs.io/\r\n\r\n**Reference files**:\r\n- `references/installation.md`: Complete installation instructions\r\n- `references/solvers.md`: Available solvers and selection guide\r\n- `references/simulation_workflow.md`: Detailed workflow examples\r\n- `references/parameters.md`: Comprehensive parameter documentation\r\n- `references/output_analysis.md`: Output types and analysis methods\r\n- `references/advanced_features.md`: Forcing, MPI, parametric studies, custom solvers",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The fluidsim/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/fluidsim",
    "exported_at": "2026-11-03T07:42:39.716Z"
  }
}

format: aiskill/v1
skill:
  name: fluidsim
  slug: fluidsim
  version: 1.0.0
  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.
  category: Research
  tags:
    - research-science
    - python
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: CECILL FREE SOFTWARE LICENSE AGREEMENT
prompts:
  system: "# FluidSim\r\n\r\n## Overview\r\n\r\nFluidSim 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.\r\n\r\n**Key strengths**:\r\n- Multiple solvers: 2D/3D Navier-Stokes, shallow water, stratified flows\r\n- High performance: Pythran/Transonic compilation, MPI parallelization\r\n- Complete workflow: Parameter configuration, simulation execution, output analysis\r\n- Interactive analysis: Python-based post-processing and visualization\r\n\r\n## Core Capabilities\r\n\r\n### 1. Installation and Setup\r\n\r\nInstall fluidsim using uv with appropriate feature flags:\r\n\r\n```bash\r\n# Basic installation\r\nuv uv pip install fluidsim\r\n\r\n# With FFT support (required for most solvers)\r\nuv uv pip install \"fluidsim[fft]\"\r\n\r\n# With MPI for parallel computing\r\nuv uv pip install \"fluidsim[fft,mpi]\"\r\n```\r\n\r\nSet environment variables for output directories (optional):\r\n\r\n```bash\r\nexport FLUIDSIM_PATH=/path/to/simulation/outputs\r\nexport FLUIDDYN_PATH_SCRATCH=/path/to/working/directory\r\n```\r\n\r\nNo API keys or authentication required.\r\n\r\nSee `references/installation.md` for complete installation instructions and environment configuration.\r\n\r\n### 2. Running Simulations\r\n\r\nStandard workflow consists of five steps:\r\n\r\n**Step 1**: Import solver\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\n```\r\n\r\n**Step 2**: Create and configure parameters\r\n```python\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 256\r\nparams.oper.Lx = params.oper.Ly = 2 * 3.14159\r\nparams.nu_2 = 1e-3\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"noise\"\r\n```\r\n\r\n**Step 3**: Instantiate simulation\r\n```python\r\nsim = Simul(params)\r\n```\r\n\r\n**Step 4**: Execute\r\n```python\r\nsim.time_stepping.start()\r\n```\r\n\r\n**Step 5**: Analyze results\r\n```python\r\nsim.output.phys_fields.plot(\"vorticity\")\r\nsim.output.spatial_means.plot()\r\n```\r\n\r\nSee `references/simulation_workflow.md` for complete examples, restarting simulations, and cluster deployment.\r\n\r\n### 3. Available Solvers\r\n\r\nChoose solver based on physical problem:\r\n\r\n**2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\n```\r\n\r\n**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows\r\n```python\r\nfrom fluidsim.solvers.ns3d.solver import Simul\r\n```\r\n\r\n**Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows\r\n```python\r\nfrom fluidsim.solvers.ns2d.strat.solver import Simul\r\nparams.N = 1.0  # Brunt-Väisälä frequency\r\n```\r\n\r\n**Shallow water** (`sw1l`): Geophysical flows, rotating systems\r\n```python\r\nfrom fluidsim.solvers.sw1l.solver import Simul\r\nparams.f = 1.0  # Coriolis parameter\r\n```\r\n\r\nSee `references/solvers.md` for complete solver list and selection guidance.\r\n\r\n### 4. Parameter Configuration\r\n\r\nParameters are organized hierarchically and accessed via dot notation:\r\n\r\n**Domain and resolution**:\r\n```python\r\nparams.oper.nx = 256  # grid points\r\nparams.oper.Lx = 2 * pi  # domain size\r\n```\r\n\r\n**Physical parameters**:\r\n```python\r\nparams.nu_2 = 1e-3  # viscosity\r\nparams.nu_4 = 0     # hyperviscosity (optional)\r\n```\r\n\r\n**Time stepping**:\r\n```python\r\nparams.time_stepping.t_end = 10.0\r\nparams.time_stepping.USE_CFL = True  # adaptive time step\r\nparams.time_stepping.CFL = 0.5\r\n```\r\n\r\n**Initial conditions**:\r\n```python\r\nparams.init_fields.type = \"noise\"  # or \"dipole\", \"vortex\", \"from_file\", \"in_script\"\r\n```\r\n\r\n**Output settings**:\r\n```python\r\nparams.output.periods_save.phys_fields = 1.0  # save every 1.0 time units\r\nparams.output.periods_save.spectra = 0.5\r\nparams.output.periods_save.spatial_means = 0.1\r\n```\r\n\r\nThe Parameters object raises `AttributeError` for typos, preventing silent configuration errors.\r\n\r\nSee `references/parameters.md` for comprehensive parameter documentation.\r\n\r\n### 5. Output and Analysis\r\n\r\nFluidSim produces multiple output types automatically saved during simulation:\r\n\r\n**Physical fields**: Velocity, vorticity in HDF5 format\r\n```python\r\nsim.output.phys_fields.plot(\"vorticity\")\r\nsim.output.phys_fields.plot(\"vx\")\r\n```\r\n\r\n**Spatial means**: Time series of volume-averaged quantities\r\n```python\r\nsim.output.spatial_means.plot()\r\n```\r\n\r\n**Spectra**: Energy and enstrophy spectra\r\n```python\r\nsim.output.spectra.plot1d()\r\nsim.output.spectra.plot2d()\r\n```\r\n\r\n**Load previous simulations**:\r\n```python\r\nfrom fluidsim import load_sim_for_plot\r\nsim = load_sim_for_plot(\"simulation_dir\")\r\nsim.output.phys_fields.plot()\r\n```\r\n\r\n**Advanced visualization**: Open `.h5` files in ParaView or VisIt for 3D visualization.\r\n\r\nSee `references/output_analysis.md` for detailed analysis workflows, parametric study analysis, and data export.\r\n\r\n### 6. Advanced Features\r\n\r\n**Custom forcing**: Maintain turbulence or drive specific dynamics\r\n```python\r\nparams.forcing.enable = True\r\nparams.forcing.type = \"tcrandom\"  # time-correlated random forcing\r\nparams.forcing.forcing_rate = 1.0\r\n```\r\n\r\n**Custom initial conditions**: Define fields in script\r\n```python\r\nparams.init_fields.type = \"in_script\"\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nvx = sim.state.state_phys.get_var(\"vx\")\r\nvx[:] = sin(X) * cos(Y)\r\nsim.time_stepping.start()\r\n```\r\n\r\n**MPI parallelization**: Run on multiple processors\r\n```bash\r\nmpirun -np 8 python simulation_script.py\r\n```\r\n\r\n**Parametric studies**: Run multiple simulations with different parameters\r\n```python\r\nfor nu in [1e-3, 5e-4, 1e-4]:\r\n    params = Simul.create_default_params()\r\n    params.nu_2 = nu\r\n    params.output.sub_directory = f\"nu{nu}\"\r\n    sim = Simul(params)\r\n    sim.time_stepping.start()\r\n```\r\n\r\nSee `references/advanced_features.md` for forcing types, custom solvers, cluster submission, and performance optimization.\r\n\r\n## Common Use Cases\r\n\r\n### 2D Turbulence Study\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\nfrom math import pi\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 512\r\nparams.oper.Lx = params.oper.Ly = 2 * pi\r\nparams.nu_2 = 1e-4\r\nparams.time_stepping.t_end = 50.0\r\nparams.time_stepping.USE_CFL = True\r\nparams.init_fields.type = \"noise\"\r\nparams.output.periods_save.phys_fields = 5.0\r\nparams.output.periods_save.spectra = 1.0\r\n\r\nsim = Simul(params)\r\nsim.time_stepping.start()\r\n\r\n# Analyze energy cascade\r\nsim.output.spectra.plot1d(tmin=30.0, tmax=50.0)\r\n```\r\n\r\n### Stratified Flow Simulation\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.strat.solver import Simul\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 256\r\nparams.N = 2.0  # stratification strength\r\nparams.nu_2 = 5e-4\r\nparams.time_stepping.t_end = 20.0\r\n\r\n# Initialize with dense layer\r\nparams.init_fields.type = \"in_script\"\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nb = sim.state.state_phys.get_var(\"b\")\r\nb[:] = exp(-((X - 3.14)**2 + (Y - 3.14)**2) / 0.5)\r\nsim.state.statephys_from_statespect()\r\n\r\nsim.time_stepping.start()\r\nsim.output.phys_fields.plot(\"b\")\r\n```\r\n\r\n### High-Resolution 3D Simulation with MPI\r\n\r\n```python\r\nfrom fluidsim.solvers.ns3d.solver import Simul\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = params.oper.nz = 512\r\nparams.nu_2 = 1e-5\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"noise\"\r\n\r\nsim = Simul(params)\r\nsim.time_stepping.start()\r\n```\r\n\r\nRun with:\r\n```bash\r\nmpirun -np 64 python script.py\r\n```\r\n\r\n### Taylor-Green Vortex Validation\r\n\r\n```python\r\nfrom fluidsim.solvers.ns2d.solver import Simul\r\nimport numpy as np\r\nfrom math import pi\r\n\r\nparams = Simul.create_default_params()\r\nparams.oper.nx = params.oper.ny = 128\r\nparams.oper.Lx = params.oper.Ly = 2 * pi\r\nparams.nu_2 = 1e-3\r\nparams.time_stepping.t_end = 10.0\r\nparams.init_fields.type = \"in_script\"\r\n\r\nsim = Simul(params)\r\nX, Y = sim.oper.get_XY_loc()\r\nvx = sim.state.state_phys.get_var(\"vx\")\r\nvy = sim.state.state_phys.get_var(\"vy\")\r\nvx[:] = np.sin(X) * np.cos(Y)\r\nvy[:] = -np.cos(X) * np.sin(Y)\r\nsim.state.statephys_from_statespect()\r\n\r\nsim.time_stepping.start()\r\n\r\n# Validate energy decay\r\ndf = sim.output.spatial_means.load()\r\n# Compare with analytical solution\r\n```\r\n\r\n## Quick Reference\r\n\r\n**Import solver**: `from fluidsim.solvers.ns2d.solver import Simul`\r\n\r\n**Create parameters**: `params = Simul.create_default_params()`\r\n\r\n**Set resolution**: `params.oper.nx = params.oper.ny = 256`\r\n\r\n**Set viscosity**: `params.nu_2 = 1e-3`\r\n\r\n**Set end time**: `params.time_stepping.t_end = 10.0`\r\n\r\n**Run simulation**: `sim = Simul(params); sim.time_stepping.start()`\r\n\r\n**Plot results**: `sim.output.phys_fields.plot(\"vorticity\")`\r\n\r\n**Load simulation**: `sim = load_sim_for_plot(\"path/to/sim\")`\r\n\r\n## Resources\r\n\r\n**Documentation**: https://fluidsim.readthedocs.io/\r\n\r\n**Reference files**:\r\n- `references/installation.md`: Complete installation instructions\r\n- `references/solvers.md`: Available solvers and selection guide\r\n- `references/simulation_workflow.md`: Detailed workflow examples\r\n- `references/parameters.md`: Comprehensive parameter documentation\r\n- `references/output_analysis.md`: Output types and analysis methods\r\n- `references/advanced_features.md`: Forcing, MPI, parametric studies, custom solvers"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The fluidsim/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/fluidsim
  exported_at: "2026-11-03T07:42:39.716Z"