C Runtime Execution Map

Table of Contents

• 1. Solver Startup Order (<tt>src/picsolver.c</tt>)
• 3. Core Runtime Structs
• 4. Initialization Branches
• 6. Boundary System Runtime Hooks
• 8. Debugging Entry Points

This page is a contributor-oriented map of how the C solver executes from process start to timestep loop. Use it as a practical companion to architecture and methods pages when modifying solver behavior.

1. Solver Startup Order (<tt>src/picsolver.c</tt>)

High-level startup sequence:

1. PetscInitialize
2. CreateSimulationContext
3. SetupSimulationEnvironment
4. SetupGridAndSolvers
5. SetupBoundaryConditions
6. SetupDomainRankInfo
7. InitializeEulerianState
8. InitializeParticleSwarm (if np > 0)
9. DisplayBanner
10. initial settlement/restart finalization
11. AdvanceSimulation

6. Configuration Ingestion Boundaries

scripts/pic.flow is the control-plane generator. It writes normalized runtime artifacts under runs/<run_id>/config/ and launches C binaries with -control_file.

Core generated files consumed by C:

• *.control (solver flags),
• bcs.run (boundary face/type/handler + params),
• whitelist.run and profile.run,
• grid.run (for file/grid_gen paths),
• post.run (postprocessor path).

3. Core Runtime Structs

Most solver-wide state flows through:

• SimCtx: global run configuration, solver controls, pointers to hierarchy and shared runtime services.
• UserCtx: per-block/per-level field ownership, DM/Vec handles, boundary configs, and local coupling context.
• BoundaryFaceConfig: per-face mathematical type + handler + param list.
• swarm particle records and DMSwarm fields (position, DMSwarm_CellID, status fields, etc.).

4. Initialization Branches

Eulerian:

• InitializeEulerianState selects fresh/load/analytical branch and then seeds history vectors.

Lagrangian:

• InitializeParticleSwarm selects initialize-vs-load based on StartStep and particle_restart_mode.
• fresh path uses random/deterministic placement logic depending on -pinit.
• load path may use MigrateRestartParticlesUsingCellID for direct ownership migration.

1. Per-Step Particle Pipeline

Per-step sequence:

1. update step and time,
2. reset particle statuses (if particles enabled),
3. Eulerian step:
   • FlowSolver for solve mode, or load/analytical branch,
4. Lagrangian step:
   • UpdateAllParticlePositions,
   • LocateAllParticlesInGrid and migration,
   • CheckAndRemoveLostParticles,
   • InterpolateAllFieldsToSwarm,
   • UpdateAllParticleFields,
   • CalculateParticleCountPerCell and ScatterAllParticleFieldsToEulerFields,
5. update history vectors,
6. write outputs on configured cadence.

Concrete output calls in the loop are:

• WriteSimulationFields
• WriteAllSwarmFields
• ProfilingLogTimestepSummary

6. Boundary System Runtime Hooks

Boundary lifecycle is object-style (function pointers per handler):

1. parse bcs.run,
2. create handler objects via factory,
3. run Initialize once,
4. on each step, run handler phases (PreStep, Apply, optional PostStep) in priority order.

Useful entry points:

• BoundarySystem_Initialize
• BoundaryCondition_Create
• ApplyBoundaryConditions
• DeterminePeriodicity

7. Extensibility Status

When adding or changing physics behavior:

1. identify owning module (solvers.c, rhs.c, poisson.c, Particle*, Boundaries*),
2. add/modify fields in SimCtx or UserCtx only when ownership is clear,
3. keep history-vector and ghost-update contracts intact,
4. update logging labels and diagnostics,
5. update Python ingestion path so YAML and C flags remain consistent.

8. Debugging Entry Points

High-value checks during development:

• DisplayBanner summary (BCs, modes, solver selection),
• per-step profile summaries (ProfilingLogTimestepSummary),
• particle metrics and location/migration counters,
• strict YAML validation through pic.flow validate before solver execution.

1. Reference Scales

• Code Architecture
• Developer Ingestion Map
• Methods and Models Overview
• Boundary Conditions Guide
• Particle Initialization and Restart Guide