From 7ac2248d7c5857bc805f0f8f4ec94322a99d031e Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Thu, 8 Oct 2026 08:29:57 +0100 Subject: [PATCH 1/2] docs: list every search and repair stale search docs and citations - docs/api/searches.rst: add Nautilus, NSS, Drawer and MultiStartAdam / ADABelief / Lion / Prodigy, so all 15 exported searches are listed (autosummary stubs are generated at build time). - docs/cookbooks/search.md: add a Nautilus section between DynestyStatic and LBFGS; say the cookbook covers a selection of searches and link the API reference for the full list. - config/non_linear/README.md, docs/general/configs.md: only GridSearch.yaml lives there; per-search defaults are constructor arguments since #1202. - docs/installation/source.md: requirements.txt files no longer exist; use pip install -e PyAutoFit / -e "PyAutoFit[optional]". - files/citations.{bib,md}, files/citation.tex: drop MultiNest and PyMultiNest, add BlackJAX, optax and Prodigy, add Nautilus to the .md and .tex, use the sqlite2020 key that the .bib defines. Refs #1668 Co-Authored-By: Claude Fable 5.1 --- autofit/config/non_linear/README.md | 11 ++++-- docs/api/searches.rst | 7 ++++ docs/cookbooks/search.md | 35 +++++++++++++++++- docs/general/configs.md | 8 +++- docs/installation/source.md | 22 +++-------- files/citation.tex | 22 +++++++++-- files/citations.bib | 57 +++++++++++++---------------- files/citations.md | 13 ++++--- 8 files changed, 111 insertions(+), 64 deletions(-) diff --git a/autofit/config/non_linear/README.md b/autofit/config/non_linear/README.md index 3b9312061..b60f7f698 100644 --- a/autofit/config/non_linear/README.md +++ b/autofit/config/non_linear/README.md @@ -1,8 +1,11 @@ The `non_linear` folder contains configuration files which customize the default behaviour of non-linear searches in -**PyAutoLens**. +**PyAutoFit**. + +The default settings of each individual search (e.g. `Nautilus`, `Emcee`, `LBFGS`) are not set by configuration files. +They are the default values of the arguments of each search class's constructor, and are changed by passing those +arguments when the search is created. # Files -- `mcmc.yaml`: Settings default behaviour of MCMC non-linear searches (e.g. Emcee). -- `nest.yaml`: Settings default behaviour of nested sampler non-linear searches (e.g. Dynesty). -- `mle.yaml`: Settings default behaviour of maximum likelihood estimator (mle) searches (e.g. BFGS). +- `GridSearch.yaml`: Settings default behaviour of a parallelized grid search of non-linear searches (e.g. the + number of cores and the default step size). diff --git a/docs/api/searches.rst b/docs/api/searches.rst index d6cd8fb6d..60e3840ba 100644 --- a/docs/api/searches.rst +++ b/docs/api/searches.rst @@ -24,8 +24,10 @@ Nested Samplers :template: custom-class-template.rst :recursive: + Nautilus DynestyDynamic DynestyStatic + NSS MCMC ---- @@ -54,6 +56,11 @@ Maximum Likelihood Estimators BFGS LBFGS + MultiStartAdam + MultiStartADABelief + MultiStartLion + MultiStartProdigy + Drawer There are also a number of tools which are used to customize the behaviour of non-linear searches in **PyAutoFit**, including directory output structure, parameter sample initialization and MCMC auto correlation analysis. diff --git a/docs/cookbooks/search.md b/docs/cookbooks/search.md index ec011007f..8be5b8743 100644 --- a/docs/cookbooks/search.md +++ b/docs/cookbooks/search.md @@ -17,14 +17,18 @@ It first covers standard options available for all non-linear searches: - **Plots**: Perform non-linear search specific visualization using their in-built visualization tools. - **Start Point**: Manually specify the start point of a non-linear search, or sample a specific region of parameter space. -It then provides example code for using every search: +It then provides example code for a selection of the available searches: - **Emcee (MCMC)**: The Emcee ensemble sampler MCMC. - **Zeus (MCMC)**: The Zeus ensemble sampler MCMC. - **DynestyDynamic (Nested Sampling)**: The Dynesty dynamic nested sampler. - **DynestyStatic (Nested Sampling)**: The Dynesty static nested sampler. +- **Nautilus (Nested Sampling)**: The Nautilus importance nested sampler. - **LBFGS**: The L-BFGS scipy optimization. +The full list of searches, including the JAX-based BlackJAXNUTS, SMC, NSS and MultiStart optimizers, is given in the +[non-linear search API reference](https://pyautofit.readthedocs.io/en/latest/api/searches.html). + ## Example Fit An example of how to use a `search` to fit a model to data is given in other example scripts, but is shown below @@ -358,6 +362,35 @@ search = af.DynestyStatic( ) ``` +## Nautilus (Nested Sampling) + +The Nautilus sampler is a nested sampling algorithm which uses neural-network regression to build its bounds, +combined with importance nested sampling. It is the search used in most of the **PyAutoFit** workspace examples. + +Information about Nautilus can be found at the following links: + +- +- + +```python +search = af.Nautilus( + n_live=100, + n_update=None, + enlarge_per_dim=1.1, + n_points_min=None, + split_threshold=100, + n_networks=4, + n_batch=100, + n_like_new_bound=None, + vectorized=False, + seed=None, + f_live=0.01, + n_shell=1, + n_eff=500, + discard_exploration=False, +) +``` + ## LBFGS The LBFGS sampler is a Local Optimization algorithm. It is a Python implementation of the scipy.optimize.lbfgs diff --git a/docs/general/configs.md b/docs/general/configs.md index 82d63893f..682fb63d6 100644 --- a/docs/general/configs.md +++ b/docs/general/configs.md @@ -1,7 +1,11 @@ # Configs -**PyAutoFit** uses a number of configuration files that customize the default behaviour of the non-linear searches, -visualization and other aspects of **PyAutoFit**. +**PyAutoFit** uses a number of configuration files that customize the default behaviour of visualization, output, +priors, the grid search and other aspects of **PyAutoFit**. + +The default settings of each non-linear search are not set by configuration files: they are the default values of +the arguments of each search class (e.g. `af.Nautilus`, `af.Emcee`), and are changed by passing those arguments when +the search is created. Descriptions of every configuration file and their input parameters are provided in the `README.md` in the [config directory of the workspace](https://github.com/PyAutoLabs/autofit_workspace/tree/main/config) diff --git a/docs/installation/source.md b/docs/installation/source.md index 359998a8b..b52fe57ab 100644 --- a/docs/installation/source.md +++ b/docs/installation/source.md @@ -12,29 +12,19 @@ First, clone (or fork) the **PyAutoFit** GitHub repository: git clone https://github.com/PyAutoLabs/PyAutoFit ``` -Next, install the **PyAutoFit** dependencies via pip: +Next, install **PyAutoFit** and its dependencies in editable mode via pip: ```bash -pip install -r PyAutoFit/requirements.txt +pip install -e PyAutoFit ``` -If you are using a `conda` environment, add the source repository as follows: +An editable install means changes you make to the source code are used straight away, so there is no need to add +the repository to your `PYTHONPATH`. -```bash -conda-develop PyAutoFit -``` - -Alternatively, if you are using a Python environment include the **PyAutoFit** source repository in your PYTHONPATH -(noting that you must replace the text `/path/to` with the path to the **PyAutoFit** directory on your computer): - -```bash -export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoFit -``` - -For unit tests to pass you will also need the following optional requirements: +For unit tests to pass you will also need the optional requirements: ```bash -pip install -r PyAutoFit/optional_requirements.txt +pip install -e "PyAutoFit[optional]" ``` Finally, check the **PyAutoFit** unit tests run and pass (you may need to install pytest via `pip install pytest`): diff --git a/files/citation.tex b/files/citation.tex index c2dcd148c..a8649ce15 100644 --- a/files/citation.tex +++ b/files/citation.tex @@ -1,6 +1,6 @@ In the main body of the paper: -We use the probabilistic programming language \textt{PyAutoFit}\footnote{https://github.com/rhayes777/PyAutoFit} \citep{pyautofit} to... +We use the probabilistic programming language \textt{PyAutoFit}\footnote{https://github.com/PyAutoLabs/PyAutoFit} \citep{pyautofit} to... At the end of the paper (delete as appropriate, see https://pyautofit.readthedocs.io/en/latest/general/citations.html): @@ -10,6 +10,10 @@ \section*{Software Citations} \begin{itemize} +\item +\href{https://github.com/blackjax-devs/blackjax}{\textt{BlackJAX}} +\citep{blackjax} + \item \href{https://github.com/dfm/corner.py}{\textt{corner.py}} \citep{corner} @@ -26,10 +30,22 @@ \section*{Software Citations} \href{https://github.com/matplotlib/matplotlib}{\textt{matplotlib}} \citep{matplotlib} +\item +\href{https://github.com/johannesulf/nautilus}{\textt{Nautilus}} +\citep{nautilus} + \item \href{https://github.com/numpy/numpy}{\textt{NumPy}} \citep{numpy} +\item +\href{https://github.com/google-deepmind/optax}{\textt{optax}} +\citep{optax} + +\item +\href{https://github.com/konstmish/prodigy}{\textt{Prodigy}} +\citep{prodigy} + \item \href{https://www.python.org/}{\textt{Python}} \citep{python} @@ -39,8 +55,8 @@ \section*{Software Citations} \citep{scipy} \item -\href{https://www.sqlite.org/index.html} -\citep{sqlite} +\href{https://www.sqlite.org/index.html}{\textt{SQLite}} +\citep{sqlite2020} \item \href{https://github.com/minaskar/zeus}{\textt{zeus}} diff --git a/files/citations.bib b/files/citations.bib index d7945bc08..e5aad5af6 100644 --- a/files/citations.bib +++ b/files/citations.bib @@ -1,3 +1,11 @@ +@article{blackjax, +author = {Cabezas, Alberto and Corenflos, Adrien and Lao, Junpeng and Louf, R{\'e}mi and others}, +title = {{BlackJAX}: Composable {B}ayesian inference in {JAX}}, +journal = {arXiv e-prints}, +eprint = {2402.10797}, +archivePrefix = {arXiv}, +year = {2024} +} @article{corner, doi = {10.21105/joss.00024}, url = {https://doi.org/10.21105/joss.00024}, @@ -58,24 +66,6 @@ @article{matplotlib doi = {10.1109/MCSE.2007.55}, year = 2007 } -@article{multinest, -abstract = {We present further development and the first public release of our multimodal nested sampling algorithm, called MultiNest. This Bayesian inference tool calculates the evidence, with an associated error estimate, and produces posterior samples from distributions that may contain multiple modes and pronounced (curving) degeneracies in high dimensions. The developments presented here lead to further substantial improvements in sampling efficiency and robustness, as compared to the original algorithm presented in Feroz and Hobson, which itself significantly outperformed existing Markov chain Monte Carlo techniques in a wide range of astrophysical inference problems. The accuracy and economy of the MultiNest algorithm are demonstrated by application to two toy problems and to a cosmological inference problem focusing on the extension of the vanilla $\Lambda$ cold dark matter model to include spatial curvature and a varying equation of state for dark energy. The MultiNest software, which is fully parallelized using MPI and includes an interface to CosmoMC, is available at http://www.mrao.cam.ac.uk/software/multinest/. It will also be released as part of the SuperBayeS package, for the analysis of supersymmetric theories of particle physics, at http://www.superbayes.org. {\textcopyright} 2009 RAS.}, -archivePrefix = {arXiv}, -arxivId = {0809.3437}, -author = {Feroz, F. and Hobson, M. P. and Bridges, M.}, -doi = {10.1111/j.1365-2966.2009.14548.x}, -eprint = {0809.3437}, -isbn = {0035-8711}, -issn = {00358711}, -journal = {Monthly Notices of the Royal Astronomical Society}, -keywords = {Methods: Data analysis,Methods: Statistical}, -number = {4}, -pages = {1601--1614}, -pmid = {29176}, -title = {{MultiNest: An efficient and robust Bayesian inference tool for cosmology and particle physics}}, -volume = {398}, -year = {2009} -} @ARTICLE{nautilus, author = {{Lange}, Johannes U.}, title = "{NAUTILUS: boosting Bayesian importance nested sampling with deep learning}", @@ -102,21 +92,24 @@ @ARTICLE{numpy volume={13}, number={2}, pages={22-30}} -@article{pymultinest, -abstract = {Context. Aims. Active galactic nuclei are known to have complex X-ray spectra that depend on both the properties of the accreting super-massive black hole (e.g. mass, accretion rate) and the distribution of obscuring material in its vicinity (i.e. the "torus"). Often however, simple and even unphysical models are adopted to represent the X-ray spectra of AGN, which do not capture the complexity and diversity of the observations. In the case of blank field surveys in particular, this should have an impact on e.g. the determination of the AGN luminosity function, the inferred accretion history of the Universe and also on our understanding of the relation between AGN and their host galaxies. Methods. We develop a Bayesian framework for model comparison and parameter estimation of X-ray spectra. We take into account uncertainties associated with both the Poisson nature of X-ray data and the determination of source redshift using photometric methods. We also demonstrate how Bayesian model comparison can be used to select among ten different physically motivated X-ray spectral models the one that provides a better representation of the observations. This methodology is applied to X-ray AGN in the 4 Ms Chandra Deep Field South. Results. For the {\~{}}350 AGN in that field, our analysis identifies four components needed to represent the diversity of the observed X-ray spectra: (1) an intrinsic power law; (2) a cold obscurer which reprocesses the radiation due to photo-electric absorption, Compton scattering and Fe-K fluorescence; (3) an unabsorbed power law associated with Thomson scattering off ionised clouds; and (4) Compton reflection, most noticeable from a stronger-than-expected Fe-K line. Simpler models, such as a photo-electrically absorbed power law with a Thomson scattering component, are ruled out with decisive evidence (B {\textgreater} 100). We also find that ignoring the Thomson scattering component results in underestimation of the inferred column density, NH, of the obscurer. Regarding the geometry of the obscurer, there is strong evidence against both a completely closed (e.g. sphere), or entirely open (e.g. blob of material along the line of sight), toroidal geometry in favour of an intermediate case. Conclusions. Despite the use of low-count spectra, our methodology is able to draw strong inferences on the geometry of the torus. Simpler models are ruled out in favour of a geometrically extended structure with significant Compton scattering. We confirm the presence of a soft component, possibly associated with Thomson scattering off ionised clouds in the opening two of the torus. The additional Compton reflection required by data over that predicted by toroidal geometry models, may be a sign of a density gradient in the torus or reflection off the accretion disk. Finally, we release a catalogue of AGN in the CDFS with estimated parameters such as the accretion luminosity in the 2-10 keV band and the column density, NH, of the obscurer. {\textcopyright} ESO, 2014.}, +@software{optax, +author = {{DeepMind} and Babuschkin, Igor and Baumli, Kate and Bell, Alison and Bhupatiraju, Surya and Bruce, Jake and Buchlovsky, Peter and Budden, David and Cai, Trevor and Clark, Aidan and Danihelka, Ivo and Fantacci, Claudio and Godwin, Jonathan and Jones, Chris and Hemsley, Ross and Hennigan, Tom and Hessel, Matteo and Hou, Shaobo and Kapturowski, Steven and others}, +title = {The {D}eep{M}ind {JAX} Ecosystem}, +url = {http://github.com/google-deepmind}, +year = {2020} +} +@inproceedings{prodigy, +author = {Mishchenko, Konstantin and Defazio, Aaron}, +title = {{Prodigy: An Expeditiously Adaptive Parameter-Free Learner}}, +booktitle = {Proceedings of the 41st International Conference on Machine Learning}, +series = {Proceedings of Machine Learning Research}, +volume = {235}, +pages = {35779--35804}, +publisher = {PMLR}, +url = {https://proceedings.mlr.press/v235/mishchenko24a.html}, +eprint = {2306.06101}, archivePrefix = {arXiv}, -arxivId = {1402.0004}, -author = {Buchner, J. and Georgakakis, A. and Nandra, K. and Hsu, L. and Rangel, C. and Brightman, M. and Merloni, A. and Salvato, M. and Donley, J. and Kocevski, D.}, -doi = {10.1051/0004-6361/201322971}, -eprint = {1402.0004}, -file = {:home/jammy/Documents/Papers/Stats/ButchnerPyMultiNest.pdf:pdf}, -issn = {14320746}, -journal = {Astronomy and Astrophysics}, -keywords = {Accretion, accretion disks,galaxies: high-redshift,galaxies: nuclei,Methods: data analysis,Methods: statistical,X-rays: galaxies}, -pages = {A125}, -title = {{X-ray spectral modelling of the AGN obscuring region in the CDFS: Bayesian model selection and catalogue}}, -volume = {564}, -year = {2014} +year = {2024} } @article{pyautofit, doi = {10.21105/joss.02550}, diff --git a/files/citations.md b/files/citations.md index 629873b0e..a87157331 100644 --- a/files/citations.md +++ b/files/citations.md @@ -1,4 +1,4 @@ -I**nesrt in the main body of the paper:** +**Insert in the main body of the paper:** We use the probabilistic programming language `PyAutoFit` https://github.com/PyAutoLabs/PyAutoFit) [@pyautofit] to... @@ -8,16 +8,17 @@ We use the probabilistic programming language `PyAutoFit` https://github.com/PyA This work uses the following software packages: +- `BlackJAX` https://github.com/blackjax-devs/blackjax [@blackjax] - `corner.py` https://github.com/dfm/corner.py [@corner] - `dynesty` https://github.com/joshspeagle/dynesty [@dynesty] - `emcee` https://github.com/dfm/emcee [@emcee] - `matplotlib` https://github.com/matplotlib/matplotlib [@matplotlib] +- `Nautilus` https://github.com/johannesulf/nautilus [@nautilus] - `NumPy` https://github.com/numpy/numpy [@numpy] +- `optax` https://github.com/google-deepmind/optax [@optax] +- `Prodigy` https://github.com/konstmish/prodigy [@prodigy] - `PyAutoFit` https://github.com/PyAutoLabs/PyAutoFit [@pyautofit] -- `PyMultiNest` https://github.com/JohannesBuchner/PyMultiNest [@multinest] [@pymultinest] - - `Python` https://www.python.org/ [@python] - `Scipy` https://github.com/scipy/scipy [@scipy] -- `SQLite` https://www.sqlite.org/index.html [@sqlite] - -- `Zeus` https://github.com/minaskar/zeus [@zeus1] [@zeus2] \ No newline at end of file +- `SQLite` https://www.sqlite.org/index.html [@sqlite2020] +- `Zeus` https://github.com/minaskar/zeus [@zeus1] [@zeus2] From e2342aeb867aec9e20884dc859b0694da0619e49 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Thu, 8 Oct 2026 08:57:54 +0100 Subject: [PATCH 2/2] docs: blank line before the NSS roadmap bullet list so Sphinx renders the docstring Listing NSS in docs/api/searches.rst made the docs build render this docstring, where docutils reported 'Unexpected indentation'. Co-Authored-By: Claude Fable 5.1 --- autofit/non_linear/search/nest/nss/search.py | 1 + 1 file changed, 1 insertion(+) diff --git a/autofit/non_linear/search/nest/nss/search.py b/autofit/non_linear/search/nest/nss/search.py index e086096fd..7c358d696 100644 --- a/autofit/non_linear/search/nest/nss/search.py +++ b/autofit/non_linear/search/nest/nss/search.py @@ -232,6 +232,7 @@ def __init__( ``model.log_prior_list_from_vector`` traceable. Phases 1-3 of the ``nss_first_class_sampler`` roadmap are live: + - Phase 1: the wrapper itself (this class). - Phase 2: checkpoint/resume via ``checkpoint_interval`` — a ``nss_checkpoint.pkl`` is written to ``paths.search_internal_path``