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

# ==============================================================================
# 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

# ==============================================================================
# 3. PRESSURE-POISSON SOLVER CONFIGURATION
# ==============================================================================
pressure_solver:
  # --- Main Tolerance ---
  tolerance: 1.0e-9 # [Float] -> -poisson_tol

  # --- Geometric Multigrid (PCMG) Settings ---
  multigrid:
    levels: 3         # [Integer] -> -mg_level
    pre_sweeps: 2     # [Integer] -> -mg_pre_it
    post_sweeps: 2    # [Integer] -> -mg_post_it
    semi_coarsening:
      i: false        # [true/false] -> -mg_i_semi
      j: false        # [true/false] -> -mg_j_semi
      k: true         # [true/false] -> -mg_k_semi
      
    # --- CONVENIENCE: Smoother Configuration Per Level ---
    # This section sets the KSP (solver) type for the smoother on each MG level.
    # NOTE: The C-code hardcodes the preconditioner (PC) for each smoother to
    #       Block Jacobi (PCBJACOBI). You can only set the KSP type here.
    # Level 0 is the finest grid.
    level_solvers:
      level_0:
        ksp_type: "richardson" # -> -ps_mg_levels_0_ksp_type "richardson"
      level_1:
        ksp_type: "chebyshev"  # -> -ps_mg_levels_1_ksp_type "chebyshev"
      level_2:
        # The coarsest level often uses a more robust solver.
        ksp_type: "gmres"      # -> -ps_mg_levels_2_ksp_type "gmres"

# ==============================================================================
# 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:
  # --- Top-level KSP settings ---
  -ps_ksp_type: "fgmres"
  -ps_ksp_rtol: 1.0e-11
  -ps_ksp_max_it: 50
  
  # --- PC (Preconditioner) Settings ---
  # The C-code forces the top-level PC to be 'mg'. This line is for clarity.
  -ps_pc_type: "mg"

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

  # --- Redundant/Ineffective Flag Example ---
  # You could add the following line here, but the C-code's hardcoded
  # PCSetType(subpc, PCBJACOBI) call would override it. It will have no effect.
  # -ps_mg_levels_1_pc_type: "sor"

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

pressure_solver:
  tolerance: 5.0e-9
  multigrid:
    levels: 3
    pre_sweeps: 1
    post_sweeps: 1

Mappings:

tolerance -> -poisson_tol
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

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

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

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

8. Next Steps

Proceed to Configuration Reference: Monitor YAML.

For mapping and extension workflows:

Developer Ingestion Map
Configuration Extension Playbook
Momentum Solver Implementations
Dual-Time Picard RK4 Momentum Solver
Pressure-Poisson, GMRES, and Multigrid
Modular Selector Extension Guide

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

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

Table of Contents

1. operation_mode

2. strategy

3. tolerances

4. momentum_solver (Solver-Specific Block)

5. pressure_solver

6. interpolation

7. verification

8. petsc_passthrough_options

8. Next Steps

CFD Reader Guidance and Practical Use

What To Extract Before Changing A Case

Practical CFD Troubleshooting Pattern