torch_openreml.covariance.UnconstrainedMatrix

class torch_openreml.covariance.UnconstrainedMatrix(n, param_specs=None)

Bases: Matrix

Full symmetric covariance matrix parameterised by lower-triangular entries.

The matrix is built from the lower triangle (including the diagonal), then mirrored to the upper triangle to ensure symmetry:

\[\begin{split}\symbf{V}_{ij} = \begin{cases} \theta_{ij} & i \ge j \\ \theta_{ji} & i < j \end{cases}\end{split}\]

Diagonal entries (\(i = j\)) are transformed to positive values via TransformExpPow2 by default. Off-diagonal entries (\(i > j\)) are unconstrained and use TransformIdentity.

Note

This parameterisation ensures symmetry but does not guarantee positive definiteness. For a positive-definite covariance matrix, consider a Cholesky-based parameterisation.

Initialize an unconstrained symmetric matrix of size n x n.

By default, the matrix has \(n(n+1)/2\) free parameters: one for each lower-triangular entry. Diagonal entries are parameterised on the positive real line (via TransformExpPow2); off-diagonal entries are unconstrained (via TransformIdentity).

Parameters:

• n (int) – Matrix dimension.

• param_specs (dict) – Parameter specifications. Keys should be strings representing parameter names. Values should be dictionaries containing the specification for each parameter. Each specification dictionary should contain the keys "fixed", "default", and "trans", representing whether the parameter is fixed or free (bool), the default value (1D torch.Tensor), and the transform (Transform), respectively.

Example:

import torch
from torch_openreml.covariance import UnconstrainedMatrix

mat = UnconstrainedMatrix(3)
mat

UnconstrainedMatrix(shape=(3, 3), param_specs={'sigma^2_0_0': {'fixed': False, 'default': tensor([0.]), 'trans': TransformExpPow2()}, ..., 'sigma^2_2_2': {'fixed': False, 'default': tensor([0.]), 'trans': TransformExpPow2()}})

free_params = torch.tensor([0.0, 0.5, 1.0, 0.2, -0.3, 0.4])
mat(free_params)

tensor([[ 1.0000,  0.5000,  0.2000],
        [ 0.5000,  7.3891, -0.3000],
        [ 0.2000, -0.3000,  2.2255]])

mat.grad(free_params)

(tensor([[[ 2.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  0.0000]],
 
         [[ 0.0000,  1.0000,  0.0000],
          [ 1.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  0.0000]],
 
         [[ 0.0000,  0.0000,  0.0000],
          [ 0.0000, 14.7781,  0.0000],
          [ 0.0000,  0.0000,  0.0000]],
 
         [[ 0.0000,  0.0000,  1.0000],
          [ 0.0000,  0.0000,  0.0000],
          [ 1.0000,  0.0000,  0.0000]],
 
         [[ 0.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  1.0000],
          [ 0.0000,  1.0000,  0.0000]],
 
         [[ 0.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  0.0000],
          [ 0.0000,  0.0000,  4.4511]]]),
 ['sigma^2_0_0',
  'sigma^2_1_0',
  'sigma^2_1_1',
  'sigma^2_2_0',
  'sigma^2_2_1',
  'sigma^2_2_2'])

Methods

__call__([free_params])	Construct the matrix from a flat parameter tensor.
auto_grad([free_params])	Compute the Jacobian of build() with respect to free parameters using automatic differentiation.
build_params([free_params, include_fixed, ...])	Construct the full parameter tensor from free parameters.
get_intermediates(params)	Retrieve cached intermediate computation results if still valid.
grad([free_params])	Compute the Jacobian of __call__() with respect to trainable parameters.
manual_grad([free_params])	Compute the Jacobian of __call__() with respect to trainable parameters using a closed-form analytic expression.
map_theta_to_dv(theta)	An interface compatible with torch_openreml.REML that maps parameters to the matrix Jacobian.
map_theta_to_v(theta)	An interface compatible with torch_openreml.REML that maps parameters to a matrix.
reset_intermediates()	Clear the intermediate computation cache.
set_intermediates(params, intermediates)	Cache intermediate computation results keyed by parameter hash.
trans_grad([free_params])	Compute the element-wise derivative of the free parameter transforms.

Attributes

fixed_param_defaults	Fixed parameter defaults.
fixed_param_index	Index of fixed parameters.
fixed_param_names	Fixed parameter names.
fixed_param_trans	Transforms for fixed parameters.
free_param_defaults	Free parameter defaults.
free_param_index	Index of free parameters.
free_param_names	Free parameter names.
free_param_trans	Transforms for free parameters.
num_fixed_params	Total number of fixed parameters.
num_free_params	Total number of free parameters.
num_params	Total number of parameters.
param_defaults	Parameter defaults.
param_names	Parameter names.
param_specs	Parameter specifications.
param_trans	Parameter transforms.
repr_dict	Key-value pairs used to build the string representation.
shape	Output matrix shape.

__call__(free_params=None)

Construct the matrix from a flat parameter tensor.

Must be implemented by subclasses. Implementations should convert free_params via build_params() to validate, include fixed parameters, and apply transforms before any computation.

Parameters:

free_params (torch.Tensor or dict) – Flat 1D parameter tensor or parameter dictionary. If omitted, default values are used. Default: None.

Returns:

Constructed matrix of shape shape.

Return type:

torch.Tensor

manual_grad(free_params=None)

Compute the Jacobian of __call__() with respect to trainable parameters using a closed-form analytic expression.

Parameters:

free_params (torch.Tensor or dict) – Flat 1D parameter tensor or parameter dictionary. If omitted, default values are used. Default: None.

Returns:

(grad, grad_names), where grad is a 3D tensor of shape (num_free_params, *shape) and grad_names is a list of the corresponding parameter names. Returns (None, []) if all parameters are fixed.

Return type:

tuple