PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
Loading...
Searching...
No Matches
Configuration Reference: Solver YAML

Table of Contents

For the full commented template, see:

# ==============================================================================
#                 PICurv Master Solver Configuration Template
# ==============================================================================
#
# PURPOSE:
# This file defines the NUMERICAL STRATEGY for the simulation. It is divided
# into user-friendly structured sections for common settings, and a flexible
# 'petsc_passthrough_options' section for advanced users to inject any valid
# PETSc command-line flag.
#
# ==============================================================================

# ==============================================================================
# 1. SOLVER OPERATION MODE
# ==============================================================================
operation_mode:
  # 'solve': (Default) Compute the fluid dynamics equations.
  # 'load':  Load pre-computed field data from disk.
  eulerian_field_source: "solve"  # -> -euler_field_source
  # Optional analytical solution selector used when eulerian_field_source = "analytical".
  # Supported values today: "TGV3D", "ZERO_FLOW", "UNIFORM_FLOW".
  # TGV3D currently requires case.yml to use grid.mode: programmatic_c.
  # ZERO_FLOW and UNIFORM_FLOW also support file-based grid ingestion.
  analytical_type: "TGV3D"        # -> -analytical_type
  # Parameters for analytical_type: "UNIFORM_FLOW".
  # Uncomment this block only when analytical_type = "UNIFORM_FLOW".
  # uniform_flow:
  #   u: 0.0                      # -> -analytical_uniform_u
  #   v: 0.0                      # -> -analytical_uniform_v
  #   w: 0.0                      # -> -analytical_uniform_w

# Verification-only source overrides.
# Use these only when ordinary end-to-end setup cannot expose the behavior you need to test.
# New verification-pathway source injections must be implemented in
# include/verification_sources.h and src/verification_sources.c.
# verification:
#   sources:
#     diffusivity:
#       mode: "analytical"        # Verification-only selector; currently fixed to analytical
#       profile: "LINEAR_X"       # Supported today: LINEAR_X
#       gamma0: 1.0e-3             # -> -verification_diffusivity_gamma0
#       slope_x: 2.0e-4            # -> -verification_diffusivity_slope_x
#
#     scalar:
#       mode: "analytical"        # Verification-only selector; currently fixed to analytical
#       profile: "CONSTANT"       # Supported: CONSTANT, LINEAR_X, SIN_PRODUCT
#       value: 1.0                 # CONSTANT -> -verification_scalar_value
#       # phi0: 0.0                # LINEAR_X -> -verification_scalar_phi0
#       # slope_x: 1.0             # LINEAR_X -> -verification_scalar_slope_x
#       # amplitude: 1.0           # SIN_PRODUCT -> -verification_scalar_amplitude
#       # kx: 3.141592653589793    # SIN_PRODUCT -> -verification_scalar_kx
#       # ky: 3.141592653589793    # SIN_PRODUCT -> -verification_scalar_ky
#       # kz: 3.141592653589793    # SIN_PRODUCT -> -verification_scalar_kz
#
# Scalar verification is intended for runtime diagnostics such as
# logs/scatter_metrics.csv. It bypasses only the particle Psi evolution path and
# reuses the production scatter operator.

# --- Scalar Transport Properties ---
# These affect Eulerian diffusivity and particle scalar/Brownian models.
scalar_transport:
  schmidt_number: 1.0              # -> -schmidt_number
  turbulent_schmidt_number: 0.7    # -> -turb_schmidt_number

# ==============================================================================
# 2. PRIMARY SOLVER STRATEGY & TOLERANCES
# ==============================================================================
# --- Main Time-Stepping Scheme ---
strategy:
  momentum_solver: "Dual Time Picard RK4" # -> -mom_solver_type. Options: "Explicit RK4", "Dual Time Picard RK4"
  central_diff: false # [true/false] -> -central

