Refined docs to be more consistent

dgamore/DGAmore.py

@@ -633,10 +633,10 @@ def fits_everywhere(distributed: float, single: float) -> bool:
 def setup_lambda_correction_settings(comm: MPI.Comm) -> None:
     """
     Sets up the lambda correction settings based on the configuration provided by the user. If the user has enabled
-    the lambda correction in the self-consistency settings, it will be enabled in the lambda correction settings as well.
-    If the user has enabled the lambda correction in the lambda correction settings, but not in the self-consistency settings,
-    the self-consistency will be set to a single iteration with full mixing. Will raise an error if the user tries to enable
-    the lambda correction for multi-band systems.
+    the lambda correction in the self-consistency settings, it will be enabled in the lambda correction settings
+    as well. If the user has enabled the lambda correction in the lambda correction settings, but not in the
+    self-consistency settings, the self-consistency will be set to a single iteration with full mixing. Will raise
+    an error if the user tries to enable the lambda correction for multi-band systems.
 
     :param comm: The MPI communicator (only rank 0 validates the multi-band restriction).
     :return: None.
@@ -679,7 +679,7 @@ def setup_lambda_correction_settings(comm: MPI.Comm) -> None:
 def configure_matplotlib():
     """
     Configures matplotlib to use the Euler font for mathematical expressions if it is available on the system. This is
-    done because The Euler font is the default math font in my thesis.
+    done because the Euler font is the default math font in my thesis.
 
     :return: None.
     """

dgamore/brillouin_zone.py

@@ -183,8 +183,8 @@ def simultaneous_x_y_inversion() -> list[KnownSymmetries]:
 
 
 def inv_sym(mat: np.ndarray, axis) -> None:
-    """
-    Applies an inversion symmetry along ``axis`` to ``mat`` in place, assuming the grid runs over :math:`[0, 2\\pi)`
+    r"""
+    Applies an inversion symmetry along ``axis`` to ``mat`` in place, assuming the grid runs over :math:`[0, 2\pi)`
     so that the zero point does not map.
 
     :param mat: The (at least 3D) array to symmetrize in place; the leading three axes are the momentum axes.
@@ -308,12 +308,11 @@ def apply_symmetries(mat: np.ndarray, symmetries: list[KnownSymmetries]) -> None
 
 def get_lattice_symmetries_from_string(symmetry_string: str | tuple | list) -> list[KnownSymmetries]:
     """
-    Return the lattice symmetries from a string.
+    Returns the lattice symmetries from a string.
 
-    The special string "auto" signals that symmetries should be auto-detected
-    from a Hamiltonian H(k) at runtime via KGrid.specify_auto_symmetries(hk).
-    In that case an empty list is returned here, but a marker is set so that
-    the KGrid defers building fbz2irrk until specify_auto_symmetries is called.
+    The special string ``"auto"`` signals that symmetries should be auto-detected from a Hamiltonian ``H(k)`` at
+    runtime via :meth:`specify_auto_symmetries`. In that case an empty list is returned here, but a marker is set so
+    that the KGrid defers building ``fbz2irrk`` until :meth:`specify_auto_symmetries` is called.
 
     :param symmetry_string: A named preset (e.g. ``"two_dimensional_square"``), the special ``"auto"``, an empty
         string/``"none"``, or a list/tuple (or its string repr) of :class:`KnownSymmetries` values.
@@ -408,13 +407,11 @@ class KGrid:
     """
     Class to build the k-grid for the Brillouin zone.
 
-    The ``symmetries`` argument accepts the usual list of ``KnownSymmetries``
-    *and* the special "auto" mode (passed as the ``AUTO_SYMMETRIES_SENTINEL``,
-    typically obtained from ``get_lattice_symmetries_from_string("auto")``).
-    In auto mode the symmetry group is discovered from a Hamiltonian H(k) at
-    runtime: instantiate the grid with the sentinel, then call
-    :meth:`specify_auto_symmetries` with the Hamiltonian. Until that call the
-    grid behaves as if no symmetries were applied (full BZ = IBZ).
+    The ``symmetries`` argument accepts the usual list of ``KnownSymmetries`` *and* the special "auto" mode (passed as
+    the ``AUTO_SYMMETRIES_SENTINEL``, typically obtained from ``get_lattice_symmetries_from_string("auto")``). In auto
+    mode the symmetry group is discovered from a Hamiltonian ``H(k)`` at runtime: instantiate the grid with the
+    sentinel, then call :meth:`specify_auto_symmetries` with the Hamiltonian. Until that call the grid behaves as if
+    no symmetries were applied (full BZ = IBZ).
     """
 
     def __init__(self, nk: tuple = None, symmetries: list[KnownSymmetries] = None):
