torch_openreml.covariance.LowerTriangularMatrix¶

class torch_openreml.covariance.LowerTriangularMatrix(n, m, param_specs=None)[source]¶

Bases: Matrix

Lower triangular matrix parameterised by its lower-triangular entries.

The matrix has free parameters for all entries on or below the diagonal (i.e., \(j \le i\) and \(j < m\)). Entries above the diagonal are fixed at zero:

\[\begin{split}\symbf{L}_{ij} = \begin{cases} \theta_{ij} & i \ge j \;\text{and}\; j < m \\ 0 & i < j \end{cases}\end{split}\]

All parameters (including diagonal entries) are unconstrained and use TransformIdentity by default.

Initialize a lower triangular matrix of size n x m.

By default, the matrix has free parameters for all entries on or below the diagonal, all using TransformIdentity (unconstrained).

Parameters:

n (int) – Number of rows.
m (int) – Number of columns.
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 LowerTriangularMatrix

mat = LowerTriangularMatrix(3, 2)
mat

LowerTriangularMatrix(shape=(3, 2), param_specs={'L_0_0': {'fixed': False, 'default': tensor([1.]), 'trans': TransformIdentity()}, ..., 'L_2_1': {'fixed': False, 'default': tensor([1.]), 'trans': TransformIdentity()}})

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

tensor([[ 0.0000,  0.0000],
        [ 0.5000,  1.0000],
        [ 0.2000, -0.3000]])

mat.grad(free_params)

(tensor([[[1., 0.],
          [0., 0.],
          [0., 0.]],
 
         [[0., 0.],
          [1., 0.],
          [0., 0.]],
 
         [[0., 0.],
          [0., 1.],
          [0., 0.]],
 
         [[0., 0.],
          [0., 0.],
          [1., 0.]],
 
         [[0., 0.],
          [0., 0.],
          [0., 1.]]]),
 ['L_0_0', 'L_1_0', 'L_1_1', 'L_2_0', 'L_2_1'])

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)[source]¶

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)[source]¶

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