:py:mod:`nessai.nestedsampler` ============================== .. py:module:: nessai.nestedsampler .. autoapi-nested-parse:: Functions and objects related to the main nested sampling algorithm. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: nessai.nestedsampler.NestedSampler Attributes ~~~~~~~~~~ .. autoapisummary:: nessai.nestedsampler.logger .. py:data:: logger .. !! processed by numpydoc !! .. py:class:: 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 **nlive** : int, optional Number of live points. **output** : str Path for output **stopping** : float, optional Stop when remaining samples wouldn't change logZ estimate by this much. **max_iteration** : int, optional Maximum number of iterations to run before force sampler to stop. If stopping criteria is met before max. is reached sampler will stop. **checkpointing** : bool, 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_file** : str, optional If specified sampler will be resumed from this file. Still requires correct model. **seed** : int, optional seed for the initialisation of the pseudorandom chain **n_pool** : int, optional Number of threads to when for creating the multiprocessing pool. **pool** : object User defined multiprocessing pool that will be used when evaluating the likelihood. **close_pool** : bool 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. **plot** : bool (True) Boolean to toggle plotting **proposal_plots** : bool (True) Boolean to enable additional plots for the population stage of the sampler. Overwritten by plot. **prior_sampling** : bool (False) produce nlive samples from the prior. **analytic_priors** : bool (False) Boolean that indicates that the `new_point` method in the model draws directly from the priors meaning rejection sampling is not needed. **maximum_uninformed** : int (1000) Maximum number of iterations before forcing the sampler to switch to using the proposal method with the flow. **uninformed_proposal** : :obj:`nessai.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_threshold** : float (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_kwargs** : dict, ({}) Dictionary of keyword argument to pass to the class use for the initial sampling when it is initialised. **flow_class** : :obj:`nessai.proposal.FlowProposal` Class to use for flow-based proposal method **flow_config** : dict ({}) Dictionary used to configure instance of `nessai.flowmodel.FlowModel`, this includes configuring the normalising flow and the training. **training_frequency** : int (None) Number of iterations between re-training the flow. If None flow is only re-trained based on other criteria. **train_on_empty** : bool (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. **cooldown** : int (100) Minimum number of iterations between training. Can be overridden if `train_on_empty=True` and the pool is empty. **memory** : int, False (False) Number of old live points to use in training. If False only the current live points are used. **reset_weights** : bool, 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_acceptance** : bool, (True) If true use mean acceptance of samples produced with current flow as a criteria for retraining **retrain_acceptance** : bool (False) Force the flow to be reset if the acceptance falls below the acceptance threshold. Requires `reset_acceptance=True` **acceptance_threshold** : float (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 .. !! processed by numpydoc !! .. py:method:: log_evidence(self) :property: .. !! processed by numpydoc !! .. py:method:: information(self) :property: .. !! processed by numpydoc !! .. py:method:: likelihood_calls(self) :property: .. !! processed by numpydoc !! .. py:method:: likelihood_evaluation_time(self) :property: .. !! processed by numpydoc !! .. py:method:: proposal_population_time(self) :property: .. !! processed by numpydoc !! .. py:method:: acceptance(self) :property: .. !! processed by numpydoc !! .. py:method:: current_sampling_time(self) :property: .. !! processed by numpydoc !! .. py:method:: last_updated(self) :property: Last time the normalising flow was retrained .. !! processed by numpydoc !! .. py:method:: mean_acceptance(self) :property: Mean acceptance of the last nlive // 10 points .. !! processed by numpydoc !! .. py:method:: configure_max_iteration(self, max_iteration) Configure the maximum iteration. If None then no maximum is set. .. !! processed by numpydoc !! .. py:method:: configure_training_frequency(self, training_frequency) Configure the training frequency. If None, 'inf' or 'None' flow will only train when empty. .. !! processed by numpydoc !! .. py:method:: configure_uninformed_proposal(self, uninformed_proposal, analytic_priors, maximum_uninformed, uninformed_acceptance_threshold, **kwargs) Setup the uninformed proposal method (is NOT trained) :Parameters: **uninformed_proposal** : None or obj Class to use for uninformed proposal **analytic_priors** : bool 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_threshold** : float 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 .. !! processed by numpydoc !! .. py:method:: configure_flow_proposal(self, flow_class, flow_config, proposal_plots, **kwargs) Set up the flow-based proposal method :Parameters: **flow_class** : None or obj or str Class to use for proposal. If None FlowProposal is used. **flow_config** : dict Configuration dictionary passed to the class. **proposal_plots** : bool or str Configuration of plotting in proposal class. **\*\*kwargs** Kwargs passed to init function. .. !! processed by numpydoc !! .. py:method:: setup_output(self, output, resume_file=None) Set up the output folder :Parameters: **output** : str Directory where the results will be stored **resume_file** : optional Specific file to use for checkpointing. If not specified the default is used (nested_sampler_resume.pkl) :Returns: **resume_file** : str File used for checkpointing .. !! processed by numpydoc !! .. py:method:: setup_random_seed(self, seed) initialise the random seed .. !! processed by numpydoc !! .. py:method:: configure_flow_reset(self, reset_weights, reset_permutations) Configure how often the flow parameters are reset. Values are converted to floats. :Parameters: **reset_weights** : int, float or bool Frequency with which the weights will be reset. **reset_permutations** : int, float or bool Frequency with which the permutations will be reset. .. !! processed by numpydoc !! .. py:method:: 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). .. !! processed by numpydoc !! .. py:method:: log_likelihood(self, x) Wrapper for the model likelihood so evaluations are counted .. !! processed by numpydoc !! .. py:method:: yield_sample(self, oldparam) Draw points and applying rejection sampling .. !! processed by numpydoc !! .. py:method:: insert_live_point(self, live_point) Insert a live point .. !! processed by numpydoc !! .. py:method:: consume_sample(self) Replace a sample for single thread .. !! processed by numpydoc !! .. py:method:: populate_live_points(self) Initialise the pool of live points. .. !! processed by numpydoc !! .. py:method:: initialise(self, live_points=True) Initialise the nested sampler :Parameters: **live_points** : bool, 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. .. !! processed by numpydoc !! .. py:method:: 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: **force** : bool, optional If True proposal is forced to switch. :Returns: bool Flag to indicated if proposal was switched .. !! processed by numpydoc !! .. py:method:: 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: **train** : bool Try to train if true **force** : bool Force the training irrespective of cooldown .. !! processed by numpydoc !! .. py:method:: 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`. .. !! processed by numpydoc !! .. py:method:: train_proposal(self, force=False) Try to train the proposal. Proposal will not train if cooldown is not exceeded unless force is True. :Parameters: **force** : bool Override training checks .. !! processed by numpydoc !! .. py:method:: check_state(self, force=False) Check if state should be updated prior to drawing a new sample Force will override the cooldown mechanism. .. !! processed by numpydoc !! .. py:method:: 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: **filename** : str, optional If specified the figure will be saved, otherwise the figure is returned. .. !! processed by numpydoc !! .. py:method:: plot_trace(self, filename=None) Make trace plots for the nested samples. :Parameters: **filename** : str, optional If filename is None, the figure is returned. Else the figure is saved with that file name. .. !! processed by numpydoc !! .. py:method:: plot_insertion_indices(self, filename=None, **kwargs) Make a plot of all the insertion indices. :Parameters: **filename** : str, 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`. .. !! processed by numpydoc !! .. py:method:: update_state(self, force=False) Update state after replacing a live point .. !! processed by numpydoc !! .. py:method:: checkpoint(self, periodic=False) Checkpoint the classes internal state :Parameters: **periodic** : bool 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. .. !! processed by numpydoc !! .. py:method:: check_resume(self) Check the normalising flow is correctly configured is the sampler was resumed. .. !! processed by numpydoc !! .. py:method:: finalise(self) Finalise things after sampling .. !! processed by numpydoc !! .. py:method:: nested_sampling_loop(self) Main nested sampling loop. :Returns: **log_evidence** : float The final log evidence. **nested_samples** : numpy.ndarray Array of nested samples. .. rubric:: Notes If :code:`prior_sampling=True` then sampling will stop after drawing the initial live points. .. !! processed by numpydoc !! .. py:method:: resume(cls, filename, model, flow_config=None, weights_file=None) :classmethod: Resumes the interrupted state from a checkpoint pickle file. :Parameters: **filename** : str Pickle pickle to resume from **model** : :obj:`nessai.model.Model` User-defined model **flow_config** : dict, optional Dictionary for configuring the flow **weights_file** : str, optional Weights files to use in place of the weights file stored in the pickle file. :Returns: obj Instance of NestedSampler .. !! processed by numpydoc !!