forte2.helpers.matrix_functions
===============================

.. py:module:: forte2.helpers.matrix_functions






Module Contents
---------------

.. py:data:: MACHEPS
   :value: 1e-14


.. py:function:: invsqrt_matrix(M, tol=1e-07)

   
   Compute the inverse square root of a symmetric (Hermitian) matrix A.
   Small eigenvalues below 'tol' are treated as zero (pseudo-inverse style).


   :Parameters:

       **M** : NDArray
           A symmetric matrix (must be positive semi-definite).

       **tol** : float, optional, default=1e-7
           Eigenvalue threshold below which values are treated as zero.



   :Returns:

       **invsqrt_M** : NDArray
           The inverse square root of A.




   :Raises:

       ValueError
           If the matrix M is not positive semi-definite.







   ..
       !! processed by numpydoc !!

.. py:function:: canonical_orth(S, tol=1e-07)

   
   Compute the canonical orthogonalization given the metric matrix S.


   :Parameters:

       **S** : NDArray
           Metric matrix (must be positive semi-definite).

       **tol** : float, optional, default=1e-7
           Eigenvalue threshold below which values are treated as zero.



   :Returns:

       **X** : NDArray
           The (possibly rectangular) canonical orthogonalization matrix X, such that ``X.T @ S @ X = I``.




   :Raises:

       ValueError
           If the matrix S is not positive semi-definite.







   ..
       !! processed by numpydoc !!

.. py:function:: eigh_gen(A, B=None, remove_lindep=True, orth_tol=1e-07, orth_method='canonical')

   
   Solve the generalized eigenvalue problem ``A @ x = lambda * B @ x``.


   :Parameters:

       **A** : NDArray
           The matrix A.

       **B** : NDArray
           The matrix B. If None, the identity matrix is used.

       **remove_lindep** : bool, optional, default=True
           If True, perform orthogonalization to remove linear dependencies, else use ``sp.linalg.eigh``.

       **orth_tol** : float, optional, default=1e-7
           Eigenvalue threshold below which values are treated as zero.

       **orth_method** : str, optional, default="canonical"
           Orthogonalization method. Options are "canonical" or "symmetric".
           "canonical" should be used when there are linear dependencies in the basis functions.



   :Returns:

       tuple(NDArray, NDArray)
           A tuple containing the eigenvalues and eigenvectors.











   ..
       !! processed by numpydoc !!

.. py:function:: givens_rotation(A, c, s, i, j, column=True)

   
   Apply a Givens rotation to the matrix A.


   :Parameters:

       **A** : NDArray
           The matrix to apply the rotation to.

       **c** : float
           The cosine of the rotation angle.

       **s** : float
           The sine of the rotation angle.

       **i** : int
           The index of the first row/column to rotate.

       **j** : int
           The index of the second row/column to rotate.

       **column** : bool, optional, default=True
           If True, apply the rotation to columns; if False, to rows.



   :Returns:

       NDArray
           The rotated matrix.











   ..
       !! processed by numpydoc !!

.. py:function:: cholesky_wrapper(M, tol)

   
   Perform a Cholesky decomposition with complete pivoting, works with any symmetric positive semi-definite matrix.


   :Parameters:

       **M** : NDArray
           The matrix to decompose.

       **tol** : float
           The tolerance for the decomposition.



   :Returns:

       **B** : NDArray
           The Cholesky factor such that ``B.T @ B = M``.











   ..
       !! processed by numpydoc !!

.. py:function:: 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:

       **M** : NDArray
           The matrix to convert, shape (n, n).

       **complex** : bool, optional, default=True
           If True, the output will be explicitly converted to complex type.



   :Returns:

       NDArray
           The block-diagonal matrix, shape (2n, 2n).











   ..
       !! processed by numpydoc !!