|
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. DIAGNOSTICS
# Controls PETSc-native diagnostics and the compact runtime memory log.
# ==============================================================================
diagnostics:
petsc:
# These options are passed on the solver/postprocessor command line so
# PETSc sees them during PetscInitialize().
# Example:
# malloc_debug: true -> executable arg: -malloc_debug
# log_view: true -> executable args: -log_view :runs/<run_id>/logs/PETSc_LogView_Solver.log
# objects_dump: all -> executable args: -objects_dump all
malloc_debug: false
malloc_test: false
malloc_dump: false
# Boolean true uses run-local default log files where PETSc supports file
# output. A non-empty string can override the PETSc viewer/path.
malloc_view: false
malloc_view_threshold: null
memory_view: false
log_view: false
log_view_memory: false
log_all: false
log_trace: false
objects_dump: false
options_left: null
runtime_memory_log:
# This custom PICurv log is emitted from the runtime through control-file
# flags, independent of PETSc-native diagnostics above.
enabled: true
file: "Runtime_Memory.log"
# ==============================================================================
# 4. 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
# ==============================================================================
# 5. SOLVER MONITORING (PASSTHROUGH)
# ==============================================================================
#
# This section exposes common solver-monitor controls with readable names.
# PICurv maps these keys to the C/PETSc flags written into the generated
# `.control` file.
#
# For advanced one-off PETSc flags, keep them under `petsc_passthrough_options`.
#
# ==============================================================================
solver_monitoring:
poisson:
# Custom PICurv pressure-correction residual monitor.
pic_true_residual: true # -> -ps_ksp_pic_monitor_true_residual
# PETSc's standard true residual monitor.
true_residual: false # -> -ps_ksp_monitor_true_residual
# Print the KSP convergence/divergence reason.
converged_reason: true # -> -ps_ksp_converged_reason
# View the pressure-correction KSP object configuration.
view: false # -> -ps_ksp_view
petsc_passthrough_options:
# Raw escape hatch for PETSc monitor/debug flags not yet exposed above.
# Boolean true emits a switch-only flag; false omits it.
# -ps_pc_svd_monitor: true
# -ts_monitor: true
monitor.yml controls observability, diagnostics, 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 fileStructured diagnostics for PETSc memory/object/function debugging plus a compact PICurv runtime memory log:
Rules:
malloc_debug and malloc_test are passed on the executable command line, not only through the generated .control file.adds PETSc startup arguments like:
for the solver stage, with analogous PostProcessor log names for post runs.
malloc_view, log_view, and log_trace accept false, true, or a non-empty PETSc viewer/path string. When set to true, PICurv writes run-local defaults such as logs/PETSc_MallocView_Solver.log, logs/PETSc_LogView_Solver.log, and matching PostProcessor files.objects_dump accepts false, true, or all.options_left accepts true, false, or null; use null to omit the PETSc option entirely.logs/, with solver/postprocessor-specific filenames. Boolean-only PETSc diagnostics remain in the captured solver/post stream logs.runtime_memory_log writes a rank-reduced, terminal-readable log with max process/PETSc allocation signals per step.picurv summarize reports the latest runtime memory signals when the log is present.Human-readable solver monitor controls. PICurv maps these keys to the raw C/PETSc flags written into the generated .control file:
Mappings:
poisson.pic_true_residual -> -ps_ksp_pic_monitor_true_residualpoisson.true_residual -> -ps_ksp_monitor_true_residualpoisson.converged_reason -> -ps_ksp_converged_reasonpoisson.view -> -ps_ksp_viewRules:
poisson.* keys are booleans.petsc_passthrough_options remains available for raw PETSc flags not yet exposed as structured YAML. In passthrough, true emits a switch-only flag, false omits the flag, and non-boolean values emit flag value.solver_monitoring is written into the generated .control file and consumed during solver setup, while diagnostics.petsc is placed on the executable command line for PETSc initialization-time diagnostics.solver_monitoring are still accepted for compatibility, but new profiles should prefer the structured form above.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