Docs/Particles.rst still documents the i%2==0 && j%2==1 quarter-cell seeding removed by PR #213 and advertises a tracer_particles_mass_density plot variable that nothing can produce (massDensity/GetMeshPlotVar have no caller) #261

Severity: low · Category: build-config
Locations: Docs/sphinx_documentation/source/Particles.rst:109-111, Docs/sphinx_documentation/source/Particles.rst:146-148, src/particles/incflo_PCInit.cpp:108-122, src/particles/incflo_PC.H:117-121, src/particles/incflo_PC.H:134-143, src/particles/ParticleData.H:79-115, src/particles/incflo_PCUtils.cpp:8-39, src/utilities/io.cpp:424-430, src/utilities/io.cpp:680-694
Based on commit 46de3367 (line numbers refer to that tree).

The defect

Two statements in the particle chapter (built and deployed by .github/workflows/docs.yml) do not describe
this tree:

1. Particles.rst:109-111:

   Note that, as currently implemented, particles are placed only in cells whose indices satisfy
   i mod 2 = 0 and j mod 2 = 1, so only one quarter of the cells in the box receive particles.

   This documented the if (i%2 == 0 && j%2 == 1) filter reported as incflo_PCInit: seeding fills only 1/4 of cells; cylinder cull ignores cylinder.direction #171 and removed by PR fix issues 171 176 181 188 189 191 #213. At
   46de336 the seeding loop (incflo_PCInit.cpp:108-122) fills every cell of the particle box (subject to
   vfrac > 0 under EB), so the note now tells users the opposite of what the code does and makes the
   fixed bug look intentional.

2. Particles.rst:146-148:

   A mass density computed by depositing the particle mass onto the mesh ... which appears in plotfiles
   as the variable tracer_particles_mass_density.

   incflo_PC::meshPlotVarNames()/computeMeshVar() (incflo_PC.H:117-143), ParticleData::GetMeshPlotVarNames()
   / GetMeshPlotVar() (ParticleData.H:79-115) and incflo_PC::massDensity() (incflo_PCUtils.cpp:8-39)
   have no caller outside src/particles/ (grep -rn 'GetMeshPlotVar\|computeMeshVar\|massDensity\|meshPlotVarNames' src/
   finds only their definitions). WritePlotVariables knows particle_count (io.cpp:424-430, :680-694)
   and nothing else particle-related; a deck that lists tracer_particles_mass_density in amr.plt_* hits
   amrex::Abort("... plotfile variable ... not found") (io.cpp:705). The incflo_PC::massDensity reads dxi[2] out of bounds in 2D builds (GpuArray has SPACEDIM entries) #168 fix (PR Guard the cell-volume product by dimension in massDensity. #200) therefore
   patched a function that cannot be reached.

Why it matters

Users reading the deployed documentation are told that seeding is deliberately sparse (it is not) and that a
mass-density plot variable exists (requesting it aborts the run). Both are leftovers of the round-1 fixes.

How to reach it

Read Docs/sphinx_documentation/source/Particles.rst at 46de336, or add tracer_particles_mass_density to
amr.plt_vars-style inputs in a -DINCFLO_PARTICLES=ON build: WritePlotVariables aborts with
"plotfile variable 'tracer_particles_mass_density' not found".

Suggested fix

Drop the stale note and state that the mass density is not yet exposed (or, alternatively, wire
ParticleData::GetMeshPlotVarNames/GetMeshPlotVar into WritePlotVariables, which is the larger change the
docs anticipate). Docs-only diff checked with git apply --check (audit/notes/T8-scratch/031.diff):

--- a/Docs/sphinx_documentation/source/Particles.rst
+++ b/Docs/sphinx_documentation/source/Particles.rst
@@ -106,10 +106,6 @@
 - If the cylinder inputs are present, particles lying outside the cylinder are removed immediately after
   initialization.
 
-Note that, as currently implemented, particles are placed only in cells whose indices satisfy
-:math:`i \bmod 2 = 0` and :math:`j \bmod 2 = 1`, so only one quarter of the cells in the box receive
-particles.
-
 Advection
 ---------
 
@@ -144,5 +140,5 @@
-  ``incflo.refine_particles`` is true (the default), cells containing at least one particle are tagged
+  ``amr.refine_particles`` is true (the default), cells containing at least one particle are tagged
   for refinement.
 - A mass density computed by depositing the particle mass onto the mesh with linear interpolation in
-  :cpp:`incflo_PC::massDensity()`, which appears in plotfiles as the variable
-  ``tracer_particles_mass_density``.
+  :cpp:`incflo_PC::massDensity()`. This is not yet connected to the plotfile writer, so there is no
+  ``tracer_particles_mass_density`` plot variable at present.