Commit d3937951 authored by Gaetano Scandariato's avatar Gaetano Scandariato
Browse files

docs: explain why NUTS starts take one walker per lineage

parent fa01c0a7
Loading
Loading
Loading
Loading
+14 −9
Changes for docs/config/sampling.md: 14 added lines, 9 removed lines.
Original line number Diff line number Diff line
@@ -172,9 +172,9 @@ shrinkage (Skilling 2006). When publishing an evidence, cite the works in the
   harmless when NUTS follows, because only the lowest-energy walkers are used.
   The re-seeding is needed also when NUTS follows: the spread of the walkers
   decides between NUTS and ensemble production (step 3) and sets the NUTS mass
   matrix, and stuck walkers would distort both. A re-seeded walker, however,
   continues the history of the walker it was copied from, so NUTS never starts
   two chains from walkers of the same lineage (step 4).
   matrix, and stuck walkers would distort both. A re-seeded walker,
   however, is a copy that continues the history of its donor, so NUTS never
   starts two chains from the same lineage (step 4; "NUTS mechanics" below).
3. **Phase 2, energy-spread test.** Compares the spread of walker potential
   energies with `chain_energy_threshold × n_free_params`.
4. **Phase 3a, unimodal → NUTS.** If the spread is ≤ threshold, NUTS chains
@@ -276,12 +276,17 @@ For a $D$-dimensional posterior:
  chains that did not share their starting point make R-hat meaningful: R-hat
  compares the spread between chains with the spread within them, and chains
  started from one point agree with each other for a while even when they have
  not converged. For the same reason the starts are taken at most one per
  lineage: a walker re-seeded from another during the warmup and the walker it
  was copied from count as one, and the next lowest energy is taken instead
  (only if there are fewer lineages than chains do two chains share one). Until
  October 2026 all chains started from the single best walker, and until
  2026-10-05 a re-seeded walker and its donor could both be chosen. R-hat above 1.01 is flagged in the diagnostics table (`*`, and `**`
  not converged, so R-hat then looks better than it should. A walker restarted
  from another during the warmup (step 2) is a copy: it continues the history of
  its donor and, for a while, moves like it. Chains started from a copy and its
  donor would therefore agree for the same reason, so PyAETNA records the
  *lineage* of every walker (the original walker whose history it continues) and
  takes the starts at most one per lineage, the next lowest energy replacing a
  duplicate. This keeps the restart of stuck walkers, which the route decision
  and the mass matrix need, while the chains start independently. Only if there
  are fewer lineages than chains do two chains share one. Until October 2026 all
  chains started from the single best walker, and until 2026-10-05 a restarted
  walker and its donor could both be chosen. R-hat above 1.01 is flagged in the diagnostics table (`*`, and `**`
  above 1.1).
- **Frozen inverse mass matrix**: a diagonal inverse mass matrix from the
  variance of the walker positions (`adapt_mass_matrix=False`). Only the step