Modular Selector Extension Guide

Table of Contents

• 1. Standard Checklist For Any Selector
• 2. Momentum Solver Selector
• 4. Particle Initialization Mode
• 5. Field Initialization Mode
• 6. Analytical Type

This page is the contributor checklist for adding new selector-driven options without drifting the YAML -> launcher -> C runtime contract.

1. Standard Checklist For Any Selector

For every new selector value:

1. define the canonical user-facing value in YAML docs/templates,
2. add or update Python normalization/validation in scripts/picurv,
3. emit the correct generated control/post artifact mapping,
4. add any C enum/storage and parser wiring,
5. add the runtime dispatch/consumer branch,
6. update tests,
7. update the relevant reference pages.

Use the canonical value only. Do not add placeholder enum values or compatibility aliases for unimplemented options.

2. Momentum Solver Selector

• Schema home: solver.yml -> strategy.momentum_solver
• Canonical values:
  • Explicit RK4
  • Dual Time Picard RK4
• Python hook:
  • normalize_momentum_solver_type() in scripts/picurv
• Generated mapping:
  • strategy.momentum_solver -> -mom_solver_type
• C enum/storage:
  • MomentumSolverType in include/variables.h
• C parser:
  • -mom_solver_type in CreateSimulationContext (src/setup.c)
• Runtime dispatch:
  • FlowSolver in src/solvers.c
• String/log display:
  • MomentumSolverTypeToString() in src/logging.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Solver YAML
  • Dual-Time Picard RK4 Momentum Solver
  • Momentum Solver Implementations

5. boundary_conditions

• Schema home: case.yml -> boundary_conditions
• Canonical values:
  • see the supported type/handler matrix in Boundary Conditions Guide
• Python hooks:
  • BC_TYPE_MAP
  • BC_HANDLER_SPECS
  • validate_and_prepare_boundary_conditions() in scripts/picurv
• Generated artifact:
  • bcs.run
• C parse/load:
  • ParseAllBoundaryConditions in src/io.c
• C validation/factory:
  • ValidateBCHandlerForBCType
  • BoundaryCondition_Create
• Runtime application:
  • src/Boundaries.c
  • src/BC_Handlers.c
• Canonical runtime representation:
  • UserCtx.boundary_faces
• Compatibility policy:
  • add any temporary adapter only when a concrete consumer exists; do not maintain parallel legacy BC arrays in UserCtx
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Case YAML
  • Boundary Conditions Guide

4. Particle Initialization Mode

• Schema home: case.yml -> models.physics.particles.init_mode
• Canonical values:
  • Surface
  • Volume
  • PointSource
  • SurfaceEdges
• Python hook:
  • normalize_particle_init_mode() in scripts/picurv
• Generated mapping:
  • init_mode -> -pinit
• C enum/storage:
  • ParticleInitializationType in include/variables.h
• C parser:
  • -pinit in CreateSimulationContext
• Runtime:
  • src/ParticleSwarm.c
  • src/ParticleMotion.c
  • src/runloop.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Particle Initialization and Restart Guide

5. Field Initialization Mode

• Schema home: case.yml -> properties.initial_conditions.mode
• Canonical values:
  • Zero
  • Constant
  • Poiseuille
• Python hooks:
  • normalize_field_init_mode()
  • resolve_initial_velocity_components()
• Generated mapping:
  • mode -> -finit
  • u_physical/v_physical/w_physical -> -ucont_x/-ucont_y/-ucont_z
• C storage/parser:
  • FieldInitialization in SimCtx
  • -finit in CreateSimulationContext
• Runtime:
  • src/initialcondition.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Initial Condition Modes

6. Analytical Type

• Schema home: solver.yml -> operation_mode.analytical_type
• Canonical values:
  • TGV3D
  • ZERO_FLOW
• Python hook:
  • normalize_analytical_type() in scripts/picurv
• Generated mapping:
  • analytical_type -> -analytical_type
• C storage/parser:
  • AnalyticalSolutionType in SimCtx
  • -analytical_type in CreateSimulationContext
• Runtime:
  • src/AnalyticalSolutions.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Solver YAML
  • Analytical Solution Modes

3. grid

• Schema homes:
  • case.yml -> grid.mode
  • case.yml -> grid.generator.grid_type
• Canonical values:
  • programmatic_c
  • file
  • grid_gen
• Python orchestration:
  • scripts/picurv grid validation and run-dir staging
• Generator implementation:
  • scripts/grid.gen
• Generated mapping:
  • programmatic_c emits -im/-jm/-km/...
  • file emits -grid_file
  • grid_gen shells out to grid.gen
• C consumption:
  • src/grid.c
  • src/io.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Case YAML
  • Grid Generator Guide: scripts/grid.gen

3. profiling

• Schema home: monitor.yml -> profiling.timestep_output.mode
• Canonical values:
  • off
  • selected
  • all
• Python hooks:
  • resolve_profiling_config()
  • prepare_monitor_files() in scripts/picurv
• Generated mapping:
  • timestep_output.mode -> -profiling_timestep_mode
  • timestep_output.file -> -profiling_timestep_file
  • final_summary.enabled -> -profiling_final_summary
  • selected function list -> profile.run + -profile_config_file
• C storage/parser:
  • profiling fields in SimCtx
  • option parsing in CreateSimulationContext
• Runtime:
  • src/logging.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Monitor YAML

4. Post-Processing Recipes

• Schema home: post.yml -> statistics_pipeline
• Canonical values:
  • msd
• Python hook:
  • normalize_statistics_task() in scripts/picurv
• Generated mapping:
  • msd -> ComputeMSD token in generated post.run (dispatched to ComputeParticleMSD)
• C dispatch:
  • src/postprocessor.c
• Kernel declaration/implementation:
  • include/particle_statistics.h
  • src/particle_statistics.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Configuration Reference: Postprocessor YAML

6. Related Docs

• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Developer Ingestion Map
• Configuration Extension Playbook
• Momentum Solver Implementations
• Boundary Conditions Guide