Developer Ingestion Map

Table of Contents

• 1. End-to-End Flow
• 2. Mapping Matrix
• 3. Python-Only Orchestration Mapping (No C Ingestion)
• 4. Important Exceptions
• 5. Mode-Dependent Normalization in <tt>picurv</tt>
• 6. Drift Prevention
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This page maps configuration flow from YAML schema to generated artifacts and C ingestion/use sites.

1. End-to-End Flow

1. picurv validates YAML inputs.
2. picurv generates *.control, bcs*.run, and post.run, plus optional whitelist.run / profile.run sidecars when those features are enabled.
3. CreateSimulationContext() in src/setup.c loads -control_file and ingests options.
4. Secondary file parsers ingest BC/post/logging profile inputs.
5. Runtime modules consume parsed values during setup, solve, and postprocess.

2. Mapping Matrix

YAML / Source Key	Generated Artifact Key	C Ingestion Site	Primary Runtime Consumers
case.run_control.*	-start_step, -totalsteps, -dt	src/setup.c (CreateSimulationContext)	src/runloop.c, setup/timestep logic
case.grid.programmatic_settings.im/jm/km/...	-im/-jm/-km, bounds, stretch (im/jm/km translated from YAML cell counts to C node counts)	src/io.c (ReadGridGenerationInputs, PopulateFinestUserGridResolutionFromOptions)	src/grid.c, analytical geometry setup
case.grid.da_processors_*	-da_processors_x/y/z	src/setup.c	src/grid.c DMDA creation
case.models.domain.blocks	-nblk	src/setup.c	src/grid.c
paired case.boundary_conditions periodic faces	BC rows; periodic axes are derived in C	src/Boundaries.c, src/io.c (DeterminePeriodicity)	src/grid.c DMDA creation, periodic field synchronization
case.models.physics.particles.*	-numParticles, -pinit, -particle_restart_mode, -psrc_*	src/setup.c	src/ParticleSwarm.c, src/ParticleMotion.c, statistics kernels
case.models.physics.turbulence.*	-les, -const_cs, -max_cs, -dynamic_freq, -testfilter_ik, -rans, -wallfunction, -wall_roughness	src/setup.c	src/solvers.c, src/les.c, src/Filter.c, src/Boundaries.c, src/wallfunction.c
solver.interpolation.method	-interpolation_method	src/setup.c	src/interpolation.c (dispatch in InterpolateEulerFieldToSwarm)
case.boundary_conditions	bcs*.run rows	BC parser path (src/Boundaries.c + helpers)	BC handler factory and boundary application
solver.operation_mode.*	-euler_field_source, -analytical_type, -analytical_uniform_u/-v/-w	src/setup.c	src/initialcondition.c, src/grid.c, src/AnalyticalSolutions.c
solver.verification.sources.diffusivity.*	-verification_diffusivity_mode/-profile/-gamma0/-slope_x	src/setup.c	src/verification_sources.c, src/rhs.c
solver.verification.sources.scalar.*	-verification_scalar_mode/-profile/-value/-phi0/-slope_x/-amplitude/-kx/-ky/-kz	src/setup.c	src/verification_sources.c, src/AnalyticalSolutions.c, src/ParticlePhysics.c, src/logging.c
solver.strategy/tolerances/momentum_solver.*	solver flags (-mom_*, pseudo-CFL, etc.)	src/setup.c	src/momentumsolvers.c
solver.momentum_solver.newton_krylov.*	prefixed -mom_nk_snes_*, -mom_nk_ksp_*, -mom_nk_pc_type	PETSc options db via SNESSetFromOptions()	src/momentum_newton_krylov.c
solver.solution_convergence.*	-solution_convergence_mode/-solution_convergence_period_steps/-solution_convergence_window_steps	src/setup.c	src/logging.c, src/runloop.c
solver.scalar_transport.*	-schmidt_number, -turb_schmidt_number	src/setup.c	src/rhs.c, src/particle_statistics.c, scalar/particle transport
solver.poisson_solver.* / legacy solver.pressure_solver.*	-poisson_tol, -ps_ksp_*, -ps_pc_type, -mg_*, -ps_mg_levels_*	src/setup.c + PETSc options db	src/poisson.c
solver.petsc_passthrough_options	raw flags in control	PETSc options db	PETSc KSP/PC stack, mostly in src/poisson.c
monitor.io.data_output_frequency	-tio	src/setup.c	src/io.c, src/setup.c, src/runloop.c
monitor.io.particle_console_output_frequency	-particle_console_output_freq	src/setup.c	src/io.c, src/setup.c, particle console logging
monitor.io.particle_log_interval	-logfreq	src/setup.c	particle console row subsampling
monitor.io.directories.*	-output_dir, -restart_dir, -log_dir, -euler_subdir, -particle_subdir	src/setup.c	src/io.c, src/setup.c, src/runloop.c
monitor.logging.*	whitelist.run, LOG_LEVEL env	src/setup.c + src/logging.c	logging macros/system
monitor.profiling.*	profile.run (selected-mode only) + explicit profiling flags in *.control	src/setup.c + profiling init	profiler summaries
monitor.diagnostics.petsc.*	solver/postprocessor executable arguments (-malloc_*, -log_view, -objects_dump, etc.)	PETSc initialization	PETSc memory/log/object diagnostics
monitor.diagnostics.runtime_memory_log.*	-runtime_memory_log_enabled, -runtime_memory_log_file	src/setup.c	src/logging.c, src/runloop.c, src/postprocessor.c, src/simulator.c
cluster.execution.walltime_guard.*	-walltime_guard_* in solver *.control	src/setup.c	src/runloop.c runtime walltime estimator and graceful final-write cutoff
monitor.solver_monitoring.poisson.*	prefixed Poisson monitor flags in control (-ps_ksp_*)	PETSc options db	src/poisson.c KSP monitor setup
monitor.solver_monitoring.momentum.*	bare Newton history/SNES/KSP monitor flags (-mom_nk_*)	src/setup.c + PETSc options db	src/momentum_newton_krylov.c
monitor.solver_monitoring.petsc_passthrough_options	raw flags in control	PETSc options db	PETSc monitors/debug options
post.run_control.*	startTime/endTime/timeStep in post.run	src/io.c (ParsePostProcessingSettings)	src/postprocessor.c main loop
post.io.input_extensions.*	eulerianExt, particleExt in post.run	src/io.c	ReadSimulationFields, ReadAllSwarmFields, swarm precheck
post.io.eulerian_fields_averaged	output_fields_averaged in post.run	src/io.c	reserved/no-op in current writer path
post.statistics_pipeline.*	statistics_pipeline, statistics_output_prefix	src/io.c	GlobalStatisticsPipeline dispatch

