Numeric patterns

Numeric Arrays

class paragami.numeric_array_patterns.NumericArrayPattern(shape, lb=-inf, ub=inf, default_validate=True, free_default=None)

A pattern for (optionally bounded) arrays of numbers.

Attributes:

default_validate: `bool`, optional

Whether or not the array is checked by default to lie within the specified bounds.

__init__(shape, lb=-inf, ub=inf, default_validate=True, free_default=None)

Parameters:

shape: `tuple` of `int`

The shape of the array.

lb: `float`

The (inclusive) lower bound for the entries of the array.

ub: `float`

The (inclusive) upper bound for the entries of the array.

default_validate: `bool`, optional

Whether or not the array is checked by default to lie within the specified bounds.

free_default: `bool`, optional

Whether the pattern is free by default.

as_dict()

Return a dictionary of attributes describing the pattern.

The dictionary should completely describe the pattern in the sense that if the contents of two patterns’ dictionaries are identical the patterns should be considered identical.

If the keys of the returned dictionary match the arguments to __init__, then the default methods for to_json and from_json will work with no additional modification.

empty(valid)

Return an empty parameter in its folded shape.

Parameters:

valid : bool

Whether or folded shape should be filled with valid values.

Returns:

folded_val : Folded value

A parameter value in its original folded shape.

flat_indices(folded_bool, free=None)

Get which flattened indices correspond to which folded values.

Parameters:

folded_bool : Folded booleans

A variable in the folded shape but containing booleans. The elements that are True are the ones for which we will return the flat indices.

free : bool

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

Returns:

indices : numpy.ndarray (N,)

A list of indices into the flattened value corresponding to the True members of folded_bool.

flat_length(free=None)

Return the length of the pattern’s flattened value.

Parameters:

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, free_default is used.

Returns:

length : int

The length of the pattern’s flattened value.

flatten(folded_val, free=None, validate_value=None)

Flatten a folded value into a flat vector.

Parameters:

folded_val : Folded value

The parameter in its original folded shape.

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

flat_val : numpy.ndarray, (N, )

The flattened value.

fold(flat_val, free=None, validate_value=None)

Fold a flat value into a parameter.

Parameters:

flat_val : numpy.ndarray, (N, )

The flattened value.

free : bool, optional.

Whether or not the flattened value is a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool, optional.

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

folded_val : Folded value

The parameter value in its original folded shape.

validate_folded(folded_val, validate_value=None)

Check whether a folded value is valid.

Parameters:

folded_val : Folded value

A parameter value in its original folded shape.

validate_value : bool

Whether to validate the value in addition to the shape. The shape is always validated.

Returns:

is_valid : bool

Whether folded_val is an allowable shape and value.

err_msg : str

Symmetric Positive Definite Matrices

class paragami.psdmatrix_patterns.PSDSymmetricMatrixPattern(size, diag_lb=0.0, default_validate=True, free_default=None)

A pattern for a symmetric, positive-definite matrix parameter.

Attributes:

validate: Bool

Whether or not the matrix is automatically checked for symmetry positive-definiteness, and the diagonal lower bound.

__init__(size, diag_lb=0.0, default_validate=True, free_default=None)

Parameters:

size: `int`

The length of one side of the square matrix.

diag_lb: `float`

A lower bound for the diagonal entries. Must be >= 0.

default_validate: `bool`, optional

Whether or not to check for legal (i.e., symmetric positive-definite) folded values by default.

free_default: `bool`, optional

Default setting for free.

as_dict()

Return a dictionary of attributes describing the pattern.

The dictionary should completely describe the pattern in the sense that if the contents of two patterns’ dictionaries are identical the patterns should be considered identical.

If the keys of the returned dictionary match the arguments to __init__, then the default methods for to_json and from_json will work with no additional modification.

diag_lb()

Returns the diagonal lower bound.

empty(valid)

Return an empty parameter in its folded shape.

Parameters:

valid : bool

Whether or folded shape should be filled with valid values.

Returns:

folded_val : Folded value

A parameter value in its original folded shape.

flat_indices(folded_bool, free=None)

Get which flattened indices correspond to which folded values.

Parameters:

folded_bool : Folded booleans

A variable in the folded shape but containing booleans. The elements that are True are the ones for which we will return the flat indices.

free : bool

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

Returns:

indices : numpy.ndarray (N,)

A list of indices into the flattened value corresponding to the True members of folded_bool.

