Developer Portal

Table of Contents

• 1. Architecture and Contracts
• 2. Numerical Methods and Models
• 3. Documentation and Maintenance
• 4. Suggested Contributor Read Path
• 5. Expected Outcomes
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This section is for maintainers and contributors changing solver behavior, YAML contracts, or workflow logic. It emphasizes architecture boundaries, method-level reasoning, and safe extension points.

1. Architecture and Contracts

• Code Architecture: module boundaries and runtime ownership model.
• Configuration Contract (YAML -> Generated Artifacts -> Runtime): YAML -> generated artifact -> runtime contract.
• Developer Ingestion Map: where specific YAML keys enter C/Python paths.
• Configuration Extension Playbook: adding new keys/features safely.
• Modular Selector Extension Guide: selector-by-selector hook points for extending current user-facing options.
• Workflow Extensibility Guide: extending orchestration beyond current run/sweep modes.
• C Runtime Execution Map: startup/timestep execution trace across C modules.
• Field Identity and Layout Catalog: typed Eulerian/particle field identities, runtime views, and coupling metadata.
• Field Statistics: scientific field statistics — accumulation, monitoring, checkpoint state, derived output, and extension points.
• Future Architecture Specifications: status and sequencing of proposed future architecture.
• Field Statistics Planned Extensions: spatial targets, further products, and histories, with their dependency order.
• Function Identity and Observability Specification: deferred, benchmark-gated logging/profiling identity design.

2. Numerical Methods and Models

• Methods and Models Overview: entry map across all numerical method pages.
• CurvIB Method Overview through IEM Mixing and Statistical Averaging: flow solve, pressure solve, coupling, and mixing/statistics internals.
• Momentum Solver Implementations: runtime-dispatched momentum solver implementations.
• Analytical Solution Modes and Initial Condition Modes: initialization and analytical-mode behavior.
• Boundary Conditions Guide: BC handler mapping from YAML to C handler objects.
• Particle Initialization and Restart Guide: seeding and restart/migration behavior.
• Particle Model and Coupling Overview: particle lifecycle and projection coupling.

3. Documentation and Maintenance

• API Documentation Status: current API documentation coverage and gaps.
• Grid, Cell, and Variable Architecture Guide: data-structure contracts in grid/cell storage.
• Maintenance Backlog and Low-Priority Fixes: low-priority but known technical-debt items.
• Documentation Map: alternate categorized entry path.

4. Suggested Contributor Read Path

1. Code Architecture
2. Configuration Contract (YAML -> Generated Artifacts -> Runtime)
3. Developer Ingestion Map
4. Configuration Extension Playbook
5. Modular Selector Extension Guide
6. C Runtime Execution Map
7. Field Identity and Layout Catalog
8. Field Statistics
9. Methods and Models Overview

5. Expected Outcomes

After working through this section, you should be able to:

• trace a new YAML key from schema to runtime consumer,
• identify the right C module for a numerical feature change,
• update docs/tests/validation alongside code changes,
• preserve diagnostics and contract clarity while extending behavior.

CFD Reader Guidance and Practical Use

This page describes Developer Portal 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.