Add missing QEOMResult docs (qiskit-community#1037)

* Fix docstring and add deprecation messages for stds * Fix docstring and add deprecation messages for stds * Implement the commutators for SparsePauliOp and make the QEOM code rely less on QubitOperator * fix spelling * Revert "Implement the commutators for SparsePauliOp and make the QEOM code rely less on QubitOperator" This reverts commit f21487d. * Update Release note and fix spelling * Fix spelling * Add word pylintdict * Spelling releasenote * Fix spelling releasenote * Fix docstring and eigenstate error * add reference * Fix black * Update releasenotes/notes/update-qeomresult-docstring-and-pending-deprecate-mqwv-matrix-std-setters-5bc2d84a941dca72.yaml Co-authored-by: Max Rossmannek <[email protected]> * Docs and links * Fix init * Expose QEOMResult documentation * Change copyrights * Delete duplicate release note * fix link spelling --------- Co-authored-by: Max Rossmannek <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Anthony-Gandon · Feb 8, 2023 · dbe573b · dbe573b
1 parent 4329755
commit dbe573b
Show file tree

Hide file tree

Showing 5 changed files with 129 additions and 19 deletions.
diff --git a/.pylintdict b/.pylintdict
@@ -302,6 +302,7 @@ lijh
 linewidths
 linux
 listordict
+listordicttype
 ljik
 lk
 logfile
@@ -531,6 +532,8 @@ str
 stylesheet
 subcircuits
 subclasses
+submatrix
+submatrices
 submodule
 submodules
 subtest

diff --git a/qiskit_nature/second_q/algorithms/__init__.py b/qiskit_nature/second_q/algorithms/__init__.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2019, 2022.
+# (C) Copyright IBM 2019, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -40,6 +40,14 @@
    ExcitedStatesEigensolver
    QEOM
 
+the specific raw result for the qEOM solver
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   QEOMResult
+
 and factories to provision quantum and/or classical algorithms upon which the above solvers may
 depend
 
@@ -97,6 +105,7 @@
     ExcitedStatesEigensolver,
     ExcitedStatesSolver,
     QEOM,
+    QEOMResult,
     EigensolverFactory,
     NumPyEigensolverFactory,
 )
@@ -113,6 +122,7 @@
     "ExcitedStatesEigensolver",
     "ExcitedStatesSolver",
     "QEOM",
+    "QEOMResult",
     "EigensolverFactory",
     "NumPyEigensolverFactory",
     "GroundStateEigensolver",

diff --git a/qiskit_nature/second_q/algorithms/excited_states_solvers/__init__.py b/qiskit_nature/second_q/algorithms/excited_states_solvers/__init__.py
@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2020, 2022.
+# (C) Copyright IBM 2020, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -19,7 +19,7 @@
 """
 
 from .excited_states_solver import ExcitedStatesSolver
-from .qeom import QEOM
+from .qeom import QEOM, QEOMResult
 from .eigensolver_factories import EigensolverFactory, NumPyEigensolverFactory
 from .excited_states_eigensolver import ExcitedStatesEigensolver
 
@@ -29,4 +29,5 @@
     "EigensolverFactory",
     "NumPyEigensolverFactory",
     "QEOM",
+    "QEOMResult",
 ]
diff --git a/qiskit_nature/second_q/algorithms/excited_states_solvers/qeom.py b/qiskit_nature/second_q/algorithms/excited_states_solvers/qeom.py
@@ -166,6 +166,8 @@ class QEOM(ExcitedStatesSolver):
     Auxiliary observables can be specified to the ``solve`` method along with auxiliary evaluation
     rules of the ``QEOM`` object.
 
+    For more details, please refer to https://arxiv.org/abs/1910.12890.
+
     The following attributes can be read and updated once the ``QEOM`` object has been
     constructed.
 
@@ -352,15 +354,18 @@ def solve(
     ) -> EigenstateResult:
         """Run the excited-states calculation.
 
-        Construct and solves the EOM pseudo-eigenvalue problem to obtain the excitation energies
+        Construct and solve the EOM pseudo-eigenvalue problem to obtain the excitation energies
         and the excitation operators expansion coefficients.
 
         Args:
             problem: A class encoding a problem to be solved.
             aux_operators: Additional auxiliary operators to evaluate.
+
         Returns:
             An interpreted :class:`~.EigenstateResult`. For more information see also
-            :meth:`~.BaseProblem.interpret`.
+            :meth:`~.BaseProblem.interpret`. The :class:`~.EigenstateResult` is constructed
+            from a :class:`~qiskit_nature.second_q.algorithms.excited_states_solvers.qeom.QEOMResult`
+            instance which holds additional information specific to the qEOM problem.
         """
 
         # 1. Prepare all operators and set the particle number in the qubit converter
@@ -458,7 +463,7 @@ def _build_hopping_ops(
             )
         else:
             raise NotImplementedError(
-                "The building of QEOM hopping operators is not yet implemented for a problem of "
+                "The building of qEOM hopping operators is not yet implemented for a problem of "
                 f"type {type(problem)}"
             )
 
@@ -717,7 +722,7 @@ def _build_qeom_pseudoeigenvalue_problem(
             deviation errors.
         """
 
