clarified gauge, lattice vs. atomic is clearer than cell vs. atom

The old values are still respected. This is a minor edit that doesn't change anything but the recommended wording of the Gauge. Signed-off-by: Nick Papior <[email protected]>
zerothi · Dec 9, 2024 · c1b875e · c1b875e
1 parent 7fa3157
commit c1b875e
Show file tree

Hide file tree

Showing 18 changed files with 139 additions and 128 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,8 @@ we hit release version 1.0.0.
   inline arguments: `read_scf(imd=...)` where `imd=:` is not
   allowed, partly fixes #835
 - enabled `...` for `atoms=` arguments. Selects all atoms.
+- clarified gauge, lattice vs. atomic is clearer than cell vs. atom.
+  The old values are still respected.
 
 ### Fixed
 - `projection` arguments of several functions has been streamlined

diff --git a/src/sisl/physics/_common.py b/src/sisl/physics/_common.py
@@ -11,13 +11,15 @@
 def comply_gauge(gauge: GaugeType) -> str:
     """Comply the gauge to one of two words: atom | cell"""
     return {
-        "R": "cell",
-        "cell": "cell",
-        "r": "atom",
-        "orbital": "atom",
-        "orbitals": "atom",
-        "atom": "atom",
-        "atoms": "atom",
+        "R": "lattice",
+        "cell": "lattice",
+        "lattice": "lattice",
+        "r": "atomic",
+        "orbital": "atomic",
+        "orbitals": "atomic",
+        "atom": "atomic",
+        "atoms": "atomic",
+        "atomic": "atomic",
     }[gauge]
 
 

diff --git a/src/sisl/physics/_matrix_ddk.pyx b/src/sisl/physics/_matrix_ddk.pyx
@@ -28,7 +28,7 @@ def _phase_ddk(gauge, M, sc, cnp.ndarray[floats_st] k, dtype):
     # two dependent variables
     # We always do the Voigt representation
     #  Rd = dx^2, dy^2, dz^2, dzy, dxz, dyx
-    if gauge == 'atom':
+    if gauge == "atomic":
         M.finalize()
         rij = M.Rij()._csr._D
         phases = phase_rij(rij, sc, k, dtype).reshape(-1, 1)
@@ -38,14 +38,16 @@ def _phase_ddk(gauge, M, sc, cnp.ndarray[floats_st] k, dtype):
         del rij, phases
         p_opt = 0
 
-    elif gauge == 'cell':
+    elif gauge == "lattice":
         phases = phase_rsc(sc, k, dtype).reshape(-1, 1)
         Rs = np.dot(sc.sc_off, sc.cell)
         Rd = - (Rs * Rs * phases).astype(dtype, copy=False)
         Ro = - (np.roll(Rs, 1, axis=1) * phases).astype(dtype, copy=False) # z, x, y
         Ro *= np.roll(Rs, -1, axis=1) # y, z, x
         del phases, Rs
         p_opt = 1
+    else:
+        raise ValueError("phase_ddk: gauge must be in [lattice, atomic]")
 
     assert p_opt >= 0, "Not implemented"
 

diff --git a/src/sisl/physics/_matrix_dk.pyx b/src/sisl/physics/_matrix_dk.pyx
@@ -26,18 +26,20 @@ def _phase_dk(gauge, M, sc, cnp.ndarray[floats_st] k, dtype):
     # See _phase.pyx, we are using exp(i k.R/r)
     #  i R
 
-    if gauge == 'atom':
+    if gauge == "atomic":
         M.finalize()
         rij = M.Rij()._csr._D
         iRs = (1j * rij * phase_rij(rij, sc, k, dtype).reshape(-1, 1)).astype(dtype, copy=False)
         del rij
         p_opt = 0
 
-    elif gauge == 'cell':
+    elif gauge == "lattice":
         iRs = phase_rsc(sc, k, dtype).reshape(-1, 1)
         iRs = (1j * np.dot(sc.sc_off, sc.cell) * iRs).astype(dtype, copy=False)
         p_opt = 1
 
+    else:
+        raise ValueError("phase_dk: gauge must be in [lattice, atomic]")
 
     assert p_opt >= 0, "Not implemented"
 

diff --git a/src/sisl/physics/_matrix_k.pyx b/src/sisl/physics/_matrix_k.pyx
@@ -28,17 +28,17 @@ def _phase_k(gauge, M, sc, cnp.ndarray[floats_st] K, dtype):
         p_opt = -1
         phases = np.empty([0], dtype=dtype)
 
-    elif gauge == "atom":
+    elif gauge == "atomic":
         M.finalize()
         phases = phase_rij(M.Rij()._csr._D, sc, k, dtype)
         p_opt = 0
 
-    elif gauge == "cell":
+    elif gauge == "lattice":
         phases = phase_rsc(sc, k, dtype)
         p_opt = 1
 
     else:
-        raise ValueError("phase_k: gauge must be in [cell, atom]")
+        raise ValueError("phase_k: gauge must be in [lattice, atomic]")
 
     return p_opt, phases
 

