Modular Selector Extension Guide

Table of Contents

• 1. Standard Checklist For Any Selector
• 2. Momentum Solver Selector
• 3. Boundary Condition Type Or Handler
• 4. Particle Initialization Mode
• 5. Interpolation Method
• 6. Field Initialization Mode
• 7. Analytical Type
• 8. Verification Source Overrides
• 9. Grid Selector / Generator Selector
• 10. Profiling Selector
• 11. Postprocessing / Statistics Tasks
• 11. Related Pages
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

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 picurv_cli/core.py,
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 Jameson RK
• Python hook:
  • normalize_momentum_solver_type() in picurv_cli/core.py
• 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 Jameson RK Momentum Solver
  • Momentum Solver Implementations

3. Boundary Condition Type Or Handler

• 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 picurv_cli/core.py
• 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 picurv_cli/core.py
• 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. Interpolation Method

• Schema home: solver.yml -> interpolation.method
• Canonical values:
  • Trilinear
  • CornerAveraged
• Python hook:
  • normalize_interpolation_method() in picurv_cli/core.py
• Generated mapping:
  • interpolation_method -> -interpolation_method
• C enum/storage:
  • InterpolationMethod in include/variables.h
• C parser:
  • -interpolation_method in CreateSimulationContext (src/setup.c)
• Runtime dispatch:
  • InterpolateEulerFieldToSwarm in src/interpolation.c
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Trilinear Interpolation and Particle-Grid Projection
  • Particle Initialization and Restart Guide

6. Field Initialization Mode

• Schema home: case.yml -> properties.initial_conditions.mode
• Canonical values:
  • generated with generator: zero|constant|streamwise_constant|poiseuille|ic_gen
  • file with field: Ucat|Ucont
• Python hooks:
  • resolve_initial_condition_config()
  • stage_initial_condition_file()
  • run_initial_condition_generator()
  • normalize_flow_direction_token()
  • resolve_ic_cli_params()
• Generated mapping:
  • built-in generator -> matching -finit and parameter flags
  • file or ic_gen -> -finit 4 -ic_field ... -ic_dir ...
• C storage/parser:
  • initialConditionMode, initialConditionField, initialConditionDirectory, icVelocityPhysical, and flowDirection in SimCtx
• Runtime:
  • src/initialcondition.c — PopulateInitialUcont, SetInitialInteriorField
  • src/setup.c — Cart2Contra, UniformCart2Contra
• Tests/docs to update:
  • tests/test_cli_smoke.py
  • Initial Condition Modes

7. Analytical Type

• Schema home: solver.yml -> operation_mode.analytical_type
• Canonical values:
  • TGV3D
  • ZERO_FLOW
  • UNIFORM_FLOW
• Python hook:
  • normalize_analytical_type() in picurv_cli/core.py
• 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

8. Verification Source Overrides

• Schema home: solver.yml -> verification.sources.*
• Design intent:
  • reserved for verification-only source injections when no ordinary end-to-end path is sufficient
  • keep runtime call sites thin and centralize override implementations in verification_sources.*
• Current support:
  • verification.sources.diffusivity
  • verification.sources.scalar
  • diffusivity profile LINEAR_X
  • scalar profiles CONSTANT, LINEAR_X, SIN_PRODUCT
• Python hooks:
  • validation and flag emission in picurv_cli/core.py
• Generated mapping:
  • verification.sources.diffusivity.mode -> -verification_diffusivity_mode
  • verification.sources.diffusivity.profile -> -verification_diffusivity_profile
  • verification.sources.diffusivity.gamma0 -> -verification_diffusivity_gamma0
  • verification.sources.diffusivity.slope_x -> -verification_diffusivity_slope_x
  • verification.sources.scalar.mode -> -verification_scalar_mode
  • verification.sources.scalar.profile -> -verification_scalar_profile
  • verification.sources.scalar.value -> -verification_scalar_value
  • verification.sources.scalar.phi0 -> -verification_scalar_phi0
  • verification.sources.scalar.slope_x -> -verification_scalar_slope_x
  • verification.sources.scalar.amplitude -> -verification_scalar_amplitude
  • verification.sources.scalar.kx/ky/kz -> -verification_scalar_kx/-verification_scalar_ky/-verification_scalar_kz
• C storage/parser:
  • verificationDiffusivity and verificationScalar in SimCtx
  • option parsing in CreateSimulationContext
• Runtime:
  • src/verification_sources.c
  • thin delegation from src/rhs.c for diffusivity
  • analytical scalar truth in src/AnalyticalSolutions.c
  • gated particle-physics bypass in src/ParticlePhysics.c
  • runtime metric writer in src/logging.c (logs/scatter_metrics.csv)
• Design boundary:
  • verification sources exist only for otherwise-unreachable verification scenarios
  • analytical truth definitions belong in AnalyticalSolutions, not in model-evolution code such as ParticlePhysics
• Tests/docs to update:
  • tests/test_config_regressions.py
  • tests/c/test_poisson_rhs.c
  • tests/c/test_solver_kernels.c
  • tests/c/test_logging.c
  • tests/c/test_setup_lifecycle.c
  • Configuration Reference: Solver YAML
  • Analytical Solution Modes
  • Configuration Extension Playbook

9. Grid Selector / Generator Selector

• Schema homes:
  • case.yml -> grid.mode
  • case.yml -> grid.generator.grid_type
• Canonical values:
  • programmatic_c
  • file
  • grid_gen
• Python orchestration:
  • picurv_cli/core.py grid validation and run-dir staging
• Generator implementation:
  • generators/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: generators/grid.gen

10. Profiling Selector

• Schema home: monitor.yml -> profiling.timestep_output.mode
• Canonical values:
  • off
  • selected
  • all
• Python hooks:
  • resolve_profiling_config()
  • prepare_monitor_files() in picurv_cli/core.py
• 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

11. Postprocessing / Statistics Tasks

• Schema home: post.yml -> statistics_pipeline
• Canonical values:
  • msd
• Python hook:
  • normalize_statistics_task() in picurv_cli/core.py
• 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

11. Related Pages

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

CFD Reader Guidance and Practical Use

This page describes Modular Selector Extension Guide 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.