The NormalDistribution class#

Aliases#

halerium.core.distribution.NormalDistribution

class NormalDistribution(variable=None, shape=None, dtype=None, mean=None, variance=None, set_dependent_parameters=True)#

Normal distribution class.

The normal distribution is characterized by a mean and a variance. This NormalDistribution class does not allow for multivariate covariances. Each entry of a multidimensional random variable is independent.

Normal distribution.

Parameters:

variable (optional) – The variable which has this as distribution.
shape (optional) – The variable shape of the distribution (if the variable is not given itself).
dtype (optional) – The data type of the distribution.
mean (optional) – The mean of the distribution. The default is None.
variance (optional) – The variance of the distribution. The default is None.
set_dependent_parameters (bool) – Whether to automatically set any dependent parameters using values derived from the provided parameters. Users should keep this set to the default True.

assert_has_compatible_shape(array, name_of_array)#

Assert array has compatible shape.

Parameters:

array – The array to check shape.
name_of_array (str) – The name of the array in the potential error message.

Raises:

ValueError : – If shape of array is incompatible.

assert_is_valid_parameter_value(name, value)#

Check if is valid parameter value.

Checks if value is valid. Caveats: only performs checks if: - value is not None, and - value is not an operator, or - value is known to be a constant operator and can be evaluated.

Parameters:

name – The name of the parameter.
value – The value of the parameter.

Raises:

ValueError : – If value is not valid.

assert_is_valid_variable_value(value, mask)#

Check is valid variable value.

Checks if value is valid. Caveats: only performs checks if: - value is not None, - value not an operator or is known to be a constant operator

that can be evaluated,

mask not an operator or is known to be a constant operator that can be evaluated.

Parameters:

value – The value to check.
mask – The mask to apply to value.

Raises:

ValueError : – If value is not valid.

default_dtype = 'float'#

property dtype#: The data type of the distribution.

classmethod get_default_parameters()#

Get a default parameter dict.

Returns:: result – The default parameter dict.
Return type:: dict

get_fisher_quantities(mask=None)#

Get Fisher quantities.

Returns the scalar quantities

theta^t M theta

and

theta^t M^(1/2) xi

where M is the Fisher information metric (see Eq. (22) in arxiv 1901.11033), theta are the parameters of the distribution, and xi is a standard normal random generator in theta space.

Additionally, pointers for to the (identity-distinguished) Operators that make up theta and M are provided. These are needed in order to apply M using derivative tricks.

Parameters:

mask (optional) – The boolean mask (cast to float) indicating which elements of the full Fisher matrix contribute to the Fisher scalars. Entries with True/False (1/0) mark elements that don’t/do contribute. The default of None corresponds to all mask entries being False (0), i.e. all entries contribute.

Returns:

fisher_scalar (scalar Operator) – The fully contracted Fisher information.
noise_scalar (scalar Operator) – The fully contracted Fisher noise.
theta_fixed (list of Operators) – The list of distribution parameters for theta (usable for stop gradients).
fisher_metric_fixed (list of operators) – The list of distribution parameters for M (usable for stop gradients).

get_mandatory_kwargs()#

Get mandatory keyword arguments for init.

The default is to return an empty dict. Should be overridden for distributions with mandatory attributes.

Returns:: A dictionary of mandatory keyword arguments and their current values.
Return type:: kwargs

get_parameter(name, check_name=True)#

Get distribution parameter.

Parameters:

name (str) – The name of the distribution parameter.
check_name (bool, optional) – Whether to check the name is the name of a distribution parameter.

Returns:

The requested parameter of the distribution.

Return type:

parameter

get_parameter_shape(name, check_name=True)#

Get parameter shape.

Returns the shape of the parameter specified by name. Should return a tuple for operator parameter names. The default is to return the distribution’s shape.

Parameters:

name (str) – The name of the parameter.
check_name (bool, optional) – Whether to check the name is the name of a distribution parameter.

Returns:

shape – The shape of the parameter.

Return type:

tuple, None

classmethod get_parameters_from_mean_and_variance(mean, variance)#

Get parameters from mean and variance.

Get distribution parameters such that the distribution mean and variance (if possible) match the provided values.

Parameters:

mean – The mean of the distribution.
variance – The variance of the distribution.

Returns:

The parameters of the distribution. A dictionary of the parameter names as keys and the parameters as value.

Return type:

parameters

classmethod get_parameters_from_scaled_parameters(location_parameter_value, scale_parameter_value, location, scale)#

Get parameters from scaled parameters.

Get the distribution location and scale parameters (if they exist) from values, optionally scaling those values first using location and scale.

Parameters:

location_parameter_value – The (possibly scaled) location parameter value of the distribution (if the distribution has such a parameter, else None).
scale_parameter_value – The (possibly scaled) scale parameter value of the distribution (if the distribution has such a parameter, else None).
location – The reference location (as to be used in a scaling operation). Assumed to represent the mean of the distribution.
scale – The reference scale (as to be used in a scaling operation). Assumed to represent the standard deviation of the distribution.

Returns:

parameters – The parameters of the distribution. A dictionary of the parameter names as keys and the scaled parameters as value.

