calipy.primitives  (API)

This module provides primitives needed for performing basic probabilistic actions like declaring parameters and smapling distributions

The classes and functions are
param: Declares a tensor as a parameter subject to optimization with SVI.

Produces a CalipyTensor with dims and subsampling capability

sample:

The param function is the basic function called to declare unknown parameters; it is often found as an ingredient when defining effects.

The script is meant solely for educational and illustrative purposes. Written by Dr. Jemil Avers Butt, Atlas optimization GmbH, www.atlasoptimization.com.

calipy.primitives.param(name, init_tensor, dims, constraint=Real(), subsample_index=None)

Wrapper function for pyro.param producing a CalipyTensor valued parameter. The tensor is inialized once, then placed in the param store and can be used like a regular CalipyTensor.

Parameters:

  • name (string) – Unique name of the parameter

  • init_tensor (torch.tensor) – The initial value of the parameter tensor, adjusted later on by optimization

  • dims (DimTuple) – A tuple of dimensions indicating the dims of the CalipyTensor created by param()

  • constraint (pyro.distributions.constraints.Constraint) – Pyro constraint that constrains the parameter of a distribution to lie in a pre-defined subspace of R^n like e.g. simplex, positive, …

  • subsample_index (CalipyIndex) – The subsampling index indicating how subsampling of the parameter is to be performed

Returns:

A CalipyTensor parameter being tracked by gradient tape and marked for optimization. Starts as init_tensor, has dims and constraints as specified and is automatically subsampled by subsampling_index.

Return type:

CalipyTensor

Example usage: Run line by line to investigate Class

# Create parameter ---------------------------------------------------
#
# i) Imports and definitions
import calipy
from calipy.base import param

batch_dims = dim_assignment(dim_names = ['bd_1_A'], dim_sizes = [4])
event_dims = dim_assignment(dim_names = ['ed_1_A'], dim_sizes = [2])
param_dims = batch_dims + event_dims
init_tensor = torch.ones(param_dims.sizes) + torch.normal(0,0.01, param_dims.sizes)
parameter = param('generic_param', init_tensor, param_dims)

# Create constrained, subsampled parameter ---------------------------
#
param_constraint = pyro.distributions.constraints.positive
subsample_indices = TensorIndexer.create_simple_subsample_indices(batch_dims[0],
                                                        batch_dims.sizes[0], 3)
ssi = subsample_indices[1]
ssi_expanded = ssi.expand_to_dims(param_dims, param_dims.sizes)
parameter_subsampled = param('param_subsampled', init_tensor, param_dims,
                             constraint = param_constraint, subsample_index = ssi_expanded)
print(parameter_subsampled)
assert((parameter_subsampled.tensor - parameter.tensor[ssi_expanded.tuple] == 0).all())


# Investigate parameter ----------------------------------------------
#

# Parameters are CalipyTensors with names, dims, and populated indexers
parameter.name
parameter.dims
parameter.indexer
parameter.indexer.global_index
parameter.indexer.global_index.tensor

parameter_subsampled.name
parameter_subsampled.dims
parameter_subsampled.indexer
parameter_subsampled.indexer.global_index
parameter_subsampled.indexer.global_index.tensor

# The underlying tensors are also saved in pyro's param store
pyro_param = pyro.get_param_store()['generic_param']
assert (pyro_param - parameter.tensor == 0).all()

pyro.param doc:

Saves the variable as a parameter in the param store. To interact with the param store or write to disk, see Parameters.

Parameters:

  • name (str) – name of parameter

  • init_tensor (torch.Tensor or callable) – initial tensor or lazy callable that returns a tensor. For large tensors, it may be cheaper to write e.g. lambda: torch.randn(100000), which will only be evaluated on the initial statement.

  • constraint (torch.distributions.constraints.Constraint) – torch constraint, defaults to constraints.real.

  • event_dim (int) – (optional) number of rightmost dimensions unrelated to batching. Dimension to the left of this will be considered batch dimensions; if the param statement is inside a subsampled plate, then corresponding batch dimensions of the parameter will be correspondingly subsampled. If unspecified, all dimensions will be considered event dims and no subsampling will be performed.

Returns:

A constrained parameter. The underlying unconstrained parameter is accessible via pyro.param(...).unconstrained(), where .unconstrained is a weakref attribute.

Return type:

torch.Tensor

calipy.primitives.sample(name, dist, dist_dims, observations=None, subsample_index=None, vectorizable=True)

Flexible sampling function handling multiple plates and four cases based on obs and subsample_index.

Parameters:

  • name (str) – Base name for the sample site.

  • dist (pyro.distributions.Distribution) – The distribution to sample from.

  • dist_dims (list of CalipyDim objects) – The dimensions of the sample from the distribution; need to contain batch_dims as subset.

  • vectorizable (bool, optional) – If True, uses vectorized sampling. If False, uses sequential sampling. Default is True.

  • obs (CalipyIO or None, optional) – Observations wrapped in CalipyIO. If provided, sampling is conditioned on these observations.

  • subsample_index (list of torch.Tensor or None, optional) – Subsample indices for each plate dimension. If provided, sampling is performed over these indices.

Returns:

A CalipyTensor sample being tracked by gradient tape.

Return type:

CalipyTensor

Example usage:

# Investigate 2D noise ------------------------------------------------
#
# i) Imports and definitions
...