Retain shifted density perturbation in opt-in blocked collision

docs/shifted_blocked_candidate.md

@@ -0,0 +1,43 @@
+# Opt-in shifted blocked candidate
+
+This candidate is based on fbe7377. The default remains unshifted. Enable with
+`LBMConfig(ddf_shifting=True)` only on the supported routes below.
+
+| Route | Candidate support |
+|---|---|
+| PeriodicBlockStepper, FP32 D2Q9 SRT double-buffer, no LES | shifted or unshifted |
+| FixedPatchStepper, every level blocked and same representation | shifted or unshifted |
+| Passive stationary circular BFL boundary and raw exchange | supported candidate scope |
+| Synchronized three-level child remap | private raw shifted snapshot, exact overlap/copy |
+| Dense root/refinement or mixed representation | rejected for shifted |
+| Slot/reservoir, surface actuation, velocity Jet | existing public shifted exclusion retained |
+| Other collision/lattice/storage/streaming/LES combinations | existing exclusions retained |
+
+The D2Q9 equilibrium helper accepts a retained density offset only in shifted
+compilation. BlockStep computes delta=sum(g) before adding the unit density;
+velocity uses the existing macro calculation. The existing SRT collision and
+all unshifted expressions remain. No global precision type or duplicate
+collision implementation is introduced. Ordinary shifted Simulation callers
+still use the existing rho−1 overload; this candidate does not change their
+numerical method.
+
+Public initialize receives physical populations and performs shifted subtraction
+in FP64 before the one FP32 storage cast. Public shifted download returns FP64
+physical populations with exact-rational D2Q9 background weights. Internal raw
+snapshots retain FP32 g and a representation tag; runtime remap never decodes
+and re-encodes overlap. Exact mass is interpreted as 1+sum(g), and momentum as
+sum(c*g); analyses should use raw values for tiny perturbation budgets. The
+FP32 BFL force constants have their own arithmetic rounding; no exact global
+conservation claim follows from shifting.
+
+Planar helper formulas include their shifted reference-density offsets and have
+actual-header host tests. Their public shifted route remains excluded until a
+separate test-gated migration. Next velocity-Jet work must validate physical
+wall density, incoming/outgoing populations, raw force/mass, ownership and
+transfer interactions before relaxing that restriction.
+
+Evidence so far: selected-cell CUDA replay favored retained-delta shifting;
+this is not full-solver validation. Host algebra/storage/remap tests and staged
+GPU continuation, three-grid cylinder physics, raw budgets, Couette helper
+stress and measured runtime are separate gates. Original failed experiments
+remain evidence; no acceptance threshold is relaxed.