_AbstractDistribution#

class hmclab.Distributions._AbstractDistribution(*args, **kwargs)[source]#

Bases: object

Abstract base class for distributions.

This class is used as the template for any distribution supplied in the package or made by the user. It ensures key componenets are present (such as abstract methods) and takes care of bounded distributions.

The abstract methods (e.g. functions that need to be created by the user) of this class are: 1. hmclab.Distributions._AbstractDistribution.misfit() 2. hmclab.Distributions._AbstractDistribution.gradient() Make sure the signature of these functions is correct when implementing. Special care needs to be given to input and output shapes of NumPy arrays, all of which should be column vectors (n×1). Reshaping can be done within the function at will.

One abstract attribute is also required: hmclab.Distributions._AbstractDistribution.dimensions()

__init__()#

Methods

`__init__`
`corrector`	Correct HMC trajectory.
`create_default`	Create default instance.
`dimensions`	Dimensionality of misfit space.
`generate`	Draw samples from distribution.
`gradient`	Compute gradient of distribution.
`misfit`	Compute misfit of distribution.
`misfit_bounds`	Compute misfit of bounded distribution.
`normalize`	Normalize distribution.
`update_bounds`	Update bounded distribution.

Attributes

`lower_bounds`	Lower bounds for every parameter.
`name`	Name of the distribution.
`normalized`	Boolean describing if the distribution is normalized.
`upper_bounds`	Upper bounds for every parameter.

name: str = None#: Name of the distribution.

dimensions() → int[source]#

Dimensionality of misfit space.

This is an abstract parameter. If it is not defined either in your class directly or in its constructor (the __init__ function) then attempting to use the class will raise a NotImplementedError.

Access it like a parameter, not a function: distribution.dimensions.

lower_bounds: Optional[numpy.ndarray] = None#: Lower bounds for every parameter. If initialized to None, no bounds are used.

upper_bounds: Optional[numpy.ndarray] = None#: Upper bounds for every parameter. If initialized to None, no bounds are used.

normalized: bool = False#

Boolean describing if the distribution is normalized.

Boolean describing if the distribution is normalized, i.e. if we can use it in mixtures of distributions. Is computed typically only after running hmclab.Distributions._AbstractDistribution.normalize()

abstract misfit(coordinates: numpy.ndarray) → float[source]#

Compute misfit of distribution.

Misfit computation (e.g. log likelihood) of the distribution. This method is present in all implemented derived classes, and should be present, with this exact signature, in all user-implemented derived classes.

Parameters: coordinates (numpy.ndarray) – Numpy array shaped as (dimensions, 1) representing a column vector containing the coordinates \(\mathbf{m}\).
Returns: misfit – The distribution misfit \(\chi\).
Return type: float

The distribution misfit is related to the distribution probability density as:

\[\chi_\text{distribution} (\mathbf{m}) \propto -\log p(\mathbf{m}).\]

This method is called many times in an HMC appraisal. It is therefore beneficial to optimize the implementation.

Note that the distribution need not be normalized, except when using mixtures of distributions. Therefore, distributions for which the normalization constant is intractable should not be used in mixtures. These distributions can be combined using Bayes’ rule with other mixtures.

abstract gradient(coordinates: numpy.ndarray) → numpy.ndarray[source]#

Compute gradient of distribution.

Parameters: coordinates (numpy.ndarray) – Numpy array shaped as (dimensions, 1) representing a column vector containing the coordinates \(\mathbf{m}\).
Returns: gradient – The distribution misfit gradient \(\nabla_\mathbf{m}\chi\).
Return type: numpy.ndarray

The distribution misfit gradient is related to the distribution probability density as:

\[\nabla_\mathbf{m} \chi_\text{distribution} (\mathbf{m}) = - \nabla_\mathbf{m} \log p(\mathbf{m}).\]

This method is called many times in an HMC appraisal. It is therefore beneficial to optimize the implementation.

normalize()[source]#

Normalize distribution.

Method to compute the normalization constant of a distribution. As this might take significant time, it is not done in initialization.

Raises: AttributeError – An AttributeError is raised if the distribution provides no way to be normalized, e.g. when the normalization constant is intractable.

abstract generate(repeat=1, rng=Generator(PCG64) at 0x11A3F23C0) → numpy.ndarray[source]#

Draw samples from distribution.

Returns: sample – A numpy array shaped as (dimensions, repeat) containing a sample of the distribution.
Return type: numpy.ndarray
Raises: NotImplementedError – If the distribution does not allow generation of samples.

This method is mostly a convenience class. The algorithm itself does not require the implementation.

static create_default(dimensions: int) → hmclab.Distributions.base._AbstractDistribution[source]#

Create default instance.

Method to create a default version of the distribution, given a specific dimensionality. Used in automated testing. Can be used on the class instead of an instance, e.g.:

class.create_default(10)

Parameters: dimensions (int) – Integer corresponding to the amount of free parameters the distribution should have.
Returns: distribution – An instance of the derived class with the requested amount of free parameters.
Return type: derivative of _AbstractDistribution
Raises: NotImplementedError – A NotImplementedError is raised if the distribution provides no way create a model for the requested dimensionality.

corrector(coordinates: numpy.ndarray, momentum: numpy.ndarray)[source]#

Correct HMC trajectory.

Method to correct an HMC particle for bounded distributions, which is called after every time integration step.

Parameters

coordinates (numpy.ndarray) – Numpy array shaped as (dimensions, 1) representing a column vector containing the coordinates \(\mathbf{m}\) upon which to operate by reference.
momentum (numpy.ndarray) – Numpy array shaped as (dimensions, 1) representing a column vector containing the momenta \(\mathbf{p}\) upon which to operate by reference.

update_bounds(lower: Optional[numpy.ndarray] = None, upper: Optional[numpy.ndarray] = None)[source]#

Update bounded distribution.

This method updates the bounds of a distribution. Note that invocating it, does not require both bounds to be passed.

If both vectors are passed, ensure that all upper bounds are above the corresponding lower bounds.

Parameters

lower (numpy.ndarray or None) – Either an array shaped as (dimensions, 1) with floats for the lower bounds, or None for no bounds. If some dimensions should be bounded, while others should not, use -numpy.inf within the vector as needed.
upper (numpy.ndarray or None) – Either an array shaped as (dimensions, 1) with floats for the upper bounds, or None for no bounds. If some dimensions should be bounded, while others should not, use numpy.inf within the vector as needed.

Raises

ValueError – A ValueError is raised if the supplied upper and lower bounds are incompatible.

misfit_bounds(coordinates: numpy.ndarray) → float[source]#

Compute misfit of bounded distribution.

Method to compute the misfit associated with the truncated part of the distribution. Used internally.