Configuration Extension Playbook

Table of Contents

• 1. Standard Extension Workflow
• 2. Design Rules
• 3. ParticlePhysics Extension Checklist
• 4. Data-Driven Closure Model Note
• 5. Verification Checklist
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This playbook defines the standard workflow for adding new options/models without breaking YAML->C contract consistency.

1. Standard Extension Workflow

1. Choose the schema home (case.yml, solver.yml, monitor.yml, or post.yml).
2. Add template documentation in examples/master_template/*.yml.
3. Add validation and normalization in scripts/picurv.
4. Emit the mapped control/post key into generated artifacts.
5. Add C-side ingestion default + parser wiring (setup.c or io.c).
6. Connect runtime consumer logic in domain module (grid.c, poisson.c, particle modules, etc.).
7. Update references:
   • docs/pages/14_Config_Contract.md
   • docs/pages/15_Config_Ingestion_Map.md
8. Update scripts/audit_ingress_manifest.json when PETSc ingress changes.
9. Verify with a config-generation run and static ingress audit.

2. Design Rules

• Prefer structured schema first; use passthrough only for advanced/temporary gaps.
• Keep defaults in one place, and prefer explicit rejection over temporary compatibility aliases when contracts change.
• Reject unsupported shapes early in Python validation (for example, list-vs-scalar contract mismatches).
• Keep C ingestion concentrated in setup/parsing layers (setup.c, io.c) unless data is truly file-local to a subsystem.

3. ParticlePhysics Extension Checklist

Use this checklist when adding a new particle model constant, source term, or initialization mode.

1. Schema:
   • Add structured keys under models.physics.particles (case) or solver (if solver-policy).
2. Generator:
   • Map to control flags in scripts/picurv.
   • Add validation for domain/range and mode compatibility.
3. C ingestion:
   • Add default in CreateSimulationContext.
   • Parse flag via PetscOptionsGet* in setup.c.
4. Runtime:
   • Wire into ParticlePhysics.c, ParticleSwarm.c, or ParticleMotion.c as needed.
   • Ensure post/statistics kernels are updated if new fields are emitted.
5. I/O:
   • If new field is restart/post relevant, add read/write hooks in io.c and post field registration where needed.
6. Docs and audit:
   • Update contract/map pages and audit manifest.

4. Data-Driven Closure Model Note

• Offline integration (recommended first):
  • Treat solver/post outputs as the canonical data contract and run ML training/inference in external Python workflows.
  • Keep C-side ingestion unchanged unless the model must feed back into timestep updates.
• Tightly coupled inference (next step):
  • Add a runtime-selectable closure model interface in ParticlePhysics.c (model type + config + evaluation hook).
  • Expose model selection and coefficients in YAML (solver.yml or case.yml), map through picurv, parse in setup.c, and wire runtime consumers.
  • Keep fallback behavior to current deterministic model when no ML model is selected.

5. Verification Checklist

• Scalar/list and type validation works as expected.
• Generated control/post artifacts contain intended keys.
• C parser consumes keys without unknown-key warnings.
• Runtime behavior changes only when new key is explicitly set.
• Existing templates/run paths still work with omitted new keys.
• Verification-only source overrides should live in verification_sources.* and be used only when no ordinary end-to-end path can test the feature.

See also Workflow Extensibility Guide for higher-level workflow expansion patterns. For selector-by-selector hook points, use Modular Selector Extension Guide.

CFD Reader Guidance and Practical Use

This page describes Configuration Extension Playbook 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.