dyson.util.linalg

Linear algebra.

Module Attributes

einsum(*operands[, out, optimize])	einsum(subscripts, *operands, out=None, dtype=None, order='K',
AVOID_SCIPY_EIG	Default biorthonormalisation method.

Functions

as_diagonal(matrix, ndim)	Return the diagonal of a matrix, unless it has been passed as a diagonal.
as_trace(matrix, ndim[, axis1, axis2])	Return the trace of a matrix, unless it has been passed as a trace.
biorthonormalise(left, right[, transpose, ...])	Biorthonormalise two sets of vectors.
biorthonormalise_with_overlap(left, right, ...)	Biorthonormalise two sets of vectors with a given overlap matrix.
block_diag(*arrays)	Return a block diagonal matrix from a list of arrays.
concatenate_paired_vectors(vectors, size)	Concatenate vectors that are partitioned into two spaces, the first of which is common.
eig(matrix[, hermitian, overlap])	Compute the eigenvalues and eigenvectors of a matrix.
eig_lr(matrix[, hermitian, overlap])	Compute the eigenvalues and biorthogonal left- and right-hand eigenvectors of a matrix.
hermi_sum(matrix)	Return the sum of a matrix with its Hermitian conjugate.
is_orthonormal(vectors_left[, vectors_right])	Check if a set of vectors is orthonormal.
matrix_power(matrix, power[, hermitian, ...])	Compute the power of a matrix via the eigenvalue decomposition.
null_space_basis(matrix[, threshold, hermitian])	Find a basis for the null space of a matrix.
orthonormalise(vectors[, transpose])	Orthonormalise a set of vectors.
rotate_subspace(vectors, rotation)	Rotate the subspace of a set of vectors.
scaled_error(matrix1, matrix2[, ord])	Return the scaled error between two matrices.
set_subspace(vectors, subspace)	Set the subspace of a set of vectors.
unit_vector(size, index[, dtype])	Return a unit vector of size size with a 1 at index index.
unpack_vectors(vector)	Unpack a block vector in the dyson convention.

dyson.util.linalg.einsum(*operands, out=None, optimize=True, **kwargs)

Flag to avoid using scipy.linalg.eig() and scipy.linalg.eigh().

On some platforms, mixing numpy and scipy eigenvalue solvers can lead to performance issues, likely from repeating warm-up overhead from conflicting BLAS and/or LAPACK libraries.

dyson.util.linalg.AVOID_SCIPY_EIG: bool = True

Default biorthonormalisation method.

dyson.util.linalg.is_orthonormal(vectors_left: Array, vectors_right: Array | None = None) → bool

Check if a set of vectors is orthonormal.

Parameters:

• vectors_left – The left set of vectors to be checked.

• vectors_right – The right set of vectors to be checked. If None, use the left vectors.

Returns:

A boolean array indicating whether each vector is orthonormal.

dyson.util.linalg.orthonormalise(vectors: Array, transpose: bool = False) → Array

Orthonormalise a set of vectors.

Parameters:

• vectors – The set of vectors to be orthonormalised.

• transpose – Whether to transpose the vectors before and after orthonormalisation.

Returns:

The orthonormalised set of vectors.

dyson.util.linalg.biorthonormalise_with_overlap(left: Array, right: Array, overlap: Array, method: Literal['eig', 'eig-balanced', 'lu'] = 'lu') → tuple[Array, Array]

Biorthonormalise two sets of vectors with a given overlap matrix.

Parameters:

• left – The left set of vectors.

• right – The right set of vectors.

• overlap – The overlap matrix to be used for biorthonormalisation.

• method – The method to use for biorthonormalisation. See biorthonormalise() for available methods.

Returns:

The biorthonormalised left and right sets of vectors.

See also

biorthonormalise() for details on the available methods.

dyson.util.linalg.biorthonormalise(left: Array, right: Array, transpose: bool = False, method: Literal['eig', 'eig-balanced', 'lu'] = 'lu') → tuple[Array, Array]

Biorthonormalise two sets of vectors.

Parameters:

• left – The left set of vectors.

• right – The right set of vectors.

• transpose – Whether to transpose the vectors before and after biorthonormalisation.

• method – The method to use for biorthonormalisation. The "eig" method uses the eigenvalue decomposition, the "eig-balanced" method uses the same decomposition but applies a balanced transformation to the left- and right-hand vectors, and the "lu" method uses the LU decomposition.

Returns:

The biorthonormalised left and right sets of vectors.

See also

biorthonormalise_with_overlap() for a more general method that allows for a custom overlap matrix.

dyson.util.linalg.eig(matrix: Array, hermitian: bool = True, overlap: Array | None = None) → tuple[Array, Array]

Compute the eigenvalues and eigenvectors of a matrix.

Parameters:

• matrix – The matrix to be diagonalised.

• hermitian – Whether the matrix is hermitian.

• overlap – An optional overlap matrix to be used for the eigenvalue decomposition.

Returns:

The eigenvalues and eigenvectors of the matrix.

dyson.util.linalg.eig_lr(matrix: Array, hermitian: bool = True, overlap: Array | None = None) → tuple[Array, tuple[Array, Array]]

Compute the eigenvalues and biorthogonal left- and right-hand eigenvectors of a matrix.

Parameters:

• matrix – The matrix to be diagonalised.

• hermitian – Whether the matrix is hermitian.

• overlap – An optional overlap matrix to be used for the eigenvalue decomposition.

Returns:

The eigenvalues and biorthogonal left- and right-hand eigenvectors of the matrix.

dyson.util.linalg.null_space_basis(matrix: Array, threshold: float = 1e-11, hermitian: bool | None = None) → tuple[Array, Array]

Find a basis for the null space of a matrix.

Parameters:

• matrix – The matrix for which to find the null space.

• threshold – Threshold for removing vectors to obtain the null space.

• hermitian – Whether the matrix is hermitian. If None, infer from the matrix.

Returns:

The basis for the null space.

Note

The full vector space may not be biorthonormal.

dyson.util.linalg.matrix_power(matrix: Array, power: int | float, hermitian: bool = True, threshold: float = 1e-10, return_error: bool = False, ord: int | float = inf) → tuple[Array, float | None]

Compute the power of a matrix via the eigenvalue decomposition.

Parameters:

• matrix – The matrix to be exponentiated.

• power – The power to which the matrix is to be raised.

• hermitian – Whether the matrix is hermitian.

• threshold – Threshold for removing singularities.

• return_error – Whether to return the error in the power.

• ord – The order of the norm to be used for the error.

Returns:

The matrix raised to the power, and the error if requested.

dyson.util.linalg.hermi_sum(matrix: Array) → Array

Return the sum of a matrix with its Hermitian conjugate.

Parameters:

matrix – The matrix to be summed with its hermitian conjugate.

Returns:

The sum of the matrix with its hermitian conjugate.

dyson.util.linalg.scaled_error(matrix1: Array, matrix2: Array, ord: int | float = inf) → float

Return the scaled error between two matrices.

Parameters:

• matrix1 – The first matrix.

• matrix2 – The second matrix.

• ord – The order of the norm to be used for the error.

Returns:

The scaled error between the two matrices.

dyson.util.linalg.as_trace(matrix: Array, ndim: int, axis1: int = -2, axis2: int = -1) → Array

Return the trace of a matrix, unless it has been passed as a trace.

Parameters:

• matrix – The matrix to be traced.

• ndim – The number of dimensions of the matrix before the trace.

• axis1 – The first axis of the trace.

• axis2 – The second axis of the trace.

Returns:

The trace of the matrix.

dyson.util.linalg.as_diagonal(matrix: Array, ndim: int) → Array

Return the diagonal of a matrix, unless it has been passed as a diagonal.

Parameters:

• matrix – The matrix to be diagonalised.

• ndim – The number of dimensions of the matrix before the diagonal.

Returns:

The diagonal of the matrix.

dyson.util.linalg.unit_vector(size: int, index: int, dtype: str = 'float64') → Array

Return a unit vector of size size with a 1 at index index.

Parameters:

• size – The size of the vector.

• index – The index of the vector.

• dtype – The data type of the vector.

Returns:

The unit vector.

dyson.util.linalg.concatenate_paired_vectors(vectors: list[Array], size: int) → Array

Concatenate vectors that are partitioned into two spaces, the first of which is common.

Parameters:

• vectors – The vectors to be concatenated.

• size – The size of the first space.

Returns:

The concatenated vectors.

Note

The concatenation is

\[\begin{split}\begin{pmatrix} p_1 & p_2 & \cdots & p_n \\ a_1 & & & \\ & a_2 & & \\ & & \ddots & \\ & & & a_n \\ \end{pmatrix} = \begin{pmatrix} p_1 \\ a_1 \end{pmatrix} + \begin{pmatrix} p_2 \\ a_2 \end{pmatrix} + \cdots + \begin{pmatrix} p_n \\ a_n \end{pmatrix}\end{split}\]

where \(p_i\) are the vectors in the first space and \(a_i\) are the vectors in the second space.

This is useful for combining couplings between a common physical space and a set of auxiliary degrees of freedom.

dyson.util.linalg.unpack_vectors(vector: Array) → tuple[Array, Array]

Unpack a block vector in the dyson convention.

Parameters:

vector – The vector to be unpacked. The vector should either be a 2D array (n, m) or a 3D array (2, n, m). The latter case is non-Hermitian.

Returns:

Left- and right-hand vectors.

dyson.util.linalg.block_diag(*arrays: Array) → Array

Return a block diagonal matrix from a list of arrays.

Parameters:

arrays – The arrays to be combined into a block diagonal matrix.

Returns:

The block diagonal matrix.

dyson.util.linalg.set_subspace(vectors: Array, subspace: Array) → Array

Set the subspace of a set of vectors.

Parameters:

• vectors – The vectors to be set.

• subspace – The subspace to be applied to the vectors.

Returns:

The vectors with the subspace applied.

Note

This operation is equivalent to applying vectors[: n] = subspace where n is the size of both dimensions in the subspace.

dyson.util.linalg.rotate_subspace(vectors: Array, rotation: Array) → Array

Rotate the subspace of a set of vectors.

Parameters:

• vectors – The vectors to be rotated.

• rotation – The rotation matrix to be applied to the vectors.

Returns:

The rotated vectors.

Note

This operation is equivalent to applying vectors[: n] = rotation @ vectors[: n] where n is the size of both dimensions in the rotation matrix.