Code Architecture

Table of Contents

• 1. Executable Entry Points
• 2. Solver Runtime Flow (simulator.c)
• 3. Postprocessor Runtime Flow (postprocessor.c)
• 4. Core Context Objects
  • 4.1 SimCtx
  • 4.2 UserCtx
• 5. Module Responsibilities
  • 5.1 File-Level API Entry Points
  • 5.2 Source-to-Test Coverage Lens
• 6. Configuration Ingestion Boundaries
• 7. Where to Extend
• 8. Next Steps

This page is the developer-oriented map of the current PICurv C codebase.

1. Executable Entry Points

• Solver executable entry: src/simulator.c
• Postprocessor executable entry: src/postprocessor.c

Both rely on shared setup/context infrastructure from setup.c, io.c, and variables.h. Persistent Eulerian field identity/runtime DM-Vec binding and separate solver-particle DMSwarm identity are shared through field_catalog.c, particle_field_catalog.c, and their headers; see Field Identity and Layout Catalog.

2. Solver Runtime Flow (simulator.c)

High-level stages:

1. PetscInitialize
2. CreateSimulationContext (setup.c) parses control/options and initializes defaults
3. SetupSimulationEnvironment configures run directories and environment-dependent logging setup
4. Setup stack:
   • SetupGridAndSolvers
   • SetupBoundaryConditions
   • SetupDomainRankInfo
   • InitializeEulerianState
   • InitializeParticleSwarm (if particles enabled)
5. Time integration via AdvanceSimulation
6. Finalization via profiling teardown + FinalizeSimulation + PetscFinalize

3. Postprocessor Runtime Flow (postprocessor.c)

• Parse post recipe (post.run) into PostProcessParams
• Load requested Eulerian/particle fields by timestep
• Execute configured Eulerian/Lagrangian/statistics pipelines
• Write VTK outputs (.vts, .vtp) and statistics CSV outputs

After successful field processing, the conductor's finalize_post_paraview_series can write .pvd indexes using committed checkpoint times and manifest ancestry. This serial presentation stage belongs to post.pipeline; it does not alter the C field kernels. Caught-up post invocations can refresh collections under the same post writer lock. See Physical-Time ParaView Collections (post.pipeline) for the tested scope.

4. Core Context Objects

4.1 SimCtx

• Declared in include/variables.h
• Holds global run configuration and top-level handles
• Populated mainly in CreateSimulationContext

4.2 UserCtx

• Block/grid-level state container (DM, vectors, metrics, block-local geometry)
• Used throughout grid, solver, BC, and post kernels
• Finest-level block arrays are central runtime work objects

5. Module Responsibilities

• Setup/config ingestion:
  • src/setup.c
  • src/io.c
• Field identity/storage binding:
  • src/field_catalog.c
  • src/particle_field_catalog.c
• Grid and metrics:
  • src/grid.c
  • src/Metric.c
• Momentum/pressure/rhs:
  • src/momentumsolvers.c
  • src/poisson.c
  • src/rhs.c
  • src/solvers.c
• BC system:
  • src/Boundaries.c
  • src/BC_Handlers.c
• Particles and coupling:
  • src/ParticleSwarm.c
  • src/ParticleMotion.c
  • src/ParticlePhysics.c
  • src/ParticleInitialConditions.c
  • src/interpolation.c
  • src/particle_statistics.c
• Postprocessing and VTK:
  • src/postprocessor.c
  • src/postprocessing_kernels.c
  • src/vtk_io.c
• Observability:
  • src/logging.c

Observability sits apart from the list above rather than inside one of its rows, because every other module reports through it. logging.c owns the console tier system, the runtime metric emitters, and the lifecycle of the per-run diagnostic files in <run.runtime_logs>. Its dependency direction is one-way and deliberate: it reads SimCtx for the step, physical time, log directory, rank, and continuation state, and it depends on PETSc for collectives and formatted output, but no solver module depends on logging for a numerical result. That is what lets any module report without acquiring a dependency on any other, and it is why a change here can alter what a user sees without altering what the solver computes.

5.1 File-Level API Entry Points

