Comprehensive FluidSim

A scientific computing skill for computational fluid dynamics (CFD) simulations using FluidSim — the Python framework providing object-oriented interfaces for pseudo-spectral solvers for turbulence, Navier-Stokes equations, and shallow water models on structured grids.

When to Use This Skill

Choose Comprehensive FluidSim when:

• Running turbulence simulations with pseudo-spectral methods
• Solving 2D/3D Navier-Stokes equations on periodic domains
• Simulating shallow water dynamics and geophysical flows
• Building custom fluid dynamics solvers with FluidSim's framework

Consider alternatives when:

• You need finite element/volume methods (use OpenFOAM or FEniCS)
• You need complex geometry handling (use OpenFOAM or ANSYS Fluent)
• You need compressible flow simulation (use SU2)
• You need particle-based methods (use SPH or DEM tools)

Quick Start

Copy
claude "Run a 2D turbulence simulation using FluidSim"

Copy
from fluidsim.solvers.ns2d import Simul

# Configure simulation parameters
params = Simul.create_default_params()
params.short_name_type_run = "2d_turbulence"

# Domain and resolution
params.oper.nx = 256
params.oper.ny = 256
params.oper.Lx = 2 * 3.14159
params.oper.Ly = 2 * 3.14159

# Time stepping
params.time_stepping.deltat0 = 0.01
params.time_stepping.t_end = 10.0

# Forcing (energy injection)
params.forcing.enable = True
params.forcing.type = "proportional"

# Output configuration
params.output.periods_print.print_stdout = 1.0
params.output.periods_save.phys_fields = 1.0
params.output.periods_save.spatial_means = 0.1

# Initialize and run
sim = Simul(params)
sim.time_stepping.start()

# Analyze results
sim.output.spatial_means.plot()
sim.output.phys_fields.plot(field="rot")  # Vorticity field

Core Concepts

Available Solvers

Solver	Equation	Dimensions
ns2d	2D Navier-Stokes	2D periodic
ns3d	3D Navier-Stokes	3D periodic
ns2d.strat	Stratified 2D NS	2D with buoyancy
sw1l	Shallow water (1 layer)	2D
plate2d	Elastic plate equation	2D
ad1d	1D advection-diffusion	1D

Pseudo-Spectral Method

Copy
# FluidSim uses FFT-based spectral methods:
# 1. Compute spatial derivatives in Fourier space (exact)
# 2. Compute nonlinear terms in physical space
# 3. Time-step in Fourier space

# Key advantages:
# - Exponential convergence for smooth solutions
# - Exact derivatives (no numerical diffusion)
# - Efficient with FFT: O(N log N)

# Key limitations:
# - Requires periodic boundary conditions
# - Structured (rectangular) grids only
# - Aliasing requires dealiasing (2/3 rule)

Output Analysis

Copy
# Load saved simulation data
from fluidsim import load_sim_for_plot

sim = load_sim_for_plot("path/to/simulation")

# Energy spectrum
sim.output.spectra.plot1d(coef_compensate=5/3)

# Spatial means (energy, enstrophy over time)
sim.output.spatial_means.plot()

# Physical fields at specific time
sim.output.phys_fields.set_of_phys_files.plot_field(
    "rot", time=5.0
)

Configuration

Parameter	Description	Default
oper.nx / oper.ny	Grid resolution	128
oper.Lx / oper.Ly	Domain size	2π
nu_2	Kinematic viscosity	0
nu_8	Hyperviscosity coefficient	0
time_stepping.deltat0	Initial time step	0.01
forcing.type	Energy injection method	None

Best Practices

1. Use hyperviscosity for high-Reynolds turbulence. Standard viscosity (nu_2) dissipates energy at all scales. Hyperviscosity (nu_8) concentrates dissipation at the smallest scales, preserving the inertial range for cleaner energy spectra.

2. Check the CFL condition for time step stability. Spectral methods are sensitive to the CFL number. If the simulation blows up, reduce deltat0. FluidSim's adaptive time stepping helps, but the initial step must be reasonable.

3. Use adequate resolution for the Reynolds number. The grid must resolve the dissipation scale. As a rule of thumb, kmax * eta > 1 where kmax = N/3 (dealiased) and eta is the Kolmogorov scale. Under-resolved simulations develop aliasing artifacts.

4. Save spatial means frequently, fields infrequently. Spatial mean data (energy, enstrophy) is small and should be saved at high frequency (every 0.1 time units). Physical field snapshots are large — save them less frequently (every 1-5 time units) for visualization.

5. Start from developed turbulence for statistics. Turbulent statistics require a statistically stationary state. Run the simulation until energy reaches a plateau, then start collecting statistics. Transient data contaminates statistical averages.

Common Issues

Simulation blows up with NaN values. The time step is too large for the current flow velocity. Reduce deltat0 or enable adaptive time stepping. Also check that the viscosity is not zero — inviscid simulations without dissipation accumulate energy at the grid scale and crash.

Energy spectrum shows a pile-up at high wavenumbers. This indicates insufficient dissipation at the grid scale — the simulation is under-resolved. Increase viscosity, increase resolution, or add hyperviscosity to properly dissipate energy at the smallest resolved scales.

Forcing doesn't maintain statistically stationary turbulence. Check that the forcing amplitude and scale match the dissipation rate. Too little forcing and turbulence decays; too much and it blows up. Start with proportional forcing, which adjusts automatically to maintain constant energy input.