Update code docstrings

tkwantoperator/energy.pyx

@@ -205,7 +205,7 @@ cdef class EnergyCurrent:
         .. math::
             I_{ji}^ε(t) = \sum_{\text{lead } α} \; \sum_{{\text{mode } m_α}} \int \frac{{\text{d}E}}{2\pi} f_α(E) \sum_{k} - \text{Im} \left [ \left [ ψ_k^{m_α E} \right ]^\dagger ε_{ki} ε_{ij} ψ_j^{m_α E} - \left [ ψ_k^{m_α E} \right ]^\dagger ε_{kj} ε_{ji} ψ_i^{m_α E} \right ]
 
-        Where the written products are matrix products (where each dimension describes an orbital).
+        The above formula has been derived in :ref:`article-ref` for single-orbital Hamiltonians. In practice, the operator `EnergyCurrent` has been implemented for generic multi-orbital Hamiltonian matrices but the physical meaning of the multi-orbital formula is not clear in general. It has not yet been investigated.
         :math:`ε` is the energy operator derived from the system's Hamiltonian:
 
         * Its values on hoppings coincide with the Hamiltonian        
@@ -353,8 +353,8 @@ cdef class EnergyCurrent:
         Returns
         -------
         :py:class:`list` [:py:class:`float`] or :py:class:`float`
-            List of the values fo the contribution of ``psi`` to the currents on each hopping :math:`\left [ I_{ji}^E(ψ, t) \right ]_{(j,i) \in \text{where}}`, when `sum` :math:`= 0`. 
-            Otherwise the sum of these values :math:`\sum_{(j,i) \in \text{where}} I_{ji}^E(ψ, t)`.
+            List of the values fo the contribution of ``psi`` to the currents on each hopping :math:`\left [ I_{ji}^ε(ψ, t) \right ]_{(j,i) \in \text{where}}`, when `sum` :math:`= 0`. 
+            Otherwise the sum of these values :math:`\sum_{(j,i) \in \text{where}} I_{ji}^ε(ψ, t)`.
         """
         cdef gint i, norbs_i, offset_i
         cdef gint j, norbs_j, offset_j
@@ -539,7 +539,7 @@ cdef class EnergySource:
         .. math::
             S_i^ε(t) = \sum_{\text{lead } α} \; \sum_{{\text{mode } m_α}} \int \frac{{\text{d}E}}{2\pi} f_α(E) \sum_{k} \left\{- \text{Im} \left [ \left [ ψ_i^{m_α E} \right ]^\dagger V_i  ε_{ik} ψ_k^{m_α E} + \left [ ψ_k^{m_α E} \right ]^\dagger V_k ε_{ki} ψ_i^{m_α E} \right ] + \text{Re} \left [ \left [ ψ_i^{m_α E} \right ]^\dagger ∂_t ε_{ik} ψ_k^{m_α E} \right ]\right\}
 
-        Where the written products are matrix products (where each dimension describes an orbital).
+        The above formula has been derived in :ref:`article-ref` for single-orbital Hamiltonians. In practice, the operator `EnergySource` has been implemented for generic multi-orbital Hamiltonian matrices but the physical meaning of the multi-orbital formula is not clear in general. It has not yet been investigated.
         :math:`ε` is the energy operator derived from the system's Hamiltonian:
 
         * Its values on hoppings coincide with the hamiltonian        
@@ -702,7 +702,7 @@ cdef class EnergySource:
         written as ":math:`ψ`" :
 
         .. math::
-            S_i^ε(ψ, t) = \sum_{k} - \text{Im} \left [ψ_i^\dagger V'_i  ε_{ik} ψ_k + ψ_k^\dagger V'_k ε_{ki} ψ_i \right ] + \text{Re} \left [ ψ_i^\dagger ∂_t ε_{ik} ψ_k \right ]
+            S_i^ε(ψ, t) = \sum_{k} - \text{Im} \left [ψ_i^\dagger V_i  ε_{ik} ψ_k + ψ_k^\dagger V_k ε_{ki} ψ_i \right ] + \text{Re} \left [ ψ_i^\dagger ∂_t ε_{ik} ψ_k \right ]
 
         Parameters
         ----------
@@ -922,7 +922,7 @@ cdef class EnergyDensity:
         .. math::
             ρ^ε_i(t) = \sum_{\text{lead } α} \; \sum_{{\text{mode } m_α}} \int \frac{{\text{d}E}}{2π} f_α(E) \sum_{j} \text{Re} \left [ \left [ ψ_i^{m_α E} \right ]^\dagger ε_{ij} ψ_j^{m_α E} \right ]
 
-        Where the written products are matrix products (where each dimension describes an orbital).
+        The above formula has been derived in :ref:`article-ref` for single-orbital Hamiltonians. In practice, the operator `EnergyDensity` has been implemented for generic multi-orbital Hamiltonian matrices but the physical meaning of the multi-orbital formula is not clear in general. It has not yet been investigated.
         :math:`ε` is the energy operator derived from the system's Hamiltonian:
 
         * Its values on hoppings coincide with the Hamiltonian        
@@ -1036,8 +1036,8 @@ cdef class EnergyDensity:
     def __call__(self, 
                  psi: Sequence[complex],
                  params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
-        r"""Returns the contribution :math:`ρ_i^E(ψ, t)` of ``psi`` to the expectation value
-        of the energy density on each site of the `where` list.
+        r"""Returns the contribution :math:`ρ_i^ε(ψ, t)` of ``psi`` to the expectation value
+        of the energy density on each site :math:`i` of the `where` list.
 
         This method enables calling an instance `A` of this class like a 
         function, with a wave function and the "params" dictionary as parameters :
@@ -1048,7 +1048,7 @@ cdef class EnergyDensity:
         written as ":math:`ψ`" :
 
         .. math::
-            ρ^ε_i(ψ, t) = \sum_{j} \text{Re} \left [ ψ_k^\dagger ε_{ij} ψ_j \right ]
+            ρ^ε_i(ψ, t) = \sum_{j} \text{Re} \left [ ψ_i^\dagger ε_{ij} ψ_j \right ]
 
         Parameters
         ----------
@@ -1217,7 +1217,7 @@ cdef class LeadHeatCurrent:
         
         Notes
         -----
-        This class calculates the heat current :math:`I^H(t)` flowing out of a given lead :math:`L` to
+        This class calculates the heat current :math:`I_L^H(t)` flowing out of a given lead :math:`L` to
         the central system :math:`C`:
 
         .. math::
@@ -1231,7 +1231,7 @@ cdef class LeadHeatCurrent:
         to site :math:`j` (calculated by the `~kwant.operator.Current` class). :math:`μ`
         is the chemical potential of the lead, given by `chemical_potential`.
 
-        Please note that the value of the heat current :math:`I^H(t)` depends on the position
+        Please note that the value of the heat current :math:`I_L^H(t)` depends on the position
         of the interface between the lead and the central system. 
         The user is free to choose this position by adding an arbitrary number of 
         (first) cells of the lead into the central system.
@@ -1284,14 +1284,14 @@ cdef class LeadHeatCurrent:
         It must contain sites that belonged originally to the lead (in particular the on-site potential
         on these sites is spatially uniform and time-independent).         
         More precisely, for a given position of the :math:`L-C` interface 
-        at which the heat current :math:`I^H(t)` will be calculated,
+        at which the heat current :math:`I_L^H(t)` will be calculated,
         `added_lead_sites` must contain the neighbors that are in :math:`L` of the sites in :math:`C`
         and the neighbors that are in :math:`L` of those former neighbors. 
         It should form one unique closed surface (i.e. a connected graph), and without "holes". 
 
         Eventually, for each hopping :math:`(j, i)` from `hoppings` a heat current 
         contribution :math:`I_{ji}^H(t) = I^ε_{ji} - S^ε_i - μ I^N_{ji}` is calculated
-        and the sum over all heat current contributions is done to deduce :math:`I^H(t)`.
+        and the sum over all heat current contributions is done to deduce :math:`I_L^H(t)`.
 
         .. rubric:: Attributes
 
@@ -1403,7 +1403,7 @@ cdef class LeadHeatCurrent:
     def __call__(self, 
                  psi: Sequence[complex],
                  params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
-        r"""Returns the contribution :math:`I^H(ψ, t)` of ``psi`` to the expectation value
+        r"""Returns the contribution :math:`I_L^H(ψ, t)` of ``psi`` to the expectation value
         of the lead's outgoing heat current.
 
         This method enables calling an instance `A` of this class like a 
@@ -1415,7 +1415,7 @@ cdef class LeadHeatCurrent:
         written as ":math:`ψ`" :
 
         .. math::
-            I^H(ψ, t) = \sum_{(j, i) \in \text{hoppings}} I^ε_{ji} - S^ε_i - μ I^N_{ji}
+            I_L^H(ψ, t) = \sum_{(j, i) \in \text{hoppings}} I^ε_{ji}(ψ, t) - S^ε_i(ψ, t) - μ I^N_{ji}(ψ, t)
 
         Parameters
         ----------
@@ -1429,7 +1429,7 @@ cdef class LeadHeatCurrent:
         Returns
         -------
         :py:class:`float`
-            The contribution :math:`I^H(ψ, t)` of ``psi`` to the expectation value
+            The contribution :math:`I_L^H(ψ, t)` of ``psi`` to the expectation value
             of the lead's outgoing heat current.
         """
 
