Configuration Contract (YAML -> Generated Artifacts -> Runtime)

Table of Contents

• 1. Required Input Roles
• 3. Case Contract Highlights
• 4. Solver Contract Highlights
• 5. Monitor Contract Highlights
• 7. Cluster Contract Highlights (<tt>cluster.yml</tt>)
• 8. Study Contract Highlights (<tt>study.yml</tt>)

This page is the user-facing source of truth for the configuration contract implemented by pic.flow.

1. Required Input Roles

pic.flow composes a standard single-run workflow from five logical inputs, with two additional files for cluster/sweep modes:

1. case.yml: physics, grid, BC definitions, run control.
2. solver.yml: numerical strategy and solver parameters.
3. monitor.yml: I/O and logging/profiling controls.
4. post.yml: post-processing recipe.
5. MPI launch settings (-n, executable stage selection).
6. (Cluster mode) cluster.yml: scheduler/resource/launcher contract.
7. (Sweep mode) study.yml: parameter matrix + metrics/plot contract.

You can name files however you want. File names are not hardcoded on the C side; pic.flow resolves paths and emits generated artifacts.

5. Generated Runtime Artifacts

For each run, pic.flow generates:

• <run_id>.control: master PETSc/control flags for solver/post setup.
• bcs.run or bcs_block*.run: boundary condition definitions.
• whitelist.run: logging function allow-list.
• profile.run: profiling critical-function list.
• post.run: key=value post-processing recipe consumed by C post parser.

3. Case Contract Highlights

• grid.mode supports: file, programmatic_c, grid_gen.
• For programmatic_c, per-block arrays are supported for geometry (im/jm/km, bounds, stretching).
• da_processors_x/y/z are scalar integers only (global DMDA layout). Per-block MPI decomposition is not currently supported.
• boundary_conditions supports single-block list or multi-block list-of-lists.
• solver_parameters is an advanced passthrough map for raw flags not yet modeled in schema.

4. Solver Contract Highlights

• operation_mode.eulerian_field_source -> -euler_field_source
• operation_mode.analytical_type -> -analytical_type
• strategy.momentum_solver -> -mom_solver_type via normalized names.
• Solver-specific block support currently includes momentum_solver.dual_time_picard_rk4.
• petsc_passthrough_options remains the escape hatch for advanced PETSc/C flags.

5. Monitor Contract Highlights

• io.data_output_frequency -> -tio
• io.particle_log_interval -> -logfreq
• io.directories.output/restart/log -> -output_dir/-restart_dir/-log_dir
• io.directories.eulerian_subdir/particle_subdir -> -euler_subdir/-particle_subdir
• solver_monitoring maps raw flags directly into control output.

4. Post-Processing

• Pipelines are serialized into semicolon-delimited C pipeline strings.
• io.eulerian_fields -> output_fields_instantaneous
• io.eulerian_fields_averaged -> output_fields_averaged (reserved/no-op in current writer path)
• io.particle_fields -> particle_fields_instantaneous
• io.input_extensions.eulerian/particle -> eulerianExt/particleExt for post input readers
• source_data.directory -> source_directory

7. Cluster Contract Highlights (<tt>cluster.yml</tt>)

• scheduler.type currently supports slurm only.
• resources.account/nodes/ntasks_per_node/mem/time are required.
• resources.partition is optional.
• notifications.mail_user/mail_type are optional; email is validated when provided.
• execution.module_setup injects shell lines before launch.
• execution.launcher controls launch style (srun, mpirun, custom).
• execution.launcher_args provides site-specific launch flags.
• execution.extra_sbatch supports scheduler-specific pass-through flags.

pic.flow run --cluster ... generates:

• runs/<run_id>/scheduler/solver.sbatch
• runs/<run_id>/scheduler/post.sbatch
• runs/<run_id>/scheduler/submission.json

8. Study Contract Highlights (<tt>study.yml</tt>)

• base_configs provides case/solver/monitor/post template paths.
• study_type is one of:
  • grid_independence
  • timestep_independence
  • sensitivity
• parameters defines cartesian-product sweeps using keys of form:
  • case.<yaml.path>
  • solver.<yaml.path>
  • monitor.<yaml.path>
  • post.<yaml.path>
• metrics defines CSV/log extractors for aggregate tables.
• plotting controls whether plots are generated and output format.
• execution.max_concurrent_array_tasks maps to Slurm array throttling N.

pic.flow sweep --study ... --cluster ... generates:

• studies/<study_id>/scheduler/case_index.tsv
• studies/<study_id>/scheduler/solver_array.sbatch
• studies/<study_id>/scheduler/post_array.sbatch
• studies/<study_id>/results/metrics_table.csv
• studies/<study_id>/results/plots/*

6. <tt>solver_parameters</tt> (Advanced)

• Escape hatches stay supported:
  • case.solver_parameters
  • solver.petsc_passthrough_options
  • monitor.solver_monitoring
• Default post input/output extension is dat unless overridden.
• Missing optional keys preserve existing C defaults.

For workflow growth patterns (grid generation orchestration, multi-run studies, and ML coupling paths), see Workflow Extensibility Guide.