Importance nested sampler
In Williams et al. 2023, we proposed importance nested sampling with normalising flows and called the algorithm i-nessai.
The algorithm described there is available in nessai
alongside the standard algorithm.
Important
The API for the importance nested sampler is still under-development and may change between minor versions.
Basic usage
The importance nested sampler is implemented in ImportanceNestedSampler
and, just like standard nessai, it can be run through the FlowSampler
class.
To do so, simply set importance_nested_sampler=True
when creating the instance of FlowSampler
.
The sampler is then run using the nessai.flowsampler.FlowSampler.run()
, e.g.
from nessai.flowsampler import FlowSampler
sampler = FlowSampler(
GaussianModel(),
output="output/",
nlive=5000,
importance_nested_sampler=True,
)
sampler.run()
Important
The importance nested sampler requires the user to define the methods to_unit_hypercube
and from_unit_hypercube
in the model class,
see the examples linked below.
Configuration
All keyword arguments passed to FlowSampler
will in turn be passed to either
ImportanceNestedSampler
or ImportanceFlowProposal
.
We now highlight some key settings, for a complete list see the documentation for the two classes,
nlive
: more complex problems will often need largernlive
,threshold_kwargs
: dictionary of keyword arguments for determining the likelihood threshold, the most important isq
(\(\rho\) in the paper),reparameterisation
: either'logit'
orNone
, the former should be used in most cases, unless the flow has the domain on \([0, 1]^n\),flow_config
: identical to the standard sampler, see Normalising flows configuration for details,reset_flow
: reset the flow before training every ith iteration,
Stopping criterion
By default, the stopping criterion is the log-ratio of the evidence above the likelihood threshold and the current evidence, called ratio
in the code.
The default tolerance is tolerance=0.0
and should be suitable for most applications.
Logging
By default the sampler will log every iteration and the log will look something like this:
07-01 08:46 nessai.samplers.importancesampler INFO : Removing 1830/3000 samples to train next proposal
07-01 08:46 nessai.samplers.importancesampler INFO : Log-likelihood threshold: -487.90392013926345
07-01 08:46 nessai.samplers.importancesampler INFO : Training next proposal with 1170 samples
07-01 08:46 nessai.samplers.importancesampler INFO : Drawing 2000 samples from the new proposal
07-01 08:46 nessai.samplers.importancesampler INFO : Stopping criteria (['ratio']): [0.638027881338866] - Tolerance: [0.0]
07-01 08:46 nessai.samplers.importancesampler INFO : Update 1 - log Z: -5.804 +/- 0.089 ESS: 123.7 logL min: -3874.530 logL median: -96.682 logL max: -0.015
From top to bottom this shows:
the number of samples discarded to train the next proposal (flow),
the corresponding log-likelihood threshold,
the start of the training stage with n samples,
the number of samples being drawn from the new proposal,
the current values of all stopping criteria and the corresponding tolerance,
a summary of statistics at the end of the current iteration, this shows:
the log-evidence,
the effective sample size of the posterior,
the minimum, median and maximum log-likelihood of the current set of live samples.
Output
The importance nested sampler returns:
a result file, by default
result.h5
,samples
contains the final samples drawn from meta-proposal,log_evidence
is the final estimate of the log-evidence,
a state plot (
state.png
), this is similar to the state plot for the standard sampler,a trace plot (
trace.png
), this is similar to the trace plot from the standard sampler but plots the ratio of the prior and the meta-proposal on the x-axis,a levels plot (
levels.png
), this shows the log-likelihood distribution for each proposal.
Examples
For basic examples, see the examples directory.
Gravitational-wave inference
The importance nested sampler is not currently supported in bilby
but will be in a future release.