nessai.samplers.nestedsampler

Functions and objects related to the main nested sampling algorithm.

Module Contents

Classes

NestedSampler

Nested Sampler class.

class nessai.samplers.nestedsampler.NestedSampler(model, nlive=2000, output=None, stopping=0.1, max_iteration=None, checkpointing=True, checkpoint_interval=600, checkpoint_on_iteration=False, checkpoint_on_training=False, checkpoint_callback=None, logging_interval=None, log_on_iteration=True, resume_file=None, seed=None, pool=None, close_pool=False, 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, reset_flow=False, retrain_acceptance=True, reset_acceptance=False, acceptance_threshold=0.01, shrinkage_expectation='logt', trace_parameters=None, **kwargs)

Bases: nessai.samplers.base.BaseNestedSampler

Nested Sampler class.

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.

checkpoint_intervalint

The interval used for checkpointing. By default this is a time interval in seconds. If checkpoint_on_iteration=True this corresponds to the number of iterations between checkpointing.

checkpoint_on_iterationbool

If true the checkpointing interval is checked against the number of iterations

logging_intervalint, optional

The interval in seconds used for periodic logging. If not specified, then periodic logging is disabled.

log_on_iterationbool

If true logging will occur based on the iteration. If false logging will be periodic if logging_interval is set. In case where neither logging is enabled, log_on_iteration will be set to true with an interval of nlive.

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_flowbool, int

Boolean to toggle resetting the entire flow whenever re-training. If an integer is specified the flow is reset every nth time it trains. This option overrides reset_weights and reset_permutations.

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.

shrinkage_expectationstr, {“t”, “logt”}

Method used to compute the expectation value for the shrinkage t. Choose between log <t> or <log t>. Defaults to <log t>.

trace_parametersOptional[list[str]]

List of parameters to include in the trace plot. If None, all model parameters are included.

kwargs

Keyword arguments passed to the flow proposal class

property last_updated

Last time the normalising flow was retrained

property mean_acceptance

Mean acceptance of the last nlive // 10 points

property posterior_effective_sample_size

The effective sample size of the posterior distribution

property birth_log_likelihoods

Return the birth log-likelihoods for the nested samples

configure_max_iteration(max_iteration)

Configure the maximum iteration.

If None then no maximum is set.

Parameters:

max_iterationint, None

Maximum iteration.

configure_training_frequency(training_frequency)

Configure the training frequency.

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

configure_uninformed_proposal(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(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.

configure_output(output: str | None, resume_file: str | None = None)

Configure the output folder

Creates a “diagnostics” directory plotting is enabled.

Parameters:

outputstr

Directory where the results will be stored

resume_filestr, optional

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

configure_flow_reset(reset_weights, reset_permutations, reset_flow)

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.

reset_flowint, float or bool

Frequency with which the entire flow will be reset. Will overwrite the value for the other resets.

initialise_history()

Initialise the dictionary to store history

update_history()

Update the history dictionary

log_state()

Log the current state of the sampler

check_insertion_indices(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).

yield_sample(oldparam)

Draw points and applying rejection sampling

insert_live_point(live_point)

Insert a live point

consume_sample()

Replace a sample for single thread

populate_live_points()

Initialise the pool of live points.

initialise(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(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()

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()

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(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(force=False)

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

Force will override the cooldown mechanism.

plot_state(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(filename=None, **kwargs)

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.

kwargs

Additional keyword arguments passed to nessai.plot.plot_trace().

plot_insertion_indices(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(force=False)

Update state after replacing a live point

check_resume()

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

finalise()

Finalise things after sampling

nested_sampling_loop()

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.

get_result_dictionary()

Return a dictionary that contains results

classmethod resume_from_pickled_sampler(sampler, model, flow_config=None, weights_path=None, **kwargs)

Resume from a pickled sampler.

Parameters:

sampler: Any

Pickled sampler.

modelnessai.model.Model

User-defined model

flow_configOptional[dict]

Dictionary for configuring the flow

weights_pathOptional[str]

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

kwargs

Keyword arguments passed to the parent class’s method.

Returns:

Instance of NestedSampler