|
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:
# This file does not change the solved flow equations. It only changes what is
# observed, recorded, and written to disk.
#
# ==============================================================================
# ==============================================================================
# 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. PHYSICAL-SOLUTION MONITORING
# Controls convergence reporting for the completed flow state.
# ==============================================================================
solution_monitoring:
convergence:
# Preserves the existing logs/solution_convergence.log writer and records
# every completed timestep.
enabled: true
mode: "steady_deterministic"
# Options: steady_deterministic | periodic_deterministic |
# statistical_steady | transient
# periodic_deterministic:
# period_steps: 200
# statistical_steady:
# window_steps: 500
# ==============================================================================
# 5. SCIENTIFIC FIELD STATISTICS
# Accumulates weighted centered moments of Eulerian fields while the solver
# runs, so turbulence statistics do not depend on how many instantaneous
# states happened to be saved. Windows are independent, are carried across a
# restart, and are derived into Reynolds stresses, RMS, TKE, and fluxes by
# post.yml -> field_statistics.
#
# Omit this block entirely to accumulate nothing: no storage is allocated and
# no statistics output is produced.
# ==============================================================================
field_statistics:
# Master switch. When false the windows below are ignored.
# [Boolean] -> -field_statistics_enabled
enabled: false
# One independent accumulator per named window. A name identifies the window's
# saved state across a restart, so it must be unique and stable.
# [List] -> -field_statistics_window_count
windows:
- # [String] -> -field_statistics_window_<i>_name
name: "production"
# Physical time at which the window starts accumulating. The first accepted
# state anchors the window; it contributes no interval of its own.
# [Number] -> -field_statistics_window_<i>_start_time
start_time: 1.0
# Physical time at which the window stops. Omit for an open-ended window
# that keeps accumulating until the run ends.
# [Number] -> -field_statistics_window_<i>_end_time
# end_time: 10.0
# How an accepted state is weighted.
# sample -> every accepted state counts equally
# physical_time -> a state is weighted by the interval it represents,
# which is what a variable timestep requires
# [Enum] -> -field_statistics_window_<i>_weighting
weighting: "physical_time"
# Exactly one of step_cadence and time_cadence. step_cadence samples every
# N completed steps from activation; time_cadence takes the first state at
# or past each multiple of the interval.
# [Positive Integer] -> -field_statistics_window_<i>_step_cadence
step_cadence: 10
# [Positive Number] -> -field_statistics_window_<i>_time_cadence
# time_cadence: 0.05
# Fields to accumulate. The first moment is always kept, because every
# centered product is measured against it; list "second" as well to keep
# the centered second moment that Reynolds stresses, RMS, and TKE need.
# Available fields: Ucat, P, Nvert, Phi, Psi, ParticleCount, Nu_t, CS.
# Psi and ParticleCount require particles; Nu_t requires a turbulence
# model; CS requires LES. A field whose subsystem is inactive is rejected
# at validation rather than accumulated as zeros.
# [List] -> -field_statistics_window_<i>_field_<j>_name / _moments
fields:
- {field: "Ucat", moments: ["first", "second"]}
- {field: "P", moments: ["first"]}
# Cross-field co-moments, for fluxes such as <u'p'>. Both members must also
# appear in fields above, because a co-moment is centered against their
# means. Pairing a field with itself belongs in moments: ["second"].
# [List of pairs] -> -field_statistics_window_<i>_covariance_<k>
covariances:
- ["Ucat", "P"]
# ==============================================================================
# 6. 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
# Frequency for printing a one-line-per-window field-statistics snapshot into
# the main solver log. Reports window progress only; it never dumps field data.
# Snapshots also require logging.verbosity of INFO or finer. Set to 0, or omit,
# to disable them without affecting what is accumulated.
# [Non-negative Integer] -> -statistics_console_output_freq
statistics_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
# ==============================================================================
# 7. SOLVER MONITORING
# ==============================================================================
#
# 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:
momentum:
# PICurv structured nonlinear history (does not enable PETSc stdout monitors).
# The Newton summary log is unconditional, like the Jameson/Poisson logs.
newton_krylov_history: false # -> -mom_nk_pic_monitor
snes_monitor: false # -> -mom_nk_snes_monitor
snes_converged_reason: false # -> -mom_nk_snes_converged_reason
ksp_monitor: false # -> -mom_nk_ksp_monitor
ksp_converged_reason: false # -> -mom_nk_ksp_converged_reason
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 runtime monitoring, diagnostics, profiling, run I/O behavior, and scientific Eulerian field statistics.
Physical-solution convergence uses the existing runtime monitor through this contract:
PICurv writes the normalized settings directly into the generated master .control file as the existing -solution_convergence_* options. It retains logs/solution_convergence.log, its columns, and its current observable loops. enabled: false disables that writer and its private history allocation. The default remains enabled steady_deterministic monitoring. Convergence is observed after every completed timestep; there is no user-facing cadence key.
Mode-specific rules:
periodic_deterministic requires periodic_deterministic.period_steps > 0;statistical_steady requires statistical_steady.window_steps > 0;steady_deterministic and transient take no nested mode block; andThere is no observations.run sidecar and no observation-plan schema/version at this boundary. control remains the single generated C-ingress artifact for these settings.
Scientific field statistics are configured separately, under field_statistics; see 3. field_statistics. Solution monitoring answers whether the run has converged, field statistics answer what the converged flow is, and they share no state.
The removed case.yml -> models.statistics.time_averaging and -averaging surface is not compatible input and is not translated into a replacement workflow.
Mappings:
data_output_frequency -> -tioparticle_console_output_frequency -> -particle_console_output_freqstatistics_console_output_frequency -> -statistics_console_output_freqparticle_log_interval -> -logfreqdirectories.output -> -output_dirdirectories.restart -> -restart_dirdirectories.log -> -log_dirSemantics:
data_output_frequency controls committed-checkpoint cadence. Initial and final completed states are also checkpointed, including an off-cadence final state.eulerian/, particles/, and statistics/ names are fixed and are not user configuration. See 7. Checkpoints, Restart, and Continuation.statistics_console_output_frequency controls how often field-statistics window snapshots are printed to the main log. It defaults to data_output_frequency, and 0 disables the snapshot without disabling accumulation. It is reporting only: changing it cannot change any accumulated result.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.Accumulates weighted centered moments of Eulerian fields while the solver runs. Omit the block entirely to accumulate nothing: no storage is allocated and no statistics output is produced.
Mappings:
enabled -> -field_statistics_enabled-field_statistics_window_count<i> -> -field_statistics_window_<i>_name, _start_time, _end_time, _weighting, _step_cadence or _time_cadence, _field_count, _field_<j>_name, _field_<j>_moments, _covariance_count, _covariance_<k>end_time is omitted from the control file rather than given a sentinel, because its absence is what makes a window open-ended.
Each window is an independent average. Windows may overlap; each owns its state. The name identifies a window's saved state across a restart, so it must be unique within the file and stable across runs.
start_time is when the window begins. The first state at or after it anchors the window without being sampled; see 2.2 Bounds, Clipping, and the First State.end_time is optional. A bounded window completes when it passes it and stops changing; an open window accumulates until the run ends.weighting is sample (every accepted state counts equally) or physical_time (a state is weighted by the interval it represents). Use physical_time whenever the timestep can vary. On a constant timestep the two agree exactly.step_cadence (positive integer) and time_cadence (positive number) must be set.fields lists what to accumulate. The first moment is always kept, because every centered product is measured against it; adding second keeps the centered second moment that Reynolds stresses, RMS, and TKE are derived from.
| Field | Components | Requires |
|---|---|---|
Ucat | 3 | — |
P | 1 | — |
Nvert | 1 | — |
Phi | 1 | — |
Psi | 1 | particles |
ParticleCount | 1 | particles |
Nu_t | 1 | a turbulence model |
CS | 1 | LES |
covariances lists cross-field co-moments, such as [Ucat, P] for a pressure-velocity flux. A vector's own Reynolds stresses are not a covariance; they come from moments: [second] on that field.
picurv validate rejects, naming the offending window:
start_time greater than or equal to end_time;step_cadence and time_cadence, or a non-positive value;weighting outside {sample, physical_time};fields list, a repeated field, or an empty or unknown moments entry;fields, that names one field twice, that pairs two vector fields, or that is requested twice.Combining --restart-from with enabled statistics is also rejected: a branch may follow a different trajectory than the samples already collected, so the windows would silently restart from zero. Use --continue to resume in place, or disable statistics to branch without them.
Accumulated state is written into each committed checkpoint under statistics/window_<n>/block_<n>/, and is restored on --continue. Nothing is derived at solve time; Configuration Reference: Postprocessor YAML turns saved state into Reynolds stresses, RMS, TKE, and fluxes.
While the run is live, io.statistics_console_output_frequency prints one line per window with its state, sample count, accumulated weight, represented time, progress, and mask coverage. Field Statistics explains the semantics behind each of those numbers, and Field Statistics Planned Extensions records what is not built yet.
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, which is main and CreateSimulationContext only.verbosity alone, so a run always reports what it is doing. Code-level diagnostics are dual-gated on verbosity and this allow list, so instrumenting one function for debugging does not drag every other function's output along with it.verbosity therefore does not surface a function's diagnostics on its own; name the function here as well. See User How-To Guides section 3.4 for the workflow.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:
ERRORWARNINGINFODEBUGTRACEVERBOSEThe rank-zero CASE SUMMARY is an effective-configuration report, rather than a dump of every possible option. It is printed independently of logging.verbosity so a quiet production profile still records the run identity, I/O cadence, walltime-guard status, and active state source.
load authority.Initial Pseudo-CFL (Courant) appears only for Dual Time Picard Jameson RK. It is intentionally absent for Newton Krylov and explicit RK, where that controller is not active.solver_monitoring.momentum below and its structured solver controls are documented in Configuration Reference: Solver YAML and Newton–Krylov Momentum Solver.Statistics Console Cadence is always present. It reports the configured cadence, or DISABLED distinguishing a silenced console over accumulating windows from a run that configured none, so a log is never ambiguous about whether statistics were being collected.The C unit-io contract test verifies these conditional banner fields, while unit-logging verifies the logging behavior described on this page. Both are included in the runtime layer of make certify-docs; the GitHub documentation workflow runs the dependency-free structural documentation checks on every main push and every third day.
The structural certification also runs a user-facing reporting audit. It rejects raw C console emissions outside the approved banner/logging/bootstrap/progress surfaces and verifies that the C banner plus CLI and picurv summarize retain their solver-specific reporting branches. The checked-in tests/tooling/user_facing_reporting_contract.json also declares every CLI command's parser, handler, and context marker, including submission and plot paths.
Rules:
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.picurv summarize --list-plot-series exposes available plottable scalar monitor histories, and --plot <qualified-series> renders full or last-N append-order histories through standalone generators/plot.gen.Human-readable solver monitor controls. PICurv maps these keys to the raw C/PETSc flags written into the generated .control file:
Mappings:
momentum.newton_krylov_history -> -mom_nk_pic_monitormomentum.snes_monitor -> -mom_nk_snes_monitormomentum.snes_converged_reason -> -mom_nk_snes_converged_reasonmomentum.ksp_monitor -> -mom_nk_ksp_monitormomentum.ksp_converged_reason -> -mom_nk_ksp_converged_reasonpoisson.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:
momentum.* and poisson.* keys are booleans. true emits a bare switch and false emits nothing; no Boolean monitor is serialized as a numeric viewer argument.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