|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
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.
High-level startup sequence:
PetscInitializenp > 0)Startup branch details:
StartStep == 0:StartStep > 0:load -> PerformLoadedParticleSetupinit -> PerformInitializedParticleSetuppicurv_cli/core.py 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).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.position, DMSwarm_CellID, status fields, etc.).Related ownership note:
simCtx->usermg.mgctx[simCtx->usermg.mglevels-1].user[*]for bi in block_number) are common in setup, IO, and update stagesEulerian:
Lagrangian:
StartStep and particle_restart_mode.-pinit.Per-step sequence:
step and time,Concrete output calls in the loop are:
Loop-time branch notes:
solve, load, or analytical), then particle coupling follows.Boundary lifecycle is object-style (function pointers per handler):
bcs.run,Initialize once,PreStep, Apply, optional PostStep) in priority order.Useful entry points:
Any field read by the momentum residual or its boundary handlers must be reconstructed or synchronized from the current SNES trial vector before it can influence F(X). A matrix-free residual (MomentumNewtonKrylov_FormResidual) that reads stale state is not a deterministic function of X, which breaks the finite-difference Jacobian action and the line search.
Concretely, the Cartesian velocity state must be seeded in dependency order at the top of each residual evaluation, before ApplyBoundaryConditions runs (the conservation-outlet handler reads lUcat on its first pass):
Contra2Cart() alone is insufficient (it does not refresh lUcat), and the reconstruction inside ApplyBoundaryConditions() runs after the first handler sweep, so it cannot prepare that sweep. When adding a new field read by the residual or a boundary handler, seed it from X here or expect residual-purity regressions. See Newton–Krylov Momentum Solver, Section 5.
When adding or changing physics behavior:
solvers.c, rhs.c, poisson.c, Particle*, Boundaries*),SimCtx or UserCtx only when ownership is clear,Cross-layer reminder:
setup.c / io.c option ingestion should also update:tests/tooling/audit_ingress_manifest.jsondocs/pages/15_Config_Ingestion_Map.mdtest_config_regressions.py / test_cli_smoke.py)High-value checks during development:
DisplayBanner summary (BCs, modes, solver selection),ProfilingLogTimestepSummary),picurv validate before solver execution.Additional fast diagnostics:
manifest.json + generated config/*.control against expected YAML role settingspicurv run --dry-run --format json to verify launch-mode/rank assumptions before expensive runs--restart-from / --continue resolution and the generated -restart_dir in control artifactsThis page describes C Runtime Execution Map 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.
1.9.8