Return type:

dict

has_additional_randomness = False#

has_source = True#

invalid_parameter_combinations = []#

is_valid_parameter_value(name, value)#

Check if parameter value is valid.

Parameters:

name – The name of the parameter.
value – The value of the parameter.

Returns:

Whether the value is valid.

Return type:

is_valid

is_valid_variable_value(value)#

Check if variable value is valid.

The default implementation does not perform any checks.

Parameters:: value – The variable value to check.
Returns:: Whether the value is valid.
Return type:: is_valid

property mean#

non_operator_parameter_names = {}#

property numpy_dtype#: The numpy data type of the distribution.

operator_parameter_names = {'mean', 'variance'}#

parameter_names = {'mean', 'variance'}#

property parameters#: The parameters of the distribution and their values.

set_parameter(name, value, check_name=True, set_dependent_parameters=True)#

Set a parameter of the distribution.

Parameters:

name (str) – The name of the parameter. Must be in parameters.
value (Operator or other) – The value for the parameter, typically an operator, but this can depend on the specific parameter and distribution.
check_name (bool, optional) – Whether to check the name is a parameter name. The default is True.
set_dependent_parameters (bool) – Whether to automatically set any dependent parameters using values derived from the provided parameters. Users should keep this set to the default True.

Raises:

AttributeError : – If name is not a valid parameter name.
ValueError : – If the value is not compatible.

set_parameters_from_mean_and_variance(mean, variance)#

Parameters:

mean – The mean of the distribution.
variance – The variance of the distribution.

set_parameters_from_scaled_parameters(location_parameter_value, scale_parameter_value, location, scale)#

Set parameters from scaled parameters.

Set the distribution location and scale parameters (if they exist) from values, optionally scaling those values first using location and scale. Note that passing None as parameter values will not set parameters (instead of setting them to None).

Parameters:

location_parameter_value – The scaled location parameter.
scale_parameter_value – The scaled scale parameter.
location – The reference location. Assumed to represent the mean of the distribution.
scale – The reference scale. Assumed to represent the standard deviation of the distribution.

property shape#: The variable shape of the distribution.

property size#: The total variable size of the distribution.

source_from_value(value)#

Source from value.

Transforms a variable value into a source value.

Parameters:: value – The value.
Returns:: The source. Think of this as a sample from a standard random normal distribution with a mean of zero and a variance of one.
Return type:: source

source_neg_log_prob(source, mask=None, keep_leading_axis=False, include_constants=False)#

Source neg. log. probability.

Construct the negative logarithmic probability operator from a source operator. This default implementation assumes a standard normal source.

Parameters:

source (Operator) – The source operator.
mask (optional) – The boolean mask (cast to float) indicating which elements of source contribute to the source neg. log. probability. Entries with True/False (1/0) mark elements of source that do/don’t contribute to the source_neg_log_prob. The default of None corresponds to all mask entries being True (1), i.e. all elements contribute.
keep_leading_axis (bool, optional) – Whether the first axis is kept or not. With True the output operator will have a shape of (N,). With False the output operator will have a shape of ().
include_constants (bool, optional) – Whether to include constants of the normalization. e.g. whether to include the 2pi in the normal distribution. The default is False.

Raises:

ValueError : – If the source is not compatible.

Returns:

nlp – The scalar (or vector) negative log-probability.

Return type:

Operator

valid_dtypes = {'float', 'int'}#

valid_parameter_value_description(name)#

Describe when parameter value is valid.

Parameters:: name – The name of the parameter.
Returns:: The description of the rules for a valid value.
Return type:: description

valid_variable_value_description()#

Describe when variable value is valid.

The default implementation does not give any description.

Returns:: The description of rules for a valid value.
Return type:: description

value_from_source(source)#

Value operator from source operator.

Transforms a source operator into a value operator.

Parameters:: source (Operator) – The source operator. Think of this operator as a sample from a standard random normal distribution with a mean of zero and a variance of one.
Returns:: value – The transformed source operator. If the source operator was a sample from a standard random normal distribution the value operator will be a sample of the distribution specified by self.
Return type:: Operator

value_neg_log_prob(value, mask=None, keep_leading_axis=False, include_constants=False)#

Neg. log. prob. op. from value op.

Construct the negative logarithmic probability operator from a value operator.

Parameters:

value (Operator) – The value operator.
mask (optional) – The boolean mask (cast to float) indicating which elements of value contribute to the value neg. log. probability. Entries with True/False (1/0) mark elements of value that don’t /do contribute to the value_neg_log_prob. The default of None corresponds to all mask entries being False (0), i.e. all entries contribute.
keep_leading_axis (bool, optional) – Whether the first axis is kept or not. With True the output operator will have a shape of (N,). With False the output operator will have a shape of (), i.e. be a scalar.
include_constants (bool, optional) – Whether to include constants of the normalization. e.g. whether to include the 2*pi in the normal distribution. The default is False.

Returns:

nlp – the scalar (or vector) negative log-probability.

Return type:

Operator

property variable#: The variable that has this distribution.

property variance#