Skip to content

Solver Guide

shaia edited this page Oct 5, 2026 · 4 revisions

Solver Guide

This guide covers the available solvers, their characteristics, and how to choose the right one for your simulation.

Available Solvers

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

Backend requirements

  • *_optimized solvers 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. Otherwise init returns CFD_ERROR_UNSUPPORTED instead of running scalar kernels. projection_optimized also needs OpenMP, because its pressure solver is threaded.
  • *_omp solvers are registered only when OpenMP is found at configure time.
  • *_gpu solvers 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.

Solver Selection

Using the Simulation API

#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);

Listing Available Solvers

#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);

Checking Solver Availability

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.

Solver Capabilities

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

Querying Capabilities

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");
}

Solver Statistics

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

Choosing a Solver

For Learning and Debugging

Use explicit_euler - it's the simplest and easiest to understand.

For Production (CPU)

  • Small grids (< 200x200): projection or explicit_euler
  • Medium grids (200x200 - 1000x1000): projection_optimized or rk2_optimized
  • Large grids with multi-core CPU: projection_omp or rk2_omp
  • Fourth-order time accuracy: rk4, rk4_optimized, or rk4_omp

For High Performance (GPU)

  • Requires NVIDIA GPU and CUDA Toolkit
  • Use projection_gpu or explicit_euler_gpu; rk2_gpu and rk4_gpu for 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)

Solver Comparison

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

Solver Parameters

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 tolerance

Default Values

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

Advanced Solver Options

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.

Pressure Solver (pressure_solver)

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_optimized and projection_gpu reject 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_multigrid example.

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.

Convection Scheme (convection_scheme)

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, &params);

Viscous Time Stepping (viscous_scheme)

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;

Heat Transfer (Energy Equation)

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;      // adiabatic

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

Turbulence (turb_model, turb_bc)

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, &params, 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.

Performance Tips

  1. Match solver to hardware: Use SIMD solvers on modern CPUs (with -DCFD_ENABLE_AVX2=ON), GPU solvers on NVIDIA hardware
  2. Use appropriate grid size: Larger grids benefit more from parallelization
  3. Monitor CFL number: Keep it below 1.0 for stability
  4. Profile your simulation: Use solver statistics to identify bottlenecks
  5. Consider RK2 or RK4 for accuracy: When temporal accuracy matters, RK2 gives O(dt^2) and RK4 O(dt^4) convergence
  6. 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

See Also