-        logger.debug("Build QEOM pseudoeigenvalue problem...")
+        logger.debug("Build qEOM pseudoeigenvalue problem...")
 
         # 1. Build all EOM operators to evaluate on the ground state
         untap_eom_matrix_ops = self._build_all_eom_operators(
@@ -924,7 +929,7 @@ def _evaluate_observables_excited_states(
     ) -> tuple[dict[tuple[int, int], dict[str, Any]], dict[tuple[int, int], dict[str, Any]]]:
         """Evaluate the expectation values and transition amplitudes of the auxiliary operators on the
         excited states. Custom rules can be used to define which expectation values and transition
-        amplitudes to compute. A typical rule is specified in the form of a nary
+        amplitudes to compute. A typical rule is specified in the form of a dictionary
         {'hamiltonian':[(1,1)]}
 
         Args:
@@ -1029,7 +1034,30 @@ def _build_qeom_result(
 
 
 class QEOMResult(EigensolverResult):
-    """The results class for the QEOM algorithm."""
+    """The results class for the qEOM algorithm.
+
+    For more details about the definitions, please refer to https://arxiv.org/abs/1910.12890.
+
+    Attributes:
+        ground_state_raw_result (EigenstateResult): The raw results of the ground state eigensolver.
+        excitation_energies (np.ndarray): The excitation energies approximated by the qEOM algorithm.
+        expansion_coefficients (np.ndarray): The expansion coefficients matrix of the excitation
+            operators onto the set of basis operators spanning the linear qEOM subspace.
+        h_matrix (np.ndarray): Matrix representing the Hamiltonian in the qEOM subspace. Because of our
+            choice for the expansion basis, the two square sub-matrices on the diagonal are related by
+            a transposition and the two submatrices on the anti diagonal are hermitian conjugates.
+        s_matrix (np.ndarray): Matrix representing the geometry of the qEOM subspace. Because of our
+            choice for the expansion basis, the two square submatrices on the diagonal are related by
+            a transposition (with a sign) and the two submatrices on the anti diagonal are hermitian
+            conjugates.
+        h_matrix_std (np.ndarray): 2 by 2 matrix representing the sums of standard deviations in the four
+            square submatrices of H.
+        s_matrix_std (np.ndarray): 2 by 2 matrix representing the sums of standard deviations in the four
+            square submatrices of S.
+        transition_amplitudes (list[ListOrDictType[tuple[complex, dict[str, Any]]]): Transition
+            amplitudes of the auxiliary operators computed following the evaluation rules specified when
+            the qEOM class was created.
+    """
 
     def __init__(self) -> None:
         super().__init__()
@@ -1051,9 +1079,6 @@ def __init__(self) -> None:
         self._q_matrix_std: float = 0.0
         self._w_matrix_std: float = 0.0
 
-        self.aux_operators_evaluated: list[
-            ListOrDictType[tuple[complex, dict[str, Any]]]
-        ] | None = None
         self.transition_amplitudes: list[
             ListOrDictType[tuple[complex, dict[str, Any]]]
         ] | None = None
@@ -1069,14 +1094,19 @@ def m_matrix(self) -> np.ndarray | None:
 
     @m_matrix.setter
     @deprecate_function(
-        "The M matrix is now computed from the H matrix. "
+        "You should now set the H matrix from which the M matrix will be extracted. "
         "This setter will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
     )
     def m_matrix(self, value: np.ndarray) -> None:
         """sets the M matrix"""
         self._m_matrix = value
+        logger.warning(
+            "This setter for the M matrix will not update the H matrix to match. "
+            "Using this setter will make this result object bypass the H matrix "
+            "values for M."
+        )
 
     @property
     def v_matrix(self) -> np.ndarray | None:
@@ -1088,14 +1118,19 @@ def v_matrix(self) -> np.ndarray | None:
 
     @v_matrix.setter
     @deprecate_function(
-        "The V matrix is now computed from the S matrix. "
+        "You should now set the S matrix from which the V matrix will be extracted. "
         "This setter will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
     )
     def v_matrix(self, value: np.ndarray) -> None:
         """sets the V matrix"""
         self._v_matrix = value
+        logger.warning(
+            "This setter for the V matrix will not update the S matrix to match. "
+            "Using this setter will make this result object bypass the S matrix "
+            "values for V."
+        )
 
     @property
     def q_matrix(self) -> np.ndarray | None:
@@ -1109,14 +1144,19 @@ def q_matrix(self) -> np.ndarray | None:
 
     @q_matrix.setter
     @deprecate_function(
-        "The Q matrix is now computed from the H matrix. "
+        "You should now set the H matrix from which the Q matrix will be extracted. "
         "This setter will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
     )
     def q_matrix(self, value: np.ndarray) -> None:
         """sets the Q matrix"""
         self._q_matrix = value
+        logger.warning(
+            "This setter for the Q matrix will not update the H matrix to match. "
+            "Using this setter will make this result object bypass the H matrix "
+            "values for Q."
+        )
 
     @property
     def w_matrix(self) -> np.ndarray | None:
@@ -1128,14 +1168,19 @@ def w_matrix(self) -> np.ndarray | None:
 
     @w_matrix.setter
     @deprecate_function(
-        "The W matrix is now computed from the S matrix. "
+        "You should now set the S matrix from which the W matrix will be extracted. "
         "This setter will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
     )
     def w_matrix(self, value: np.ndarray) -> None:
         """sets the W matrix"""
         self._w_matrix = value
+        logger.warning(
+            "This setter for the W matrix will not update the S matrix to match. "
+            "Using this setter will make this result object bypass the S matrix "
+            "values for W."
+        )
 
     @property
     def m_matrix_std(self) -> float:
@@ -1146,9 +1191,22 @@ def m_matrix_std(self) -> float:
             return self._m_matrix_std
 
     @m_matrix_std.setter
+    @deprecate_function(
+        "You should now set the H matrix standard deviation from which the M matrix "
+        "standard deviation will be extracted. "
+        "This setter will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def m_matrix_std(self, value: float) -> None:
         """sets the M matrix standard deviation"""
         self._m_matrix_std = value
+        logger.warning(
+            "This setter for the M standard deviation matrix will not "
+            "update the H standard deviation matrix to match. "
+            "Using this setter will make this result object bypass the H "
+            "standard deviation matrix values for M."
+        )
 
     @property
     def v_matrix_std(self) -> float:
@@ -1159,9 +1217,22 @@ def v_matrix_std(self) -> float:
             return self._v_matrix_std
 
     @v_matrix_std.setter
+    @deprecate_function(
+        "You should now set the S matrix standard deviation from which the V matrix "
+        "standard deviation will be extracted. "
+        "This setter will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def v_matrix_std(self, value: float) -> None:
         """sets the V matrix standard deviation"""
         self._v_matrix_std = value
+        logger.warning(
+            "This setter for the V standard deviation matrix will not "
+            "update the S standard deviation matrix to match. "
+            "Using this setter will make this result object bypass the S "
+            "standard deviation matrix values for V."
+        )
 
     @property
     def q_matrix_std(self) -> float:
@@ -1172,9 +1243,22 @@ def q_matrix_std(self) -> float:
             return self._q_matrix_std
 
     @q_matrix_std.setter
+    @deprecate_function(
+        "You should now set the H matrix standard deviation from which the Q matrix "
+        "standard deviation will be extracted. "
+        "This setter will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def q_matrix_std(self, value: float) -> None:
         """sets the Q matrix standard deviation"""
         self._q_matrix_std = value
+        logger.warning(
+            "This setter for the Q standard deviation matrix will not "
+            "update the H standard deviation matrix to match. "
+            "Using this setter will make this result object bypass the H "
+            "standard deviation matrix values for Q."
+        )
 
     @property
     def w_matrix_std(self) -> float:
@@ -1185,6 +1269,19 @@ def w_matrix_std(self) -> float:
             return self._w_matrix_std
 
     @w_matrix_std.setter
+    @deprecate_function(
+        "You should now set the S matrix standard deviation from which the W matrix "
+        "standard deviation will be extracted. "
+        "This setter will be deprecated in a future release and subsequently "
+        "removed after that.",
+        category=PendingDeprecationWarning,
+    )
     def w_matrix_std(self, value: float) -> None:
         """sets the W matrix standard deviation"""
         self._w_matrix_std = value
+        logger.warning(
+            "This setter for the W standard deviation matrix will not "
+            "update the S standard deviation matrix to match. "
+            "Using this setter will make this result object bypass the S "
+            "standard deviation matrix values for W."
+        )
diff --git a/releasenotes/notes/pending-deprecate-mqwv-matrix-setter-1cd9e2dfb68d1a85.yaml b/releasenotes/notes/pending-deprecate-mqwv-matrix-setter-1cd9e2dfb68d1a85.yaml
@@ -1,7 +1,6 @@
 ---
 deprecations:
   - |
-    The M, Q, W, V matrix setters from
-    :class:`~qiskit_nature.second_q.algorithms.excited_state_solvers.qeom.QEOMResult`
+    The M, Q, W, V matrix setters and M, Q, W, V matrix standard deviation setters from
+    :class:`~qiskit_nature.second_q.algorithms.excited_states_solvers.qeom.QEOMResult`
     were pending deprecated and remain computable from the H and S matrices.
-