PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
Loading...
Searching...
No Matches
Developer Ingestion Map

Table of Contents

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

1. End-to-End Flow

  1. pic.flow validates YAML inputs.
  2. pic.flow generates *.control, bcs*.run, whitelist.run, profile.run, post.run.
  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/simulation.c, setup/timestep logic
case.grid.programmatic_settings.im/jm/km/... -im/-jm/-km, bounds, stretch src/io.c (ReadGridGenerationInputs, PopulateFinestUserGridResolutionFromOptions) src/grid.c, analytical geometry setup
case.grid.programmatic_settings.da_processors_* -da_processors_x/y/z src/setup.c src/grid.c DMDA creation
case.models.domain.* -nblk, periodic flags src/setup.c src/grid.c, BC setup
case.models.physics.particles.* -numParticles, -pinit, -particle_restart_mode, -psrc_* src/setup.c src/ParticleSwarm.c, src/ParticleMotion.c, statistics kernels
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 src/setup.c src/initialcondition.c, src/grid.c, src/AnalyticalSolutions.c
solver.strategy/tolerances/momentum_solver.* solver flags (-mom_*, pseudo-CFL, etc.) src/setup.c src/momentumsolvers.c
solver.pressure_solver.* -poisson_tol, -mg_*, prefixed PETSc flags 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.* -tio, -logfreq, -output_dir, -restart_dir, -log_dir, -euler_subdir, -particle_subdir src/setup.c src/io.c, src/setup.c env setup
monitor.logging.* whitelist.run, LOG_LEVEL env src/setup.c + src/logging.c logging macros/system
monitor.profiling.* profile.run src/setup.c + profiling init profiler summaries
monitor.solver_monitoring raw flags in control PETSc options db PETSc monitors/convergence output
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 pic.flow orchestration only:

YAML / Source Key Generated Artifact Key Ingestion Site Runtime Consumer
cluster.scheduler.type scheduler selector scripts/pic.flow (validate_cluster_config) run/sweep scheduler dispatch
cluster.resources.* #SBATCH directives scripts/pic.flow (Slurm renderers) Slurm scheduler
cluster.notifications.* #SBATCH --mail-* scripts/pic.flow Slurm scheduler
cluster.execution.module_setup pre-launch shell lines in *.sbatch scripts/pic.flow batch script runtime env
cluster.execution.launcher* launch command (srun/mpirun) scripts/pic.flow solver/post executable launch
study.base_configs.* per-case config materialization scripts/pic.flow (sweep_workflow) case generation pipeline
study.parameters case matrix expansion scripts/pic.flow (expand_parameter_matrix) study case synthesis
study.execution.max_concurrent_array_tasks Slurm array N throttle scripts/pic.flow Slurm scheduler
study.metrics metrics_table.csv extraction contract scripts/pic.flow metric extractors study aggregation/reporting
study.plotting results/plots/* output controls scripts/pic.flow 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.
  • LOG_LEVEL is environment-driven (src/logging.c) and intentionally outside control-file parsing.

5. Drift Prevention

  • Use scripts/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 scripts/audit_ingress.py
    • or make audit-ingress

For roadmap-oriented workflow extensions built on this contract, see Workflow Extensibility Guide.