Sampler configuration

There are various settings in nessai which can be configured. These can be grouped in to general settings and proposal settings. The former controls general aspects of the sampler such as the model being sampler or how many live points are used. The latter affect the proposal process and how new points are drawn.

All of the settings are controlled when creating an instance of FlowSampler. The most important settings to consider when using nessai are the reparameterisations used for the proposals.

General configuration

These are general settings which apply to the whole algorithm and are parsed to NestedSampler. However some of these settings, such as training_frequency which defines how often the proposal method is retrained, will affect the normalising flow used in the proposal class.

class nessai.nestedsampler.NestedSampler(model, nlive=2000, output=None, stopping=0.1, max_iteration=None, checkpointing=True, checkpoint_on_training=False, resume_file=None, seed=None, pool=None, close_pool=True, n_pool=None, plot=True, proposal_plots=False, prior_sampling=False, analytic_priors=False, maximum_uninformed=None, uninformed_proposal=None, uninformed_acceptance_threshold=None, uninformed_proposal_kwargs=None, flow_class=None, flow_config=None, training_frequency=None, train_on_empty=True, cooldown=200, memory=False, reset_weights=False, reset_permutations=False, retrain_acceptance=True, reset_acceptance=False, acceptance_threshold=0.01, **kwargs)

Nested Sampler class. Initialisation arguments:

Parameters

model:obj:nessai.model.Model: User defined model
nliveint, optional: Number of live points.
outputstr: Path for output
stoppingfloat, optional: Stop when remaining samples wouldn’t change logZ estimate by this much.
max_iterationint, optional: Maximum number of iterations to run before force sampler to stop. If stopping criteria is met before max. is reached sampler will stop.
checkpointingbool, optional: Boolean to toggle checkpointing, must be enabled to resume the sampler. If false the sampler is still saved at the end of sampling.
resume_filestr, optional: If specified sampler will be resumed from this file. Still requires correct model.
seedint, optional: seed for the initialisation of the pseudorandom chain
n_poolint, optional: Number of threads to when for creating the multiprocessing pool.
poolobject: User defined multiprocessing pool that will be used when evaluating the likelihood.
close_poolbool: Boolean to indicated if the pool should be closed at the end of the nested sampling loop. If False, the user must manually close the pool.
plotbool (True): Boolean to toggle plotting
proposal_plotsbool (True): Boolean to enable additional plots for the population stage of the sampler. Overwritten by plot.
prior_samplingbool (False): produce nlive samples from the prior.
analytic_priorsbool (False): Boolean that indicates that the new_point method in the model draws directly from the priors meaning rejection sampling is not needed.
maximum_uninformedint (1000): Maximum number of iterations before forcing the sampler to switch to using the proposal method with the flow.
uninformed_proposalnessai.proposal.Proposal: (None): Class to use for initial sampling before training the flow. If None RejectionProposal or AnalyticProposal are used depending if analytic_priors is False or True.
uninformed_acceptance_thresholdfloat (None): Acceptance threshold for initialising sampling, if acceptance falls below this value sampler switches to flow-based proposal. If None then value is set to 10 times acceptance_threshold
uninformed_proposal_kwargsdict, ({}): Dictionary of keyword argument to pass to the class use for the initial sampling when it is initialised.
flow_classnessai.proposal.FlowProposal: Class to use for flow-based proposal method
flow_configdict ({}): Dictionary used to configure instance of nessai.flowmodel.FlowModel, this includes configuring the normalising flow and the training.
training_frequencyint (None): Number of iterations between re-training the flow. If None flow is only re-trained based on other criteria.
train_on_emptybool (True): If true the flow is retrained every time the proposal pool is empty. If false it is only training according to the other criteria.
cooldownint (100): Minimum number of iterations between training. Can be overridden if train_on_empty=True and the pool is empty.
memoryint, False (False): Number of old live points to use in training. If False only the current live points are used.
reset_weightsbool, int, (False): Boolean to toggle resetting the flow weights whenever re-training. If an integer is specified the flow is reset every nth time it is trained.
reset_permutations: bool, int, (False): Boolean to toggle resetting the permutation layers in the flow whenever re-training. If an integer is specified the flow is reset every nth time it is trained.
reset_acceptancebool, (True): If true use mean acceptance of samples produced with current flow as a criteria for retraining
retrain_acceptancebool (False): Force the flow to be reset if the acceptance falls below the acceptance threshold. Requires reset_acceptance=True
acceptance_thresholdfloat (0.01): Threshold to determine if the flow should be retrained, will not retrain if cooldown is not satisfied.
kwargs: Keyword arguments passed to the flow proposal class

Proposal configuration

The proposal configuration includes a variety of settings ranging from the hyper-parameters for the normalising flow to the size of pool used to store new samples. This also includes the reparameterisations which are essential to efficient sampling. All the available settings are listed below and there are dedicated pages that explain how to configure the reparmeterisations and normalising flows.