3. Python-Only Orchestration Mapping (No C Ingestion)

These keys are consumed by picurv orchestration only:

YAML / Source Key	Generated Artifact Key	Ingestion Site	Runtime Consumer
cluster.scheduler.type	scheduler selector	picurv_cli/core.py (validate_cluster_config)	run/sweep scheduler dispatch
cluster.resources.*	#SBATCH directives	picurv_cli/core.py (Slurm renderers)	Slurm scheduler
cluster.notifications.*	#SBATCH --mail-*	picurv_cli/core.py	Slurm scheduler
cluster.execution.module_setup	pre-launch shell lines in *.sbatch	picurv_cli/core.py	batch script runtime env
cluster.execution.launcher*	launch command (srun/mpirun)	picurv_cli/core.py	solver launch plus forced single-rank post launch
study.base_configs.*	per-case config materialization	picurv_cli/core.py (sweep_workflow)	case generation pipeline
study.parameters	case matrix expansion	picurv_cli/core.py (expand_parameter_matrix)	study case synthesis
study.execution.max_concurrent_array_tasks	Slurm array N throttle	picurv_cli/core.py	Slurm scheduler
study.metrics	metrics_table.csv extraction contract	picurv_cli/core.py metric extractors	study aggregation/reporting
study.plotting	results/plots/* output controls	picurv_cli/core.py plotting pipeline	study reporting

4. Important Exceptions

• PETSc runtime option consumption is not only explicit PetscOptionsGet*.
• KSPSetFromOptions in src/poisson.c ingests prefixed PETSc options dynamically.
• monitor.diagnostics.petsc.* is intentionally emitted as executable arguments rather than control-file rows so PETSc initialization-time options are available before runtime setup reads *.control.
• LOG_LEVEL is environment-driven (src/logging.c) and intentionally outside control-file parsing.

5. Mode-Dependent Normalization in <tt>picurv</tt>

Some launcher behaviors depend on other config selections before values ever reach C:

• case.properties.initial_conditions.mode: generated resolves generator and params into built-in C flags or a staged ic_gen PETSc vector.
• case.properties.initial_conditions.mode: file validates and stages one Ucat or Ucont PETSc vector in the existing ReadFieldData naming layout.
• file-backed ICs are rejected for multi-block cases in the first implementation.
• solver.operation_mode.eulerian_field_source and case.run_control.start_step supersede IC materialization when load, analytical, or restart state has authority.
• solver.operation_mode.eulerian_field_source: analytical routes through the analytical grid-ingestion split: TGV3D still requires case.grid.mode: programmatic_c, while ZERO_FLOW and UNIFORM_FLOW accept case.grid.mode: programmatic_c or case.grid.mode: file.
• case.properties.initial_conditions.mode is an explicit launcher requirement.

This means the YAML contract is intentionally stricter than "whatever C would do with missing options" in several places.

6. Drift Prevention

• Use tests/tooling/audit_ingress.py to compare PETSc option ingress in setup.c/io.c with the maintained manifest.
• Keep this map and the manifest updated whenever new options are introduced.
• Run manually with:
  • python3 tests/tooling/audit_ingress.py
  • or make audit-ingress

For roadmap-oriented workflow extensions built on this contract, see Workflow Extensibility Guide. For selector-specific contributor hook points, see Modular Selector Extension Guide.

CFD Reader Guidance and Practical Use

This page describes Developer Ingestion Map 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

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