diff --git a/src/sisl/physics/_ufuncs_matrix.py b/src/sisl/physics/_ufuncs_matrix.py
@@ -23,20 +23,20 @@ def matrix_at_k(
     k: KPoint = (0, 0, 0),
     *args,
     dtype=None,
-    gauge: GaugeType = "cell",
+    gauge: GaugeType = "lattice",
     format: str = "csr",
     **kwargs,
 ):
     r"""Fold the matrix with the :math:`\mathbf k` phase applied in the `gauge` specified
 
     Fold the auxilliary supercell matrix elements into the primary cell by adding a phase factor:
 
-    When `gauge` is ``cell`` the matrix is folded like:
+    When `gauge` is ``lattice`` the matrix is folded like:
 
     .. math::
         \mathbf M(\mathbf k) = \sum_{\mathbf{k}} \mathbf M^{\mathrm{sc}_i} e^{i \mathbf R_{\mathrm{sc}_i} \cdot \mathbf k}
 
-    when `gauge` is ``atom`` the matrix is folded with the interatomic distances, like:
+    when `gauge` is ``atomic`` the matrix is folded with the interatomic distances, like:
 
     .. math::
         \mathbf M(\mathbf k) = \sum_{\mathbf{k}} \mathbf M^{\mathrm{sc}_i} e^{i (\mathbf r_i - \mathbf r_j) \cdot \mathbf k}
@@ -48,7 +48,8 @@ def matrix_at_k(
     dtype : numpy.dtype, optional
        default to `numpy.complex128`
     gauge :
-       chosen gauge, either the lattice gauge (``cell``), or the interatomic distance gauge (``atom``).
+       chosen gauge, either the lattice gauge (``lattice``), or the interatomic distance
+       gauge (``atomic``).
     format : {"csr", "array", "coo", ...}
        the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
        however if one always requires operations on dense matrices, one can always
@@ -70,20 +71,20 @@ def overlap_at_k(
     k: KPoint = (0, 0, 0),
     *args,
     dtype=None,
-    gauge: GaugeType = "cell",
+    gauge: GaugeType = "lattice",
     format: str = "csr",
     **kwargs,
 ):
     r"""Fold the overlap matrix with the :math:`\mathbf k` phase applied in the `gauge` specified
 
     Fold the auxilliary supercell overlap matrix elements into the primary cell by adding a phase factor:
 
-    When `gauge` is ``cell`` the overlap matrix is folded like:
+    When `gauge` is ``lattice`` the overlap matrix is folded like:
 
     .. math::
         \mathbf S(\mathbf k) = \sum_{\mathbf{k}} \mathbf S^{\mathrm{sc}_i} e^{i \mathbf R_{\mathrm{sc}_i} \cdot \mathbf k}
 
-    when `gauge` is ``atom`` the overlap matrix is folded with the interatomic distances, like:
+    when `gauge` is ``atomic`` the overlap matrix is folded with the interatomic distances, like:
 
     .. math::
         \mathbf S(\mathbf k) = \sum_{\mathbf{k}} \mathbf S^{\mathrm{sc}_i} e^{i (\mathbf r_i - \mathbf r_j) \cdot \mathbf k}
