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