pymoto.DyadicMatrix

class pymoto.DyadicMatrix(u: Iterable = None, v: Iterable = None, shape: Tuple[int, int] = (-1, -1))

Efficient storage for dyadic or rank-N matrix

Stores only the vectors instead of creating a full rank-N matrix \(\mathbf{A} = \sum_k^N \mathbf{u}_k\otimes\mathbf{v}_k\) or in index notation \(A_{ij} = \sum_k^N u_{ki} v_{kj}\). This saves a lot of memory for low \(N\).

__init__(u: Iterable = None, v: Iterable = None, shape: Tuple[int, int] = (-1, -1))

Initialize a DyadicMatrix

Parameters:

u (optional) – List of vectors.
v (optional) – List of vectors (if u is given and v not, a symmetric dyad is assumed with v = u).
shape (optional) – Shape of the matrix

Methods

`__init__`([u, v, shape])	Initialize a DyadicMatrix
`add_dyad`(u[, v, fac])	Adds a list of vectors to the dyad carrier
`conj`()	Returns (a deep copied) complex conjugate of the DyadicMatrix
`contract`([mat, rows, cols])	Performs a number of contraction operations using the DyadicMatrix
`contract_multi`(mats[, dtype])	Faster version of contraction for a list of sparse matrices
`copy`()	Returns a deep copy of the DyadicMatrix
`diagonal`([k])	Returns the diagonal of the DyadicMatrix matrix
`dot`(other)	Inner product
`iscomplex`()	Check if the DyadicMatrix is of complex type
`max`()
`min`()
`toarray`()	Convert to array, same as todense().
`todense`()	Returns a full (dense) matrix from the DyadicMatrix matrix
`transpose`()	Returns a deep copy of the transposed DyadicMatrix matrix

Attributes

`T`	Shorthand transpose (returns deep copy)
`imag`	Returns a deep copy of the imaginary part of the DyadicMatrix
`n_dyads`	Number of dyads stored
`ndim`
`real`	Returns a deep copy of the real part of the DyadicMatrix
`shape`	The shape of the matrix (nrows, ncols)
`size`	Size of the matrix (nrows x ncols)

ndim = 2

property shape: The shape of the matrix (nrows, ncols)

property size: Size of the matrix (nrows x ncols)

property n_dyads: Number of dyads stored

add_dyad(u: Iterable, v: Iterable = None, fac: float = None)

Adds a list of vectors to the dyad carrier

Checks for conforming sizes of u and v. The data inside the vectors are copied.

It is possible to add higher-dimensional matrices, which are summed along all but the last dimension. The effect of this is that also cross-terms are added, e.g. adding the matrices \(\mathbf{U}=[\mathbf{u}_1, \mathbf{u}_2, \mathbf{u}_3]\) and \(\mathbf{V}=[\mathbf{v}_1, \mathbf{v}_2, \mathbf{v}_3]\) results in \((\mathbf{u}_1+\mathbf{u}_2+\mathbf{u}_3)\otimes(\mathbf{v}_1+\mathbf{v}_2+\mathbf{v}_3)\) being added to the DyadicMatrix.

Parameters:

u – List of vectors
v – List of vectors [Optional: If not given, use v=u]
fac – Optional multiplication factor

Returns:

self

copy(): Returns a deep copy of the DyadicMatrix

conj(): Returns (a deep copied) complex conjugate of the DyadicMatrix

property real: Returns a deep copy of the real part of the DyadicMatrix

property imag: Returns a deep copy of the imaginary part of the DyadicMatrix

min()

max()

contract(mat: ndarray[tuple[Any, ...], dtype[_ScalarT]] | spmatrix = None, rows: ndarray[tuple[Any, ...], dtype[int]] = None, cols: ndarray[tuple[Any, ...], dtype[int]] = None)

Performs a number of contraction operations using the DyadicMatrix

Calculates the result(s) of the quadratic form: \(y = \sum_k \mathbf{u}_k^{\text{T}} \mathbf{B} \mathbf{v}_k\)

Examples

Contraction using identity matrix, is the sum of dot products, which is equal to the trace of the rank-N matrix:

y = A.contract() equals \(y = \text{trace}(\mathbf{A}) = \sum_k \mathbf{u}_k^{\text{T}}\mathbf{v}_k\)
Contraction using matrix B of size (N, M) calculates the quadratic form:

y = A.contract(B) equals \(y = \sum_k \mathbf{u}_k^{\text{T}} \mathbf{B} \mathbf{v}_k\)
Sliced contraction with sliced row, matrix B of size (n, M) and rows of size n:

y = A.contract(B, rows) \(y =\sum_k \mathbf{u}[\texttt{rows}]_k^{\text{T}} \mathbf{B} \mathbf{v}_k\)
Sliced contraction with sliced column, matrix B of size (N, m) and cols of size m:

y = A.contract(B, cols=cols) equals \(y = \sum_k \mathbf{u}_k^{\text{T}} \mathbf{B} \mathbf{v}[\texttt{cols}]_k\)
Sliced contraction with both sliced rows and columns, matrix B of size (n, m), rows of size n, and cols of size m:

y = A.contract(B, rows, cols) equals \(y = \sum_k \mathbf{u}[\texttt{rows}]_k^{\text{T}} \mathbf{B} \mathbf{v}[\texttt{cols}]_k\)
Batch contraction with multiple matrices in batch mode, matrix B of size (P, N, M):

y = A.contract(B) equals \(y_p = \sum_k \mathbf{u}_k^{\text{T}} \mathbf{B}_p \mathbf{v}_k\)
Batch contraction with multiple slices, matrix B of size (n, M), rows of size (P, n):

y = A.contract(B, rows) equals \(y_p = \sum_k \mathbf{u}[\texttt{rows}_p]_k^{\text{T}} \mathbf{B} \mathbf{v}_k\)
Batch contraction with multiple matrices and slices, matrix B of size (P, n, M), rows of size (P, n):

y = A.contract(B, rows) equals \(y_p = \sum_k \mathbf{u}[\texttt{rows}_p]_k^{\text{T}} \mathbf{B}_p \mathbf{v}_k\)
Batch contraction with multiple matrices, row slice, and column slice, which is used ,`e.g.`, for finite element sensitivities. Matrix B is of size (P, n, m), rows of size (P, n), and cols of size (P, m):

y = A.contract(B, rows, cols) equals \(y_p = \sum_k \mathbf{u}[\texttt{rows}_p]_k^{\text{T}} \mathbf{B}_p \mathbf{v}[\texttt{cols}_p]_k\)
Batch contractions can be extended with multiple extra batch-dimensions. For instance, matrix B of size (P, Q, R, N, M) results in y of size (P, Q, R):

y = A.contract(B) equals \(y_{pqr} = \sum_k \mathbf{u}_k^{\text{T}} \mathbf{B}_{pqr} \mathbf{v}_k\)

Parameters:

mat – The matrix to contract with (optional)
rows – Indices for the rows (optional)
cols – Indices for the columns to use (optional)

Returns:

Contraction result

contract_multi(mats: List[spmatrix], dtype=None): Faster version of contraction for a list of sparse matrices

todense(): Returns a full (dense) matrix from the DyadicMatrix matrix

toarray(): Convert to array, same as todense(). To be consistent with scipy.sparse

iscomplex(): Check if the DyadicMatrix is of complex type

diagonal(k: int = 0): Returns the diagonal of the DyadicMatrix matrix

property T: Shorthand transpose (returns deep copy)

transpose(): Returns a deep copy of the transposed DyadicMatrix matrix

dot(other): Inner product