|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
For the full commented template, see:
# ==============================================================================
# PICurv Master Monitor Configuration Template
# ==============================================================================
#
# PURPOSE:
# This file defines the OBSERVATION and DATA MANAGEMENT strategy for a SOLVER run.
# It controls console verbosity, performance profiling, I/O frequency, and
# detailed monitoring of the numerical solvers.
#
# IMPORTANT:
# Changing this file will NEVER change the scientific result of the simulation.
# It only changes what is observed and recorded.
#
# ==============================================================================
# ==============================================================================
# 1. LOGGING
# Controls what is printed to the console and saved in the main .log file.
# ==============================================================================
logging:
# --- Verbosity Level ---
# Sets the master LOG_LEVEL for the C-code.
# Options: ERROR, WARNING, INFO, DEBUG, TRACE, VERBOSE
# WARNING is the production default: quiet runtime, still shows warnings.
# The startup banner remains visible and reports walltime-guard status.
# Runtime metrics such as logs/search_metrics.csv may still be written even
# when console verbosity stays low.
verbosity: WARNING
# --- Function Allow-List ---
# For targeted debugging. If this list is empty, picurv omits the whitelist
# file so the C runtime falls back to its built-in default allow-list.
# Example: allow-list LOG_SEARCH_METRICS with DEBUG verbosity when you want
# compact console summaries in addition to the always-written
# logs/search_metrics.csv artifact for particle-enabled runs.
enabled_functions: []
# ==============================================================================
# 2. PROFILING
# Controls the performance measurement system.
# ==============================================================================
profiling:
# --- Per-Step Profiling Output ---
# Controls whether timestep-level profiling rows are written to a dedicated file.
# mode:
# off -> no timestep profiling output
# selected -> write only the listed functions
# all -> write every instrumented function that ran that step
timestep_output:
mode: "off"
# functions:
# - AdvanceSimulation
# - Flow_Solver
file: "Profiling_Timestep_Summary.csv"
# --- Final Profiling Summary ---
# Controls the end-of-run aggregated profiling summary file.
final_summary:
enabled: true
# ==============================================================================
# 3. I/O AND DATA MANAGEMENT
# Controls data file generation and locations for the SOLVER.
# ==============================================================================
io:
# --- Frequency Control ---
# How often data is written or printed, measured in timesteps.
# Frequency for saving full simulation field data (for restarts/post-processing).
# [Integer] -> -tio
data_output_frequency: 100
# Frequency for printing particle snapshots into the main solver log.
# If omitted, picurv uses data_output_frequency. Set to 0 to disable periodic
# particle console snapshots entirely.
# [Non-negative Integer] -> -particle_console_output_freq
particle_console_output_frequency: 100
# --- Particle Tracking Row Subsampling ---
# Within each particle console snapshot, print only every Nth particle row.
# [Integer] -> -logfreq
particle_log_interval: 50
# --- Directory Management ---
# Specifies subdirectory names within the run folder. If omitted, C-code
# defaults will be used.
directories:
output: "output" # [string] -> -output_dir
restart: "restart" # [string] -> -restart_dir
log: "logs" # [string] -> -log_dir
eulerian_subdir: "eulerian" # [string] -> -euler_subdir
particle_subdir: "particles" # [string] -> -particle_subdir
# ==============================================================================
# 4. SOLVER MONITORING (PASSTHROUGH)
# ==============================================================================
#
# This section provides maximum flexibility for debugging the numerical solvers.
# Any key-value pair defined here is passed DIRECTLY to the C solver as a
# command-line flag. This is primarily for PETSc monitoring options.
#
# The keys must be the exact flag names (e.g., '-ps_ksp_monitor_true_residual').
# For flags that don't take an argument (boolean switches), set the value to `true`.
#
# ==============================================================================
solver_monitoring:
# --- Example: KSP (Krylov Subspace Method) Monitors ---
# Uncomment to enable live monitoring of the pressure solver's convergence.
# This custom monitor provides detailed, formatted output.
-ps_ksp_pic_monitor_true_residual: true
# PETSc's standard true residual monitor.
# -ps_ksp_monitor_true_residual: true
# Print the reason for KSP convergence or divergence (very useful for debugging).
# -ps_ksp_converged_reason: true
# View the KSP object's configuration at runtime.
# -ps_ksp_view: true
# --- Example: PC (Preconditioner) Monitors ---
# If using an SVD-based preconditioner for debugging, monitor its singular values.
# -ps_pc_svd_monitor: true
# --- Example: TS (Time Stepper) Monitors ---
# (If your implicit solver uses PETSc's TS object)
# -ts_monitor: true
monitor.yml controls observability and run I/O behavior.
Mappings:
data_output_frequency -> -tioparticle_console_output_frequency -> -particle_console_output_freqparticle_log_interval -> -logfreqdirectories.output -> -output_dirdirectories.restart -> -restart_dirdirectories.log -> -log_dirdirectories.eulerian_subdir -> -euler_subdirdirectories.particle_subdir -> -particle_subdirSemantics:
data_output_frequency controls file/restart output cadence.particle_console_output_frequency controls how often particle snapshots are printed to the main log.particle_log_interval controls row subsampling within each particle snapshot.particle_console_output_frequency is omitted, picurv defaults it to data_output_frequency.particle_console_output_frequency is 0, periodic particle console snapshots are disabled.verbosity maps to environment variable LOG_LEVEL via picurv launcher.enabled_functions is serialized into whitelist.run only when non-empty.enabled_functions is empty, picurv omits whitelist.run and the C runtime falls back to its default allow-list.whitelist.run must contain at least one function name; an empty whitelist file is invalid.config/monitors/Standard_Output.yml uses WARNING with an empty allow-list for quiet production runs; the startup banner still reports the walltime-guard status.logs/search_metrics.csv is written automatically and includes both raw search counters and derived signals such as search_failure_fraction, search_work_index, and re_search_fraction; allow-listing LOG_SEARCH_METRICS only affects the optional compact console summary.Supported verbosity strings:
ERRORWARNINGINFODEBUGTRACEVERBOSERules:
timestep_output.mode:off: disable per-step profiling outputselected: write only the listed functions each timestepall: write all instrumented functions seen in a timesteptimestep_output.functions is required only when mode: selectedtimestep_output.file sets the filename written under the run logs/ directoryfinal_summary.enabled controls the end-of-run ProfilingSummary_*.log fileRaw flag passthrough for PETSc monitors/debug options:
Rules:
-).true emits switch-only flag.false omits flag.flag value.Proceed to Configuration Reference: Postprocessor YAML.
Also see:
This page describes Configuration Reference: Monitor 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