@@ -480,8 +477,8 @@ def specify_auto_symmetries(
         verbose: bool = False,
         include_antiunitary: bool = False,
     ) -> None:
-        """
-        Auto-detect the symmetry group of the Hamiltonian ``hk`` and replay
+        r"""
+        Auto-detects the symmetry group of the Hamiltonian ``hk`` and replay
         the IBZ reduction onto this grid.
 
         Only applicable when this ``KGrid`` was constructed in auto mode
@@ -684,8 +681,8 @@ def kmesh_list(self):
         return self.kmesh.reshape((3, -1))
 
     def set_k_axes(self) -> None:
-        """
-        Builds the three k-axis arrays spanning :math:`[0, 2\\pi)` for the full BZ.
+        r"""
+        Builds the three k-axis arrays spanning :math:`[0, 2\pi)` for the full BZ.
 
         :return: None.
         """
@@ -713,18 +710,18 @@ def get_irrq_list(self) -> np.ndarray:
 class KPath:
     """
     Object to generate paths in the Brillouin zone.
-    Currently assumed that the BZ grid is from (0,2*pi).
+    It is currently assumed that the BZ grid is from (0,2*pi).
     """
 
     def __init__(self, nk, path, kx=None, ky=None, kz=None, path_deliminator="-"):
-        """
+        r"""
         Builds the k-axes and the discretized path (and its k-points) from the path string.
 
         :param nk: Number of k-points per spatial direction, as a tuple ``(nx, ny, nz)``.
         :param path: The desired path through the BZ as a delimiter-separated string of corner-point labels.
-        :param kx: Optional explicit kx-axis array; a :math:`[0, 2\\pi)` grid is built if None.
-        :param ky: Optional explicit ky-axis array; a :math:`[0, 2\\pi)` grid is built if None.
-        :param kz: Optional explicit kz-axis array; a :math:`[0, 2\\pi)` grid is built if None.
+        :param kx: Optional explicit kx-axis array; a :math:`[0, 2\pi)` grid is built if None.
+        :param ky: Optional explicit ky-axis array; a :math:`[0, 2\pi)` grid is built if None.
+        :param kz: Optional explicit kz-axis array; a :math:`[0, 2\pi)` grid is built if None.
         :param path_deliminator: The delimiter separating corner-point labels in ``path``.
         """
         self.path_deliminator = path_deliminator
@@ -748,12 +745,12 @@ def get_kpath_val(self):
 
         :return: The k-axis values along the path as a list ``[kx_vals, ky_vals, kz_vals]``.
         """
-        k = [self.kx[self.kpts[:, 0]], self.kx[self.kpts[:, 1]], self.kx[self.kpts[:, 2]]]
+        k = [self.kx[self.kpts[:, 0]], self.ky[self.kpts[:, 1]], self.kz[self.kpts[:, 2]]]
         return k
 
     def set_kgrid(self, k_in, nk):
-        """
-        Returns an explicit k-axis if given, otherwise builds a :math:`[0, 2\\pi)` grid of ``nk`` points.
+        r"""
+        Returns an explicit k-axis if given, otherwise builds a :math:`[0, 2\pi)` grid of ``nk`` points.
 
         :param k_in: Explicit k-axis array, or None to build a default grid.
         :param nk: Number of points in the default grid.

dgamore/bubble_gen.py

@@ -124,7 +124,7 @@ def create_generalized_chi0_q_fft_auto(
         beta: float,
         logger: DgaLogger,
     ):
-        """
+        r"""
         Dispatches :meth:`create_generalized_chi0_q_fft` to the GPU when CuPy and a usable CUDA device are available
         (assigning one GPU per MPI rank round-robin), otherwise falls back to the CPU.
 
@@ -133,7 +133,7 @@ def create_generalized_chi0_q_fft_auto(
         :param niw: Number of positive bosonic frequencies.
         :param niv: Number of positive fermionic frequencies.
         :param k_grid: The :class:`KGrid` over which the BZ sum/FFT is performed.
-        :param beta: Inverse temperature :math:`\\beta`.
+        :param beta: Inverse temperature :math:`\beta`.
         :param logger: Logger used to report whether GPU acceleration is used.
         :return: The bubble as a :class:`FourPoint` over the irreducible BZ.
         """
@@ -239,7 +239,7 @@ def create_generalized_chi0_q_auto(
         beta: float,
         logger: DgaLogger,
     ):
-        """
+        r"""
         Dispatches :meth:`create_generalized_chi0_q` to the GPU when CuPy and a usable CUDA device are available
         (assigning one GPU per MPI rank round-robin), otherwise falls back to the CPU.
 
