Research: investigate hierarchical TruncatedNormal sampling geometry

[AlexanderFengler]

Purpose and status

This is the research-only sink PR for the hierarchical TruncatedNormal
numerical investigation. It is not a production feature PR and must not be
merged into main.

• Base: permanent frozen experimental branch
  codex/1269-truncated-normal-experimental-base at exact candidate commit
  9e7002f00e7ff40524a8afc9e83b62723461c98f
• Head: codex/1282-qualify-truncated-hierarchy at 47274ca0
• Diff: 9 commits, 23 files, 23,214 additions and 2 deletions
• The rejected production candidate PR Rejected experiment: centered TruncatedNormal bounded group priors #1277 is closed unmerged; this PR's base
  and evidence remain intact independently of Fix safe priors for unmatched group-only effects #1272.

The only permitted intersection with the production prior-robustification
stream is a later, small policy/default bridge PR justified by the completed
numerical evidence.

Completed research machinery

• freeze an executable v2 smoke, qualification, and stress design: 55 scenarios
  and 748 planned cells with exact prior, truth, data, seed, initialization,
  precision, artifact, and decision contracts;
• implement artifact-producing direct PyMC, Bambi, and HSSM runners with
  deterministic datasets, exact transformed starts, process/cache isolation,
  immutable data/start/chain evidence, and atomic final markers;
• co-locate candidate/control pairs, bind evidence to source, environment,
  precision and artifact hashes, and recompute all gradient, convergence,
  efficiency, recovery, backend, and SBC gates in the assessor;
• add an opt-in qualification workflow with pair-aware shards, mandatory smoke
  gating, always-run aggregation, and uploaded raw evidence.

Canonical result

Canonical run
33410419447
on exact commit 8fdd272b returned screening-fail. Qualification and
stress were correctly skipped.

• 10 smoke cells planned; 9 completed; 1 LBA post-sampling diagnostics failure;
  no missing evidence.
• Four frozen divergence checks failed: direct PyMC lower-only, direct PyMC
  two-sided, current Bambi lower-only, and HSSM softmax beta.
• All nine completed local finite-difference and PyTensor/JAX contracts passed.
• The raw LBA chain was unusable independently of its diagnostics exception:
  R-hat up to 2.97, bulk ESS 2.33, BFMI 0.029, and every retained draw at 1,023
  leapfrog steps.

The LBA reporting exception is fixed in dbb2858e; the failed chain remains
immutable evidence and its scientific interpretation is unchanged.

Current conclusion

The proposed automatic centered native-TruncatedNormal default is not
qualified. Direct PyMC failures show that the observed problem sits below
HSSM and Bambi, but they do not by themselves demonstrate a PyMC software bug.
The leading explanation is difficult centered hierarchical funnel geometry,
amplified near bounds by the truncation normalization and, in some HSSM cases,
by prior calibration, initialization, and likelihood geometry.

Passing local density/gradient contracts argue against recurrence of the
historical local wrong-gradient defect for the nine completed cells. The
canonical LBA gradient contract did not complete, so LBA still requires an
explicit likelihood audit.

Next decision-grade work

Focused child PRs should extend this research sink prospectively:

1. Implementation audit: compare PyMC's transformed log density, gradient,
   and Hessian with an independent closed-form oracle over boundary-distance
   and hierarchy-scale grids.
2. Same-model causal parameterization panel: compare native centered TN,
   independently coded centered TN, exact inverse-CDF non-centering of group
   coefficients, and exact inverse-CDF non-centering of both hyper-location and
   group coefficients.
3. Controlled factors: lower-only versus two-sided bounds, boundary versus
   interior truth, weak versus informative data, current versus calibrated
   anchors, diagnostic start variants, repeated fixed seeds, and PyMC versus
   NumPyro.
4. HSSM likelihood isolation: advance only surviving candidates to softmax,
   DDM, and LBA; for LBA, separately audit likelihood values and gradients and
   compare the identical hierarchy under Gaussian and LBA likelihoods.

Decision rules remain prospective:

• centered TN fails but exact non-centered TN succeeds: centered coordinates
  are the primary cause;
• native and independently coded centered TN disagree: prepare a minimal PyMC
  bug reproducer;
• only one backend fails: investigate backend-specific sampling/adaptation;
• both exact TN parameterizations fail while linked alternatives succeed: TN is
  unsuitable as an automatic HSSM default;
• only anchor/start cases fail: repair those choices, freeze a new candidate,
  and requalify without weakening thresholds or rerolling failed seeds.

Frozen v2 contract

• manifest: 55 scenarios / 748 cells — 10 smoke, 720 qualification, 18 stress
• semantic SHA-256: 05d8be96204f124abe723fb38f65080631d2cdcb7c9b776428201ee66045e15e
• canonical raw evidence is uploaded on run 33410419447

Validation

• pre-runner stable-tree review: 238 focused tests passed
• post-smoke diagnostics/geometry regression: 59 tests passed
• Ruff check and format check passed
• Pyrefly reported 0 errors; mypy passed
• actionlint 1.7.12 passed
• both frozen locks passed uv lock --check --offline
• manifest validation and git diff --check passed

Tracks #1282.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}