From c05c03b4d8be5c5b6bc857b8eab67d88a8a07c38 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Thu, 29 Oct 2026 08:53:58 +0100 Subject: [PATCH] DOC: add software and sampling method citations --- CHANGELOG.md | 2 + CONTRIBUTING.md | 6 ++- docs/citation.rst | 50 +++++++++++++++++-- .../running_inference/prebuilt_samplers.rst | 24 ++++++++- 4 files changed, 76 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db821c18..e2467592 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- Software archive DOIs and algorithm references for SMC variants and flow + preconditioning. - Documentation sidebar links to sequince-density and sequince-examples under Related Packages. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da96370a..252d132c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -296,7 +296,7 @@ should also follow this format and describe the final change. ## Pull requests and review For each pull request with user-visible changes, update -[CHANGELOG.md](CHANGELOG.md) under `Unreleased` in the same pull request. Follow +[CHANGELOG.md][changelog] under `Unreleased` in the same pull request. Follow the entry categories and guidance in the releases section below. Push your branch and open a pull request targeting `sequince-dev/sequince:main`: @@ -323,7 +323,7 @@ needed. ## Releases -Maintain [CHANGELOG.md](CHANGELOG.md) using +Maintain [CHANGELOG.md][changelog] using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Add user-visible changes under `Unreleased`, grouped as `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, or `Security`; omit empty groups. Describe the effect on users, @@ -349,3 +349,5 @@ built distribution in a clean environment. Publishing a GitHub release triggers the PyPI workflow in `.github/workflows/publish.yml`. Check that the workflow completes successfully. Published distributions cannot be overwritten, so verify the tag and artifacts before publishing. + +[changelog]: https://github.com/sequince-dev/sequince/blob/main/CHANGELOG.md diff --git a/docs/citation.rst b/docs/citation.rst index 30bcefbd..2c1a4558 100644 --- a/docs/citation.rst +++ b/docs/citation.rst @@ -1,8 +1,52 @@ Citing sequince =============== -If you use ``sequince`` in your work, please cite: +Software citations +------------------ -.. TODO: add citation details (e.g. paper reference and/or Zenodo DOI, BibTeX). +If you use ``sequince``, please cite the Zenodo archive: -*Citation details coming soon.* +Williams, M. J., and Chapman-Bird, C. (2026). *sequince-dev/sequince*. +Zenodo. `doi:10.5281/zenodo.23596103 `_. + +If you also use ``sequince-density``, please cite its Zenodo archive: + +Williams, M. J. (2026). *sequince-dev/sequince-density*. +Zenodo. `doi:10.5281/zenodo.23687687 `_. + +Ideally, cite the Zenodo record for the exact version of each package used +in your analysis. Select that version on Zenodo and export its citation +in your preferred format. + +Algorithm references +-------------------- + +Please also cite the methods used in your analysis. These references credit +algorithm development; they are separate from the software citation. + +* **SMC samplers:** Del Moral, P., Doucet, A., and Jasra, A. (2006). + *Sequential Monte Carlo samplers*. Journal of the Royal Statistical Society: + Series B, 68(3), 411–436. + `doi:10.1111/j.1467-9868.2006.00553.x `_. +* **Persistent sampling:** Karamanis, M., and Seljak, U. (2025). + *Persistent sampling: enhancing the efficiency of sequential Monte Carlo*. + Statistics and Computing, 35, 144. + `doi:10.1007/s11222-025-10682-y `_. +* **Waste-free SMC:** Dau, H.-D., and Chopin, N. (2022). + *Waste-free sequential Monte Carlo*. Journal of the Royal Statistical Society: + Series B, 84(1), 114–148. + `doi:10.1111/rssb.12475 `_. +* **Nested sampling via SMC (NS-SMC):** Salomone, R., South, L. F., + Drovandi, C., Kroese, D. P., and Johansen, A. M. (2025). + *Unbiased and consistent nested sampling via sequential Monte Carlo*. + Journal of the Royal Statistical Society Series B: Statistical Methodology, + 87(4), 1221–1238. + `doi:10.1093/jrsssb/qkaf015 `_. +* **Flow-preconditioned SMC:** Karamanis, M., Beutler, F., Peacock, J. A., + Nabergoj, D., and Seljak, U. (2022). + *Accelerating astronomical and cosmological inference with Preconditioned + Monte Carlo*. + `doi:10.1093/mnras/stac2272 `_. + +For mutation backends, density estimators, and flow architectures, also follow +the citation guidance of the packages and methods used. diff --git a/docs/user_guide/running_inference/prebuilt_samplers.rst b/docs/user_guide/running_inference/prebuilt_samplers.rst index 71935e4b..f2f2abae 100644 --- a/docs/user_guide/running_inference/prebuilt_samplers.rst +++ b/docs/user_guide/running_inference/prebuilt_samplers.rst @@ -13,7 +13,9 @@ Standard Bayesian SMC particle population through a sequence of tempered distributions, combining weighting, resampling, and mutation. It uses adaptive temperatures by default; ``adaptive=False`` with ``num_steps`` selects a fixed temperature schedule. -The usual posterior endpoint is ``max_beta=1.0``. +The usual posterior endpoint is ``max_beta=1.0``. For the SMC sampler +framework, see `Del Moral, Doucet, and Jasra (2006) +`_. This is the helper used in the :ref:`quick start `. See :doc:`smc_configuration` for configuration and manual pipeline assembly. @@ -21,6 +23,9 @@ This is the helper used in the :ref:`quick start `. See Persistent Bayesian SMC ----------------------- +Persistent sampling was introduced by `Karamanis and Seljak (2025) +`_. + :func:`~sequince.prebuilt_samplers.make_persistent_bayesian_smc` retains an archive of previous particle batches and reweights that archive as the temperature changes. ``n_particles`` sets the active batch size; @@ -35,6 +40,12 @@ Set ``resample_at_end=False`` to return the complete weighted archive instead. Nested-sampling SMC ------------------- +Nested sampling via SMC (NS-SMC) follows the framework of +`Salomone et al. (2025) `_. +The paper distinguishes fixed-threshold NS-SMC from adaptive NS-SMC (ANS-SMC). +The helper uses adaptive thresholds by default; these do not inherit the +fixed-schedule unbiasedness guarantee. + :func:`~sequince.prebuilt_samplers.make_nested_sampling_smc` raises a likelihood threshold and explores the remaining constrained prior. It accumulates evidence over the discarded likelihood shells and the final @@ -53,3 +64,14 @@ completed run and ``store_shell_particles=True`` (the default). See All three helpers expose mutation, resampling, and particle-transform options; see :doc:`../sampling_options/index` and their API references for supported settings. For standalone MCMC, see :doc:`../advanced_workflows/mcmc_sampler`. + +Waste-free SMC +-------------- + +Waste-free SMC, introduced by `Dau and Chopin (2022) +`_, retains intermediate MCMC states within +each stage. Assemble it in a custom pipeline with +:class:`~sequince.steps.waste_free.WasteFreeResampleMove`; see the +`worked tutorial `_. +Persistent sampling instead reuses populations across stages. +Full method references are collected in :doc:`../../citation`.