@@ -95,7 +96,8 @@ def overlap_at_k(
     dtype : numpy.dtype, optional
        default to `numpy.complex128`
     gauge :
-       chosen gauge, either the lattice gauge (``cell``), or the interatomic distance gauge (``atom``).
+       chosen gauge, either the lattice gauge (``lattice``), or the interatomic distance
+       gauge (``atomic``).
     format : {"csr", "array", "coo", ...}
        the returned format of the overlap matrix, defaulting to the `scipy.sparse.csr_matrix`,
        however if one always requires operations on dense matrices, one can always

diff --git a/src/sisl/physics/densitymatrix.py b/src/sisl/physics/densitymatrix.py
@@ -1483,7 +1483,7 @@ def Dk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -1518,7 +1518,7 @@ def Dk(
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
         gauge :
-           the chosen gauge, ``cell`` for cell vector gauge, and ``atom`` for atomic distance
+           the chosen gauge, ``lattice`` for cell vector gauge, and ``atomic`` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
@@ -1547,7 +1547,7 @@ def dDk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -1583,7 +1583,7 @@ def dDk(
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
         gauge :
-           the chosen gauge, ``cell`` for cell vector gauge, and ``atom`` for atomic distance
+           the chosen gauge, ``lattice`` for cell vector gauge, and ``atomic`` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
@@ -1610,7 +1610,7 @@ def ddDk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -1646,7 +1646,7 @@ def ddDk(
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
         gauge :
-           the chosen gauge, ``cell`` for cell vector gauge, and ``atom`` for atomic distance
+           the chosen gauge, ``lattice`` for cell vector gauge, and ``atomic`` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,

diff --git a/src/sisl/physics/dynamicalmatrix.py b/src/sisl/physics/dynamicalmatrix.py
@@ -59,7 +59,7 @@ def Dk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -93,8 +93,8 @@ def Dk(
            the data type of the returned matrix. Do NOT request non-complex
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
-        gauge : {'cell', 'orbital'}
-           the chosen gauge, `cell` for cell vector gauge, and `orbital` for atomic distance
+        gauge :
+           the chosen gauge, `lattice` for lattice vector gauge, and `atomic` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
@@ -119,7 +119,7 @@ def dDk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -154,8 +154,8 @@ def dDk(
            the data type of the returned matrix. Do NOT request non-complex
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
-        gauge : {'cell', 'orbital'}
-           the chosen gauge, `cell` for cell vector gauge, and `orbital` for atomic distance
+        gauge :
+           the chosen gauge, `lattice` for lattice vector gauge, and `atomic` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
@@ -178,7 +178,7 @@ def ddDk(
         self,
         k=(0, 0, 0),
         dtype=None,
-        gauge: GaugeType = "cell",
+        gauge: GaugeType = "lattice",
         format="csr",
         *args,
         **kwargs,
@@ -214,7 +214,7 @@ def ddDk(
            data-type for non-Gamma k.
            The default data-type is `numpy.complex128`
         gauge :
-           the chosen gauge, ``cell`` for cell vector gauge, and ``atom`` for atomic distance
+           the chosen gauge, ``lattice`` for cell vector gauge, and ``atomic`` for atomic distance
            gauge.
         format : {'csr', 'array', 'dense', 'coo', ...}
            the returned format of the matrix, defaulting to the `scipy.sparse.csr_matrix`,
@@ -291,15 +291,15 @@ def apply_newton(self) -> None:
         del d_uc
 
     def eigenvalue(
-        self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs
+        self, k=(0, 0, 0), gauge: GaugeType = "lattice", **kwargs
     ) -> EigenvaluePhonon:
         """Calculate the eigenvalues at `k` and return an `EigenvaluePhonon` object containing all eigenvalues for a given `k`
 
         Parameters
         ----------
         k : array_like*3, optional
             the k-point at which to evaluate the eigenvalues at
-        gauge : str, optional
+        gauge :
             the gauge used for calculating the eigenvalues
         sparse : bool, optional
             if ``True``, `eigsh` will be called, else `eigh` will be
@@ -324,7 +324,7 @@ def eigenvalue(
         return EigenvaluePhonon(_correct_hw(hw), self, **info)
 
     def eigenmode(
-        self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs
+        self, k=(0, 0, 0), gauge: GaugeType = "lattice", **kwargs
     ) -> EigenmodePhonon:
         r"""Calculate the eigenmodes at `k` and return an `EigenmodePhonon` object containing all eigenmodes
 
@@ -336,7 +336,7 @@ def eigenmode(
         ----------
         k : array_like*3, optional
             the k-point at which to evaluate the eigenmodes at
-        gauge : str, optional
+        gauge :
             the gauge used for calculating the eigenmodes
         sparse : bool, optional
             if ``True``, `eigsh` will be called, else `eigh` will be

diff --git a/src/sisl/physics/electron.py b/src/sisl/physics/electron.py
@@ -1222,10 +1222,10 @@ def _lowdin(state):
             pass
 
     else:
-        gauge = eigenstate_kwargs.get("gauge", "cell")
+        gauge = eigenstate_kwargs.get("gauge", "lattice")
 
         def _lowdin(state):
-            """change state to the lowdin state, assuming everything is in R gauge
+            """change state to the lowdin state, assuming everything is in lattice gauge
             So needs to be done before changing gauge"""
             S12 = sqrth(
                 state.parent.Sk(state.info["k"], gauge=gauge, format="array"),
@@ -1348,7 +1348,7 @@ def wavefunction(
 
     Notes
     -----
-    Currently this method only works for `v` being coefficients of the gauge="cell" method. In case
+    Currently this method only works for `v` being coefficients of the ``gauge="lattice"`` method. In case
     you are passing a `v` with the incorrect gauge you will find a phase-shift according to:
 
     .. math::
@@ -1362,7 +1362,7 @@ def wavefunction(
     v : array_like
        coefficients for the orbital expansion on the real-space grid.
        If `v` is a complex array then the `grid` *must* be complex as well. The coefficients
-       must be using the ``R`` gauge.
+       must be using the *lattice* gauge.
     grid : Grid
        grid on which the wavefunction will be plotted.
        If multiple eigenstates are in this object, they will be summed.
@@ -1846,8 +1846,8 @@ def wavefunction(self, grid, spinor=0, eta=None):
             # at least this makes it easier to parse
             grid = Grid(grid, geometry=geometry, dtype=self.dtype)
 
-        # Ensure we are dealing with the R gauge
-        self.change_gauge("cell")
+        # Ensure we are dealing with the lattice gauge
+        self.change_gauge("lattice")
 
         # Retrieve k
         k = self.info.get("k", _a.zerosd(3))