# --- Convergence Criteria for the Momentum Solver ---
tolerances:
  max_iterations: 50   # [Integer] -> -mom_max_pseudo_steps
  absolute_tol: 1.0e-8 # [Float] -> -mom_atol
  relative_tol: 1.0e-5 # [Float] -> -mom_rtol
  step_tol:     1.0e-8 # [Float] -> -imp_stol

# --- Advanced Momentum Solver Controls (optional) ---
# This section exposes newer dual-time controls directly (no passthrough needed).
momentum_solver:
  # Solver-specific controls for Dual Time Picard RK4.
  dual_time_picard_rk4:
    max_pseudo_steps: 50         # -> -mom_max_pseudo_steps
    absolute_tol: 1.0e-8         # -> -mom_atol
    relative_tol: 1.0e-5         # -> -mom_rtol
    step_tol: 1.0e-8             # -> -imp_stol
    pseudo_cfl:
      initial: 0.1               # -> -pseudo_cfl
      minimum: 0.001             # -> -min_pseudo_cfl
      maximum: 1.0               # -> -max_pseudo_cfl
      growth_factor: 1.0         # -> -pseudo_cfl_growth_factor
      reduction_factor: 1.0      # -> -pseudo_cfl_reduction_factor
    rk4_residual_noise_allowance_factor: 1.05 # -> -mom_dt_rk4_residual_norm_noise_allowance_factor

# --- Physical Solution Convergence Logging ---
# This layer is separate from the inner solver-health logs. It always records
# physical solution drift into logs/solution_convergence.csv without changing
# solver stopping behavior. The optional block below only overrides the mode.
# solution_convergence:
#   mode: "steady_deterministic"   # -> -solution_convergence_mode
#   # For periodic runs, compare each timestep to the same phase in the previous cycle.
#   # periodic_deterministic:
#   #   period_steps: 200          # -> -solution_convergence_period_steps
#   # For statistical-steady runs, compare adjacent windows of scalar observables.
#   # statistical_steady:
#   #   window_steps: 500          # -> -solution_convergence_window_steps

# ==============================================================================
# 3. POISSON SOLVER CONFIGURATION
# ==============================================================================
poisson_solver:
  # Solves for pressure correction Phi, then the runtime updates pressure P.
  # The outer linear solver uses PETSc KSP under the hood, but this block uses
  # PICurv-facing names for the common controls.
  method: "fgmres"             # -> -ps_ksp_type
  absolute_tolerance: 1.0e-5   # -> -ps_ksp_atol and legacy -poisson_tol
  relative_tolerance: 1.0e-11  # -> -ps_ksp_rtol
  max_iterations: 50           # -> -ps_ksp_max_it
  gmres:
    # Only valid for GMRES-family methods: gmres, fgmres, lgmres.
    restart: 20                # -> -ps_ksp_gmres_restart

  preconditioner:
    # Only multigrid is supported for the outer Poisson preconditioner today.
    # Other values are rejected until the C runtime grows a non-PCMG path.
    type: "multigrid"          # -> -ps_pc_type mg

  # --- Geometric Multigrid (PCMG) Settings ---
  multigrid:
    levels: 3         # [Integer] -> -mg_level
    pre_sweeps: 2     # [Integer] -> -mg_pre_it
    post_sweeps: 2    # [Integer] -> -mg_post_it
    # Current PETSc binding applies one smoother count; if these differ,
    # PICurv uses the larger value and logs a warning.
    semi_coarsening:
      i: false        # [true/false] -> -mg_i_semi
      j: false        # [true/false] -> -mg_j_semi
      k: true         # [true/false] -> -mg_k_semi
      
    cycle: "v"        # Currently supported: "v"
    mode: "multiplicative" # Currently supported: "multiplicative"

    # --- Smoother / Coarse Solver Configuration Per MG Level ---
    # PETSc/PICurv level numbering uses level_0 as the coarsest grid; larger
    # level numbers are progressively finer.
    # `method` maps to PETSc KSP type. `preconditioner` maps to PETSc PC type.
    # The default level preconditioner is bjacobi when omitted.
    level_solvers:
      level_0:
        # The coarsest level often uses a more robust solver.
        method: "fgmres"          # -> -ps_mg_levels_0_ksp_type
        preconditioner: "bjacobi" # -> -ps_mg_levels_0_pc_type
      level_1:
        method: "richardson"
        preconditioner: "bjacobi"
      level_2:
        method: "richardson"
        preconditioner: "bjacobi"

