forte2.props.mutual_correlation
===============================

.. py:module:: forte2.props.mutual_correlation




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

.. py:class:: MutualCorrelationAnalysis(solver, root=0, sub_solver_index=0)

   
   Performs a mutual correlation analysis.


   :Parameters:

       **solver** : forte2 solver object of type ActiveSpaceSolver
           The solver from which to extract the RDMs.

       **root** : int, optional
           The root index for which to perform the analysis. Default is 0.

       **sub_solver_index** : int, optional
           The index of the sub-solver within the active space solver. Default is 0.

   :Attributes:

       **total_correlation** : float
           Total correlation measure.

       **M1** : NDArray
           Single orbital correlation measure.

       **M2** : NDArray
           Dyad mutual correlation measure.

       **M3** : NDArray
           Triad mutual correlation measure.

       **M4** : NDArray
           Tetrad mutual correlation measure.

       **Q** : NDArray
           Orthogonal transformation matrix to form the maximally correlated orbitals.










   .. rubric:: Notes

   This analysis expects an active space solver with the following API
   on the selected sub-solver `solver.sub_solvers[sub_solver_index]`:

   - make_sd_1rdm(root) -> tuple[NDArray, NDArray]
           Returns (γa, γb) spin-dependent 1-RDMs with shape (norb, norb) each.
   - make_sd_2rdm(root) -> tuple[NDArray, NDArray, NDArray]
           Returns (γaa, γab, γbb) spin-dependent 2-RDMs.
           γaa and γbb are packed (lower-triangular pair indices) and are
           converted to full (norb, norb, norb, norb) tensors via
           `cpp_helpers.packed_tensor4_to_tensor4`. γab is already full with shape
           (norb, norb, norb, norb).

   Derived tensors and outputs:
   - Γ1 = γa + γb with shape (norb, norb).
   - Cumulants λaa, λab, λbb with shape (norb, norb, norb, norb) each.
   - total_correlation: scalar.
   - M1: shape (norb,), orbital correlation.
   - M2: shape (norb, norb), dyad mutual correlations (diagonal zeroed).
   - M3: shape (norb, norb, norb), triad mutual correlations (entries with
       any repeated indices are zeroed).
   - M4: shape (norb, norb, norb, norb), tetrad mutual correlations (entries
       with any repeated pair of indices are zeroed).
   - Q: shape (norb, norb), real orthogonal matrix from expm of a real
       antisymmetric generator. Stored after `optimize_orbitals`.

   Notes:
   - This implementation targets the non-relativistic case.



   ..
       !! processed by numpydoc !!

   .. py:attribute:: Q
      :value: None



   .. py:attribute:: active_mo_indices


   .. py:attribute:: Γ1


   .. py:attribute:: λaa


   .. py:attribute:: λab


   .. py:attribute:: λbb


   .. py:method:: mutual_correlation_matrix_summary(print_threshold: float = 0.00075) -> str

      
      Generates a summary of the mutual correlation matrix M2.


      :Parameters:

          **print_threshold** : float, optional, default=7.5e-4
              Only values greater than this threshold are printed.



      :Returns:

          **summary** : str
              A formatted string summarizing the mutual correlation matrix M2.











      ..
          !! processed by numpydoc !!


   .. py:method:: optimize_orbitals(k=2, random_guess_noise=0.001, method='L-BFGS-B', seed: int | None = None) -> numpy.typing.NDArray

      
      Optimize the orbitals by maximizing the sum of the k-th power of the mutual correlation M2.


      :Parameters:

          **k** : int, optional, default=2
              The power to which to raise the mutual correlation values in the cost function.

          **random_guess_noise** : float, optional, default=0.001
              The amplitude of the random noise to add to the initial guess for the antisymmetric matrix.

          **method** : str, optional, default="L-BFGS-B"
              The optimization method to use.

          **seed** : int | None, optional
              Seed for the random initial antisymmetric matrix. If None, a
              nondeterministic seed is used (different results across runs).



      :Returns:

          **Q** : NDArray
              The optimized orthogonal transformation matrix.











      ..
          !! processed by numpydoc !!