Pressure-Poisson, GMRES, and Multigrid

Table of Contents

• 1. Pressure-Correction Equation
• 2. Multigrid/KSP Stack In Code
• 3. YAML Mapping and PETSc Options
• 4. Robustness Characteristics
• 5. Current test status
• 6. Related Pages
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This page describes the pressure-correction solve path used by projection in PICurv.

1. Pressure-Correction Equation

The correction solve enforces incompressibility through:

\[ \nabla^2 \phi = \frac{1}{\Delta t}\nabla\cdot\mathbf{u}^*. \]

In code terms:

• RHS assembly: divergence source in PoissonRHS
• LHS assembly: metric-aware operator in PoissonLHSNew
• solve orchestration: PoissonSolver_MG

Null-space handling is explicitly configured for Neumann-like pressure systems via function PoissonNullSpaceFunction in the Poisson module.

2. Multigrid/KSP Stack In Code

PoissonSolver_MG currently:

1. assembles per-level operators,
2. configures KSP + PCMG,
3. sets restriction/interpolation operators (MyRestriction and MyInterpolation plus solid-aware variants),
4. applies level smoothers/coarse solve,
5. solves finest-level system for Phi.

After Poisson solve:

• pressure is updated by UpdatePressure
• velocity is projected by Projection

3. YAML Mapping and PETSc Options

From solver.yml via scripts/picurv:

• poisson_solver.method -> -ps_ksp_type
• poisson_solver.absolute_tolerance -> -ps_ksp_atol and legacy -poisson_tol
• poisson_solver.relative_tolerance -> -ps_ksp_rtol
• poisson_solver.max_iterations -> -ps_ksp_max_it
• poisson_solver.gmres.restart -> -ps_ksp_gmres_restart
• poisson_solver.preconditioner.type -> -ps_pc_type; only multigrid is supported today
• poisson_solver.multigrid.levels -> -mg_level
• poisson_solver.multigrid.pre_sweeps -> -mg_pre_it
• poisson_solver.multigrid.post_sweeps -> -mg_post_it
• poisson_solver.multigrid.semi_coarsening.{i,j,k} -> -mg_i_semi, -mg_j_semi, -mg_k_semi
• poisson_solver.multigrid.level_solvers.level_N.method -> -ps_mg_levels_N_ksp_type
• poisson_solver.multigrid.level_solvers.level_N.preconditioner -> -ps_mg_levels_N_pc_type
• poisson_solver.multigrid.cycle and .mode are accepted structured keys; current supported values are v and multiplicative
• pressure_solver remains a legacy alias for poisson_solver
• petsc_passthrough_options -> advanced PETSc flags not exposed as structured YAML

Final option parsing happens in function CreateSimulationContext during context creation.

MG level numbering follows PETSc/PICurv convention: level_0 is the coarsest grid. Larger level numbers are progressively finer. The default MG level preconditioner is block Jacobi (bjacobi) when not specified. The current PETSc binding applies one MG smoother count; if pre_sweeps and post_sweeps differ, PICurv uses the larger value and logs a warning.

Common MG-level preconditioner notes:

• jacobi and sor are simple smoother PCs. SOR can use -ps_mg_levels_N_pc_sor_omega <positive-real> through passthrough when needed.
• ilu and lu are factor PCs. Useful passthrough knobs include -ps_mg_levels_N_pc_factor_levels <nonnegative-integer> and -ps_mg_levels_N_pc_factor_shift_amount <nonnegative-real>.
• bjacobi owns nested block solves; inspect exact nested PETSc prefixes with -ps_ksp_view before tuning sub-KSP/sub-PC options for a specific PETSc build.

4. Robustness Characteristics

Current implementation includes:

• periodic-boundary pressure synchronization,
• immersed-boundary-aware treatment paths (Nvert/solid checks),
• optional Poisson monitor logging via monitor.yml -> solver_monitoring.poisson.pic_true_residual.

If pressure solve quality degrades, check first:

1. BC consistency,
2. MG level/smoother settings,
3. grid metrics/orientation quality,
4. solver tolerances vs timestep.

5. Current test status

Current direct tests are strongest for helper and invariant behavior:

• PoissonLHSNew
• Projection
• PoissonNullSpaceFunction
• RHS-related helpers used by ComputeRHS

The main remaining gap is PoissonSolver_MG: it is exercised in runtime smoke, but still lacks equivalent direct bespoke coverage for debugging. Periodic and immersed-boundary stencil branches also remain thinner than the core Cartesian helper surface.

6. Related Pages

• Fractional-Step (Projection) Method
• Dual-Time Picard RK4 Momentum Solver
• Momentum Solver Implementations

CFD Reader Guidance and Practical Use

This page describes Pressure-Poisson, GMRES, and Multigrid within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.

Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.

What To Extract Before Changing A Case

• Identify which YAML role or runtime stage this page governs.
• List the primary control knobs (tolerances, cadence, paths, selectors, or mode flags).
• Record expected success indicators (convergence trend, artifact presence, or stable derived metrics).
• Record failure signals that require rollback or parameter isolation.

Practical CFD Troubleshooting Pattern

1. Reproduce the issue on a tiny case or narrow timestep window.
2. Change one control at a time and keep all other roles/configs fixed.
3. Validate generated artifacts and logs after each change before scaling up.
4. If behavior remains inconsistent, compare against a known-good baseline example and re-check grid/BC consistency.