flatten(folded_val, free=None, validate_value=None)

Flatten a folded value into a flat vector.

Parameters:

folded_val : Folded value

The parameter in its original folded shape.

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

flat_val : numpy.ndarray, (N, )

The flattened value.

fold(flat_val, free=None, validate_value=None)

Fold a flat value into a parameter.

Parameters:

flat_val : numpy.ndarray, (N, )

The flattened value.

free : bool, optional.

Whether or not the flattened value is a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool, optional.

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

folded_val : Folded value

The parameter value in its original folded shape.

shape()

Returns the matrix shape, i.e., (size, size).

size()

Returns the matrix size.

validate_folded(folded_val, validate_value=None)

Check that the folded value is valid.

If validate_value = True, checks that folded_val is a symmetric, matrix of the correct shape with diagonal entries greater than the specified lower bound. Otherwise, only the shape is checked.

Note

This method does not currently check for positive-definiteness.

Parameters:

folded_val : Folded value

A candidate value for a positive definite matrix.

validate_value: `bool`, optional

Whether to check the matrix for attributes other than shape. If None, the value of self.default_validate is used.

Returns:

is_valid : bool

Whether folded_val is a valid positive semi-definite matrix.

err_msg : str

A message describing the reason the value is invalid or an empty string if the value is valid.

Simplexes

class paragami.simplex_patterns.SimplexArrayPattern(simplex_size, array_shape, default_validate=True, free_default=None)

A pattern for an array of simplex parameters.

The last index represents entries of the simplex. For example, if array_shape=(2, 3) and simplex_size=4, then the pattern is for a 2x3 array of 4d simplexes. If such value of the simplex array is given by val, then val.shape = (2, 3, 4) and val[i, j, :] is the i,j`th of the six simplicial vectors, i.e, `np.sum(val[i, j, :]) equals 1 for each i and j.

Attributes:

default_validate: Bool

Whether or not the simplex is checked by default to be non-negative and to sum to one.

Methods

array_shape: tuple of ints	The shape of the array of simplexes, not including the simplex dimension.
simplex_size: int	The length of each simplex.
shape: tuple of ints	The shape of the entire array including the simplex dimension.

__init__(simplex_size, array_shape, default_validate=True, free_default=None)

Parameters:

simplex_size: `int`

The length of the simplexes.

array_shape: `tuple` of `int`

The size of the array of simplexes (not including the simplexes themselves).

default_validate: `bool`, optional

Whether or not to check for legal (i.e., positive and normalized) folded values by default.

free_default: `bool`, optional

The default value for free.

as_dict()

Return a dictionary of attributes describing the pattern.

The dictionary should completely describe the pattern in the sense that if the contents of two patterns’ dictionaries are identical the patterns should be considered identical.

If the keys of the returned dictionary match the arguments to __init__, then the default methods for to_json and from_json will work with no additional modification.

empty(valid)

Return an empty parameter in its folded shape.

Parameters:

valid : bool

Whether or folded shape should be filled with valid values.

Returns:

folded_val : Folded value

A parameter value in its original folded shape.

flat_indices(folded_bool, free=None)

Get which flattened indices correspond to which folded values.

Parameters:

folded_bool : Folded booleans

A variable in the folded shape but containing booleans. The elements that are True are the ones for which we will return the flat indices.

free : bool

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

Returns:

indices : numpy.ndarray (N,)

A list of indices into the flattened value corresponding to the True members of folded_bool.

flatten(folded_val, free=None, validate_value=None)

Flatten a folded value into a flat vector.

Parameters:

folded_val : Folded value

The parameter in its original folded shape.

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

flat_val : numpy.ndarray, (N, )

The flattened value.

fold(flat_val, free=None, validate_value=None)

Fold a flat value into a parameter.

Parameters:

flat_val : numpy.ndarray, (N, )

The flattened value.

free : bool, optional.

Whether or not the flattened value is a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool, optional.

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.

Returns:

folded_val : Folded value

The parameter value in its original folded shape.

classmethod from_json(json_string)

Return a pattern instance from json_string created by to_json.

validate_folded(folded_val, validate_value=None)

Check whether a folded value is valid.

Parameters:

folded_val : Folded value

A parameter value in its original folded shape.

validate_value : bool

Whether to validate the value in addition to the shape. The shape is always validated.

Returns:

is_valid : bool

Whether folded_val is an allowable shape and value.

err_msg : str