markovflow.utils

Module containing utility functions.

Module Contents

tf_scope_fn_decorator(fn)

Decorator to wrap the function call in a name_scope of the form “.{name of function}”.

The prefix . is required because names_scopes cannot be prefixed with _.

Without this some function names (such as private functions) would raise an error.

tf_scope_class_decorator(cls)

Decorator to wrap all the methods in a class in a name_scope of the form “{name of class}.{name of method}”.

Do not decorate the top level; TensorBoard renders badly if there is only one block.

block_diag(matrices: List[tf.Tensor]) → tf.Tensor

Construct block diagonal matrices from a list of batched 2D tensors.

Parameters

matrices – A list of tensors with shape [..., Nᵢ, Mᵢ]. That is, a list of matrices with the same batch dimension.

Returns

A matrix with the input matrices stacked along its main diagonal, with shape [..., ∑ᵢ,Nᵢ, ∑ᵢ,Mᵢ].

to_delta_time(time_points: tf.Tensor) → tf.Tensor

Convert a tensor of time points to differences between the times. This function returns:

\[Δtₖ = tₖ₊₁ - tₖ\]

Time points must be a strictly increasing vector, for example:

\[tₖ₊₁ > tₖ, so Δtₖ > 0\]

Parameters

time_points – A tensor \(tₖ\) with shape [..., a].

Returns

A tensor \(Δtₖ\) with shape [..., a - 1].

Raises

InvalidArgumentError – Raises if \(Δtₖ ≤ 0\).

kronecker_product(matrices: List[tf.Tensor]) → tf.Tensor

Return the tensor representing the Kronecker product of the argument matrices.

Parameters

matrices – The list of matrices to compute the Kronecker product from.

Returns

The Kronecker product tensor.

augment_square_matrix(matrix: tf.Tensor, extra_dim: int, fill_zeros: bool = False) → tf.Tensor

Augment a square matrix to match state_dim + extra_dim, where state_dim is the dimensionality of the inner square matrix of matrix.

Effectively it creates a block diagonal by padding (if necessary) with an identity or zeros:

\[matrix -> [[matrix, 0s], [0s, (I or 0s)]]\]

Parameters

• matrix – A tensor with shape [..., state_dim, state_dim].

• extra_dim – The extra dimension we want to augment it with. If extra_dim is \(0\), the matrix remains unaltered.

• fill_zeros – Whether to fill with zeros or identity.

Returns

A tensor with shape [..., max_dim, max_dim], where max_dim = state_dim + extra_dim.

augment_matrix(matrix: tf.Tensor, extra_dim: int) → tf.Tensor

Augment a non-square matrix so that the last dimension becomes state_dim + extra_dim, where state_dim is the size of the last dimension of the matrix.

Effectively it expands the matrix (if necessary) with zeros in the last dimension to match max_dim = state_dim + extra_dim. In other words:

\[matrix -> [matrix, 0s]\]

Parameters

• matrix – A tensor with shape [..., state_dim].

• extra_dim – The extra dimension we want to augment it with. If extra_dim is \(0\) the matrix remains unaltered.

Returns

A tensor with shape [..., max_dim], where max_dim = state_dim + extra_dim.

batch_base_conditional(Kmn: tf.Tensor, Kmm: tf.Tensor, Knn: tf.Tensor, f: tf.Tensor, *, q_sqrt: Optional[tf.Tensor] = None, white=False)

Given a g1_n and g2_n, and distributions ps and qs such that

p_n(g2_n) = N(g2_n; 0, Kmm) (independent of n) p_n(g1_n) = N(g1; 0, knn) p_n(g1_n | g2_n) = N(g1_n; knm (Kmm⁻¹) g2_n, knn - knm (Kmm⁻¹) kmn)

And

q_n(g2_n) = N(g2_n; f_n, q_sqrt_n q_sqrt_nᵀ)

This method computes the means and (co)variances of

q_n(g1_n) = ∫ q_n(g2_n) p_n(g1_n| g2_n)

Parameters

• Kmn – [M, …, N]

• Kmm – [M, M]

• Knn – […, N, N] or N

• f – [M, N]

• q_sqrt – If this is a Tensor, it must have shape [N, M, M] (lower triangular) or [M, N] (diagonal)

• white – bool

Returns

[N,], [N,]