nessai.nestedsampler

Functions and objects related to the main nested sampling algorithm.

Module Contents

Classes

NestedSampler

Nested Sampler class.

Attributes

logger

nessai.nestedsampler.logger

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

property log_evidence(self)

property information(self)

property likelihood_calls(self)

property likelihood_evaluation_time(self)

property proposal_population_time(self)

property acceptance(self)

property current_sampling_time(self)

property last_updated(self)

Last time the normalising flow was retrained

property mean_acceptance(self)

Mean acceptance of the last nlive // 10 points

configure_max_iteration(self, max_iteration)

Configure the maximum iteration.

If None then no maximum is set.

configure_training_frequency(self, training_frequency)

Configure the training frequency.

If None, ‘inf’ or ‘None’ flow will only train when empty.

configure_uninformed_proposal(self, uninformed_proposal, analytic_priors, maximum_uninformed, uninformed_acceptance_threshold, **kwargs)

Setup the uninformed proposal method (is NOT trained)

Parameters

uninformed_proposalNone or obj

Class to use for uninformed proposal

analytic_priorsbool

If True AnalyticProposal is used to directly sample from the priors rather than using rejection sampling.

maximum_uninformed{False, None, int, float}

Maximum number of iterations before switching to FlowProposal. If None, two times nlive is used. If False uninformed sampling is not used.

uninformed_acceptance_thresholdfloat or None:

Threshold to use for uninformed proposal, once reached proposal method will switch. If None acceptance_threshold is used if greater than 0.1 else 10 x acceptance_threshold is used.

kwargs

Kwargs are passed to init method for uninformed proposal class

configure_flow_proposal(self, flow_class, flow_config, proposal_plots, **kwargs)

Set up the flow-based proposal method

Parameters

flow_classNone or obj or str

Class to use for proposal. If None FlowProposal is used.

flow_configdict

Configuration dictionary passed to the class.

proposal_plotsbool or str

Configuration of plotting in proposal class.

**kwargs

Kwargs passed to init function.

setup_output(self, output, resume_file=None)

Set up the output folder

Parameters

outputstr

Directory where the results will be stored

resume_fileoptional

Specific file to use for checkpointing. If not specified the default is used (nested_sampler_resume.pkl)

Returns

resume_filestr

File used for checkpointing

setup_random_seed(self, seed)

initialise the random seed

configure_flow_reset(self, reset_weights, reset_permutations)

Configure how often the flow parameters are reset.

Values are converted to floats.

Parameters

reset_weightsint, float or bool

Frequency with which the weights will be reset.

reset_permutationsint, float or bool

Frequency with which the permutations will be reset.

check_insertion_indices(self, rolling=True, filename=None)

Checking the distribution of the insertion indices either during the nested sampling run (rolling=True) or for the whole run (rolling=False).

log_likelihood(self, x)

Wrapper for the model likelihood so evaluations are counted

yield_sample(self, oldparam)

Draw points and applying rejection sampling

insert_live_point(self, live_point)

Insert a live point

consume_sample(self)

Replace a sample for single thread

populate_live_points(self)

Initialise the pool of live points.

initialise(self, live_points=True)

Initialise the nested sampler

Parameters

live_pointsbool, optional (True)

If true and there are no live points, new live points are drawn using populate_live_points else all other initialisation steps are complete but live points remain empty.

check_proposal_switch(self, force=False)

Check if the proposal should be switch from uninformed to flowproposal given the current state.

If the flow proposal is already in use, no changes are made.

Parameters

forcebool, optional

If True proposal is forced to switch.

Returns

bool

Flag to indicated if proposal was switched

check_training(self)

Check if the normalising flow should be trained

Checks that can force training:

• Training was previously stopped before completion

• The pool is empty and the proposal was not in the process of populating when stopped.

Checks that cannot force training is still on cooldown:

• Acceptance falls below threshold and retrain_acceptance is true

• The number of iterations since last training is equal to the training frequency

Returns

trainbool

Try to train if true

forcebool

Force the training irrespective of cooldown

check_flow_model_reset(self)

Check if the normalising flow model should be reset.

Checks acceptance if reset_acceptance is True and always checks how many times the flow has been trained.

Flow will not be reset if it has not been trained. To force a reset manually call proposal.reset_model_weights.

train_proposal(self, force=False)

Try to train the proposal. Proposal will not train if cooldown is not exceeded unless force is True.

Parameters

forcebool

Override training checks

check_state(self, force=False)

Check if state should be updated prior to drawing a new sample

Force will override the cooldown mechanism.

plot_state(self, filename=None)

Produce plots with the current state of the nested sampling run. Plots are saved to the output directory specified at initialisation.

Parameters

filenamestr, optional

If specified the figure will be saved, otherwise the figure is returned.

plot_trace(self, filename=None)

Make trace plots for the nested samples.

Parameters

filenamestr, optional

If filename is None, the figure is returned. Else the figure is saved with that file name.

plot_insertion_indices(self, filename=None, **kwargs)

Make a plot of all the insertion indices.

Parameters

filenamestr, optional

If filename is None, the figure is returned. Else the figure is saved with that file name.

kwargs

Keyword arguments passed to nessai.plot.plot_indices.

update_state(self, force=False)

Update state after replacing a live point

checkpoint(self, periodic=False)

Checkpoint the classes internal state

Parameters

periodicbool

Indicates if the checkpoint is regular periodic checkpointing or forced by a signal. If forced by a signal, it will show up on the state plot.

check_resume(self)

Check the normalising flow is correctly configured is the sampler was resumed.

finalise(self)

Finalise things after sampling

nested_sampling_loop(self)

Main nested sampling loop.

Returns

log_evidencefloat

The final log evidence.

nested_samplesnumpy.ndarray

Array of nested samples.

Notes

If prior_sampling=True then sampling will stop after drawing the initial live points.

classmethod resume(cls, filename, model, flow_config=None, weights_file=None)

Resumes the interrupted state from a checkpoint pickle file.

Parameters

filenamestr

Pickle pickle to resume from

modelnessai.model.Model

User-defined model

flow_configdict, optional

Dictionary for configuring the flow

weights_filestr, optional

Weights files to use in place of the weights file stored in the pickle file.

Returns

obj

Instance of NestedSampler