How to Configure FluidSim CFD for 2D vs 3D Turbulence Simulations

To configure FluidSim CFD for 2D or 3D turbulence simulations, import the appropriate solver class—fluidsim.solvers.ns2d.solver.Simul for 2D or fluidsim.solvers.ns3d.solver.Simul for 3D—and set the spatial resolution via params.oper.nx, ny, and nz (3D only) in the hierarchical Parameters object.

FluidSim, included in the K-Dense-AI/scientific-agent-skills repository, implements turbulence simulations through isolated solver packages that share a common configuration API. Switching between dimensionalities requires only changing the solver import and adding the third spatial dimension, while forcing, output, and analysis workflows remain identical.

Selecting the Solver for 2D vs 3D Simulations

FluidSim enforces strict solver isolation to optimize memory usage and prevent dimensionality errors. The 2D Navier-Stokes solver resides in the ns2d package, while 3D simulations use the ns3d package. Both inherit from a common base class but expose only dimensionality-specific fields.

To run a 2D simulation, import the solver from the ns2d module:

from fluidsim.solvers.ns2d.solver import Simul

For 3D turbulence studies, import from the ns3d module instead:

from fluidsim.solvers.ns3d.solver import Simul

According to the source documentation in scientific-skills/fluidsim/SKILL.md, this import determines the entire simulation geometry. The 2D solver never allocates memory for a third dimension, ensuring minimal overhead for planar turbulence studies.

Configuring Domain Resolution and Grid Parameters

All configuration occurs through the typed Parameters object created via Simul.create_default_params(). This hierarchical container validates fields at runtime, raising AttributeError for misspelled keys to prevent silent configuration errors.

Spatial Resolution Setup

The spatial resolution is defined under the params.oper namespace. For 2D simulations, set nx and ny to define the grid:

from math import pi

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = 512
params.oper.Lx = params.oper.Ly = 2 * pi

For 3D simulations, you must additionally define nz for the third dimension:

params = Simul.create_default_params()
params.oper.nx = params.oper.ny = params.oper.nz = 256
params.oper.Lx = params.oper.Ly = params.oper.Lz = 2 * pi

As documented in scientific-skills/fluidsim/references/parameters.md, the same API is used for both; the 2D solver simply ignores the nz field if present.

Viscosity and Physics Parameters

3D turbulence simulations typically require lower viscosity to achieve realistic Reynolds numbers compared to 2D cases. Configure the kinematic viscosity via params.nu_2:

• 2D simulations: params.nu_2 = 1e-4
• 3D simulations: params.nu_2 = 5e-5

For advanced physics, 3D cases may require hyper-viscosity adjustments, while 2D configurations often remain stable with standard viscosity only. These parameters are detailed in the physical parameters section of scientific-skills/fluidsim/SKILL.md.

Forcing and Initial Conditions

Both solvers support identical forcing APIs, allowing seamless reuse of turbulence injection strategies. Enable forcing and set the type via the params.forcing namespace:

params.forcing.enable = True
params.forcing.type = "tcrandom"
params.forcing.forcing_rate = 1.0
params.init_fields.type = "noise"

No additional flags are required for dimensionality switching. The forcing rate and type behave consistently across ns2d and ns3d, as detailed in scientific-skills/fluidsim/references/advanced_features.md.

Executing Simulations and Parallelization

Launching Single-Node Runs

Instantiate the simulation object with the configured parameters and start the time-stepping loop:

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

This workflow is identical for both dimensionalities. The time_stepping interface handles CFL conditions and output schedules uniformly.

Enabling MPI for 3D Workloads

High-resolution 3D turbulence simulations typically require distributed memory parallelism. When the fluidsim[mpi] extra is installed, the 3D solver automatically partitions the grid across MPI processes. The 2D solver also supports MPI but typically runs on a single node due to lower memory demands.

This parallelization is transparent to the configuration; the same parameter object works whether running on 1 or 1024 cores, as noted in scientific-skills/fluidsim/references/simulation_workflow.md.

Post-Processing with Unified I/O

FluidSim writes HDF5 output files with identical dataset layouts regardless of dimensionality. This allows a single analysis script to process both 2D and 3D results without modification.

Physical Field Visualization

Access output data through the sim.output namespace:

# Plot vorticity (2D) or velocity component (3D)

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

Energy Spectrum Analysis

Compute turbulence spectra using identical function calls for both solvers:

def plot_energy_spectrum(sim):
    sim.output.spectra.plot1d(tmin=10.0, tmax=sim.params.time_stepping.t_end)

# Works for sim from either ns2d or ns3d

plot_energy_spectrum(sim)

As implemented in scientific-skills/fluidsim/SKILL.md, the spectra and spatial_means output objects expose the same API across all solvers, enabling portable analysis pipelines.

Summary

• Import the correct solver: Use fluidsim.solvers.ns2d.solver.Simul for 2D and fluidsim.solvers.ns3d.solver.Simul for 3D turbulence simulations.
• Set spatial dimensions: Configure params.oper.nx and ny for both; add nz only for 3D.
• Adjust viscosity: 3D simulations typically use smaller nu_2 values to achieve target Reynolds numbers.
• Reuse configuration: Forcing, time-stepping, and output parameters use identical APIs across dimensionalities.
• Leverage MPI: Install fluidsim[mpi] for automatic distributed parallelism in 3D workloads.
• Unified analysis: Post-processing scripts work interchangeably with 2D and 3D output files.

Frequently Asked Questions

What is the primary difference between the ns2d and ns3d solvers in FluidSim?

The ns2d and ns3d solvers are isolated Python packages that share a common base class but enforce strict dimensionality separation. The 2D solver allocates memory only for planar grids, while the 3D solver manages volumetric arrays. This architecture prevents accidental dimension mismatch errors and optimizes memory usage, as detailed in scientific-skills/fluidsim/SKILL.md.

Can I use the same analysis script for both 2D and 3D FluidSim simulations?

Yes. FluidSim implements unified I/O using HDF5 files with identical dataset structures regardless of dimensionality. Methods like sim.output.spectra.plot1d() and sim.output.phys_fields.plot() expose the same API for both solvers, allowing you to write generic post-processing code that handles 2D and 3D data without conditional logic.

How do I enable parallel computing for large-scale 3D turbulence simulations?

Install the optional MPI dependencies using pip install fluidsim[mpi]. The 3D solver automatically detects MPI environments and distributes the 3D grid across available processes. No code changes are required in your simulation script; the same parameter configuration and execution commands work in both single-node and distributed modes.

Which parameters must change when converting a 2D simulation to 3D?

You must change the solver import to fluidsim.solvers.ns3d.solver.Simul and add params.oper.nz to define the third spatial dimension. Additionally, you typically reduce params.nu_2 to maintain appropriate Reynolds numbers in 3D turbulence. All other configurations—including forcing types, time-stepping settings, and output specifications—remain identical between dimensionalities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}