class nessai.proposal.flowproposal.FlowProposal(model, flow_config=None, output='./', poolsize=None, rescale_parameters=True, latent_prior='truncated_gaussian', constant_volume_mode=True, volume_fraction=0.95, fuzz=1.0, plot='min', fixed_radius=False, drawsize=None, check_acceptance=False, truncate=False, rescale_bounds=[- 1, 1], expansion_fraction=4.0, boundary_inversion=False, inversion_type='split', update_bounds=True, min_radius=False, max_radius=50.0, max_poolsize_scale=10, update_poolsize=True, save_training_data=False, compute_radius_with_all=False, draw_latent_kwargs=None, detect_edges=False, detect_edges_kwargs=None, reparameterisations=None, fallback_reparameterisation=None, use_default_reparameterisations=None, **kwargs)

Object that handles training and proposal points

Parameters

modelnessai.model.Model: User defined model.
flow_configdict, optional: Configuration for training the normalising flow. If None, uses default settings. Defaults to None.
outputstr, optional: Path to output directory.
plot{True, False, ‘all’, ‘min’}, optional: Controls the plotting level: True - all plots; False - no plots; 'all' - all plots and 'min' - 1d plots and loss.
latent_prior{‘truncated_gaussian’, ‘gaussian’, ‘uniform_nsphere’, ‘gaussian’}, optional: Prior distribution in the latent space. Defaults to ‘truncated_gaussian’.
poolsizeint, optional: Size of the proposal pool. Defaults to 10000.
update_poolsizebool, optional: If True the poolsize is updated using the current acceptance of the nested sampler.
max_poolsize_scaleint, optional: Maximum scale for increasing the poolsize. E.g. if this value is 10 and the poolsize is 1000 the maximum number of points in the pool is 10,000.
drawsizeint, optional: Number of points to simultaneously draw when populating the proposal Defaults to 10000
check_acceptancebool, optional: If True the acceptance is computed after populating the pool. This includes computing the likelihood for every point. Default False.
min_radiusfloat, optional: Minimum radius used for population. If not specified not minimum is used.
max_radiusfloat, optional: If a float then this value is used as an upper limit for the computed radius when populating the proposal. If unspecified no upper limit is used.
fixed_radiusfloat, optional: If specified and the chosen latent distribution is compatible, this radius will be used to draw new samples instead of the value computed with the flow.
constant_volume_modebool: If True, then a constant volume is used for the latent contour used to draw new samples. The exact volume can be set using volume_fraction
volume_fractionfloat: Fraction of the total probability to contain with the latent contour when using a constant volume.
compute_radius_with_allbool, optional: If True all the radius of the latent contour is computed using the maximum radius of all the samples used to train the flow.
fuzzfloat, optional: Fuzz-factor applied to the radius. If unspecified no fuzz-factor is applied.
expansion_fractionfloat, optional: Similar to fuzz but instead a scaling factor applied to the radius this specifies a rescaling for volume of the n-ball used to draw samples. This is translated to a value for fuzz.
truncatebool, optional: Truncate proposals using probability compute for worst point. Not recommended.
rescale_parameterslist or bool, optional: If True live points are rescaled to rescale_bounds before training. If an instance of list then must contain names of parameters to rescale. If False no rescaling is applied.
rescale_boundslist, optional: Lower and upper bound to use for rescaling. Defaults to [-1, 1]. See rescale_parameters.
update_boundsbool, optional: If True bounds used for rescaling are updated at the starting of training. If False prior bounds are used.
boundary_inversionbool or list, optional: If True boundary inversion is applied to all bounds. If If an instance of list of parameters names, then inversion only applied to these parameters. If False (default )no inversion is used.
inversion_type{‘split’, ‘duplicate’}: Type of inversion to use. 'split' keeps the number of samples the sample but mirrors half around the bound. 'duplicate' mirrors all the samples at the bound.
detect_edgesbool, optional: If True, when applying the version the option of no inversion is allowed.
detect_edges_kwargsdict, optional: Dictionary of keyword arguments passed to nessai.utils.detect_edge().
reparameterisationsdict, optional: Dictionary for configure more flexible reparameterisations. This ignores any of the other settings related to rescaling. For more details see the documentation.
fallback_reparameterisationNone or str: Name of the reparameterisation to be used for parameters that have not been specified in the reparameterisations dictionary. If None, the NullReparameterisation is used. Reparameterisation should support multiple parameters.
use_default_reparameterisationsbool, optional: If True then reparameterisations will be used even if reparameterisations is None. The exact reparameterisations used will depend on add_default_reparameterisations() which may be overloaded by child classes. If not specified then the value of the attribute use_default_reparameterisations is used.
draw_latent_kwargsdict, optional: Dictionary of kwargs passed to the function for drawing samples in the latent space. See the functions in utils for the possible kwargs.

Other proposals

nessai also includes variations on the main FlowProposal class:

nessai.gw.proposal.GWFlowProposal as version of FlowProposal that includes specific reparameterisations for gravitational-wave inference.
nessai.proposal.augmented.AugmentedFlowProposal this proposal is designed for highly multimodal likelihoods where the standard proposal can break down. It is based around using Augmented Normalising Flows which introduce extra augment dimensions. See the documentation for further details.