forte2.helpers.matrix_functions#
Module Contents#
- forte2.helpers.matrix_functions.MACHEPS = 1e-14#
- forte2.helpers.matrix_functions.print_metric_info(info, description=None)#
- forte2.helpers.matrix_functions.invsqrt_matrix(M, rtol=1e-07, precomp=None)#
Compute the inverse square root of a symmetric (Hermitian) matrix A.
- Parameters:
- MNDArray
A symmetric matrix (must be positive semi-definite).
- rtolfloat, optional, default=1e-7
Relative threshold for treating eigenvalues as zero. Eigenvalues smaller than rtol * max_eigenvalue will be discarded in the computation of the inverse square root.
- precomptuple(NDArray, NDArray, dict), optional
If provided, should be the output of _eigh_metric_kernel(M, rtol=rtol), i.e., (eigenvalues, eigenvectors, info). This allows reusing the eigen-decomposition if it has already been computed for the same matrix M with the same rtol, which can be more efficient if multiple functions need to use the same decomposition.
- Returns:
- invsqrt_MNDArray
The inverse square root of A.
- sqrt_MNDArray
The square root of A.
- infodict
A dictionary containing additional information from the eigen-decomposition, including: - “max_eigenvalue”: The largest eigenvalue of M. - “min_eigenvalue”: The smallest eigenvalue of M. - “condition_number”: The condition number of M (max_eigenvalue / min_eigenvalue). - “n_discarded”: The number of eigenvalues discarded due to being below the threshold. - “n_kept”: The number of eigenvalues kept. - “largest_discarded_eigenvalue”: The largest eigenvalue that was discarded. - “smallest_kept_eigenvalue”: The smallest eigenvalue that was kept.
- forte2.helpers.matrix_functions.canonical_orth(S, rtol=1e-07, precomp=None)#
Compute the canonical orthogonalization given the metric matrix S.
- Parameters:
- SNDArray
Metric matrix (must be positive semi-definite).
- rtolfloat, optional, default=1e-7
Relative threshold t for which values below t * max_eigenvalue are treated as zero.
- precomptuple(NDArray, NDArray, dict), optional
If provided, should be the output of _eigh_metric_kernel(S, rtol=rtol), i.e., (eigenvalues, eigenvectors, info). This allows reusing the eigen-decomposition if it has already been computed for the same matrix S with the same rtol, which can be more efficient if multiple functions need to use the same decomposition.
- Returns:
- XNDArray
The (possibly rectangular) canonical orthogonalization matrix X, such that
X.T @ S @ X = I.- Xm1NDArray
The inverse of the orthogonalization matrix, such that
Xm1 @ X = I.- infodict
A dictionary containing additional information, including: - “max_eigenvalue”: The largest eigenvalue of S. - “min_eigenvalue”: The smallest eigenvalue of S. - “condition_number”: The condition number of S (max_eigenvalue / min_eigenvalue). - “n_discarded”: The number of eigenvalues discarded due to being below the threshold. - “n_kept”: The number of eigenvalues kept. - “largest_discarded_eigenvalue”: The largest eigenvalue that was discarded. - “smallest_kept_eigenvalue”: The smallest eigenvalue that was kept.
- Raises:
- ValueError
If the matrix S is not positive semi-definite.
Notes
The canonical orthogonalization is defined as follows:
\[\mathbf{X}_{\eta} = \mathbf{U}_{\eta} \mathbf{s}^{-1/2}_{\eta},\]where \(\mathbf{U}_{\eta}\) are the eigenvectors of \(\mathbf{S}\) corresponding to eigenvalues larger than \(\eta\), \(\mathbf{s}^{-1/2}_{\eta}\) is a diagonal matrix containing the inverse square roots of those eigenvalues, and \(\eta=\mathrm{rtol} \times \max(\mathbf{s})\) is the threshold for discarding small eigenvalues.
The resulting matrix \(\mathbf{X}_{\eta}\) satisfies \(\mathbf{X}_{\eta}^{\dagger} \mathbf{S} \mathbf{X}_{\eta} = \mathbf{I}_{\eta}\). If any eigenvalues are discarded, the resulting \(\mathbf{X}_{\eta}\) will be rectangular with fewer columns than rows, and the inverse \(\mathbf{X}_{\eta}^{-1}\) will be a left-inverse satisfying \(\mathbf{X}_{\eta}^{-1} \mathbf{X}_{\eta} = \mathbf{I}_{\eta}\) but not necessarily \(\mathbf{X}_{\eta} \mathbf{X}_{\eta}^{-1} = \mathbf{I}\).
- forte2.helpers.matrix_functions.eigh_gen(A, B, rtol=1e-07, mode='canonical')#
Solve the generalized eigenvalue problem
A @ x = lambda * B @ x.- Parameters:
- ANDArray
The matrix A.
- BNDArray
The metric matrix B (must be positive semi-definite). If identity, the problem reduces to a standard eigenvalue problem.
- rtolfloat, optional, default=1e-7
Relative threshold for removing linear dependencies, passed to the orthogonalization step.
- modestr, optional, default=”canonical”
“auto”: Automatically choose the orthogonalization method based on the condition number of B. If the inverse condition number of B is larger than rtol, use symmetric orthogonalization; otherwise, use canonical orthogonalization.
“canonical”: Always use canonical orthogonalization.
“symmetric”: Always use symmetric orthogonalization.
- Returns:
- tuple(NDArray, NDArray, dict)
A tuple containing the eigenvalues, eigenvectors, and additional information.
- forte2.helpers.matrix_functions.givens_rotation(A, c, s, i, j, column=True)#
Apply a Givens rotation to the matrix A.
- Parameters:
- ANDArray
The matrix to apply the rotation to.
- cfloat
The cosine of the rotation angle.
- sfloat
The sine of the rotation angle.
- iint
The index of the first row/column to rotate.
- jint
The index of the second row/column to rotate.
- columnbool, optional, default=True
If True, apply the rotation to columns; if False, to rows.
- Returns:
- NDArray
The rotated matrix.
- forte2.helpers.matrix_functions.cholesky_wrapper(M, tol)#
Perform a Cholesky decomposition with complete pivoting, works with any symmetric positive semi-definite matrix.
- Parameters:
- MNDArray
The matrix to decompose.
- tolfloat
The tolerance for the decomposition.
- Returns:
- BNDArray
The Cholesky factor such that
B.T @ B = M.
- forte2.helpers.matrix_functions.block_diag_2x2(M, complex=True)#
Return a block-diagonal matrix with two copies of M on the diagonal. Note this is not a function to block-diagonalize a matrix.
- Parameters:
- MNDArray
The matrix to convert, shape (n, n).
- complexbool, optional, default=True
If True, the output will be explicitly converted to complex type.
- Returns:
- NDArray
The block-diagonal matrix, shape (2n, 2n).
- forte2.helpers.matrix_functions.random_unitary(size, cmplx=True, rng=None, rotation=True)#
Generate a random orthogonal/unitary matrix of given size.
- Parameters:
- sizeint
The size of the matrix.
- cmplxbool, optional, default=True
If True, generate a complex unitary matrix; otherwise, generate a real orthogonal matrix.
- rngnp.random.Generator, optional
A random number generator for reproducibility.
- rotationbool, optional, default=True
If True, return a proper rotation (determinant = 1) by adjusting the sign of the last column if necessary. If False, the determinant may be -1.
- Returns:
- NDArray
A random unitary (or orthogonal) matrix of shape (size, size). It is guaranteed to be uniformly distributed over the appropriate group ((S)O(n) or (S)U(n)).
Notes
The QR of a random (not necessarily Hermitian) matrix with normally distributed entries can give an orthogonal/unitary matrix. However, due to the way QR works, the distribution of the resulting matrices is not uniform over O(n) or U(n). To ensure a uniform distribution (Haar measure), we need to adjust the signs/phases of the columns based on the diagonal of R. This method is commonly used to generate random unitary/orthogonal matrices that are uniformly distributed over the appropriate group (O(n) or U(n)). These matrices will have determinant ±1 for O(n) and determinant with magnitude 1 and arbitrary phase for U(n). For special groups (determinant = 1), we can further adjust the sign/phase of a single column (here chosen as the first column) to ensure the determinant is exactly 1, which gives us a uniform distribution over SO(n) or SU(n)). See more at https://case.edu/artsci/math/mwmeckes/elizabeth/Meckes_SAMSI_Lecture2.pdf
- forte2.helpers.matrix_functions.i_sigma_dot(scalar, x, y, z)#
Construct the matrix i * (I2, sigma_x, sigma_y, sigma_z) dot (scalar, x, y, z).
- Parameters:
- scalarndarray
The scalar component.
- xndarray
The x component.
- yndarray
The y component.
- zndarray
The z component.
- Returns:
- NDArray
The resulting matrix, with double the dimensions of the input arrays.