nessai.model ============ .. py:module:: nessai.model .. autoapi-nested-parse:: Object for defining the use-defined model. .. !! processed by numpydoc !! Exceptions ---------- .. autoapisummary:: nessai.model.ModelError nessai.model.OneDimensionalModelError Classes ------- .. autoapisummary:: nessai.model.Model Module Contents --------------- .. py:exception:: ModelError Bases: :py:obj:`Exception` Exception raised when the model is not configured correctly. .. versionadded:: 0.15.0 .. !! processed by numpydoc !! .. py:exception:: OneDimensionalModelError Bases: :py:obj:`ModelError` Exception raised when the model is one-dimensional. .. versionchanged:: 0.15.0 Changed to inherit from ModelError. .. !! processed by numpydoc !! .. py:class:: Model Bases: :py:obj:`abc.ABC` Base class for the user-defined model being sampled. The user must define the attributes ``names`` ``bounds`` and the methods ``log_likelihood`` and ``log_prior``. The user can also define the reparemeterisations here instead of in the keyword arguments passed to the sampler. .. !! processed by numpydoc !! .. py:attribute:: reparameterisations :value: None dict Dictionary of reparameterisations that overrides the values specified. .. !! processed by numpydoc !! .. py:attribute:: likelihood_evaluations :value: 0 int Number of likelihood evaluations. .. !! processed by numpydoc !! .. py:attribute:: likelihood_evaluation_time :py:obj:`datetime.timedelta()` Time spent evaluating the likelihood. .. !! processed by numpydoc !! .. py:attribute:: pool :value: None obj Multiprocessing pool for evaluating the log-likelihood. .. !! processed by numpydoc !! .. py:attribute:: allow_vectorised_prior :value: True bool Allow the model to use a vectorised prior. If True, nessai will try to check if the log-prior is vectorised and use call the method as a vectorised function. If False, nessai won't check and, even if the log-prior is vectorised, it will only evaluate the log-prior one sample at a time. .. !! processed by numpydoc !! .. py:attribute:: allow_vectorised :value: True bool Allow the model to use a vectorised likelihood. If True, nessai will try to check if the model is vectorised and use call the likelihood as a vectorised function. If False, nessai won't check and, even if the likelihood is vectorised, it will only evaluate the likelihood one sample at a time. .. !! processed by numpydoc !! .. py:attribute:: likelihood_chunksize :value: None int Chunksize to use with a vectorised likelihood. If specified the likelihood will be called with at most chunksize points at once. .. !! processed by numpydoc !! .. py:attribute:: allow_multi_valued_likelihood :value: False bool Allow for a multi-valued likelihood function that will return different likelihood values for the same point in parameter space. This is only recommended when the variation is significantly smaller that the variations in the likelihood across the prior. .. !! processed by numpydoc !! .. py:attribute:: parallelise_prior :value: False bool Parallelise calculating the log-prior using the multiprocessing pool. .. !! processed by numpydoc !! .. py:method:: set_rng(rng: Optional[numpy.random.Generator] = None) Set the random number generator. :Parameters: **rng** : np.random.Generator, optional Random number generator. If not provided, a new generator is created. .. !! processed by numpydoc !! .. py:property:: names List of the names of each parameter in the model. .. !! processed by numpydoc !! .. py:property:: bounds Dictionary with the lower and upper bounds for each parameter. .. !! processed by numpydoc !! .. py:property:: dims Number of dimensions in the model .. !! processed by numpydoc !! .. py:property:: discrete_parameters List of discrete parameters. None if there are no discrete parameters. .. !! processed by numpydoc !! .. py:property:: has_discrete_parameters Indicates if the model contains discrete parameters. .. !! processed by numpydoc !! .. py:property:: lower_bounds Lower bounds on the priors .. !! processed by numpydoc !! .. py:property:: upper_bounds Upper bounds on the priors .. !! processed by numpydoc !! .. py:property:: vectorised_likelihood Boolean to indicate if the likelihood is vectorised or not. Checks that the values returned by computing the likelihood for individual samples matches those return by evaluating the likelihood in a batch. If a TypeError or ValueError are raised the likelihood is assumed to be vectorised. This check can be prevented by setting :py:attr:`nessai.model.Model.allowed_vectorised` to ``False``. .. !! processed by numpydoc !! .. py:method:: configure_pool(pool=None, n_pool=None) Configure a multiprocessing pool for the likelihood computation. Configuration will be skipped if the pool has already been configured. :Parameters: **pool** User provided pool. Must call :py:func:`nessai.utils.multiprocessing.initialise_pool_variables` before creating the pool or pass said function to the initialiser with the model. **n_pool** : int Number of threads to use to create an instance of :py:obj:`multiprocessing.Pool`. .. !! processed by numpydoc !! .. py:method:: close_pool(code=None) Close the the multiprocessing pool. Also resets the pool configuration. .. !! processed by numpydoc !! .. py:method:: new_point(N=1) Create a new LivePoint, drawn from within bounds. See `new_point_log_prob` if changing this method. :Parameters: **N** : int, optional Number of points to draw. By default draws one point. If N > 1 points are drawn using a faster method. :Returns: ndarray Numpy structured array with fields for each parameter and log-prior (logP) and log-likelihood (logL) .. !! processed by numpydoc !! .. py:method:: new_point_log_prob(x) Computes the proposal probability for a new point. This does not assume the that points will be drawn according to the prior. If `new_point` is redefined this method must be updated to match. :Parameters: **x** : ndarray Points in a structured array :Returns: ndarray Log proposal probability for each point .. !! processed by numpydoc !! .. py:method:: in_bounds(x) Check if a set of live point are within the prior bounds. :Parameters: **x** : :obj:`numpy.ndarray` Structured array of live points. Must contain all of the parameters in the model. :Returns: Array of bool Array with the same length as x where True indicates the point is within the prior bounds. .. !! processed by numpydoc !! .. py:method:: in_unit_hypercube(x: numpy.ndarray) -> numpy.ndarray Check if samples are within the unit hypercube :Parameters: **x** : numpy.ndarray Structured array of live points. Must contain all of the parameters in the model. :Returns: Array of bool Array with the same length as x where True indicates the point is within the prior bounds. .. !! processed by numpydoc !! .. py:method:: sample_parameter(name, n=1) :abstractmethod: Draw samples for a specific parameter from the prior. Should be implemented by the user and return a numpy array of length n. The array should NOT be a structured array. This method is not required for standard sampling with nessai. It is intended for use with :py:class:`nessai.conditional.ConditionalFlowProposal`. :Parameters: **name** : str Name for the parameter to sample **n** : int, optional Number of samples to draw. .. !! processed by numpydoc !! .. py:method:: parameter_in_bounds(x, name) Check if an array of values for specific parameter are in the prior bounds. :Parameters: **x** : :obj:`numpy:ndarray` Array of values. Not a structured array. :Returns: Array of bool Array with the same length as x where True indicates the value is within the prior bounds. .. !! processed by numpydoc !! .. py:method:: sample_unit_hypercube(n: int = 1) -> numpy.ndarray "Sample from the unit hypercube. :Parameters: **n** : int Number of samples :Returns: numpy.ndarray Structured array of samples .. !! processed by numpydoc !! .. py:method:: log_prior_unit_hypercube(x) -> numpy.ndarray Compute the log-prior in the unit hypercube. By default this returns log(1) and checks if the values are in the unit hypercube. .. !! processed by numpydoc !! .. py:method:: from_unit_hypercube(x) :abstractmethod: Map from the unit hypercube to the priors. Not implemented by default. .. !! processed by numpydoc !! .. py:method:: to_unit_hypercube(x) :abstractmethod: Map from the prior space to the unit hypercube. Not implemented by default. .. !! processed by numpydoc !! .. py:method:: log_prior(x) :abstractmethod: Returns log-prior, must be defined by the user. .. !! processed by numpydoc !! .. py:method:: log_likelihood(x) :abstractmethod: Returns the log-likelihood, must be defined by the user. .. !! processed by numpydoc !! .. py:method:: evaluate_log_likelihood(x) Evaluate the log-likelihood and track the number of calls. :Returns: float Log-likelihood value .. !! processed by numpydoc !! .. py:method:: batch_evaluate_log_likelihood(x: numpy.ndarray, unit_hypercube: bool = False) -> numpy.ndarray Evaluate the likelihood for a batch of samples. Uses the pool if available. :Parameters: **x** : :obj:`numpy.ndarray` Array of samples **unit_hypercube** : bool Indicates if input samples are from the unit hypercube or not. :Returns: :obj:`numpy.ndarray` Array of log-likelihood values .. !! processed by numpydoc !! .. py:method:: batch_evaluate_log_prior(x: numpy.ndarray, unit_hypercube: bool = False) -> numpy.ndarray Evaluate the log-prior for a batch of samples. Uses the pool if available. :Parameters: **x** : :obj:`numpy.ndarray` Array of samples **unit_hypercube** : bool Indicates if input samples are from the unit hypercube or not. :Returns: :obj:`numpy.ndarray` Array of log-prior values .. !! processed by numpydoc !! .. py:method:: batch_evaluate_log_prior_unit_hypercube(x: numpy.ndarray) -> numpy.ndarray Evaluate the log-prior in the unit hypercube for a batch of samples. Uses the pool if available. :Parameters: **x** : :obj:`numpy.ndarray` Array of samples :Returns: :obj:`numpy.ndarray` Array of log-prior values .. !! processed by numpydoc !! .. py:method:: unstructured_view(x) An unstructured view of point(s) x that only contains the parameters in the model. This is quicker than converting to a unstructured array and does not create a copy of the array. Calls :py:func:`nessai.livepoint.unstructured_view` with a pre-computed dtype. .. warning:: Will only work if all of the model parameters use the same dtype. :Parameters: **x** : structured_array Structured array of points :Returns: numpy.ndarray View of x as an unstructured array that contains only the parameters in the model. Shape is (x.size, self.dims). .. !! processed by numpydoc !! .. py:method:: check_new_point_methods() :classmethod: Check if the new_point methods have been redefined. .. versionadded:: 0.15.0 :Raises: ModelError If the new_point methods have been redefined but not both. .. !! processed by numpydoc !! .. py:method:: verify_model() Verify that the model is correctly setup. This includes checking the names, bounds and log-likelihood. :Returns: bool True if the model was verified as valid. .. !! processed by numpydoc !!