:py:mod:`nessai.proposal.flowproposal` ====================================== .. py:module:: nessai.proposal.flowproposal .. autoapi-nested-parse:: Main proposal object that includes normalising flows. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: nessai.proposal.flowproposal.FlowProposal Attributes ~~~~~~~~~~ .. autoapisummary:: nessai.proposal.flowproposal.logger .. py:data:: logger .. !! processed by numpydoc !! .. py:class:: 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) Bases: :py:obj:`nessai.proposal.rejection.RejectionProposal` Object that handles training and proposal points :Parameters: **model** : :obj:`nessai.model.Model` User defined model. **flow_config** : dict, optional Configuration for training the normalising flow. If None, uses default settings. Defaults to None. **output** : str, 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'. **poolsize** : int, optional Size of the proposal pool. Defaults to 10000. **update_poolsize** : bool, optional If True the poolsize is updated using the current acceptance of the nested sampler. **max_poolsize_scale** : int, 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. **drawsize** : int, optional Number of points to simultaneously draw when populating the proposal Defaults to 10000 **check_acceptance** : bool, optional If True the acceptance is computed after populating the pool. This includes computing the likelihood for every point. Default False. **min_radius** : float, optional Minimum radius used for population. If not specified not minimum is used. **max_radius** : float, 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_radius** : float, 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_mode** : bool 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_fraction** : float Fraction of the total probability to contain with the latent contour when using a constant volume. **compute_radius_with_all** : bool, 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. **fuzz** : float, optional Fuzz-factor applied to the radius. If unspecified no fuzz-factor is applied. **expansion_fraction** : float, 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``. **truncate** : bool, optional Truncate proposals using probability compute for worst point. Not recommended. **rescale_parameters** : list 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_bounds** : list, optional Lower and upper bound to use for rescaling. Defaults to [-1, 1]. See `rescale_parameters`. **update_bounds** : bool, optional If True bounds used for rescaling are updated at the starting of training. If False prior bounds are used. **boundary_inversion** : bool 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_edges** : bool, optional If True, when applying the version the option of no inversion is allowed. **detect_edges_kwargs** : dict, optional Dictionary of keyword arguments passed to :func:`nessai.utils.detect_edge`. **reparameterisations** : dict, optional Dictionary for configure more flexible reparameterisations. This ignores any of the other settings related to rescaling. For more details see the documentation. **fallback_reparameterisation** : None or str Name of the reparameterisation to be used for parameters that have not been specified in the reparameterisations dictionary. If None, the :py:class:`~nessai.reparameterisations.NullReparameterisation` is used. Reparameterisation should support multiple parameters. **use_default_reparameterisations** : bool, optional If True then reparameterisations will be used even if ``reparameterisations`` is None. The exact reparameterisations used will depend on :py:func:`~nessai.proposal.flowproposal.FlowProposal.add_default_reparameterisations` which may be overloaded by child classes. If not specified then the value of the attribute :py:attr:`~nessai.proposal.flowproposal.FlowProposal.use_default_reparameterisations` is used. **draw_latent_kwargs** : dict, optional Dictionary of kwargs passed to the function for drawing samples in the latent space. See the functions in utils for the possible kwargs. .. !! processed by numpydoc !! .. py:attribute:: use_default_reparameterisations :annotation: = False Indicates whether reparameterisations will be used be default in this class. Child classes can change this value a force the default behaviour to change without changing the keyword arguments. .. !! processed by numpydoc !! .. py:method:: poolsize(self) :property: Return the poolsize based of the base value and the current value of the scaling .. !! processed by numpydoc !! .. py:method:: flow_config(self) :property: Return the configuration for the flow .. !! processed by numpydoc !! .. py:method:: dims(self) :property: Return the number of dimensions .. !! processed by numpydoc !! .. py:method:: rescaled_dims(self) :property: Return the number of rescaled dimensions .. !! processed by numpydoc !! .. py:method:: x_dtype(self) :property: Return the dtype for the x space .. !! processed by numpydoc !! .. py:method:: x_prime_dtype(self) :property: Return the dtype for the x prime space .. !! processed by numpydoc !! .. py:method:: population_dtype(self) :property: dtype used for populating the proposal, depends on if the prior is defined in the x space or x-prime space .. !! processed by numpydoc !! .. py:method:: configure_population(self, poolsize, drawsize, update_poolsize, max_poolsize_scale, fuzz, expansion_fraction, latent_prior) Configure settings related to population .. !! processed by numpydoc !! .. py:method:: configure_plotting(self, plot) Configure plotting. Plotting is split into training and pool. Training refers to plots produced during training and pool refers to plots produces during the population stage. :Parameters: **plot** : {True, False, 'all', 'train', 'pool', 'min', 'minimal'} Level of plotting. `all`, `train` and `pool` enable corner style plots. All other values that evaluate to True enable 1d histogram plots. False disables all plotting. .. !! processed by numpydoc !! .. py:method:: configure_latent_prior(self) Configure the latent prior .. !! processed by numpydoc !! .. py:method:: configure_fixed_radius(self, fixed_radius) Configure the fixed radius .. !! processed by numpydoc !! .. py:method:: configure_min_max_radius(self, min_radius, max_radius) Configure the minimum and maximum radius .. !! processed by numpydoc !! .. py:method:: configure_constant_volume(self) Configure using constant volume latent contour. .. !! processed by numpydoc !! .. py:method:: update_flow_config(self) Update the flow configuration dictionary. .. !! processed by numpydoc !! .. py:method:: initialise(self) Initialise the proposal class. This includes: * Setting up the rescaling * Verifying the rescaling is invertible * Initialising the FlowModel .. !! processed by numpydoc !! .. py:method:: update_poolsize_scale(self, acceptance) Update poolsize given the current acceptance. :Parameters: **acceptance** : float Current acceptance. .. !! processed by numpydoc !! .. py:method:: set_boundary_inversion(self) Setup boundary inversion .. !! processed by numpydoc !! .. py:method:: add_default_reparameterisations(self) Add any reparameterisations which are assumed by default .. !! processed by numpydoc !! .. py:method:: get_reparameterisation(self, name) Get the reparameterisation from the name .. !! processed by numpydoc !! .. py:method:: configure_reparameterisations(self, reparameterisations) Configure the reparameterisations. :Parameters: **reparameterisations** : {dict, None} Dictionary of reparameterisations. If None, then the defaults from :py:func`get_default_reparameterisations` are used. .. !! processed by numpydoc !! .. py:method:: set_rescaling(self) Set function and parameter names for rescaling .. !! processed by numpydoc !! .. py:method:: verify_rescaling(self) Verify the rescaling functions are invertible .. !! processed by numpydoc !! .. py:method:: rescale(self, x, compute_radius=False, **kwargs) Rescale from the physical space to the primed physical space :Parameters: **x: array_like** Array of live points to rescale **compute_radius: bool (False)** Used to indicate when rescaling is being used for computing the radius for population. This is important for rescaling that uses inversions. :Returns: array Array of rescaled values array Array of log det|J| .. !! processed by numpydoc !! .. py:method:: inverse_rescale(self, x_prime, **kwargs) Rescale from the primed physical space to the original physical space. :Parameters: **x_prime** : array_like Array of live points to rescale. :Returns: array Array of rescaled values in the data space. array Array of log-Jacobian determinants. .. !! processed by numpydoc !! .. py:method:: check_state(self, x) Operations that need to checked before training. These include updating the bounds for rescaling and resetting the bounds for inversion. :Parameters: **x: array_like** Array of training live points which can be used to set parameters .. !! processed by numpydoc !! .. py:method:: train(self, x, plot=True) Train the normalising flow given some of the live points. :Parameters: **x** : structured_array Array of live points **plot** : {True, False, 'all'} Enable or disable plots for during training. By default the plots are only one-dimensional histograms, `'all'` includes corner plots with samples, these are often a few MB in size so proceed with caution! .. !! processed by numpydoc !! .. py:method:: reset_model_weights(self, **kwargs) Reset the flow weights. :Parameters: **kwargs** Keyword arguments passed to :meth:`nessai.flowmodel.FlowModel.reset_model`. .. !! processed by numpydoc !! .. py:method:: check_prior_bounds(self, x, *args) Return only values that are within the prior bounds :Parameters: **x: array_like** Array of live points which will compared against prior bounds **\*args:** Additional arrays which correspond to the array of live points. Only those corresponding to points within the prior bounds are returned :Returns: out: tuple of arrays Array containing the subset of the original arrays which fall within the prior bounds .. !! processed by numpydoc !! .. py:method:: forward_pass(self, x, rescale=True, compute_radius=True) Pass a vector of points through the model :Parameters: **x** : array_like Live points to map to the latent space **rescale** : bool, optional (True) Apply rescaling function **compute_radius** : bool, optional (True) Flag parsed to rescaling for rescaling specific to radius computation :Returns: **x** : array_like Samples in the latent space **log_prob** : array_like Log probabilities corresponding to each sample (including the jacobian) .. !! processed by numpydoc !! .. py:method:: backward_pass(self, z, rescale=True) A backwards pass from the model (latent -> real) :Parameters: **z** : array_like Structured array of points in the latent space **rescale** : bool, optional (True) Apply inverse rescaling function :Returns: **x** : array_like Samples in the latent space **log_prob** : array_like Log probabilities corresponding to each sample (including the Jacobian) .. !! processed by numpydoc !! .. py:method:: radius(self, z, log_q=None) Calculate the radius of a latent point or set of latent points. If multiple points are parsed the maximum radius is returned. :Parameters: **z** : :obj:`np.ndarray` Array of points in the latent space **log_q** : :obj:`np.ndarray`, optional (None) Array of corresponding probabilities. If specified then probability of the maximum radius is also returned. :Returns: tuple of arrays Tuple of array with the maximum radius and corresponding log_q if it was a specified input. .. !! processed by numpydoc !! .. py:method:: log_prior(self, x) Compute the prior probability using the user-defined model :Parameters: **x** : structured_array Array of samples :Returns: array_like Array of log prior probabilities .. !! processed by numpydoc !! .. py:method:: x_prime_log_prior(self, x) Compute the prior in the prime space :Parameters: **x** : array Samples in the X-prime space. .. !! processed by numpydoc !! .. py:method:: compute_weights(self, x, log_q) Compute weights for the samples. Computes the log weights for rejection sampling sampling such that that the maximum log probability is zero. Also sets the fields `logP` and `logL`. Note `logL` is set as the proposal probability. :Parameters: **x** : structured_arrays Array of points **log_q** : array_like Array of log proposal probabilities. :Returns: array_like Log-weights for rejection sampling. .. !! processed by numpydoc !! .. py:method:: rejection_sampling(self, z, worst_q=None) Perform rejection sampling. Converts samples from the latent space and computes the corresponding weights. Then returns samples using standard rejection sampling. :Parameters: **z** : ndarray Samples from the latent space **worst_q** : float, optional Lower bound on the log-probability computed using the flow that is used to truncate new samples. Not recommended. :Returns: array_like Array of accepted latent samples. array_like Array of accepted samples in the X space. .. !! processed by numpydoc !! .. py:method:: convert_to_samples(self, x, plot=True) Convert the array to samples ready to be used. This removes are auxiliary parameters, (e.g. auxiliary radial parameters) and ensures the prior is computed. These samples can be directly used in the nested sampler. :Parameters: **x** : array_like Array of samples **plot** : bool, optional If true a 1d histogram for each parameter of the pool is plotted. This includes a comparison the live points used to train the current realisation of the flow. :Returns: array Structured array of samples. .. !! processed by numpydoc !! .. py:method:: populate(self, worst_point, N=10000, plot=True, r=None) Populate a pool of latent points given the current worst point. :Parameters: **worst_point** : structured_array The current worst point used to compute the radius of the contour in the latent space. **N** : int, optional (10000) The total number of points to populate in the pool **plot** : {True, False, 'all'} Enable or disable plots for during training. By default the plots are only one-dimensional histograms, `'all'` includes corner plots with samples, these are often a few MB in size so proceed with caution! .. !! processed by numpydoc !! .. py:method:: get_alt_distribution(self) Get a distribution for the latent prior used to draw samples. .. !! processed by numpydoc !! .. py:method:: compute_acceptance(self, logL) Compute how many of the current pool have log-likelihoods greater than the specified log-likelihood using the current value in the `logL` field. :Parameters: **float** : logL Log-likelihood to use as the lower bound :Returns: **float** : Acceptance defined on [0, 1] .. !! processed by numpydoc !! .. py:method:: draw(self, worst_point) Draw a replacement point. The new point is independent of the worst point. The worst point is only used during population. :Parameters: **worst_point** : structured_array The current worst point used to compute the radius of the contour in the latent space. :Returns: structured_array New live point .. !! processed by numpydoc !! .. py:method:: plot_pool(self, z, x) Plot the pool of points. :Parameters: **z** : array_like Latent samples to plot **x** : array_like Corresponding samples to plot in the physical space. .. !! processed by numpydoc !! .. py:method:: resume(self, model, flow_config, weights_file=None) Resume the proposal. The model and config are not stored so these must be provided. :Parameters: **model** : :obj:`nessai.model.Model` User-defined model used. **flow_config** : dict Configuration dictionary for the flow. **weights_files** : str, optional Weights file to try and load. If not provided the proposal tries to load the last weights file. .. !! processed by numpydoc !! .. py:method:: test_draw(self) Test the draw method to ensure it returns a sample in the correct format and the the log prior is computed. This method is not used since there are cases where the untrained flow is very slow to draw a new point. .. !! processed by numpydoc !! .. py:method:: reset(self) Reset the proposal .. !! processed by numpydoc !!