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

> Learn how to configure FluidSim CFD for 2D and 3D turbulence simulations. Discover how to import solver classes and set spatial resolution for accurate results.

- Repository: [K-Dense/scientific-agent-skills](https://github.com/K-Dense-AI/scientific-agent-skills)
- Tags: how-to-guide
- Published: 2026-05-14

---

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

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

```

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

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

```

According to the source documentation in [`scientific-skills/fluidsim/SKILL.md`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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:

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

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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:

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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:

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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:

```python

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

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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.