tbkit 0.2.0__tar.gz → 0.3.0__tar.gz

{tbkit-0.2.0/tbkit.egg-info → tbkit-0.3.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: tbkit
-Version: 0.2.0
-Summary: A Python package to build and solve Tight-Binding models, for research and education.
+Version: 0.3.0
+Summary: A Python package to build and solve Tight-Binding models.
 Author-email: Charles Poli <cpoli374@gmail.com>
+Maintainer-email: cpoli <cpoli374@gmail.com>
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/cpoli/tbkit
 Classifier: Intended Audience :: Education
@@ -24,14 +25,15 @@ Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
 Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
 Dynamic: license-file
 
-# tbkit — a Tight-Binding package for research and education
+# tbkit — a Tight-Binding package
 
 [![tests](https://github.com/cpoli/tbkit/actions/workflows/tests.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/tests.yml)
+[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://cpoli.github.io/tbkit/coverage/)
 [![docs](https://img.shields.io/badge/docs-cpoli.github.io%2Ftbkit-blue.svg)](https://cpoli.github.io/tbkit/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
 
-![tbkit logo](docs/source/_static/image/tbkit_logo.png)
+![tbkit logo](https://raw.githubusercontent.com/cpoli/tbkit/master/docs/source/_static/image/tbkit_logo.png)
 
 **tbkit** is a Python package to build and solve Tight-Binding models, written
 in vectorized NumPy/SciPy. It aims to make the mechanics of Tight-Binding
@@ -85,6 +87,13 @@ research prototyping.
 
 Requires Python >= 3.10.
 
+```bash
+pip install tbkit
+```
+
+or, for an editable install from a clone (e.g. to run the test suite or
+work on tbkit itself):
+
 ```bash
 git clone https://github.com/cpoli/tbkit
 cd tbkit
@@ -98,6 +107,9 @@ pip install -e ".[test]"
 pytest tests/
 ```
 
+The test suite has 100% line coverage of the `tbkit` package; see the
+[HTML coverage report](https://cpoli.github.io/tbkit/coverage/).
+
 ## Quick start
 
 Real-space flake, nearest-neighbor square lattice:
@@ -204,6 +216,7 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 
 | Script                                                                  | What it shows |
 |---------------------------------------------------------------------------|----------------|
+| [`tight_binding/plot_square_lattice_bands.py`](examples/tight_binding/plot_square_lattice_bands.py) | The square lattice: Bloch's theorem at its simplest, bands along Gamma-X-M-Gamma, the nested Fermi surface, and the van Hove singularity. |
 | [`tight_binding/plot_graphene_bands.py`](examples/tight_binding/plot_graphene_bands.py) | Real-space flake + reciprocal-space band structure; graphene's Dirac point and Wallace's 1947 linear dispersion. |
 | [`tight_binding/plot_visualizing_a_model.py`](examples/tight_binding/plot_visualizing_a_model.py) | `tbkit.plot.Plot`: lattice, spectrum with sublattice polarization, density of states, eigenstate intensity. |
 | [`magnetic_field/plot_magnetic_field.py`](examples/magnetic_field/plot_magnetic_field.py) | Peierls substitution; an Aharonov-Bohm ring's flux-periodic spectrum. |
@@ -217,6 +230,8 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`topology/plot_edge_states.py`](examples/topology/plot_edge_states.py) | Zigzag graphene ribbon edge band; Kane-Mele helical edge states. |
 | [`dynamics/plot_bloch_oscillations.py`](examples/dynamics/plot_bloch_oscillations.py) | Wannier-Stark ladder, its localization, and Bloch oscillations under a uniform tilt. |
 | [`topology/plot_thouless_pump.py`](examples/topology/plot_thouless_pump.py) | The Rice-Mele model as a Thouless quantum pump: quantized Chern number and polarization winding. |
+| [`strain/plot_pseudo_magnetic_field.py`](examples/strain/plot_pseudo_magnetic_field.py) | Triaxial strain as a gauge field: pseudo-Landau levels in graphene from a purely real Hamiltonian. |
+| [`non_hermitian/plot_pt_symmetry.py`](examples/non_hermitian/plot_pt_symmetry.py) | PT symmetry, exceptional points, the Petermann factor, and a selectively amplified topological edge mode. |
 
 The `examples/` directory also has five older Jupyter notebooks (graphene
 flakes, kagome/Lieb/dumbbell lattices, disorder, strain, time propagation)

{tbkit-0.2.0 → tbkit-0.3.0}/README.md

@@ -1,11 +1,12 @@
-# tbkit — a Tight-Binding package for research and education
+# tbkit — a Tight-Binding package
 
 [![tests](https://github.com/cpoli/tbkit/actions/workflows/tests.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/tests.yml)
+[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://cpoli.github.io/tbkit/coverage/)
 [![docs](https://img.shields.io/badge/docs-cpoli.github.io%2Ftbkit-blue.svg)](https://cpoli.github.io/tbkit/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
 
-![tbkit logo](docs/source/_static/image/tbkit_logo.png)
+![tbkit logo](https://raw.githubusercontent.com/cpoli/tbkit/master/docs/source/_static/image/tbkit_logo.png)
 
 **tbkit** is a Python package to build and solve Tight-Binding models, written
 in vectorized NumPy/SciPy. It aims to make the mechanics of Tight-Binding
@@ -59,6 +60,13 @@ research prototyping.
 
 Requires Python >= 3.10.
 
+```bash
+pip install tbkit
+```
+
+or, for an editable install from a clone (e.g. to run the test suite or
+work on tbkit itself):
+
 ```bash
 git clone https://github.com/cpoli/tbkit
 cd tbkit
@@ -72,6 +80,9 @@ pip install -e ".[test]"
 pytest tests/
 ```
 
+The test suite has 100% line coverage of the `tbkit` package; see the
+[HTML coverage report](https://cpoli.github.io/tbkit/coverage/).
+
 ## Quick start
 
 Real-space flake, nearest-neighbor square lattice:
@@ -178,6 +189,7 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 
 | Script                                                                  | What it shows |
 |---------------------------------------------------------------------------|----------------|
+| [`tight_binding/plot_square_lattice_bands.py`](examples/tight_binding/plot_square_lattice_bands.py) | The square lattice: Bloch's theorem at its simplest, bands along Gamma-X-M-Gamma, the nested Fermi surface, and the van Hove singularity. |
 | [`tight_binding/plot_graphene_bands.py`](examples/tight_binding/plot_graphene_bands.py) | Real-space flake + reciprocal-space band structure; graphene's Dirac point and Wallace's 1947 linear dispersion. |
 | [`tight_binding/plot_visualizing_a_model.py`](examples/tight_binding/plot_visualizing_a_model.py) | `tbkit.plot.Plot`: lattice, spectrum with sublattice polarization, density of states, eigenstate intensity. |
 | [`magnetic_field/plot_magnetic_field.py`](examples/magnetic_field/plot_magnetic_field.py) | Peierls substitution; an Aharonov-Bohm ring's flux-periodic spectrum. |
@@ -191,6 +203,8 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`topology/plot_edge_states.py`](examples/topology/plot_edge_states.py) | Zigzag graphene ribbon edge band; Kane-Mele helical edge states. |
 | [`dynamics/plot_bloch_oscillations.py`](examples/dynamics/plot_bloch_oscillations.py) | Wannier-Stark ladder, its localization, and Bloch oscillations under a uniform tilt. |
 | [`topology/plot_thouless_pump.py`](examples/topology/plot_thouless_pump.py) | The Rice-Mele model as a Thouless quantum pump: quantized Chern number and polarization winding. |
+| [`strain/plot_pseudo_magnetic_field.py`](examples/strain/plot_pseudo_magnetic_field.py) | Triaxial strain as a gauge field: pseudo-Landau levels in graphene from a purely real Hamiltonian. |
+| [`non_hermitian/plot_pt_symmetry.py`](examples/non_hermitian/plot_pt_symmetry.py) | PT symmetry, exceptional points, the Petermann factor, and a selectively amplified topological edge mode. |
 
 The `examples/` directory also has five older Jupyter notebooks (graphene
 flakes, kagome/Lieb/dumbbell lattices, disorder, strain, time propagation)

{tbkit-0.2.0 → tbkit-0.3.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tbkit"
-version = "0.2.0"
-description = "A Python package to build and solve Tight-Binding models, for research and education."
+version = "0.3.0"
+description = "A Python package to build and solve Tight-Binding models."
 readme = "README.md"
 license = "BSD-3-Clause"
 authors = [{ name = "Charles Poli", email = "cpoli374@gmail.com" }]
+maintainers = [{ name = "cpoli", email = "cpoli374@gmail.com" }]
 requires-python = ">=3.10"
 dependencies = [
     "numpy>=1.24",
@@ -29,6 +30,13 @@ Homepage = "https://github.com/cpoli/tbkit"
 test = ["pytest>=7", "pytest-cov>=4"]
 docs = ["sphinx>=7", "pydata-sphinx-theme>=0.15", "sphinx-gallery>=0.15"]
 
+[tool.pytest.ini_options]
+# The suite is warning-free; keep it that way. A warning from tbkit itself is
+# a defect (e.g. complex energies reaching matplotlib), and one from a test is
+# usually the test misusing an API. Add a targeted `ignore::` entry below if a
+# dependency ever emits something genuinely out of our control.
+filterwarnings = ["error"]
+
 [tool.setuptools.packages.find]
 include = ["tbkit*"]
 

{tbkit-0.2.0 → tbkit-0.3.0}/tbkit/__init__.py

@@ -6,7 +6,7 @@
 
 """tbkit: build and solve Tight-Binding models."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Lattice", "System", "Plot", "Propagation", "Save", "KSpace",

{tbkit-0.2.0 → tbkit-0.3.0}/tbkit/error_handling.py

@@ -47,8 +47,8 @@ def positive_int_lim(var, var_name, nmax):
     if var < 1:
         raise ValueError('\n\nParameter {} must be a positive integer.\n'.format(var_name))
     if var > nmax:
-        raise ValueError('\n\nParameter {} must be a positive integer\n'\
-                                   'smaller than {}.\n'.format(var_name, nmax))
+        raise ValueError('\n\nParameter {} must be a positive integer '
+                                  'smaller than {}.\n'.format(var_name, nmax))
 
 
 def real_number(var, var_name):
@@ -84,7 +84,7 @@ def positive_real_zero(var, var_name):
     if not isinstance(var, (int, float)):
         raise TypeError('\n\nParameter {} must be a real number.\n'.format(var_name))
     if var < 0:
-        raise ValueError('\n\nParameter {} must be a positive number  or zero.\n'.format(var_name))
+        raise ValueError('\n\nParameter {} must be a positive number or zero.\n'.format(var_name))
 
 
 def negative_real(var, var_name):
@@ -187,7 +187,7 @@ def ndarray_empty(var, var_name):
     :raises ValueError: Parameter *var* must not be an emptynumpy ndarray.
     '''
     if var.size == 0:
-        raise ValueError('\n\nParameter {} must not be an emptynumpy ndarray.\n'.format(var_name))
+        raise ValueError('\n\nParameter {} must not be an empty numpy ndarray.\n'.format(var_name))
 
 
 def list_tuple_2elem(var, var_name):
@@ -200,7 +200,7 @@ def list_tuple_2elem(var, var_name):
     if var is None:
         return
     if not isinstance(var, (list, tuple)):
-        raise TypeError('\n\nParameter {} must be a list/tuple\n'.format(var_name))
+        raise TypeError('\n\nParameter {} must be a list/tuple.\n'.format(var_name))
     if len(var) != 2:
         raise ValueError('\n\nParameter {} must be a list/tuple of length two.\n'.format(var_name))
 
@@ -215,7 +215,7 @@ def tuple_2elem(var, var_name):
     if var is None:
         return
     if not isinstance(var, tuple):
-        raise TypeError('\n\nParameter {} must be a tuple\n'.format(var_name))
+        raise TypeError('\n\nParameter {} must be a tuple.\n'.format(var_name))
     if len(var) != 2:
         raise ValueError('\n\nParameter {} must be a list/tuple of length two.\n'.format(var_name))
 
@@ -284,18 +284,20 @@ def prim_vec(prim_vec):
     if not isinstance(prim_vec, list):
         raise TypeError('\n\nParameter prim_vec must be a list.\n')
     if not len(prim_vec) == 1 and not len(prim_vec) == 2:
-        raise ValueError('\n\nParameter prim_vec must be a list.\n'
-                                  'of length 1 for 1D lattices or length 2 fro 2D lattices.\n')
+        raise ValueError('\n\nParameter prim_vec must be a list of length 1 '
+                                  'for 1D lattices, or of length 2 for 2D lattices.\n')
     for coor in prim_vec:
         if not isinstance(coor, tuple):
-            raise TypeError('\n\nParameter prim_vec contain tuples\n')
+            raise TypeError('\n\nParameter prim_vec must contain tuples.\n')
         if len(coor) != 2:
-            raise ValueError('\n\nParameter prim_vec contain tuples of length 2.\n')
+            raise ValueError('\n\nParameter prim_vec must contain tuples of length 2.\n')
         if (not isinstance(coor[0], (int, float))) or \
            (not isinstance(coor[1], (int, float))):
-            raise ValueError('\n\ncoor must contain real numbers.\n')
+            raise ValueError('\n\nParameter prim_vec must contain tuples of '
+                                      'real numbers.\n')
         if coor[0] ** 2 + coor[1] ** 2 < 0.1:
-            raise ValueError('\n\nNorm of coor should be larger than 0.1.\n')
+            raise ValueError('\n\nEach primitive vector must have a norm larger '
+                                      'than 0.1.\n')
 
 
 def get_lattice(prim_vec, n1, n2):
@@ -374,22 +376,6 @@ def boundary_line(cx, cy, co):
         raise TypeError('\n\nParameter co must be a real number.\n')
 
 
-def ellipse(a, b):
-    '''
-    Check *ellipse_in* and *ellipse_out*.
-    :raises TypeError: Parameter a must be a positive number.
-    :raises TypeError: Parameter b must be a positive number.
-    '''
-    if not isinstance(a, (int, float)):
-        raise TypeError('\n\nParameter a must be a positive number.\n')
-    if not isinstance(b, (int, float)):
-        raise TypeError('\n\nParameter b must be a positive number.\n')
-    if a <= 0:
-        raise ValueError('\n\nParameter a must be a positive number.\n')
-    if b <= 0:
-        raise ValueError('\n\nParameter b must be a positive number.\n')
-
-
 def sites(sites):
     '''
     Check if *get_lattice* has been called (*coor* not empty).
@@ -471,7 +457,7 @@ def set_hopping(list_hop, n_max):
         if not isinstance(dic['n'], int):
             raise TypeError('\n\n"n" value must be an integer.\n')
         if not 0 < dic['n'] <= n_max:
-            raise ValueError('\n\n"n" value must be between 1 and nmax".\n')
+            raise ValueError('\n\n"n" value must be between 1 and {}.\n'.format(n_max))
         if not isinstance(dic['t'], (int, float, complex)):
             raise TypeError('\n\n"t" value must be a real or complex number.\n')
         if len(dic) == 3:
@@ -857,7 +843,8 @@ def set_hopping_kspace(list_hop, n_sites, ndim, spin=False):
         if not all(isinstance(n, int) for n in dic['R']):
             raise TypeError('\n\n"R" must be a tuple of integers.\n')
         if dic['i'] == dic['j'] and dic['R'] == (0,) * ndim:
-            raise ValueError('\n\nUse kspace.set_onsite for i == j and R == 0.\n')
+            raise ValueError('\n\nUse kspace.set_onsite for i == j and R == 0 '
+                                  '(it accepts a 2x2 spin matrix when spin=True).\n')
         if spin:
             spin_matrix(dic['t'], '"t"')
         elif not isinstance(dic['t'], (int, float, complex)):
@@ -871,7 +858,7 @@ def set_onsite_kspace(dict_onsite, tags, spin=False):
     :raises TypeError: Parameter *dict_onsite* must be a dictionary.
     :raises ValueError: keys must be tags.
     :raises TypeError: values must be real or complex numbers (or, if
-      *spin*, a pair of real/complex numbers).
+      *spin*, a pair of real/complex numbers, or a 2x2 matrix).
     '''
     if not isinstance(dict_onsite, dict):
         raise TypeError('\n\nParameter dict_onsite must be a dictionary.\n')
@@ -879,10 +866,13 @@ def set_onsite_kspace(dict_onsite, tags, spin=False):
         if tag not in tags:
             raise ValueError('\n\nParameter dict_onsite keys must be a tag.\n')
         if spin and not isinstance(val, (int, float, complex)):
-            if not (isinstance(val, (tuple, list)) and len(val) == 2
-                          and all(isinstance(v, (int, float, complex)) for v in val)):
+            is_pair = (isinstance(val, (tuple, list)) and len(val) == 2
+                            and all(isinstance(v, (int, float, complex)) for v in val))
+            is_mat = np.ndim(val) == 2 and np.shape(val) == (2, 2)
+            if not (is_pair or is_mat):
                 raise TypeError('\n\nParameter dict_onsite values must be a number, or, '
-                                           'if spin, a pair of numbers (E_up, E_down).\n')
+                                           'if spin, a pair of numbers (E_up, E_down) or a '
+                                           '2x2 matrix.\n')
         elif not spin and not isinstance(val, (int, float, complex)):
             raise TypeError('\n\nParameter dict_onsite values must be real and/or complex numbers.\n')
 

{tbkit-0.2.0 → tbkit-0.3.0}/tbkit/graphene.py

@@ -106,40 +106,74 @@ class GrapheneSystem(System):
     def __init__(self, lat: Lattice) -> None:
         System.__init__(self, lat)
 
-    def set_hop_linear_strain(self, t: complex, beta: float) -> None:
+    def _strain_projection(self) -> tuple[NDArray[np.int64], NDArray[np.float64], NDArray[np.float64]]:
+        r'''
+        Private method.
+
+        Get, for every nearest-neighbor bond, the projection
+
+        .. math::
+
+            s_{ij} = \hat{\boldsymbol\delta}_{ij}\cdot\mathbf{r}_{ij}
+
+        of its midpoint :math:`\mathbf{r}_{ij}` on its (outward-oriented)
+        direction :math:`\hat{\boldsymbol\delta}_{ij}`, so that the strained
+        hopping is :math:`t_{ij} = t(1 + \tfrac14\beta s_{ij})`.
+
+        :returns:
+            * **ind_up** -- Integer ndarray, shape (nbonds, 2). Bond indices.
+            * **ang** -- Real ndarray. Bond angles, in degrees.
+            * **s** -- Real ndarray. The projections above.
         '''
-        Set nearest neighbors hoppings according to the linear trixial strain. 
-        
+        self.get_distances()
+        ind = np.argwhere(np.isclose(self.dist_uni[1], self.vec_hop['dis'], atol=ATOL))
+        ind_up = ind[ind[:, 1] > ind[:, 0]]
+        ang = self.vec_hop['ang'][ind_up[:, 0], ind_up[:, 1]].copy()
+        # orient the three bond families consistently outwards
+        ang[np.isclose(30., ang, atol=ATOL)] = -150.
+        ang[np.isclose(150., ang, atol=ATOL)] = -30.
+        x_center = .5 * (self.lat.coor['x'][ind_up[:, 0]] + self.lat.coor['x'][ind_up[:, 1]])
+        y_center = .5 * (self.lat.coor['y'][ind_up[:, 0]] + self.lat.coor['y'][ind_up[:, 1]])
+        s = (np.cos(PI / 180 * ang) * x_center + np.sin(PI / 180 * ang) * y_center)
+        return ind_up, ang, s
+
+    def set_hop_linear_strain(self, t: complex, beta: float) -> None:
+        r'''
+        Set nearest-neighbor hoppings according to a linear triaxial strain:
+
+        .. math::
+
+            t_{ij} = t\left(1 + \tfrac14\beta\,
+                     \hat{\boldsymbol\delta}_{ij}\cdot\mathbf{r}_{ij}\right)
+
+        with :math:`\hat{\boldsymbol\delta}_{ij}` the bond direction and
+        :math:`\mathbf{r}_{ij}` its midpoint. The strain is measured from the
+        coordinate origin, so centre the flake on it (see *lattice.center*)
+        before calling this.
+
         :param t: Hopping value without strain.
-        :param beta: Strength of the strain.
+        :param beta: Strength of the strain. See *get_beta_lims* for the
+            range that keeps every hopping positive.
         '''
         error_handling.number(t, 't')
         error_handling.real_number(beta, 'beta')
-        self.get_distances()
-        ind = np.argwhere(np.isclose(self.dist_uni[1], self.vec_hop['dis'], atol=ATOL))
-        ind_up = ind[ind[:, 1] > ind[:, 0]]  
+        ind_up, ang, s = self._strain_projection()
         self.hop = np.zeros(len(ind_up), dtype=HOP_DTYPE)
         self.hop['n'] = 1
         self.hop['i'] = ind_up[:, 0]
         self.hop['j'] = ind_up[:, 1]
         self.hop['ang'] = self.vec_hop['ang'][ind_up[:, 0], ind_up[:, 1]]
-        # change angle (to get the correct strain)
-        self.hop['ang'][np.isclose(30., self.hop['ang'], ATOL)] = -150.
-        self.hop['ang'][np.isclose(150., self.hop['ang'], ATOL)] = - 30.
-        x_center = .5 * (self.lat.coor['x'][ind_up[:, 0]] + self.lat.coor['x'][ind_up[:, 1]])
-        y_center = .5 * (self.lat.coor['y'][ind_up[:, 0]] + self.lat.coor['y'][ind_up[:, 1]])
-        self.hop['t'] = t * (1. + 0.25 * beta * (np.cos(PI / 180 * self.hop['ang']) * x_center +
-                                                                np.sin(PI / 180 * self.hop['ang']) * y_center))
-        # back to the former angle
-        self.hop['ang'][np.isclose(-150., self.hop['ang'])] = 30.
-        self.hop['ang'][np.isclose(-30., self.hop['ang'])] = 150.
+        self.hop['tag'] = npc.add(self.lat.coor['tag'][ind_up[:, 0]],
+                                                self.lat.coor['tag'][ind_up[:, 1]])
+        self.hop['t'] = t * (1. + 0.25 * beta * s)
 
     def get_butterfly(self, t: complex, N: int) -> None:
-        ''''
+        '''
         Get energies depending on strain.
 
         :param t: Unstrained hopping value.
-        :param N: number of strain values between min and max strains.
+        :param N: Positive integer. Number of strain values between the
+            minimal and maximal strains given by *get_beta_lims*.
         '''
         error_handling.number(t, 't')
         error_handling.positive_int(N, 'N')
@@ -147,25 +181,29 @@ class GrapheneSystem(System):
         self.betas = np.linspace(beta_lims[0], beta_lims[1], N)
         self.butterfly = np.zeros((N, self.lat.sites))
         for i, beta in enumerate(self.betas):
-            self.set_hop_linear_strain(t=1, beta=beta)
+            self.set_hop_linear_strain(t=t, beta=beta)
             self.get_ham()
             self.butterfly[i] = LA.eigvalsh(self.ham.toarray())
 
     def get_beta_lims(self) -> NDArray[np.float64]:
-        '''
-        Get the extremal values of strain keeping positive hoppings.
-        '''
-        beta_lims = np.zeros(2)
-        yb_min_val = self.lat.coor['y'][self.lat.coor['tag'] == 'b'].min()
-        yb_min = self.lat.coor['y'][self.lat.coor['y'] == yb_min_val][0]
-        ym = 0.5 * (2 * yb_min + 1)
-        beta_lims[1] = -4. / ym + 1e-6
-        yb_max_val = self.lat.coor['y'][self.lat.coor['tag'] == 'a'].max()
-        yb_max = self.lat.coor['y'][self.lat.coor['y'] == yb_max_val][0]
-        ym = 0.5 * (2 * yb_max - 1)
-        beta_lims[0] = -4. / ym + 1e-6
-        print('Strain limits: {}'.format(beta_lims))
-        return beta_lims
+        r'''
+        Get the extremal strain values keeping every hopping positive.
+
+        Under *set_hop_linear_strain* a bond's amplitude is
+        :math:`t(1+\tfrac14\beta s_{ij})`, so it stays positive for every bond
+        iff :math:`-4/\max_{ij} s_{ij} < \beta < -4/\min_{ij} s_{ij}`.
+
+        :returns:
+            * **beta_lims** -- Real ndarray of length 2, ``[beta_min, beta_max]``
+              (ascending). A bound is infinite if the corresponding
+              :math:`s_{ij}` never takes that sign.
+        '''
+        _, _, s = self._strain_projection()
+        eps = 1e-6
+        s_min, s_max = s.min(), s.max()
+        beta_min = -4. / s_max + eps if s_max > 0 else -np.inf
+        beta_max = -4. / s_min - eps if s_min < 0 else np.inf
+        return np.array([beta_min, beta_max])
 
 
 # Backward-compatible camelCase aliases (pre-0.2 API).

{tbkit-0.2.0 → tbkit-0.3.0}/tbkit/kspace.py

@@ -97,6 +97,9 @@ class KSpace():
         self.norb = 2*self.n_sites if spin else self.n_sites
         self.tags = np.array([dic['tag'] for dic in lat.unit_cell])
         self.onsite = np.zeros(self.norb, 'c16')
+        # spin-off-diagonal onsite terms (in-plane Zeeman, onsite Rashba):
+        # they have no place on the diagonal `onsite` array.
+        self._onsite_offdiag = np.zeros((self.norb, self.norb), 'c16')
         self._hop = []  # list of (i, j, R_cartesian (np.ndarray), t)
         self.rec_vec = reciprocal_vectors(lat.prim_vec)
         self.ks = np.array([])  # k-points of the last band-structure calculation
@@ -109,24 +112,35 @@ class KSpace():
         Set the onsite energies, by sublattice tag.
 
         :param dict_onsite: Dictionary. key: tag, val: onsite energy
-            (a plain number), or, if ``spin=True``, either a plain number
-            (applied equally to both spins) or a pair ``(E_up, E_down)`` of
-            numbers (a spin splitting, e.g. a Zeeman term along z).
+            (a plain number), or, if ``spin=True``, a plain number (applied
+            equally to both spins), a pair ``(E_up, E_down)`` of numbers (a
+            spin splitting along z), or a 2x2 complex matrix (a general spin
+            structure, e.g. an in-plane Zeeman field built from :data:`PAULI`).
 
         Example usage::
 
             kag.set_onsite({'a': 1., 'b': -1.})
             # spinful: same onsite energy for both spins on 'a', a Zeeman
-            # splitting on 'b':
+            # splitting along z on 'b':
             kag_spin.set_onsite({'a': 1., 'b': (1., -1.)})
+            # spinful: an in-plane Zeeman field on 'a':
+            kag_spin.set_onsite({'a': Bx*PAULI['x']})
         '''
         error_handling.set_onsite_kspace(dict_onsite, self.lat.tags, self.spin)
         for tag, val in dict_onsite.items():
             sites = np.where(self.tags == tag)[0]
             if self.spin:
-                e_up, e_down = (val, val) if isinstance(val, (int, float, complex)) else val
-                self.onsite[2*sites] = e_up
-                self.onsite[2*sites + 1] = e_down
+                if isinstance(val, (int, float, complex)):
+                    block = val * PAULI['0']
+                elif np.ndim(val) == 2:
+                    block = np.asarray(val, 'c16')
+                else:
+                    block = np.diag(np.asarray(val, 'c16'))
+                self.onsite[2*sites] = block[0, 0]
+                self.onsite[2*sites + 1] = block[1, 1]
+                for site in sites:
+                    self._onsite_offdiag[2*site, 2*site + 1] = block[0, 1]
+                    self._onsite_offdiag[2*site + 1, 2*site] = block[1, 0]
             else:
                 self.onsite[sites] = val
 
@@ -187,16 +201,23 @@ class KSpace():
         r'''
         Get the dense Bloch Hamiltonian :math:`H(\mathbf{k})`.
 
-        :param k: Tuple/list/ndarray of one/two real numbers. :math:`\mathbf{k}` point,
-            in the same Cartesian frame as *prim_vec*.
+        :param k: Tuple/list/ndarray of one/two real numbers. In 2D, the
+            :math:`\mathbf{k}` point in the same Cartesian frame as *prim_vec*.
+            In 1D, the crystal momentum *along* the primitive vector (so the
+            Brillouin zone spans :math:`2\pi/|\mathbf{a}_1|`), which
+            coincides with :math:`k_x` for a chain aligned with :math:`x`.
 
         :returns:
             * **ham** -- Complex ndarray, shape (norb, norb).
         '''
         error_handling.k_vector(k, 'k', self.dim)
         k_cart = np.zeros(2)
-        k_cart[:self.dim] = k
-        ham = np.diag(self.onsite).astype('c16')
+        if self.dim == 1:
+            a1 = np.asarray(self.lat.prim_vec[0], dtype='f8')
+            k_cart = np.ravel(np.asarray(k, dtype='f8'))[0] * a1 / np.linalg.norm(a1)
+        else:
+            k_cart[:self.dim] = k
+        ham = np.diag(self.onsite).astype('c16') + self._onsite_offdiag
         for i, j, R_cart, t in self._hop:
             ham[i, j] += t * np.exp(1j * np.dot(k_cart, R_cart))
         return ham
@@ -283,7 +304,9 @@ class KSpace():
         rec_vec = [np.array(b) for b in self.rec_vec]
         if self.dim == 1:
             f1 = np.arange(nk[0]) / nk[0]
-            ks = f1[:, None] * rec_vec[0][None, :self.dim]
+            # k is the crystal momentum along the chain (see get_ham), so the
+            # zone spans |b1| = 2*pi/|a1|.
+            ks = f1[:, None] * np.linalg.norm(rec_vec[0])
             return [f1], ks
         f1, f2 = np.meshgrid(np.arange(nk[0])/nk[0], np.arange(nk[1])/nk[1], indexing='ij')
         ks = (f1.ravel()[:, None] * rec_vec[0][None, :]

{tbkit-0.2.0 → tbkit-0.3.0}/tbkit/lattice.py

@@ -177,7 +177,7 @@ class Lattice():
 
     def shift_y(self, shift: float) -> None:
         '''
-        Shift by *delta_x* the x coordinates.
+        Shift the y coordinates.
 
         :param shift: Real number. Shift value.
         '''
@@ -222,7 +222,6 @@ class Lattice():
 
             (x-x_0)^2/a^2+(y-y_0)^2/b^2 < 1\,  .
 
-        :param list_hop: List of Dictionary (see set_hopping definition).
         :param rx: Positive Real number. Radius along :math:`x`.
         :param ry: Positive Real number. Radius along :math:`y`.
         :param x0: Real number. :math:`x` center.
@@ -246,7 +245,6 @@ class Lattice():
             (x-x_0)^2/a^2+(y-y_0)^2/b^2 > 1\,  .
 
 
-        :param list_hop: List of Dictionary (see set_hopping definition).
         :param rx: Positive Real number. Radius along :math:`x`.
         :param ry: Positive Real number. Radius along :math:`y`.
         :param x0: Real number. :math:`x` center.
@@ -271,18 +269,18 @@ class Lattice():
 
     def rotation(self, theta: float) -> None:
         r'''
-        Rotate the lattice structure by the angle :math:`\theta`.
+        Rotate the lattice structure about the origin by the angle
+        :math:`\theta`.
 
         :param theta: Rotation angle in degrees.
         '''
         error_handling.empty_coor(self.coor)
         error_handling.real_number(theta, 'theta')
-        theta *= PI / 360
-        for dic in self.unit_cell:
-            x  = self.coor['x'] - dic['r0'][0]
-            y  = self.coor['y'] - dic['r0'][1]
-            self.coor['x'] = x * np.cos(theta) - y * np.sin(theta) + dic['r0'][0]
-            self.coor['y'] = y * np.cos(theta) + x* np.sin(theta) + dic['r0'][1]
+        theta *= PI / 180
+        x = self.coor['x'].copy()
+        y = self.coor['y'].copy()
+        self.coor['x'] = x * np.cos(theta) - y * np.sin(theta)
+        self.coor['y'] = y * np.cos(theta) + x * np.sin(theta)
 
     def clean_coor(self) -> None:
         '''
@@ -370,10 +368,10 @@ class Lattice():
         figsize: tuple[float, float] | None = None,
     ) -> Figure:
         '''
-        Plot lattice in hopping space.
+        Plot the lattice in real space.
 
         :param ms: Positive number. Default value 20. Markersize.
-        :param fs: Positve number. Default value 20. Fontsize.
+        :param fs: Positive number. Default value 20. Fontsize.
         :param plt_index: Boolean. Default value False. Plot site labels.
         :param axis: Boolean. Default value False. Plot axis.
         :param figsize: Tuple. Default value None. Figsize.