nessai.samplers.nestedsampler ============================= .. py:module:: nessai.samplers.nestedsampler .. autoapi-nested-parse:: Functions and objects related to the main nested sampling algorithm. .. !! processed by numpydoc !! Classes ------- .. autoapisummary:: nessai.samplers.nestedsampler.NestedSampler Module Contents --------------- .. py:class:: 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, rng=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_proposal_class=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: :py:obj:`nessai.samplers.base.BaseNestedSampler` Nested Sampler class. :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. **checkpoint_interval** : int The interval used for checkpointing. By default this is a time interval in seconds. If :code:`checkpoint_on_iteration=True` this corresponds to the number of iterations between checkpointing. **checkpoint_on_iteration** : bool If true the checkpointing interval is checked against the number of iterations **logging_interval** : int, optional The interval in seconds used for periodic logging. If not specified, then periodic logging is disabled. **log_on_iteration** : bool 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 :code:`nlive`. **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_flow** : bool, 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 :code:`reset_weights` and :code:`reset_permutations`. **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. **shrinkage_expectation** : str, {"t", "logt"} Method used to compute the expectation value for the shrinkage t. Choose between log or . Defaults to . **trace_parameters** : Optional[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 .. !! processed by numpydoc !! .. py:property:: last_updated Last time the normalising flow was retrained .. !! processed by numpydoc !! .. py:property:: mean_acceptance Mean acceptance of the last nlive // 10 points .. !! processed by numpydoc !! .. py:property:: posterior_effective_sample_size The effective sample size of the posterior distribution .. !! processed by numpydoc !! .. py:property:: birth_log_likelihoods Return the birth log-likelihoods for the nested samples .. !! processed by numpydoc !! .. py:property:: tolerance Return the stopping criterion tolerance .. !! processed by numpydoc !! .. py:method:: configure_max_iteration(max_iteration) Configure the maximum iteration. If None then no maximum is set. :Parameters: **max_iteration** : int, None Maximum iteration. .. !! processed by numpydoc !! .. py:method:: configure_training_frequency(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(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(flow_proposal_class, flow_config, proposal_plots, **kwargs) Set up the flow-based proposal method :Parameters: **flow_proposal_class** : None or Callable 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:: configure_output(output: Union[str, None], resume_file: Union[str, None] = None) Configure the output folder Creates a "diagnostics" directory plotting is enabled. :Parameters: **output** : str Directory where the results will be stored **resume_file** : str, optional Specific file to use for checkpointing. If not specified the default is used (nested_sampler_resume.pkl) .. !! processed by numpydoc !! .. py:method:: update_output(output: str) -> None Update the output directory. Also creates a "diagnostics" directory for plotting. :Parameters: **output** : str Path to the output directory. .. !! processed by numpydoc !! .. py:method:: configure_flow_reset(reset_weights, reset_permutations, reset_flow) 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. **reset_flow** : int, float or bool Frequency with which the entire flow will be reset. Will overwrite the value for the other resets. .. !! processed by numpydoc !! .. py:method:: initialise_history() Initialise the dictionary to store history .. !! processed by numpydoc !! .. py:method:: update_history() Update the history dictionary .. !! processed by numpydoc !! .. py:method:: log_state() Log the current state of the sampler .. !! processed by numpydoc !! .. py:method:: 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). .. !! processed by numpydoc !! .. py:method:: yield_sample(oldparam) Draw points and applying rejection sampling .. !! processed by numpydoc !! .. py:method:: insert_live_point(live_point) Insert a live point .. !! processed by numpydoc !! .. py:method:: consume_sample() Replace a sample for single thread .. !! processed by numpydoc !! .. py:method:: populate_live_points() Initialise the pool of live points. .. !! processed by numpydoc !! .. py:method:: initialise(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(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() 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() 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(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(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(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(filename=None, **kwargs) 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. **kwargs** Additional keyword arguments passed to :py:func:`nessai.plot.plot_trace`. .. !! processed by numpydoc !! .. py:method:: plot_insertion_indices(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(force=False) Update state after replacing a live point .. !! processed by numpydoc !! .. py:method:: check_resume() Check the normalising flow is correctly configured is the sampler was resumed. .. !! processed by numpydoc !! .. py:method:: finalise() Finalise things after sampling .. !! processed by numpydoc !! .. py:method:: nested_sampling_loop() 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:: get_result_dictionary() Return a dictionary that contains results .. !! processed by numpydoc !! .. py:method:: resume_from_pickled_sampler(sampler, model, flow_config=None, weights_path=None, **kwargs) :classmethod: Resume from a pickled sampler. :Parameters: **sampler: Any** Pickled sampler. **model** : :obj:`nessai.model.Model` User-defined model **flow_config** : Optional[dict] Dictionary for configuring the flow **weights_path** : Optional[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 .. .. !! processed by numpydoc !!