expand_outer

hypercoil.functional.matrix.expand_outer(L: Tensor, R: Tensor | None = None, C: Tensor | None = None, symmetry: Literal['cross', 'skew'] | None = None) → Tensor

Multiply out a left and a right generator matrix as an outer product.

The rank of the output is limited according to the inner dimensions of the input generators. This approach can be used to produce a low-rank output or to share the generators’ parameters across the rows and columns of the output matrix.

Dimension:

L : \((*, H, rank)\)

H denotes the height of the expanded matrix, and rank denotes its maximum rank. * denotes any number of preceding dimensions.

R : \((*, W, rank)\)

W denotes the width of the expanded matrix.

C : \((*, rank, rank)\)

As above.

Output : \((*, H, W)\)

As above.

Parameters:

LTensor

Left generator of a low-rank matrix (\(L R^\intercal\)).

RTensor or None (default None)

Right generator of a low-rank matrix (\(L R^\intercal\)). If this is None, then the output matrix is symmetric \(L L^\intercal\).

CTensor or None (default None)

Coupling term. If this is specified, each outer product expansion is modulated by a corresponding coefficient in the coupling matrix. Providing a vector is equivalent to providing a diagonal coupling matrix. This term can, for instance, be used to toggle between positive and negative semidefinite outputs.

symmetry'cross', 'skew', or None (default None)

Symmetry constraint imposed on the generated low-rank template matrix.

• cross enforces symmetry by replacing the initial expansion with the average of the initial expansion and its transpose, \(\frac{1}{2} \left( L R^\intercal + R L^\intercal \right)\)

• skew enforces skew-symmetry by subtracting from the initial expansion its transpose, \(\frac{1}{2} \left( L R^\intercal - R L^\intercal \right)\)

• Otherwise, no explicit symmetry constraint is imposed. Symmetry can also be enforced by passing None for R or by passing the same input for R and L. (This approach also guarantees that the output is positive semidefinite.)