@@ -1563,7 +1563,7 @@ cdef class EnergyCurrentDivergence:
     def __call__(self, 
                  psi: Sequence[complex],
                  params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
-        r"""Returns the contribution :math:`D_i^E(ψ, t)` of ``psi`` to the expectation value
+        r"""Returns the contribution :math:`D_i^ε(ψ, t)` of ``psi`` to the expectation value
         of the current divergence on each site of the `where` list.
 
         This method enables calling an instance `A` of this class like a 
@@ -1575,9 +1575,9 @@ cdef class EnergyCurrentDivergence:
         written as ":math:`ψ`" :
 
         .. math::
-            D_i^E(ψ, t) = \sum_j I^E_{ji}(ψ, t)
+            D_i^ε(ψ, t) = \sum_j I^ε_{ji}(ψ, t)
 
-        Where :math:`I^E_{ji}(ψ, t)` is calculated with `~tkwantoperator.EnergyCurrent.__call__`
+        Where :math:`I^ε_{ji}(ψ, t)` is calculated with `~tkwantoperator.EnergyCurrent.__call__`
         from the `~tkwantoperator.EnergyCurrent` class.
 
         Parameters
@@ -1594,9 +1594,9 @@ cdef class EnergyCurrentDivergence:
         :py:class:`list` [:py:class:`float`] or :py:class:`float`
             List of the values of the contribution of ``psi`` to the energy current
             divergence on each site of the `where` list 
-            :math:`\left [ D_i^E(ψ, t) \right ]_{i \in \text{where}}`, 
+            :math:`\left [ D_i^ε(ψ, t) \right ]_{i \in \text{where}}`, 
             when `sum` :math:`= 0`. Otherwise the sum of these values 
-            :math:`\sum_{i \in \text{where}} D_i^E(ψ, t)`.
+            :math:`\sum_{i \in \text{where}} D_i^ε(ψ, t)`.
         """
 
         if self.sum: