Skip to content

docs: better VI posterior and sampling methods how-to-guides - #1942

Merged
janfb merged 12 commits into
mainfrom
docs/vi-sampler-guidance
Jul 30, 2026
Merged

docs: better VI posterior and sampling methods how-to-guides#1942
janfb merged 12 commits into
mainfrom
docs/vi-sampler-guidance

Conversation

@janfb

@janfb janfb commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

As discussed in #1765, the how-to guides around sampling methods and VI are a bit outdated and in parts misleading. This PR reworks them.

Restructure the sampler guide

09_sampler_interface was accurate but hard to act on: it opened abruptly and mixed
recommendations, configuration and low-level API across a flat list of sections. It now
follows the path a stuck user actually takes:

  1. General context — why sampling differs between methods at all: NPE approximates the
    posterior directly so sampling is a forward pass, while NLE and NRE give a score
    proportional to the log posterior and need an extra algorithm.
  2. Which sampler do you need? — routing by the inference method used, not by sampler.
    NPE/FMPE/NPSE: nothing to choose, plus the two exceptions (leakage, evaluable
    likelihood). NLE/NRE: start with MCMC, then branch to VI, rejection or importance
    sampling by the symptom you have.
  3. Setting the samplerbuild_posterior(sample_with=...) with PosteriorParameters.
  4. Full control — the potential-function API as the low-level, high-flexibility
    interface, including building the sampler classes on a potential directly to use a
    non-prior proposal.

Give VI its own guide

VI had no guide of its own, so the sampler guide was the only place documenting
train() vs train_amortized(), the vi_method options and evaluate(). That content
moves to a new 26_variational_inference guide, which covers fixed-observation VI, quality
control with $\hat{k}$, SIR refinement, sequential NLE with VI, and amortized VI. The
sampler guide now links to it, as do the abstraction-levels and PosteriorParameters
guides and the implemented-methods tutorial.

Corrections

  • Replace fixed parameter- and observation-count heuristics with guidance based on
    posterior geometry, proposal overlap, computational budget, repeated-observation needs
    and diagnostics.
  • Fix the rejection-sampling acceptance-rate claim. RejectionPosterior.sample() discards
    the rate returned by rejection_sample(), so it cannot be read from the documented
    workflow; the sub-1% logging.warning is the only user-facing signal. Call
    sbi.samplers.rejection.rejection_sample() directly if the number itself is needed.
  • Clarify the amortized ELBO/reverse-KL limitation and the mode-switching behaviour between
    train() and train_amortized().
  • Scope importance sampling and SIR refinement to fixed-observation posteriors.
  • Repair related inference-method links, including a link with a blank target.
  • Add the vector-field guide to the how-to landing page; it was registered in the sampling
    toctree but missing from the list.

Every API name, keyword argument, default and behavioural claim in the new text was checked
against the source rather than carried over on trust.

Docs-only change, so no CHANGELOG entry and no tests. Built locally with Sphinx; all
cross-references resolve.

Claude Code assisted with the restructure and with verifying the API claims.

Closes #1765

@codecov

codecov Bot commented Jul 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.66%. Comparing base (2c67b91) to head (eaa0c27).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1942      +/-   ##
==========================================
- Coverage   87.80%   87.66%   -0.14%     
==========================================
  Files         143      143              
  Lines       13435    14786    +1351     
==========================================
+ Hits        11796    12962    +1166     
- Misses       1639     1824     +185     
Flag Coverage Δ
fast 81.61% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 14 files with indirect coverage changes

@janfb janfb changed the title Improve VIPosterior sampler guidance docs: refactor VI posterior and sampling methods how-to-guides Jul 21, 2026
@janfb janfb changed the title docs: refactor VI posterior and sampling methods how-to-guides docs: better VI posterior and sampling methods how-to-guides Jul 21, 2026
@janfb
janfb requested a review from dgedon July 21, 2026 22:20
@janfb janfb mentioned this pull request Jul 22, 2026
8 tasks
Comment thread docs/how_to_guide/06_choosing_inference_method.ipynb Outdated
Comment thread docs/how_to_guide/06_choosing_inference_method.ipynb Outdated
Comment thread docs/how_to_guide/06_choosing_inference_method.ipynb Outdated
Comment thread docs/how_to_guide/06_choosing_inference_method.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
Comment thread docs/how_to_guide/09_sampler_interface.ipynb Outdated
janfb added 9 commits July 27, 2026 16:08
- name the learned quantity for NPE, NLE and NRE, and state that embedding
  networks are trained jointly with the estimator
- define IID observations at first use and link the IID guide from the NLE
  paragraph
- use "sequential (multiround)" consistently, and replace the SNPE_A/SNPE_B
  bullet with a neutral note on which variant each alias resolves to
- trim the sampler-guide intro that duplicated the inference-method guide
- add a sample_with -> posterior class table, so class names appear next to the
  argument that produces them
- replace the uncheckable rejection-sampling precondition with the acceptance
  rate, its 1% warning threshold, and the option of a better proposal
- name concrete diagnostics (R-hat and ESS, evaluate(), effective sample size
  from importance log-weights) instead of "inspect diagnostics"
- explain the VI quality score: PSIS k-hat by default, or an R^2 with "prop"
- note that VI posteriors have no log_prob_batched()
- separate the train()/train_amortized() mode exclusivity from the ELBO note
Follows the sample_with table with the typed dataclass that configures each
posterior class, and notes that the older per-sampler dictionaries plus
mcmc_method / vi_method are deprecated. Links the PosteriorParameters guide.
Makes every criterion in the intro explicitly a sampler criterion, and ties the
repeated-observation case to the fixed-observation and amortized VI sections of
this guide, so the paragraph does not read as inference-method guidance.
- DirectPosterior wraps a trained density estimator and takes no potential_fn,
  so name the four classes that can be built from one instead of "every class"
- mcmc_method and vi_method only warn at non-default values, unlike the
  per-sampler dictionaries which warn whenever passed
- the ArviZ guide shows how to get samples into an InferenceData container
  rather than computing R-hat or ESS, so attribute those to ArviZ itself
FMPE and NPSE estimate the posterior but are not part of the NPE family in
sbi's taxonomy, and their sampling works by integrating an ODE or SDE, so the
latency and sequential-workflow statements about NPE do not carry over. Point
readers at the dedicated guide from the inference-method guide, and from the
sampler guide where the ode/sde choice belongs.
Open with the general context of why sampling differs per method, then
route the reader by which inference method they used, then show how to
set the sampler, and only then expose the potential-function API as the
low-level interface.

Also correct the rejection-sampling acceptance rate claim: the rate is
not returned by RejectionPosterior.sample(), which discards it; the
sub-1% warning is the only user-facing signal.
VI had no guide of its own, so the sampler guide was the only place
documenting train() vs train_amortized(), the vi_method options and
evaluate(). Move that content into its own how-to and link to it from
the sampler guide, the abstraction-levels and PosteriorParameters
guides, and the implemented-methods tutorial.
It was registered in the sampling toctree but missing from the landing
page list.
The dataclass type already determines the posterior class, so passing
sample_with alongside it is superfluous. Present the two layers as
sample_with for the simple case and PosteriorParameters for flexibility
and type checking, and note that FMPE and NPSE still need sample_with
because VectorFieldPosteriorParameters does not encode the integrator.
@janfb
janfb merged commit b4b5d9f into main Jul 30, 2026
20 checks passed
@janfb
janfb deleted the docs/vi-sampler-guidance branch July 30, 2026 09:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve documentation of VIPosterior

2 participants