Merge pull request #110 from Joshuaalbert/develop

Develop

README.md

@@ -2,7 +2,6 @@
 [![PyPI](https://badge.fury.io/py/jaxns.svg)](https://badge.fury.io/py/jaxns)
 [![Documentation Status](https://readthedocs.org/projects/jaxns/badge/?version=latest)](https://jaxns.readthedocs.io/en/latest/?badge=latest)
 
-
 Main
 Status: ![Workflow name](https://github.com/JoshuaAlbert/jaxns/actions/workflows/unittests.yml/badge.svg?branch=main)
 
@@ -83,13 +82,34 @@ If you're unfamiliar, take a quick tour of JAX (https://jax.readthedocs.io/en/la
 
 JAXNS is really fast because it uses JAX.
 JAXNS is much faster than PolyChord, MultiNEST, and dynesty, typically achieving two to three orders of magnitude
-improvement in speed on cheap likelihood evaluations.
-This is shown in (https://arxiv.org/abs/2012.15286). With regards to how efficiently JAXNS used likelihood evaluations,
-JAXNS prizes exactness over efficiency, however since it employs an adaptive strategy, users can control efficiency by
-controlling some precision parameters.
+improvement in run time, for models with cheap likelihood evaluations.
+This is shown in (https://arxiv.org/abs/2012.15286). 
+
+Recently JAXNS has implemented Phantom-Powered Nested Sampling, which significantly reduces the number of required 
+likelihood evaluations. This is shown in (https://arxiv.org/abs/). 
+
+# Note on performance with parallelisation
+
+__Note, that this is an experimental feature.__
+
+If you set `num_parallel_workers > 1` you will use `jax.pmap` under the hood for parallelisation.
+This is a very powerful feature, but it is important to understand how it works.
+It runs identical copies of the nested sampling algorithm on multiple devices.
+There is a two-part stopping condition.
+First, each copy goes until the user defined stopping condition is met __per device__.
+Then, it performs an all-gather and finds at the highest likelihood contour among all copies, and continues all copies
+hit this likelihood contour.
+This ensures consistency of depth across all copies.
+We then merge the copies and compute the final results.
+
+The algorithm is fairly memory bound, so running parallelisation over multiple CPUs on the same machine may not yield
+the expected speed up, and depends how expensive the likelihood evaluations are. Running over separate physical devices 
+is the best way to achieve speed up.
 
 # Change Log
 
+18 Dec, 2023 -- JAXNS 2.3.1 released. Paper open science release. Default parameters from paper.
+
 11 Dec, 2023 -- JAXNS 2.3.0 released. Released of Phantom-Powered Nested Sampling algorithm.
 
 5 Oct, 2023 -- JAXNS 2.2.6 released. Minor update to evidence maximisation.
@@ -139,7 +159,6 @@ released.
 
 1 January, 2021 -- Paper submitted
 
-
 ## Star History
 
 <a href="https://star-history.com/#joshuaalbert/jaxns&Date">

docs/conf.py

@@ -14,7 +14,7 @@
 project = "jaxns"
 copyright = "2022, Joshua Albert"
 author = "Joshua Albert"
-release = "2.2.6"
+release = "2.3.1"
 
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -34,6 +34,13 @@ Our mission is to make nested sampling faster, easier, and more powerful.
 
    examples/*
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Papers
+   :glob:
+
+   papers/*
+
 
 Indices and tables
 ==================

docs/papers/phantom-powered-nested-sampling/figures/sample_tree_linear.pdf_tex

@@ -0,0 +1,67 @@
+%% Creator: Inkscape inkscape 0.92.5, www.inkscape.org
+%% PDF/EPS/PS + LaTeX output extension by Johan Engelen, 2010
+%% Accompanies image file 'sample_tree_linear.pdf' (pdf, eps, ps)
+%%
+%% To include the image in your LaTeX document, write
+%%   \input{<filename>.pdf_tex}
+%%  instead of
+%%   \includegraphics{<filename>.pdf}
+%% To scale the image, write
+%%   \def\svgwidth{<desired width>}
+%%   \input{<filename>.pdf_tex}
+%%  instead of
+%%   \includegraphics[width=<desired width>]{<filename>.pdf}
+%%
+%% Images with a different path to the parent latex file can
+%% be accessed with the `import' package (which may need to be
+%% installed) using
+%%   \usepackage{import}
+%% in the preamble, and then including the image with
+%%   \import{<path to file>}{<filename>.pdf_tex}
+%% Alternatively, one can specify
+%%   \graphicspath{{<path to file>/}}
+%% 
+%% For more information, please see info/svg-inkscape on CTAN:
+%%   http://tug.ctan.org/tex-archive/info/svg-inkscape
+%%
+\begingroup%
+  \makeatletter%
+  \providecommand\color[2][]{%
+    \errmessage{(Inkscape) Color is used for the text in Inkscape, but the package 'color.sty' is not loaded}%
+    \renewcommand\color[2][]{}%
+  }%
+  \providecommand\transparent[1]{%
+    \errmessage{(Inkscape) Transparency is used (non-zero) for the text in Inkscape, but the package 'transparent.sty' is not loaded}%
+    \renewcommand\transparent[1]{}%
+  }%
+  \providecommand\rotatebox[2]{#2}%
+  \newcommand*\fsize{\dimexpr\f@size pt\relax}%
+  \newcommand*\lineheight[1]{\fontsize{\fsize}{#1\fsize}\selectfont}%
+  \ifx\svgwidth\undefined%
+    \setlength{\unitlength}{213.99551197bp}%
+    \ifx\svgscale\undefined%
+      \relax%
+    \else%
+      \setlength{\unitlength}{\unitlength * \real{\svgscale}}%
+    \fi%
+  \else%
+    \setlength{\unitlength}{\svgwidth}%
+  \fi%
+  \global\let\svgwidth\undefined%
+  \global\let\svgscale\undefined%
+  \makeatother%
+  \begin{picture}(1,0.26620532)%
+    \lineheight{1}%
+    \setlength\tabcolsep{0pt}%
+    \put(0,0){\includegraphics[width=\unitlength,page=1]{sample_tree_linear.pdf}}%
+    \put(-0.00424403,0.1670851){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}root\end{tabular}}}}%
+    \put(0,0){\includegraphics[width=\unitlength,page=2]{sample_tree_linear.pdf}}%
+    \put(0.11028603,0.05005155){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=1$\end{tabular}}}}%
+    \put(0.26799967,0.05067752){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=3$\end{tabular}}}}%
+    \put(0.44198532,0.05380668){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=2$\end{tabular}}}}%
+    \put(0.50081493,0.00874574){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=4$\end{tabular}}}}%
+    \put(0.5996988,0.05192917){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=3$\end{tabular}}}}%
+    \put(0.72361664,0.00686802){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=2$\end{tabular}}}}%
+    \put(0.83001067,0.05505832){\color[rgb]{0,0,0}\makebox(0,0)[lt]{\lineheight{1.25}\smash{\begin{tabular}[t]{l}$m=1$\end{tabular}}}}%
+  \end{picture}%
+\endgroup%