|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
This page tracks non-blocking technical debt items (warnings cleanup, refactors, and quality-of-life fixes) that are safe to address incrementally.
Use this page for:
Do not use this page for urgent correctness/security issues.
Primary warning tracker location:
logs/doxygen.warnings (generated by make build-docs)For compiler/runtime warning campaigns, track status directly in this page.
Current warning clusters include:
These categories should be fixed in small, reviewable batches.
src/io.c).uninitialized, format overflows, type mismatches) first.sandbox/ is retained as optional developer scratch space.config/, examples/, picurv_cli/, generators/, or docs/.Potential low-priority observability improvements worth revisiting:
CASE SUMMARY and command-status reports. The fixture matrix should cover initial-condition and boundary-condition families, restart/load paths, particle modes, solver families, monitor/profiling choices, and each solution-convergence mode.tests/tooling/user_facing_reporting_contract.json from its current structural command/reporting checks into a runtime-backed reporting matrix for representative submit, cancel, sweep, plot, deferred, and continuation outcomes.runs/<run_id>/logs/ so it is not affected by solver-side log-directory recreation; scheduler/ is the existing precedent for batch stdout/stderr.solution_monitoring.convergence.mode: steady_deterministic; keep transient diagnostic-only and require configured tolerances, minimum samples, dwell windows, and safe-checkpoint final writes before stopping.P, |Ucat|, Psi, diffusivity) only if users need compact trend logs instead of verbose anatomy/min-max output.Particle_Metrics.log proves insufficient; prefer compact inventory/health summaries over larger particle state dumps.Observability policy note:
Measured 2026-08-17 on flat_channel. This is characterized and accepted, not an open defect. It is recorded here so it is not rediscovered as a bug and so future restart/statistics tolerances are set from a measured floor.
What happens. SetInitialFluidState_Load calls ApplyBoundaryConditions immediately after ReadSimulationFields (src/initialcondition.c). That runs a three-pass boundary fixed-point loop whose Contra2Cart step rebuilds Ucat from Ucont, so a restarted run resumes from BC(x_N) rather than the checkpointed x_N. Apply_OutletConservation does not refine the outlet, it overwrites it: the outlet flux is regenerated from the adjacent interior Ucat plus a global mass correction. The stored end-of-step state is therefore not a fixed point of the boundary map, and re-applying it reveals the offset.
Measured behavior.
P, Nvert, and Ucont_rm1 are bit-exact across the restart.Ucont relative L2 peaks near 5e-8 at step 55 and decays to 4.5e-8 by step 100; P peaks near 1.5e-7 and decays to 1.3e-7.Ucont |d|inf ~4.6e-10 against momentum absolute_tol 1e-8).(Recorded before momentum convergence moved to the residual criterion: absolute_tol no longer participates while a residual tolerance is set. The finding is unaffected — it is about a structural floor, not about which tolerance is active.)
The perturbation is invariant to solver tolerance. Tightening momentum relative_tol 1e-3 to 1e-8, absolute_tol 1e-8 to 1e-12, and Poisson absolute_tolerance 1e-5 to 1e-10 changed the restart offset by under one percent (Ucont relative L2 9.061e-09 versus 9.153e-09), while changing the underlying trajectory by 1.67e-05, roughly 370 times larger than the offset itself. The floor is structural. It cannot be tightened away through solver settings.
Consequences.
Ucont_rm1 avoids an artificial first-order restart step. It must not be read as promising a bit-exact trajectory. One step after restart the BDF2 history pair is asymmetric: the n-1 slot carries BC(x_N) where an uninterrupted run carries x_N.Open question, deliberately not pursued. Why the offset lands near 1e-7 rather than some other magnitude is not established. Two candidate mechanisms remain: a residual of the three-pass boundary loop, or the ordering of the pressure projection relative to the last boundary application within a step. Changing the pass count in src/Boundaries.c and re-measuring the offset would distinguish them. Geometric scaling with pass count implicates the loop; no change implicates checkpoint placement within the step.
Field statistics carry a validated acceptance suite covering moment accuracy, window scheduling and clipping, masks, layouts and periodicity, restart continuation, console monitoring, and equivalence across a changed MPI rank count. Two items in that suite were deliberately left uncovered, and are recorded here so they are not mistaken for oversights.
Multiblock equivalence has no coverage. No multiblock runtime harness exists at any level — not for statistics and not for the solver generally. Statistics payloads are block scoped and follow the same natural ordering Eulerian payloads do, so there is no reason to expect a multiblock-specific defect, but that is an argument from construction rather than a test. Building the harness is the prerequisite, and it is not specific to statistics; whoever builds it should extend it to statistics payloads at the same time.
Graceful-shutdown ordering is guaranteed by construction, not by a test. The committed bundle at a given step carries that step's contribution, which the statistics smoke scenarios assert through the ordinary cadence, and the shutdown path writes through the same coordinator. What is untested is that the run loop offers the completed state to the windows before it reaches the shutdown writer. That ordering lives in src/runloop.c. A test that drove the sequence itself would re-assert the checkpoint round trip rather than the ordering, which is why one was not written; catching a reordering needs a test that runs the loop, or a signal delivered at a controlled step.
This page describes Maintenance Backlog and Low-Priority Fixes 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