# ==============================================================================
# 4. INTERPOLATION
#    Controls grid-to-particle interpolation numerics.
# ==============================================================================
interpolation:
  # Method for interpolating Eulerian fields to particle positions.
  # Options:
  #   - "Trilinear"       (default) Direct trilinear from 8 nearest cell centers.
  #                        Second-order on both uniform and curvilinear grids.
  #   - "CornerAveraged"  Legacy two-stage: center->corner average, then trilinear
  #                        from corners. Second-order only on uniform Cartesian grids.
  method: "Trilinear"     # -> -interpolation_method

# ==============================================================================
# 5. PETSC PASSTHROUGH OPTIONS (FOR ADVANCED USERS)
# ==============================================================================
petsc_passthrough_options:
  # Use this only for advanced PETSc controls that do not have structured YAML
  # above. Structured values and passthrough flags target the same PETSc options;
  # passthrough wins when the same flag is listed in both places.

  # --- MG level preconditioner tuning examples ---
  # jacobi / sor: simple smoother PCs; no extra nested setup is normally needed.
  # -ps_mg_levels_2_pc_type: "sor"
  # -ps_mg_levels_2_pc_sor_omega: 1.0      # PETSc SOR relaxation; positive real

  # ilu / lu: factor PCs; use PETSc factor controls when pivots are fragile.
  # -ps_mg_levels_0_pc_type: "ilu"
  # -ps_mg_levels_0_pc_factor_levels: 1    # nonnegative integer
  # -ps_mg_levels_0_pc_factor_shift_amount: 1.0e-10 # nonnegative real

  # bjacobi: nested block solves. Inspect exact nested prefixes with -ps_ksp_view
  # when tuning sub-KSP/sub-PC options for your PETSc version.

  # --- Additional Momentum Controls (if you prefer passthrough style) ---
  # -pseudo_cfl: 0.1
  # -max_pseudo_cfl: 1.0
  # -min_pseudo_cfl: 0.001
  # -pseudo_cfl_growth_factor: 1.0
  # -pseudo_cfl_reduction_factor: 1.0

solver.yml controls numerical strategy and solver internals.

1. operation_mode

operation_mode:
eulerian_field_source: "solve"
analytical_type: "TGV3D"
uniform_flow:
u: 0.0
v: 0.0
w: 0.0

Mappings:

  • eulerian_field_source -> -euler_field_source (solve, load, analytical)
  • analytical_type -> -analytical_type
  • uniform_flow.u/v/w -> -analytical_uniform_u/-analytical_uniform_v/-analytical_uniform_w when analytical_type: "UNIFORM_FLOW"

uniform_flow is only valid when analytical_type: "UNIFORM_FLOW".

2. strategy

strategy:
momentum_solver: "Dual Time Picard RK4"
central_diff: false

Mappings:

  • momentum_solver -> -mom_solver_type (picurv accepts Explicit RK4 or Dual Time Picard RK4)
  • central_diff -> -central

Older boolean toggles are not supported; use strategy.momentum_solver. Only implemented momentum solver values are accepted by picurv and the C runtime.

3. tolerances

tolerances:
max_iterations: 50
absolute_tol: 1.0e-7
relative_tol: 1.0e-4
step_tol: 1.0e-8

Mappings:

  • max_iterations -> -mom_max_pseudo_steps
  • absolute_tol -> -mom_atol
  • relative_tol -> -mom_rtol
  • step_tol -> -imp_stol

4. momentum_solver (Solver-Specific Block)

