Code Architecture

Table of Contents

• 1. Executable Entry Points
• 2. Solver Runtime Flow (picsolver.c)
• 3. Postprocessor Runtime Flow (postprocessor.c)
• 4. Core Context Objects
  • 4.1 SimCtx
  • 4.2 UserCtx
• 5. Module Responsibilities
• 6. Configuration Ingestion Boundaries

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

1. Executable Entry Points

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

Both rely on shared setup/context infrastructure from setup.c, io.c, and variables.h.

2. Solver Runtime Flow (picsolver.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

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
• 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/interpolation.c
  • src/particle_statistics.c
• Postprocessing and VTK:
  • src/postprocessor.c
  • src/postprocessing_kernels.c
  • src/vtk_io.c

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. Extensibility Status

• New user-visible config key:
  1. add schema/template key
  2. validate/map in scripts/pic.flow
  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 pic.flow
  • document in post reference
• New particle model:
  • extend ParticlePhysics.c/ParticleMotion.c interface
  • add structured schema and ingestion wiring

9. Next Steps

• Config contract: Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Ingestion map: Developer Ingestion Map
• Extension workflow: Configuration Extension Playbook
• Workflow growth paths: Workflow Extensibility Guide
• 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
• Low-priority fix queue: Maintenance Backlog and Low-Priority Fixes