For contributor orientation, the table below lists high-value public entry points per subsystem. Function names come from include/*.h and represent the safest integration seams.

• startup/context:
  • files: setup.c, field_catalog.c, particle_field_catalog.c, simulator.c
  • APIs: CreateSimulationContext, SetupSimulationEnvironment, SetupGridAndSolvers, FieldGetDescriptor, FieldGetView, FinalizeSimulation
• runtime loop:
  • files: runloop.c, solvers.c
  • APIs: AdvanceSimulation, FlowSolver, UpdateSolverHistoryVectors
• pressure/projection/rhs:
  • files: poisson.c, rhs.c, momentumsolvers.c, BodyForces.c
  • APIs: PoissonSolver_Multigrid, ProjectVelocity, ComputeRHS, MomentumSolver_DualTime_Picard_JamesonRK
• grid/metrics:
  • files: grid.c, Metric.c
  • APIs: DefineAllGridDimensions, InitializeAllGridDMs, AssignAllGridCoordinates, CalculateAllGridMetrics
• boundary system:
  • files: Boundaries.c, BC_Handlers.c, wallfunction.c
  • APIs: BoundarySystem_Initialize, BoundaryCondition_Create, ApplyBoundaryConditions, Validate_DrivenFlowConfiguration
• particle stack:
  • files: ParticleSwarm.c, ParticleMotion.c, ParticlePhysics.c, ParticleInitialConditions.c, walkingsearch.c, interpolation.c
  • APIs: InitializeParticleSwarm, LocateAllParticlesInGrid, PerformMigration, UpdateAllParticleFields, InterpolateAllFieldsToSwarm
• I/O and post:
  • files: io.c, postprocessor.c, postprocessing_kernels.c, particle_statistics.c, vtk_io.c
  • APIs: ReadSimulationFields, WriteSimulationFields, ParsePostProcessingSettings, EulerianDataProcessingPipeline, GlobalStatisticsPipeline
• analytical/init:
  • files: AnalyticalSolutions.c, initialcondition.c
  • APIs: AnalyticalSolutionEngine, InitializeEulerianState, SetInitialInteriorField

5.2 Source-to-Test Coverage Lens

Current tests cover all src/*.c files at least at module level (unit suites and/or smoke). Coverage depth is intentionally uneven:

• orchestration-heavy files (setup.c, io.c, runloop.c, postprocessor.c) are mainly covered by smoke and Python orchestration tests.
• math-kernel-heavy files (Metric.c, rhs.c, poisson.c, post kernels) are covered by targeted C unit suites plus smoke.
• utility-heavy files (walkingsearch.c, wallfunction.c, Filter.c) are covered by specific unit cases but still benefit from deeper function-level API prose.

When adding docs, prioritize:

1. explicit call-sequence narratives for orchestration modules
2. contract/units/assumptions for numerical kernels
3. failure signals and diagnostics for runtime-heavy paths

6. Configuration Ingestion Boundaries

Primary ingestion sites:

• setup.c: PETSc option parsing for solver/post shared runtime controls
• io.c: grid read/generation inputs, restart/data IO, post recipe parsing
• logging path includes environment variable ingress (LOG_LEVEL)

Not all option consumption is explicit PetscOptionsGet*; PETSc dynamic ingestion also occurs through calls like KSPSetFromOptions in poisson.c.

7. Where to Extend

• New user-visible config key:
  1. add schema/template key
  2. validate/map in picurv_cli/core.py
  3. parse in setup.c or io.c
  4. wire runtime consumer
  5. update docs pages 14/15/16
• New post kernel:
  • implement in postprocessing_kernels.c
  • expose task mapping in picurv
  • document in post reference
• New particle model:
  • extend ParticlePhysics.c/ParticleMotion.c interface
  • add structured schema and ingestion wiring

8. Next Steps

• Config contract: Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Ingestion map: Developer Ingestion Map
• Extension workflow: Configuration Extension Playbook
• Numerical-method overviews: Methods and Models Overview
• Repository map: Repository Navigation and Directory Guides
• Momentum solver index: Momentum Solver Implementations
• Analytical solution index: Analytical Solution Modes
• Initial-condition index: Initial Condition Modes
• Particle-model index: Particle Model and Coupling Overview
• API docs quality status: API Documentation Status
• Field identity/layout catalog: Field Identity and Layout Catalog
• Field statistics pipeline: Field Statistics
• Low-priority fix queue: Maintenance Backlog and Low-Priority Fixes