momentum_solver:
dual_time_picard_rk4:
max_pseudo_steps: 50
absolute_tol: 1.0e-8
relative_tol: 1.0e-5
step_tol: 1.0e-8
pseudo_cfl:
initial: 0.1
minimum: 0.001
maximum: 1.0
growth_factor: 1.0
reduction_factor: 1.0
rk4_residual_noise_allowance_factor: 1.05

Mappings include:

  • -pseudo_cfl, -min_pseudo_cfl, -max_pseudo_cfl
  • -pseudo_cfl_growth_factor, -pseudo_cfl_reduction_factor
  • -mom_dt_rk4_residual_norm_noise_allowance_factor

Rule: solver-specific blocks must match selected momentum solver type.

5. poisson_solver

poisson_solver:
method: "fgmres"
absolute_tolerance: 1.0e-5
relative_tolerance: 1.0e-11
max_iterations: 50
gmres:
restart: 20
preconditioner:
type: "multigrid"
multigrid:
levels: 3
pre_sweeps: 2
post_sweeps: 2
cycle: "v"
mode: "multiplicative"
semi_coarsening:
i: false
j: false
k: true
level_solvers:
level_0:
method: "fgmres"
preconditioner: "bjacobi"
level_1:
method: "richardson"
preconditioner: "bjacobi"
level_2:
method: "richardson"
preconditioner: "bjacobi"

Mappings:

  • method -> -ps_ksp_type
  • absolute_tolerance -> -ps_ksp_atol and legacy -poisson_tol
  • relative_tolerance -> -ps_ksp_rtol
  • max_iterations -> -ps_ksp_max_it
  • gmres.restart -> -ps_ksp_gmres_restart; valid only for gmres, fgmres, or lgmres
  • preconditioner.type -> -ps_pc_type; currently only multigrid is supported
  • multigrid.levels -> -mg_level
  • multigrid.pre_sweeps -> -mg_pre_it
  • multigrid.post_sweeps -> -mg_post_it
  • multigrid.semi_coarsening.i/j/k -> -mg_i_semi/-mg_j_semi/-mg_k_semi
  • multigrid.level_solvers.level_N.method -> -ps_mg_levels_N_ksp_type
  • multigrid.level_solvers.level_N.preconditioner -> -ps_mg_levels_N_pc_type
  • multigrid.cycle and multigrid.mode are validated structured keys; current supported values are v and multiplicative.

Rules:

  • pressure_solver is accepted as a legacy alias, but poisson_solver is preferred because the linear solve computes pressure correction Phi.
  • MG level numbering follows PETSc/PICurv convention: level_0 is the coarsest level and larger numbers are finer.
  • The outer Poisson preconditioner is multigrid-only in the current runtime.
  • The current PETSc binding applies one MG smoother count; when pre_sweeps and post_sweeps differ, PICurv uses the larger value and logs a warning.
  • Advanced PETSc tuning remains available through petsc_passthrough_options; common examples include -ps_mg_levels_N_pc_sor_omega for SOR and -ps_mg_levels_N_pc_factor_shift_amount / -ps_mg_levels_N_pc_factor_levels for factor PCs.

6. solution_convergence

solution_convergence:
mode: "steady_deterministic" # steady_deterministic | periodic_deterministic | statistical_steady | transient
periodic_deterministic:
period_steps: 200
statistical_steady:
window_steps: 500

Mappings:

  • mode -> -solution_convergence_mode
  • periodic_deterministic.period_steps -> -solution_convergence_period_steps
  • statistical_steady.window_steps -> -solution_convergence_window_steps

Rules:

  • the solution_convergence block is optional; when omitted, the runtime still logs logs/solution_convergence.log once per physical timestep using the default steady_deterministic mode.
  • it is logging-only in the current implementation.
  • it does not replace the existing inner solver-health logs:
    • logs/Momentum_Solver_Convergence_History_Block_*.log
    • logs/Poisson_Solver_Convergence_History_Block_*.log
    • logs/Continuity_Metrics.log
  • periodic_deterministic.period_steps is required only when mode: "periodic_deterministic".
  • statistical_steady.window_steps is required only when mode: "statistical_steady".
  • nested mode blocks are rejected when they do not match the selected mode.

Mode intent:

  • steady_deterministic: timestep-to-timestep physical field drift for runs expected to settle to a fixed state.
  • periodic_deterministic: phase-aligned cycle drift using one stored period of field snapshots.
  • statistical_steady: adjacent-window drift of global observables for runs whose instantaneous fields should not settle pointwise.
  • transient: logs the same deterministic drift family for diagnosis, but without any implied steady-state interpretation.

7. interpolation

interpolation:
method: "Trilinear" # default; or "CornerAveraged"

Mappings:

  • method -> -interpolation_method (Trilinear = 0, CornerAveraged = 1)

The Trilinear method (default) performs direct trilinear interpolation from the 8 nearest cell centers, providing second-order accuracy on both uniform and curvilinear grids. The CornerAveraged method is the legacy two-stage path (center-to-corner average, then trilinear from corners), which is second-order only on uniform Cartesian grids.

See Trilinear Interpolation and Particle-Grid Projection for algorithmic details.

8. scalar_transport

scalar_transport:
schmidt_number: 1.0
turbulent_schmidt_number: 0.7

Mappings:

  • schmidt_number -> -schmidt_number
  • turbulent_schmidt_number -> -turb_schmidt_number

Rules:

  • values must be positive numbers
  • omitted values use the C runtime defaults: schmidt_number = 1.0 and turbulent_schmidt_number = 0.7
  • use this structured block for ordinary scalar/Brownian transport tuning; reserve petsc_passthrough_options for flags without a YAML schema

9. verification

verification:
sources:
diffusivity:
mode: "analytical"
profile: "LINEAR_X"
gamma0: 1.0e-3
slope_x: 2.0e-4
scalar:
mode: "analytical"
profile: "CONSTANT" # or LINEAR_X, SIN_PRODUCT
value: 1.0
# phi0: 0.0
# slope_x: 1.0
# amplitude: 1.0
# kx: 3.141592653589793
# ky: 3.141592653589793
# kz: 3.141592653589793

Mappings:

  • verification.sources.diffusivity.mode -> -verification_diffusivity_mode
  • verification.sources.diffusivity.profile -> -verification_diffusivity_profile
  • verification.sources.diffusivity.gamma0 -> -verification_diffusivity_gamma0
  • verification.sources.diffusivity.slope_x -> -verification_diffusivity_slope_x
  • verification.sources.scalar.mode -> -verification_scalar_mode
  • verification.sources.scalar.profile -> -verification_scalar_profile
  • verification.sources.scalar.value -> -verification_scalar_value
  • verification.sources.scalar.phi0 -> -verification_scalar_phi0
  • verification.sources.scalar.slope_x -> -verification_scalar_slope_x
  • verification.sources.scalar.amplitude -> -verification_scalar_amplitude
  • verification.sources.scalar.kx/ky/kz -> -verification_scalar_kx/-verification_scalar_ky/-verification_scalar_kz

Rules:

  • this path is verification-only and should be used only when no ordinary end-to-end workflow can expose the behavior under test
  • it is only valid with operation_mode.eulerian_field_source: "analytical"
  • verification.sources.scalar prescribes particle Psi from analytical truth and enables the runtime diagnostic logs/scatter_metrics.csv
  • scalar profiles currently supported are CONSTANT, LINEAR_X, and SIN_PRODUCT
  • new verification source overrides must be implemented in include/verification_sources.h and src/verification_sources.c

10. petsc_passthrough_options

Advanced escape hatch for raw PETSc flags:

petsc_passthrough_options:
-ps_ksp_type: "gmres"
-ps_pc_type: "ilu"

These are passed into PETSc options DB and consumed by runtime calls like KSPSetFromOptions.

11. Next Steps

Proceed to Configuration Reference: Monitor YAML.

For mapping and extension workflows:

CFD Reader Guidance and Practical Use

This page describes Configuration Reference: Solver YAML 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.
Generated by doxygen 1.9.8