@@ -249,7 +249,7 @@ def create_generalized_chi0_q_auto(
         :param niv: Number of positive fermionic frequencies.
         :param q_list: Array of integer q-point index triplets to compute.
         :param q_grid: The :class:`KGrid` providing the momentum normalization.
-        :param beta: Inverse temperature :math:`\\beta`.
+        :param beta: Inverse temperature :math:`\beta`.
         :param logger: Logger used to report whether GPU acceleration is used.
         :return: The bubble as a :class:`FourPoint` over the given q-points.
         """

dgamore/config.py

@@ -26,11 +26,11 @@ class InteractionConfig:
     interactions); the remaining parameters are reserved for future use.
 
     :ivar float udd: Intra-orbital Hubbard interaction :math:`U_{dd}` on the d orbitals.
-    :ivar float udp: d-p inter-orbital Hubbard interaction.
+    :ivar float udp: Inter-orbital d-p Hubbard interaction.
     :ivar float upp: Intra-orbital Hubbard interaction :math:`U_{pp}` on the p orbitals.
     :ivar float uppod: Off-diagonal p-p Hubbard interaction.
     :ivar float jdd: Hund's exchange :math:`J_{dd}` on the d orbitals.
-    :ivar float jdp: d-p exchange.
+    :ivar float jdp: Inter-orbital d-p exchange.
     :ivar float jpp: Hund's exchange :math:`J_{pp}` on the p orbitals.
     :ivar float jppod: Off-diagonal p-p exchange.
     :ivar float vdd: Inter-orbital interaction :math:`V_{dd}` on the d orbitals.
@@ -107,14 +107,14 @@ def __init__(self):
 
 
 class SelfConsistencyConfig:
-    """
+    r"""
     Stores the self-consistency-loop parameters: the maximum iteration count, the convergence criterion, the mixing
     parameter/scheme and continuation options. If ``previous_sc_path`` is set, the loop resumes from a previous run.
     The mixing scheme can be ``"linear"``, ``"pulay"`` or ``"anderson"`` (the latter two use an iteration history).
 
     :ivar int max_iter: Maximum number of self-consistency iterations.
     :ivar float epsilon: Relative-residual convergence threshold on the self-energy.
-    :ivar float mixing: The mixing parameter :math:`\\alpha`.
+    :ivar float mixing: The mixing parameter :math:`\alpha`.
     :ivar str mixing_strategy: The mixing scheme (``"linear"``, ``"pulay"`` or ``"anderson"``).
     :ivar int mixing_history_length: Number of past iterations used by the accelerated mixing schemes.
     :ivar str previous_sc_path: Path to a previous self-consistency run to resume from (empty to start fresh).
@@ -217,7 +217,7 @@ class SystemConfig:
     :ivar float n: Total filling :math:`n`.
     :ivar int n_bands: Number of bands.
     :ivar numpy.ndarray occ: Local (k-averaged) occupation matrix.
-    :ivar numpy.ndarray occ_k: k-resolved occupation matrix.
+    :ivar numpy.ndarray occ_k: Full (k-resolved) occupation matrix.
     :ivar numpy.ndarray occ_dmft: Local occupation matrix from the DMFT input.
     :ivar list occ_dmft_per_ineq: DMFT occupation matrices per inequivalent atom.
     """

dgamore/config_parser.py

@@ -23,7 +23,7 @@
 
 class ConfigParser:
     """
-    Parses the config file and builds the DgaConfig singleton class. The Configuration is then broadcasted to all
+    Parses the config file and builds the global ``dgamore.config`` singletons (``box``, ``lattice``, ``dmft``, ...). The configuration is then broadcast to all
     processes. The config file location can be specified with the path and/or name arguments when executing the main
     Python file.
     """

dgamore/dga_io.py

@@ -44,11 +44,11 @@ def uniquify_path(path: str = None):
 def load_from_dmft_file_and_update_config() -> (
     tuple[list[GreensFunction], list[SelfEnergy], list[LocalFourPoint], list[LocalFourPoint]]
 ):
-    """
+    r"""
     Loads the per-inequivalent-atom DMFT quantities (1- and 2-particle) and updates the global config: inverse
     temperature, interaction parameters, chemical potential, filling, frequency boxes, band count, Hamiltonian and
     output paths. Also cuts the two-particle Green's functions to the core box and applies the requested orbital and
-    :math:`(\\nu, \\nu')` symmetrizations.
+    :math:`(\nu, \nu')` symmetrizations.
 
     :return: A tuple of per-inequivalent-atom lists ``(g_per_ineq, sigma_per_ineq, g2_dens_per_ineq,
         g2_magn_per_ineq)`` of Green's functions, self-energies and density/magnetic two-particle Green's functions.

dgamore/dga_logger.py

@@ -17,8 +17,7 @@
 
 class DgaLogger:
     """
-    A logger class that handles logging messages in a distributed environment using MPI. Currently, it logs messages
-    to the stdout and can also be extended to log to a file.
+    Handles logging messages in a distributed environment using MPI. Currently, it logs messages to stdout.
     """
 
     def __init__(self, comm: MPI.Comm, output_path: str = "./", filename: str = "dga.log"):
@@ -94,7 +93,8 @@ def _log(self, message: str, level: int, allowed_ranks: tuple | int = (0,)):
 
     def debug(self, message: str, allowed_ranks: tuple = (0,)):
         """
-        Logs a debug message. This is intended for detailed debugging information that is not usually needed in production.
+        Logs a debug message. This is intended for detailed debugging information that is not usually needed in
+        production.
 
         :param message: The message to log.
         :param allowed_ranks: The MPI rank(s) permitted to emit this message.

dgamore/dmft_interface.py

@@ -27,24 +27,24 @@
 
 class DMFTInterface(ABC):
     """
-    Abstract interface for DMFT calculations. Reads the necessary quantities which are needed for a DGA calculation
+    Abstract interface for DMFT calculations. Reads the quantities needed for a DGA calculation
     from the output files.
     """
 
     def get_beta(self) -> float:
-        """
+        r"""
         Returns the inverse temperature from the DMFT calculation.
 
-        :return: The inverse temperature :math:`\\beta` from the DMFT calculation.
+        :return: The inverse temperature :math:`\beta` from the DMFT calculation.
         :raises NotImplementedError: In the abstract base class.
         """
         raise NotImplementedError()
 
     def get_mu(self) -> float:
-        """
+        r"""
         Returns the chemical potential from the DMFT calculation.
 
-        :return: The chemical potential :math:`\\mu` from the DMFT calculation.
+        :return: The chemical potential :math:`\mu` from the DMFT calculation.
         :raises NotImplementedError: In the abstract base class.
         """
         raise NotImplementedError()
@@ -79,7 +79,7 @@ def get_occ(self, ineq: int = 1) -> np.ndarray:
         raise NotImplementedError()
 
     def get_udd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Returns the density-density interaction :math:`U` for the interacting d-orbitals (used both for plain
         density-density and Kanamori interactions).
 
@@ -90,7 +90,7 @@ def get_udd(self, ineq: int = 1) -> float:
         raise NotImplementedError()
 
     def get_jdd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Returns the Hund's coupling :math:`J` for the interacting d-orbitals (nonzero only for Kanamori interactions).
 
         :param ineq: The index of the inequivalent atom (for multi-site DMFT).
@@ -100,7 +100,7 @@ def get_jdd(self, ineq: int = 1) -> float:
         raise NotImplementedError()
 
     def get_vdd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Returns the inter-orbital repulsion :math:`V` (often :math:`U'`) for the interacting d-orbitals (nonzero only
         for Kanamori interactions).
 
@@ -169,19 +169,19 @@ def __init__(self):
         self._open()
 
     def get_beta(self) -> float:
-        """
+        r"""
         Reads the inverse temperature from the w2dynamics config.
 
-        :return: The inverse temperature :math:`\\beta` from the DMFT calculation.
+        :return: The inverse temperature :math:`\beta` from the DMFT calculation.
         """
         return self.file_1p[".config"].attrs["general.beta"]
 
     def get_mu(self, dmft_iter: str = "dmft-last") -> float:
-        """
+        r"""
         Reads the chemical potential from the w2dynamics output.
 
         :param dmft_iter: The DMFT iteration to read from.
-        :return: The chemical potential :math:`\\mu`.
+        :return: The chemical potential :math:`\mu`.
         """
         return self.file_1p[dmft_iter + "/mu/value"][()]
 
@@ -215,7 +215,7 @@ def get_occ(self, ineq: int = 1, dmft_iter: str = "dmft-last") -> np.ndarray:
         return 2 * np.mean(rho1, axis=(1, 3))
 
     def get_udd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Reads the density-density interaction from the w2dynamics config.
 
         :param ineq: The index of the inequivalent atom (for multi-site DMFT).
@@ -224,7 +224,7 @@ def get_udd(self, ineq: int = 1) -> float:
         return self._from_ineq_config("udd", ineq=ineq)
 
     def get_jdd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Reads the Hund's coupling from the w2dynamics config.
 
         :param ineq: The index of the inequivalent atom (for multi-site DMFT).
@@ -233,7 +233,7 @@ def get_jdd(self, ineq: int = 1) -> float:
         return self._from_ineq_config("jdd", ineq=ineq)
 
     def get_vdd(self, ineq: int = 1) -> float:
-        """
+        r"""
         Reads the inter-orbital repulsion from the w2dynamics config.
 
         :param ineq: The index of the inequivalent atom (for multi-site DMFT).