Repository navigation
Solver Guide
This guide covers the available solvers, their characteristics, and how to choose the right one for your simulation.
| Solver Type | Description | Best For |
|---|---|---|
explicit_euler |
Basic explicit Euler method | Learning, debugging, small grids |
explicit_euler_optimized |
AVX2-optimized explicit Euler | Large grids on modern CPUs |
explicit_euler_omp |
OpenMP-parallelized explicit Euler | Multi-core systems |
explicit_euler_gpu |
GPU-accelerated explicit Euler | Very large grids with NVIDIA GPU |
projection |
Projection method for incompressible flow | Accurate pressure-velocity coupling |
projection_optimized |
AVX2-optimized projection method | Production simulations |
projection_omp |
OpenMP-parallelized projection | Multi-core production use |
projection_gpu |
GPU-accelerated projection (CG pressure solve) | High-performance simulations |
rk2 |
RK2 (Heun's method) time integration | Second-order temporal accuracy |
rk2_optimized |
AVX2-optimized RK2 | High-accuracy large grids |
rk2_omp |
OpenMP-parallelized RK2 | High-accuracy multi-core |
rk2_gpu |
GPU-accelerated RK2 | High-accuracy on NVIDIA GPU |
rk4 |
RK4 (classical Runge-Kutta) time integration | Fourth-order temporal accuracy |
rk4_optimized |
AVX2-optimized RK4 | Fourth-order accuracy, large grids |
rk4_omp |
OpenMP-parallelized RK4 | Fourth-order accuracy, multi-core |
rk4_gpu |
GPU-accelerated RK4 | Fourth-order accuracy on NVIDIA GPU |
-
*_optimizedsolvers are AVX2 only; there are no NEON Navier-Stokes kernels. They need a build with-DCFD_ENABLE_AVX2=ON(off by default) and a CPU with AVX2 and FMA. OtherwiseinitreturnsCFD_ERROR_UNSUPPORTEDinstead of running scalar kernels.projection_optimizedalso needs OpenMP, because its pressure solver is threaded. -
*_ompsolvers are registered only when OpenMP is found at configure time. -
*_gpusolvers are registered only in a build with-DCFD_ENABLE_CUDA=ON.
Use the plain names (explicit_euler, projection, rk2, rk4) for a path that works in every build.
#include "cfd/api/simulation_api.h"
// Option 1: Default solver (explicit_euler)
simulation_data* sim = init_simulation(100, 100, 1,
0.0, 1.0, 0.0, 1.0, 0.0, 0.0);
// Option 2: Specify solver at creation (returns NULL if the solver cannot initialize)
simulation_data* sim2 = init_simulation_with_solver(
100, 100, 1, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0,
NS_SOLVER_TYPE_PROJECTION_OPTIMIZED
);
// Option 3: Change solver at runtime
simulation_set_solver_by_name(sim, NS_SOLVER_TYPE_EXPLICIT_EULER_OPTIMIZED);#include "cfd/api/simulation_api.h"
#include <stdio.h>
const char* solver_names[16];
int count = simulation_list_solvers(solver_names, 16);
printf("Listed solvers:\n");
for (int i = 0; i < count; i++) {
printf(" - %s\n", solver_names[i]);
}simulation_list_solvers() returns a fixed list: explicit_euler, explicit_euler_optimized, projection, projection_optimized, explicit_euler_gpu, projection_gpu, plus explicit_euler_omp and projection_omp when built with OpenMP. It does not include the RK2 or RK4 solvers, and it lists the GPU names whether or not CUDA is present. To enumerate what a registry actually holds, use cfd_registry_list() on sim->registry:
const char* names[32];
int n = cfd_registry_list(sim->registry, names, 32);if (cfd_registry_has(sim->registry, NS_SOLVER_TYPE_RK4_GPU)) {
printf("GPU solver is registered\n");
}
if (cfd_backend_is_available(NS_SOLVER_BACKEND_SIMD)) {
printf("AVX2 solvers can run\n");
}cfd_registry_has() reports whether a name is registered in this build (*_gpu only with CUDA, *_omp only with OpenMP). It does not check that the solver can initialize: *_optimized solvers are registered in every build but fail at init without AVX2. cfd_backend_is_available() (declared in cfd/solvers/navier_stokes_solver.h) tests a backend (NS_SOLVER_BACKEND_SIMD, _OMP, _CUDA) directly. simulation_has_solver() checks the fixed list above, so it is not a reliable build probe.
Each solver reports its capabilities through bitflags:
| Capability | Description |
|---|---|
NS_SOLVER_CAP_INCOMPRESSIBLE |
Supports incompressible flow |
NS_SOLVER_CAP_COMPRESSIBLE |
Supports compressible flow |
NS_SOLVER_CAP_TRANSIENT |
Supports transient (time-dependent) problems |
NS_SOLVER_CAP_STEADY_STATE |
Supports steady-state solutions |
NS_SOLVER_CAP_SIMD |
Uses SIMD (AVX2) optimizations |
NS_SOLVER_CAP_PARALLEL |
Supports parallel execution (OpenMP) |
NS_SOLVER_CAP_GPU |
Uses GPU acceleration (CUDA) |
NS_SOLVER_CAP_IMPLICIT_VISCOUS |
Honours an implicit viscous_scheme
|
ns_solver_t* solver = simulation_get_solver(sim);
if (solver->capabilities & NS_SOLVER_CAP_SIMD) {
printf("Using SIMD optimizations\n");
}
if (solver->capabilities & NS_SOLVER_CAP_GPU) {
printf("Using GPU acceleration\n");
}After each step, you can retrieve performance statistics:
run_simulation_step(sim);
const ns_solver_stats_t* stats = simulation_get_stats(sim);
printf("Iterations: %d\n", stats->iterations);
printf("Residual: %.2e\n", stats->residual);
printf("Max velocity: %.4f\n", stats->max_velocity);
printf("Max pressure: %.4f\n", stats->max_pressure);
printf("CFL number: %.4f\n", stats->cfl_number);
printf("Time step used: %.2e\n", stats->dt_used);
printf("Elapsed time: %.2f ms\n", stats->elapsed_time_ms);max_temperature is filled when the energy equation is active and max_nu_t when a turbulence model is active. Read dt_used rather than params.dt to measure simulated time: the explicit Euler solvers clamp the step to NS_EULER_DT_LIMIT (0.0001).
Use explicit_euler - it's the simplest and easiest to understand.
-
Small grids (< 200x200):
projectionorexplicit_euler -
Medium grids (200x200 - 1000x1000):
projection_optimizedorrk2_optimized -
Large grids with multi-core CPU:
projection_omporrk2_omp -
Fourth-order time accuracy:
rk4,rk4_optimized, orrk4_omp
- Requires NVIDIA GPU and CUDA Toolkit
- Use
projection_gpuorexplicit_euler_gpu;rk2_gpuandrk4_gpufor higher temporal order - Best for grids larger than 500x500
- GPU solvers do not support turbulence models, upwind convection, or implicit viscous stepping (
CFD_ERROR_UNSUPPORTED)
| Aspect | Explicit Euler | Projection | RK2 (Heun) | RK4 |
|---|---|---|---|---|
| Simplicity | Simplest | More complex | Moderate | Moderate |
| Temporal order | 1st | 1st | 2nd | 4th |
| Stability | CFL limited | Better | CFL limited | CFL limited |
| Pressure | Approximate | Divergence-free | Approximate | Approximate |
| Speed per step | Fastest | Slowest | Moderate | Moderate |
Default solver parameters can be customized:
simulation_data* sim = init_simulation(100, 100, 1,
0.0, 1.0, 0.0, 1.0, 0.0, 0.0);
// Modify parameters
sim->params.dt = 0.001; // Time step
sim->params.cfl = 0.2; // CFL number
sim->params.mu = 0.01; // Viscosity
sim->params.max_iter = 200; // Max iterations per step
sim->params.tolerance = 1e-6; // Convergence toleranceThese are the values of ns_solver_params_default():
| Parameter | Default | Description |
|---|---|---|
dt |
0.001 | Time step size |
cfl |
0.2 | CFL number for stability |
gamma |
1.4 | Specific heat ratio |
mu |
0.01 | Dynamic viscosity |
k |
0.0242 | Thermal conductivity |
max_iter |
100 | Maximum iterations |
tolerance |
1e-6 | Convergence tolerance |
init_simulation() sets dt to 0.001, cfl to 0.2, mu to 0.01 and max_iter to 1. run_simulation_step() steps with sim->params.dt (read stats->dt_used for the step actually taken); a zero, negative or non-finite dt is refused.
These ns_solver_params_t fields select numerical methods and physics models. Each enum has 0 as the default, so a zero-initialized or ns_solver_params_default() struct keeps the original behavior. Unsupported combinations are refused at solver_init with CFD_ERROR_UNSUPPORTED (or CFD_ERROR_INVALID for an out-of-range value); the library never falls back to another backend silently.
The projection solvers solve a pressure Poisson equation each step, with CG by default. On projection and projection_omp you can switch to geometric multigrid, on the solver's own backend:
| Value | Pressure solve |
|---|---|
NS_PRESSURE_SOLVER_DEFAULT (0) |
CG |
NS_PRESSURE_SOLVER_MULTIGRID |
Multigrid V-cycles |
NS_PRESSURE_SOLVER_PCG_MG |
CG preconditioned by one multigrid V-cycle |
simulation_data* sim = init_simulation_with_solver(
129, 129, 1, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0, NS_SOLVER_TYPE_PROJECTION);
sim->params.pressure_solver = NS_PRESSURE_SOLVER_MULTIGRID; // read on every step- Multigrid needs 2^k+1 grid points per active dimension (33, 65, 129, ...); other sizes return
CFD_ERROR_UNSUPPORTED. -
projection_optimizedandprojection_gpureject any non-default value. - Multigrid convergence per cycle does not depend on grid size, which pays off on fine grids and long steady runs. See the
steady_flow_multigridexample.
params.pressure_bc prescribes the pressure on a face (POISSON_WALL_DIRICHLET) to drive a flow by an inlet/outlet pressure difference instead of a velocity; the default is zero-gradient on every wall. It is honoured by the scalar, OpenMP and AVX2 projection solvers. See the pressure_driven_channel example.
| Value | Scheme |
|---|---|
NS_CONVECTION_SCHEME_CENTRAL (0) |
Second-order central differences |
NS_CONVECTION_SCHEME_UPWIND |
First-order upwind differences |
Central differencing produces oscillations when convection dominates (cell Peclet number |u|h/nu > 2). Upwind removes them at the cost of numerical diffusion (|u|h/2) that smears gradients. Use it for coarse grids, high-Reynolds-number startup and convection-dominated flows. It applies to momentum convection and temperature advection; pressure gradients and viscous terms stay central.
Upwind is available on the scalar, OpenMP and AVX2 backends. GPU solvers return CFD_ERROR_UNSUPPORTED. Explicit steps must still satisfy the convective CFL and diffusion limits.
ns_solver_params_t params = ns_solver_params_default();
params.convection_scheme = NS_CONVECTION_SCHEME_UPWIND;
ns_solver_registry_t* registry = cfd_registry_create();
cfd_registry_register_defaults(registry);
ns_solver_t* solver = cfd_solver_create(registry, NS_SOLVER_TYPE_PROJECTION_OMP);
cfd_status_t status = solver_init(solver, grid, ¶ms);By default the viscous term is explicit, so dt is bounded by dt < h^2 / (2 * nu * ndim). Implicit schemes remove that limit:
| Value | Stability | Notes |
|---|---|---|
NS_VISCOUS_SCHEME_EXPLICIT (0) |
Diffusion-limited | Forward Euler |
NS_VISCOUS_SCHEME_BACKWARD_EULER |
Unconditional, L-stable | Damps stiff modes; use to march to steady state with a large dt
|
NS_VISCOUS_SCHEME_CRANK_NICOLSON |
Unconditional, A-stable | Second-order viscous term; use for transients near the explicit limit |
Implicit stepping buys stability, not accuracy: convection stays forward Euler and the projection is non-incremental, so a full step is still first-order in time. It is implemented on projection and projection_omp only (other solvers return CFD_ERROR_UNSUPPORTED), is limited to laminar flow (combining it with a turbulence model is rejected), and leaves the energy equation explicit. See the pressure_driven_channel example.
ns_solver_params_t params = ns_solver_params_default();
params.viscous_scheme = NS_VISCOUS_SCHEME_BACKWARD_EULER;Setting params.alpha (thermal diffusivity) above zero enables temperature advection-diffusion. Boussinesq buoyancy uses beta, T_ref and gravity; per-face thermal boundary conditions go in thermal_bc:
params.alpha = 2.0e-5; // thermal diffusivity [m^2/s]; 0 disables the energy equation
params.beta = 1.0 / 300.0; // thermal expansion coefficient [1/K]
params.T_ref = 300.0; // Boussinesq reference temperature [K]
params.gravity[1] = -9.81; // gravity vector (gx, gy, gz)
params.thermal_bc.left = BC_TYPE_DIRICHLET; // hot wall
params.thermal_bc.dirichlet_values.left = 310.0;
params.thermal_bc.top = BC_TYPE_NEUMANN; // adiabaticThermal faces default to periodic. The energy equation runs on the scalar, OpenMP and AVX2 backends of every solver and on the GPU projection solver; the GPU path accepts only periodic, Neumann and Dirichlet thermal BCs and rejects heat_source_func. See the natural_convection example.
turb_model |
Model | Cost relative to a laminar step |
|---|---|---|
TURB_MODEL_NONE (0) |
Laminar | 1x |
TURB_MODEL_K_EPSILON |
Standard k-epsilon (Launder-Spalding) | about 2x |
TURB_MODEL_SPALART_ALLMARAS |
Spalart-Allmaras, one equation | about 1.5x |
The solver adds the eddy viscosity to the molecular viscosity in the momentum equation; the eddy viscosity is stored in field->nu_t (with turb_k, turb_eps, turb_nu_tilde).
params.turb_bc sets the turbulence boundary condition on each face; faces default to BC_TYPE_PERIODIC:
| Face type | Meaning |
|---|---|
BC_TYPE_PERIODIC |
Wrap-around (default) |
BC_TYPE_NEUMANN |
Zero-gradient (outlet) |
BC_TYPE_DIRICHLET |
Fixed values from k_values, eps_values, nu_tilde_values (inlet) |
BC_TYPE_NOSLIP |
Wall function wall |
turb_bc.wall_law selects the law of the wall on NOSLIP faces: NS_WALL_LAW_LOG (default, closer to channel DNS from y+ of about 20) or NS_WALL_LAW_SPALDING (closer below y+ of about 17). Place the first interior node at 30 <= y+ <= 100. turbulence_bc_add_segment() overrides a face over part of its length, so one edge can be a wall in one stretch and an inflow in another.
#include "cfd/solvers/navier_stokes_solver.h"
#include "cfd/solvers/turbulence_solver.h"
ns_solver_params_t params = ns_solver_params_default();
params.turb_model = TURB_MODEL_K_EPSILON;
params.turb_bc.bottom = BC_TYPE_NOSLIP; // wall-function walls
params.turb_bc.top = BC_TYPE_NOSLIP; // left/right stay periodic
params.turb_bc.wall_law = NS_WALL_LAW_LOG;
// Seed k, epsilon and nu_tilde before the first step
turbulence_init_uniform(field, ¶ms, k0, eps0, nu_tilde0);Limits in this release: 2D uniform grids only (3D and non-uniform grids return CFD_ERROR_UNSUPPORTED); scalar, OpenMP and AVX2 backends only (GPU solvers return CFD_ERROR_UNSUPPORTED); the energy equation is not coupled to turbulence. See the turbulent_channel example. The channel-flow validation results are in docs/reference/solvers.md in the repository.
-
Match solver to hardware: Use SIMD solvers on modern CPUs (with
-DCFD_ENABLE_AVX2=ON), GPU solvers on NVIDIA hardware - Use appropriate grid size: Larger grids benefit more from parallelization
- Monitor CFL number: Keep it below 1.0 for stability
- Profile your simulation: Use solver statistics to identify bottlenecks
- Consider RK2 or RK4 for accuracy: When temporal accuracy matters, RK2 gives O(dt^2) and RK4 O(dt^4) convergence
- Use multigrid for long steady runs: On 2^k+1 grids it replaces the default CG pressure solve with one whose convergence rate does not depend on grid size
- Getting Started - Basic usage
- Output System - Saving simulation results
- Examples - Working code examples