From c1b875ecb111bf4f5964fc9736fe751e1c8d30ae Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Mon, 9 Dec 2024 09:53:31 +0100 Subject: [PATCH] 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 --- CHANGELOG.md | 2 + src/sisl/physics/_common.py | 16 +++-- src/sisl/physics/_matrix_ddk.pyx | 6 +- src/sisl/physics/_matrix_dk.pyx | 6 +- src/sisl/physics/_matrix_k.pyx | 6 +- src/sisl/physics/_ufuncs_matrix.py | 18 ++--- src/sisl/physics/densitymatrix.py | 12 ++-- src/sisl/physics/dynamicalmatrix.py | 24 +++---- src/sisl/physics/electron.py | 12 ++-- src/sisl/physics/energydensitymatrix.py | 18 ++--- src/sisl/physics/hamiltonian.py | 26 +++---- src/sisl/physics/sparse.py | 84 +++++++++++----------- src/sisl/physics/state.py | 9 ++- src/sisl/physics/tests/test_hamiltonian.py | 8 +-- src/sisl/physics/tests/test_state.py | 12 ++-- src/sisl/typing/_physics.py | 2 +- src/sisl/viz/processors/eigenstate.py | 2 +- src/sisl/viz/processors/wavefunction.py | 4 +- 18 files changed, 139 insertions(+), 128 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0562510e70..f1985eb43d 100644 --- 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 index 56d94bfb55..b8e70dff73 100644 --- 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 index a3139e8194..d1178cf202 100644 --- 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,7 +38,7 @@ 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) @@ -46,6 +46,8 @@ def _phase_ddk(gauge, M, sc, cnp.ndarray[floats_st] k, dtype): 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 index 10a35c6977..54d2a5f8aa 100644 --- 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 index f004a8dec1..794e85785f 100644 --- 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 index 8caed76525..e568d65e48 100644 --- a/src/sisl/physics/_ufuncs_matrix.py +++ b/src/sisl/physics/_ufuncs_matrix.py @@ -23,7 +23,7 @@ def matrix_at_k( k: KPoint = (0, 0, 0), *args, dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", **kwargs, ): @@ -31,12 +31,12 @@ def matrix_at_k( 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,7 +71,7 @@ def overlap_at_k( k: KPoint = (0, 0, 0), *args, dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", **kwargs, ): @@ -78,12 +79,12 @@ def overlap_at_k( 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 index 6e24f12c2d..8efb10dd06 100644 --- 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 index cec987b146..fb117651a9 100644 --- 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,7 +291,7 @@ 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` @@ -299,7 +299,7 @@ def eigenvalue( ---------- 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 index c03fcfd496..04630a3660 100644 --- 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)) diff --git a/src/sisl/physics/energydensitymatrix.py b/src/sisl/physics/energydensitymatrix.py index b11aa221d5..73129361c6 100644 --- a/src/sisl/physics/energydensitymatrix.py +++ b/src/sisl/physics/energydensitymatrix.py @@ -105,7 +105,7 @@ def Ek( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -117,7 +117,7 @@ def Ek( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \mathbf E(\mathbf k) = \mathbf E_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -140,7 +140,7 @@ def Ek( 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`, @@ -169,7 +169,7 @@ def dEk( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -181,7 +181,7 @@ def dEk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \nabla_{\mathbf k} \mathbf E_\alpha(\mathbf k) = i\mathbf R_\alpha \mathbf E_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -205,7 +205,7 @@ def dEk( 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`, @@ -232,7 +232,7 @@ def ddEk( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -244,7 +244,7 @@ def ddEk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \nabla_{\mathbf k^2} \mathbf E_{\alpha\beta}(\mathbf k) = -\mathbf R_\alpha\mathbf R_\beta \mathbf E_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -268,7 +268,7 @@ def ddEk( 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/hamiltonian.py b/src/sisl/physics/hamiltonian.py index e22f262037..d0f77f21d0 100644 --- a/src/sisl/physics/hamiltonian.py +++ b/src/sisl/physics/hamiltonian.py @@ -108,7 +108,7 @@ def Hk( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -120,7 +120,7 @@ def Hk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \mathbf H(\mathbf k) = \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -143,7 +143,7 @@ def Hk( 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 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`, @@ -173,7 +173,7 @@ def dHk( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -185,7 +185,7 @@ def dHk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \nabla_{\mathbf k} \mathbf H_\alpha(\mathbf k) = i \mathbf R_\alpha \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -209,7 +209,7 @@ def dHk( 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 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`, @@ -236,7 +236,7 @@ def ddHk( self, k=(0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format="csr", *args, **kwargs, @@ -248,7 +248,7 @@ def ddHk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \nabla_{\mathbf k^2} \mathbf H_{\alpha\beta}(\mathbf k) = - \mathbf R_\alpha \mathbf R_\beta \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -272,7 +272,7 @@ def ddHk( 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 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`, @@ -335,7 +335,7 @@ def shift(self, E): for i in range(nspin): self._csr._D[:, i].real += self._csr._D[:, self.S_idx].real * E[i] - def eigenvalue(self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs): + def eigenvalue(self, k=(0, 0, 0), gauge: GaugeType = "lattice", **kwargs): """Calculate the eigenvalues at `k` and return an `EigenvalueElectron` object containing all eigenvalues for a given `k` Parameters @@ -369,14 +369,14 @@ def eigenvalue(self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs): else: e = self.eigh(k, gauge, eigvals_only=True, **kwargs) info = {"k": k, "gauge": gauge} - for name in ["spin"]: + for name in ("spin",): if name in kwargs: info[name] = kwargs[name] if not format is None: info["format"] = format return EigenvalueElectron(e, self, **info) - def eigenstate(self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs): + def eigenstate(self, k=(0, 0, 0), gauge: GaugeType = "lattice", **kwargs): """Calculate the eigenstates at `k` and return an `EigenstateElectron` object containing all eigenstates Parameters @@ -410,7 +410,7 @@ def eigenstate(self, k=(0, 0, 0), gauge: GaugeType = "cell", **kwargs): else: e, v = self.eigh(k, gauge, eigvals_only=False, **kwargs) info = {"k": k, "gauge": gauge} - for name in ["spin"]: + for name in ("spin",): if name in kwargs: info[name] = kwargs[name] if not format is None: diff --git a/src/sisl/physics/sparse.py b/src/sisl/physics/sparse.py index 5e355019dc..9c369e15c7 100644 --- a/src/sisl/physics/sparse.py +++ b/src/sisl/physics/sparse.py @@ -312,7 +312,7 @@ def _Pk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", _dim=0, ): @@ -334,7 +334,7 @@ def _dPk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", _dim=0, ): @@ -356,7 +356,7 @@ def _ddPk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", _dim=0, ): @@ -378,7 +378,7 @@ def Sk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", *args, **kwargs, @@ -390,7 +390,7 @@ def Sk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \mathbf S(\mathbf k) = \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -413,8 +413,7 @@ def Sk( 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 - gauge. + the chosen gauge format : {"csr", "array", "matrix", "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 @@ -439,7 +438,7 @@ def _Sk_diagonal( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", *args, **kwargs, @@ -471,7 +470,7 @@ def _Sk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k`. @@ -491,7 +490,7 @@ def dSk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", *args, **kwargs, @@ -503,7 +502,7 @@ def dSk( Notes ----- - Currently the implemented gauge for the k-point is the cell vector gauge: + Currently the implemented gauge for the k-point is the lattice vector gauge: .. math:: \nabla_{\mathbf k} \mathbf S_\alpha(\mathbf k) = i \mathbf R_\alpha \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf R} @@ -527,8 +526,7 @@ def dSk( 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 - gauge. + the chosen gauge. format : {"csr", "array", "matrix", "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 @@ -550,7 +548,7 @@ def _dSk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k` differentiated with respect to `k` @@ -570,7 +568,7 @@ def _dSk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k` for non-collinear spin, differentiated with respect to `k` @@ -593,7 +591,7 @@ def ddSk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", *args, **kwargs, @@ -652,7 +650,7 @@ def _ddSk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k` double differentiated with respect to `k` @@ -672,7 +670,7 @@ def _ddSk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k` for non-collinear spin, differentiated with respect to `k` @@ -695,7 +693,7 @@ def _ddSk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k` for Nambu spin, differentiated with respect to `k` @@ -717,7 +715,7 @@ def _ddSk_nambu( def eig( self, k: KPoint = (0, 0, 0), - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): @@ -743,7 +741,7 @@ def eig( def eigh( self, k: KPoint = (0, 0, 0), - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): @@ -766,7 +764,7 @@ def eigsh( self, k: KPoint = (0, 0, 0), n: int = 1, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): @@ -1290,7 +1288,7 @@ def _Pk_unpolarized( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Sparse matrix (`scipy.sparse.csr_matrix`) at `k` @@ -1311,7 +1309,7 @@ def _Pk_polarized( k: KPoint = (0, 0, 0), spin=0, dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a polarized system @@ -1333,7 +1331,7 @@ def _Pk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a non-collinear system @@ -1354,7 +1352,7 @@ def _Pk_spin_orbit( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a spin-orbit system @@ -1375,7 +1373,7 @@ def _Pk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a Nambu system @@ -1396,7 +1394,7 @@ def _dPk_unpolarized( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k`, differentiated with respect to `k` @@ -1417,7 +1415,7 @@ def _dPk_polarized( k: KPoint = (0, 0, 0), spin=0, dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k`, differentiated with respect to `k` @@ -1439,7 +1437,7 @@ def _dPk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a non-collinear system, differentiated with respect to `k` @@ -1460,7 +1458,7 @@ def _dPk_spin_orbit( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a spin-orbit system, differentiated with respect to `k` @@ -1481,7 +1479,7 @@ def _dPk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a Nambu spin system, differentiated with respect to `k` @@ -1502,7 +1500,7 @@ def _ddPk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a non-collinear system, differentiated with respect to `k` twice @@ -1523,7 +1521,7 @@ def _ddPk_spin_orbit( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a spin-orbit system, differentiated with respect to `k` @@ -1544,7 +1542,7 @@ def _ddPk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Tuple of sparse matrix (`scipy.sparse.csr_matrix`) at `k` for a Nambu system, differentiated with respect to `k` @@ -1565,7 +1563,7 @@ def _Sk( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix in a `scipy.sparse.csr_matrix` at `k`. @@ -1585,7 +1583,7 @@ def _Sk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix (`scipy.sparse.csr_matrix`) at `k` for a non-collinear system @@ -1606,7 +1604,7 @@ def _Sk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix (`scipy.sparse.csr_matrix`) at `k` for a Nambu system @@ -1627,7 +1625,7 @@ def _dSk_non_colinear( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix (`scipy.sparse.csr_matrix`) at `k` for a non-collinear system @@ -1650,7 +1648,7 @@ def _dSk_nambu( self, k: KPoint = (0, 0, 0), dtype=None, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", format: str = "csr", ): r"""Overlap matrix (`scipy.sparse.csr_matrix`) at `k` for a Nambu system @@ -1672,7 +1670,7 @@ def _dSk_nambu( def eig( self, k: KPoint = (0, 0, 0), - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): @@ -1710,7 +1708,7 @@ def eig( def eigh( self, k: KPoint = (0, 0, 0), - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): @@ -1745,7 +1743,7 @@ def eigsh( self, k: KPoint = (0, 0, 0), n: int = 1, - gauge: GaugeType = "cell", + gauge: GaugeType = "lattice", eigvals_only: bool = True, **kwargs, ): diff --git a/src/sisl/physics/state.py b/src/sisl/physics/state.py index e20828c2a4..4173e8aae3 100644 --- a/src/sisl/physics/state.py +++ b/src/sisl/physics/state.py @@ -986,7 +986,8 @@ def change_gauge(self, gauge: GaugeType, offset=(0, 0, 0)): \tilde C_\alpha = e^{i\mathbf k\mathbf r_\alpha} C_\alpha - where :math:`C_\alpha` and :math:`\tilde C_\alpha` belongs to the ``atom`` and ``cell`` gauge, respectively. + where :math:`C_\alpha` and :math:`\tilde C_\alpha` belongs to the ``atomic`` and + ``lattice`` gauge, respectively. Parameters ---------- @@ -1026,12 +1027,14 @@ def change_gauge(self, gauge: GaugeType, offset=(0, 0, 0)): if self.shape[1] == g.no * 2: phase = np.repeat(phase, 2) - if gauge == "atom": + if gauge == "atomic": # R -> r gauge tranformation. self.state *= exp(-1j * phase).reshape(1, -1) - elif gauge == "cell": + elif gauge == "lattice": # r -> R gauge tranformation. self.state *= exp(1j * phase).reshape(1, -1) + else: + raise ValueError("change_gauge: gauge must be in [lattice, atomic]") # def toStateC(self, norm=1.): # r""" Transforms the states into normalized values equal to `norm` and specifies the coefficients in `StateC` as the norm diff --git a/src/sisl/physics/tests/test_hamiltonian.py b/src/sisl/physics/tests/test_hamiltonian.py index e9d314648b..759a43fe78 100644 --- a/src/sisl/physics/tests/test_hamiltonian.py +++ b/src/sisl/physics/tests/test_hamiltonian.py @@ -239,11 +239,11 @@ def test_eigenstate_gauge(self, setup): H.construct([(0.1, 1.5), ((1.0, 2.0), (0.1, 0.2))]) # Try with different gauges - for gauge in ("cell", "R"): - assert H.eigenstate(gauge=gauge).info["gauge"] == "cell" + for gauge in ("cell", "R", "lattice"): + assert H.eigenstate(gauge=gauge).info["gauge"] == "lattice" - for gauge in ("atom", "atoms", "atom", "orbitals", "r"): - assert H.eigenstate(gauge=gauge).info["gauge"] == "atom" + for gauge in ("atom", "atoms", "atom", "orbitals", "r", "atomic"): + assert H.eigenstate(gauge=gauge).info["gauge"] == "atomic" @pytest.mark.parametrize("k", [[0, 0, 0], [0.15, 0.15, 0.15]]) def test_Hk_format(self, setup, k): diff --git a/src/sisl/physics/tests/test_state.py b/src/sisl/physics/tests/test_state.py index b715f6bc12..afad7f485b 100644 --- a/src/sisl/physics/tests/test_state.py +++ b/src/sisl/physics/tests/test_state.py @@ -125,23 +125,23 @@ def test_state_norm(): def test_state_change_gauge(): g = geom.graphene(1.42) - state = State(ar(2, 2).astype(np.complex128), g, gauge="atom", k=(0.1, 0.2, 0.4)) + state = State(ar(2, 2).astype(np.complex128), g, gauge="atomic", k=(0.1, 0.2, 0.4)) assert len(state) == 2 old = state.state.copy() - state.change_gauge("cell") + state.change_gauge("lattice") assert not np.allclose(old, state.state) - state.change_gauge("atom") + state.change_gauge("atomic") assert np.allclose(old, state.state) def test_state_change_gauge_nc(): g = geom.graphene(1.42) - state = State(ar(2, 4).astype(np.complex128), g, gauge="atom", k=(0.1, 0.2, 0.4)) + state = State(ar(2, 4).astype(np.complex128), g, gauge="atomic", k=(0.1, 0.2, 0.4)) assert len(state) == 2 old = state.state.copy() - state.change_gauge("cell") + state.change_gauge("lattice") assert not np.allclose(old, state.state) - state.change_gauge("atom") + state.change_gauge("atomic") assert np.allclose(old, state.state) diff --git a/src/sisl/typing/_physics.py b/src/sisl/typing/_physics.py index 5b0639e742..d58b27188a 100644 --- a/src/sisl/typing/_physics.py +++ b/src/sisl/typing/_physics.py @@ -15,7 +15,7 @@ "ProjectionTypeHadamardAtoms", ] -GaugeType = Literal["cell", "atom"] +GaugeType = Literal["lattice", "atomic"] ProjectionTypeMatrix = Literal["matrix", "ij"] ProjectionTypeTrace = Literal["trace", "sum"] diff --git a/src/sisl/viz/processors/eigenstate.py b/src/sisl/viz/processors/eigenstate.py index a5b2baef51..ef4d448b63 100644 --- a/src/sisl/viz/processors/eigenstate.py +++ b/src/sisl/viz/processors/eigenstate.py @@ -179,7 +179,7 @@ def project_wavefunction( grid = create_wf_grid(eigenstate, grid_prec=grid_prec, grid=grid, geometry=geometry) # Ensure we are dealing with the cell gauge - eigenstate.change_gauge("cell") + eigenstate.change_gauge("lattice") # Finally, insert the wavefunction values into the grid. sisl.physics.electron.wavefunction( diff --git a/src/sisl/viz/processors/wavefunction.py b/src/sisl/viz/processors/wavefunction.py index d4283cea89..f8a932bb47 100644 --- a/src/sisl/viz/processors/wavefunction.py +++ b/src/sisl/viz/processors/wavefunction.py @@ -96,8 +96,8 @@ def eigenstate_wf( # Get the particular WF that we want from the eigenstate object wf_state = get_ith_eigenstate(eigenstate, i) - # Ensure we are dealing with the cell gauge - wf_state.change_gauge("cell") + # Ensure we are dealing with the lattice gauge + wf_state.change_gauge("lattice") # Finally, insert the wavefunction values into the grid. wavefunction(wf_state.state, grid, geometry=geometry, k=k, spinor=0, spin=spin)