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 larger nlive,

  • threshold_kwargs: dictionary of keyword arguments for determining the likelihood threshold, the most important is q (\(\rho\) in the paper),

  • reparameterisation: either 'logit' or None, 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.