|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
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:
# Accepted values:
# "Dual Time Picard Jameson RK" -> implicit dual-time pseudo-stepping (recommended)
# "Explicit RK4" -> explicit fourth-order Runge-Kutta
# "Newton Krylov" -> matrix-free PETSc SNES/KSP solve
momentum_solver: "Dual Time Picard Jameson RK" # -> -mom_solver_type
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
residual_absolute_tol: 0.0 # Disabled when non-positive
residual_relative_tol: 1.0e-3 # Use 1.0e-2 for looser exploratory LES
# Step-change tolerance: stop inner loop when ||u_n+1 - u_n|| < step_tol.
# Non-positive or omitted = disabled.
# step_tol: 0.0 # [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 Jameson RK.
# Note: 'dual_time_picard_rk4' is an accepted deprecated alias for this block.
dual_time_picard_jameson_rk:
max_pseudo_steps: 50 # -> -mom_max_pseudo_steps
absolute_tol: 1.0e-8 # -> -mom_atol
relative_tol: 1.0e-5 # -> -mom_rtol
# Step-change tolerance (optional, mirrors tolerances.step_tol):
# step_tol: 0.0 # -> -imp_stol
pseudo_cfl:
# Phase 3+: pseudo_cfl.* values are dimensionless Courant numbers, NOT fractions of dt.
# The solver computes dtau = pseudo_cfl / lambda_max, where lambda_max is the global
# maximum spectral radius of the convective operator (sum of |face fluxes| / cell volume,
# global MPI max). This makes pseudo_cfl flow- and grid-independent.
# Stability limit for 4-stage Jameson RK: ~2.83 (imaginary-axis CFL). Use 0.5-2.0 in practice.
initial: 0.5 # -> -pseudo_cfl (default: 0.5; ~half the stability limit)
minimum: 0.001 # -> -min_pseudo_cfl (default: 0.001)
maximum: 2.0 # -> -max_pseudo_cfl (default: 2.0; stability limit ~2.83)
growth_factor: 1.1 # -> -pseudo_cfl_growth_factor (default: 1.1; must be >= 1)
reduction_factor: 0.75 # -> -pseudo_cfl_reduction_factor (default: 0.75; must be in (0,1))
jameson_residual_noise_allowance_factor: 1.1 # -> -mom_dt_jameson_residual_norm_noise_allowance_factor
# Rejection threshold: a pseudo-time trial is rolled back if the EMA-smoothed step-to-step
# residual ratio exceeds this value. 1.1 allows 10% residual growth before reducing CFL.
# Raise toward 1.2-1.5 for flows with non-monotonic residual histories; lower toward 1.05
# for strict monotonic convergence. Must be >= 1.
# rk4_residual_noise_allowance_factor is a deprecated alias for the above; use only one.
ratio_ema_alpha: 0.3 # -> -mom_ratio_ema_alpha (default: 0.3; range [0, 1])
# Exponential moving average coefficient for the step-to-step residual ratio used in the
# trial-rejection decision. The smoothed ratio is:
# smoothed = alpha * raw_ratio + (1 - alpha) * smoothed_prev
# alpha = 1.0 : raw ratio (original behavior, most aggressive rejection)
# alpha = 0.3 : moderate smoothing; ~3-4 consecutive bad trials needed to trigger rejection
# alpha = 0.0 : ratio never updates (disables ratio-based rejection entirely)
# Increase alpha if the solver rejects too conservatively on noisy residual histories.
# Solver-specific controls for Newton Krylov. Uncomment only when
# strategy.momentum_solver is "Newton Krylov". Omitted fields retain the
# defaults established by src/momentum_newton_krylov.c and PETSc.
# newton_krylov:
# nonlinear_solver:
# method: "newtonls" # -> -mom_nk_snes_type
# absolute_tolerance: 1.0e-10 # -> -mom_nk_snes_atol
# relative_tolerance: 1.0e-8 # -> -mom_nk_snes_rtol
# step_tolerance: 1.0e-12 # -> -mom_nk_snes_stol
# max_iterations: 12 # -> -mom_nk_snes_max_it
# line_search:
# type: "bt" # -> -mom_nk_snes_linesearch_type
# linear_solver:
# method: "gmres" # -> -mom_nk_ksp_type
# absolute_tolerance: 1.0e-10 # -> -mom_nk_ksp_atol
# relative_tolerance: 1.0e-6 # -> -mom_nk_ksp_rtol
# max_iterations: 400 # -> -mom_nk_ksp_max_it
# gmres:
# restart: 80 # -> -mom_nk_ksp_gmres_restart
# preconditioner:
# type: "none" # -> -mom_nk_pc_type; only none is supported
# --- 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:
# # enabled: true # [true/false] Omit or set true to activate logging (default active).
# mode: "steady_deterministic" # -> -solution_convergence_mode
# # Options: "steady_deterministic" | "periodic_deterministic" | "statistical_steady"
# # 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.
# Note: 'pressure_solver' is an accepted deprecated alias for this block name.
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
# tolerance: 1.0e-5 # Legacy alias for absolute_tolerance -> -poisson_tol
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.
# Friendly aliases: `method` -> ksp_type, `preconditioner` -> pc_type.
# Any other key is forwarded verbatim as -ps_mg_levels_N_<key>.
# Supported direct keys: ksp_type, pc_type, max_it, rtol, atol
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
# max_it: 30 # -> -ps_mg_levels_0_max_it
# rtol: 1.0e-3 # -> -ps_mg_levels_0_rtol
# atol: 1.0e-8 # -> -ps_mg_levels_0_atol
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) ---
# Prefer the structured momentum solver blocks above.
# These passthrough flags override the structured block if both are present.
# -pseudo_cfl: 0.5 # dimensionless CFL = dtau * lambda_max (spectral-radius-based)
# -max_pseudo_cfl: 2.0
# -min_pseudo_cfl: 0.001
# -pseudo_cfl_growth_factor: 1.1
# -pseudo_cfl_reduction_factor: 0.75
# -mom_dt_jameson_residual_norm_noise_allowance_factor: 1.1
# -mom_ratio_ema_alpha: 0.3
solver.yml controls numerical strategy and solver internals.
Mappings:
eulerian_field_source -> -euler_field_source (solve, load, analytical)analytical_type -> -analytical_typeuniform_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".
Mappings:
momentum_solver -> -mom_solver_type (picurv accepts Explicit RK4, Dual Time Picard Jameson RK, or Newton Krylov)central_diff -> -centralOlder boolean toggles are not supported; use strategy.momentum_solver. Only implemented momentum solver values are accepted by picurv and the C runtime. The deprecated Dual Time Picard RK4 display name, dual_time_picard_rk4 solver block, and rk4_residual_noise_allowance_factor key remain readable compatibility aliases; generated controls always use the canonical Jameson names.
Mappings:
max_iterations -> -mom_max_pseudo_stepsabsolute_tol -> -mom_atolrelative_tol -> -mom_rtolresidual_absolute_tol -> -mom_resid_atolresidual_relative_tol -> -mom_resid_rtolWhen both residual tolerances are non-positive, the solver preserves its existing update-only convergence criterion. step_tol/-imp_stol remains accepted as a deprecated compatibility option but is unused by active momentum solvers.
Mappings include:
-pseudo_cfl, -min_pseudo_cfl, -max_pseudo_cfl-pseudo_cfl_growth_factor, -pseudo_cfl_reduction_factor-mom_dt_jameson_residual_norm_noise_allowance_factorRule: solver-specific blocks must match selected momentum solver type. Do not set canonical Jameson keys and their deprecated RK4 aliases together.
For strategy.momentum_solver: "Newton Krylov", the structured PETSc controls are:
Mappings are nonlinear_solver.method/absolute_tolerance/relative_tolerance/step_tolerance/max_iterations to -mom_nk_snes_type/-mom_nk_snes_atol/-mom_nk_snes_rtol/-mom_nk_snes_stol/-mom_nk_snes_max_it, line_search.type to -mom_nk_snes_linesearch_type, and the corresponding linear_solver fields to -mom_nk_ksp_type/-mom_nk_ksp_atol/-mom_nk_ksp_rtol/-mom_nk_ksp_max_it. gmres.restart maps to -mom_nk_ksp_gmres_restart, and preconditioner.type maps to -mom_nk_pc_type.
Newton tolerances are nonnegative, iteration/restart counts are positive integers, and GMRES restart is valid only for gmres, fgmres, or lgmres. Version one accepts only preconditioner.type: none. Omitted fields preserve C/PETSc defaults. Raw petsc_passthrough_options are applied last and may override structured values.
Mappings:
method -> -ps_ksp_typeabsolute_tolerance -> -ps_ksp_atol and legacy -poisson_tolrelative_tolerance -> -ps_ksp_rtolmax_iterations -> -ps_ksp_max_itgmres.restart -> -ps_ksp_gmres_restart; valid only for gmres, fgmres, or lgmrespreconditioner.type -> -ps_pc_type; currently only multigrid is supportedmultigrid.levels -> -mg_levelmultigrid.pre_sweeps -> -mg_pre_itmultigrid.post_sweeps -> -mg_post_itmultigrid.semi_coarsening.i/j/k -> -mg_i_semi/-mg_j_semi/-mg_k_semimultigrid.level_solvers.level_N.method -> -ps_mg_levels_N_ksp_typemultigrid.level_solvers.level_N.preconditioner -> -ps_mg_levels_N_pc_typemultigrid.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.level_0 is the coarsest level and larger numbers are finer.pre_sweeps and post_sweeps differ, PICurv uses the larger value and logs a warning.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.Mappings:
enabled — when false, suppresses all -solution_convergence_* flags; default truemode -> -solution_convergence_modeperiodic_deterministic.period_steps -> -solution_convergence_period_stepsstatistical_steady.window_steps -> -solution_convergence_window_stepsRules:
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.logs/Momentum_Solver_Convergence_History_Block_*.loglogs/Poisson_Solver_Convergence_History_Block_*.loglogs/Continuity_Metrics.logperiodic_deterministic.period_steps is required only when mode: "periodic_deterministic".statistical_steady.window_steps is required only when mode: "statistical_steady".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.Future completion semantics:
steady_deterministic is the intended home for future convergence-based completion criteria for fixed-state runs, such as stopping or marking a run complete once field-drift metrics remain below configured tolerances for a required dwell period.transient should remain diagnostic-only for physically evolving runs, even though it currently logs the same deterministic drift columns as steady_deterministic.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.
Mappings:
schmidt_number -> -schmidt_numberturbulent_schmidt_number -> -turb_schmidt_numberRules:
schmidt_number = 1.0 and turbulent_schmidt_number = 0.7petsc_passthrough_options for flags without a YAML schemaMappings:
verification.sources.diffusivity.mode -> -verification_diffusivity_modeverification.sources.diffusivity.profile -> -verification_diffusivity_profileverification.sources.diffusivity.gamma0 -> -verification_diffusivity_gamma0verification.sources.diffusivity.slope_x -> -verification_diffusivity_slope_xverification.sources.scalar.mode -> -verification_scalar_modeverification.sources.scalar.profile -> -verification_scalar_profileverification.sources.scalar.value -> -verification_scalar_valueverification.sources.scalar.phi0 -> -verification_scalar_phi0verification.sources.scalar.slope_x -> -verification_scalar_slope_xverification.sources.scalar.amplitude -> -verification_scalar_amplitudeverification.sources.scalar.kx/ky/kz -> -verification_scalar_kx/-verification_scalar_ky/-verification_scalar_kzRules:
operation_mode.eulerian_field_source: "analytical"verification.sources.scalar prescribes particle Psi from analytical truth and enables the runtime diagnostic logs/scatter_metrics.csvCONSTANT, LINEAR_X, and SIN_PRODUCTinclude/verification_sources.h and src/verification_sources.cAdvanced escape hatch for raw PETSc flags:
These are passed into PETSc options DB and consumed by runtime calls like KSPSetFromOptions.
Proceed to Configuration Reference: Monitor YAML.
For mapping and extension workflows:
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.
1.9.8