tbkit 0.4.1__tar.gz → 0.4.2__tar.gz

{tbkit-0.4.1/tbkit.egg-info → tbkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tbkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: A Python package to build and solve Tight-Binding models.
 Author-email: Charles Poli <cpoli374@gmail.com>
 Maintainer-email: cpoli <cpoli374@gmail.com>
@@ -97,6 +97,9 @@ topology alongside superconductivity.
   Kane-Mele) and Zeeman splitting.
 * **Edge states**: cut a ribbon (periodic in one direction, finite in the
   other) out of any periodic model, to see edge/surface physics.
+* **Surface spectral functions** of semi-infinite crystals (iterative
+  surface Green's function): edge and surface states, e.g. the surface
+  Dirac cone of a 3D topological insulator, without a finite slab.
 * **Density of states**, Gaussian- or Lorentzian-broadened, from either a
   real-space spectrum or a Brillouin-zone mesh.
 * A small library of ready-made lattices (chain, square, triangular,
@@ -116,7 +119,7 @@ topology alongside superconductivity.
 |----------------------------|---------------------------------------------------------|
 | `tbkit.Lattice`             | Define and manipulate site positions and sublattices.   |
 | `tbkit.System`              | Build the real-space Hamiltonian from a `Lattice` and solve it. |
-| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, DOS. |
+| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, surface spectral functions, DOS. |
 | `tbkit.Plot`                | Plot lattices, spectra, eigenstates, and the density of states. |
 | `tbkit.Propagation`         | Time-evolve a wavepacket.                               |
 | `tbkit.Save`                | Save figures/animations to disk.                        |
@@ -292,6 +295,7 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`topology/plot_tknn_hofstadter.py`](examples/topology/plot_tknn_hofstadter.py) | TKNN: Chern numbers of the Hofstadter bands from magnetic supercells, and the Diophantine equation. |
 | [`topology/plot_kane_mele_z2.py`](examples/topology/plot_kane_mele_z2.py) | The Kane-Mele Z2 invariant from Wannier-centre flow. |
 | [`topology/plot_fu_kane_parity.py`](examples/topology/plot_fu_kane_parity.py) | The Fu-Kane parity criterion on the BHZ model, checked against the Wannier flow. |
+| [`topology/plot_3d_topological_insulator.py`](examples/topology/plot_3d_topological_insulator.py) | 3D topological insulators: the strong index and the surface Dirac cone, from the surface spectral function of a semi-infinite crystal. |
 | [`topology/plot_quantum_geometry.py`](examples/topology/plot_quantum_geometry.py) | The quantum metric and Berry curvature of a Bloch band. |
 | [`topology/plot_tenfold_way.py`](examples/topology/plot_tenfold_way.py) | Symmetry classes of tight-binding models: the tenfold way. |
 | [`topology/plot_local_chern_marker.py`](examples/topology/plot_local_chern_marker.py) | The local Chern marker of a finite, disordered Haldane flake. |
@@ -345,6 +349,8 @@ Rendered docs (tutorial, API reference, example gallery): https://cpoli.github.i
   each one linked to the corresponding **tbkit** functionality and example
   above.
 * `docs/source/tbkit.rst` -- the API reference (auto-generated from docstrings).
+* [`ROADMAP.md`](ROADMAP.md) -- what is planned next, and what tbkit
+  does not do yet (compared with Kwant and PythTB).
 
 Build the HTML docs with `cd docs && make html` (output in `docs/build/html`).
 

{tbkit-0.4.1 → tbkit-0.4.2}/README.md

@@ -69,6 +69,9 @@ topology alongside superconductivity.
   Kane-Mele) and Zeeman splitting.
 * **Edge states**: cut a ribbon (periodic in one direction, finite in the
   other) out of any periodic model, to see edge/surface physics.
+* **Surface spectral functions** of semi-infinite crystals (iterative
+  surface Green's function): edge and surface states, e.g. the surface
+  Dirac cone of a 3D topological insulator, without a finite slab.
 * **Density of states**, Gaussian- or Lorentzian-broadened, from either a
   real-space spectrum or a Brillouin-zone mesh.
 * A small library of ready-made lattices (chain, square, triangular,
@@ -88,7 +91,7 @@ topology alongside superconductivity.
 |----------------------------|---------------------------------------------------------|
 | `tbkit.Lattice`             | Define and manipulate site positions and sublattices.   |
 | `tbkit.System`              | Build the real-space Hamiltonian from a `Lattice` and solve it. |
-| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, DOS. |
+| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, surface spectral functions, DOS. |
 | `tbkit.Plot`                | Plot lattices, spectra, eigenstates, and the density of states. |
 | `tbkit.Propagation`         | Time-evolve a wavepacket.                               |
 | `tbkit.Save`                | Save figures/animations to disk.                        |
@@ -264,6 +267,7 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`topology/plot_tknn_hofstadter.py`](examples/topology/plot_tknn_hofstadter.py) | TKNN: Chern numbers of the Hofstadter bands from magnetic supercells, and the Diophantine equation. |
 | [`topology/plot_kane_mele_z2.py`](examples/topology/plot_kane_mele_z2.py) | The Kane-Mele Z2 invariant from Wannier-centre flow. |
 | [`topology/plot_fu_kane_parity.py`](examples/topology/plot_fu_kane_parity.py) | The Fu-Kane parity criterion on the BHZ model, checked against the Wannier flow. |
+| [`topology/plot_3d_topological_insulator.py`](examples/topology/plot_3d_topological_insulator.py) | 3D topological insulators: the strong index and the surface Dirac cone, from the surface spectral function of a semi-infinite crystal. |
 | [`topology/plot_quantum_geometry.py`](examples/topology/plot_quantum_geometry.py) | The quantum metric and Berry curvature of a Bloch band. |
 | [`topology/plot_tenfold_way.py`](examples/topology/plot_tenfold_way.py) | Symmetry classes of tight-binding models: the tenfold way. |
 | [`topology/plot_local_chern_marker.py`](examples/topology/plot_local_chern_marker.py) | The local Chern marker of a finite, disordered Haldane flake. |
@@ -317,6 +321,8 @@ Rendered docs (tutorial, API reference, example gallery): https://cpoli.github.i
   each one linked to the corresponding **tbkit** functionality and example
   above.
 * `docs/source/tbkit.rst` -- the API reference (auto-generated from docstrings).
+* [`ROADMAP.md`](ROADMAP.md) -- what is planned next, and what tbkit
+  does not do yet (compared with Kwant and PythTB).
 
 Build the HTML docs with `cd docs && make html` (output in `docs/build/html`).
 

{tbkit-0.4.1 → tbkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tbkit"
-version = "0.4.1"
+version = "0.4.2"
 description = "A Python package to build and solve Tight-Binding models."
 readme = "README.md"
 license = "BSD-3-Clause"

{tbkit-0.4.1 → tbkit-0.4.2}/tbkit/__init__.py

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

{tbkit-0.4.1 → tbkit-0.4.2}/tbkit/error_handling.py

@@ -1546,6 +1546,16 @@ def lead_direction(direction):
         raise ValueError('\n\nParameter direction must be +1 or -1.\n')
 
 
+def surface_side(side):
+    '''
+    Check parameter *side* of *KSpace.surface_spectral_function*: +1 or -1.
+
+    :raises ValueError: Parameter side must be +1 or -1.
+    '''
+    if isinstance(side, bool) or side not in (1, -1):
+        raise ValueError('\n\nParameter side must be +1 or -1.\n')
+
+
 def nearest_cells(n):
     '''
     Check that a lead hopping reaches at most the neighbouring cells.

{tbkit-0.4.1 → tbkit-0.4.2}/tbkit/kspace.py

@@ -13,6 +13,7 @@ import tbkit.dos as dos
 import tbkit.occupation as occupation
 import tbkit.neighbours as neighbours
 from tbkit.lattice import Lattice
+from tbkit.transport import _green_surface_bulk
 
 
 PI = np.pi
@@ -1881,6 +1882,101 @@ class KSpace():
         return np.array([[np.trace(p0 @ dp[mu] @ dp[nu]) for nu in range(self.dim)]
                                for mu in range(self.dim)])
 
+    def surface_spectral_function(
+        self, ks: ArrayLike, energies: ArrayLike, direction: int, side: int = 1,
+        eta: float = 1e-2, bulk: bool = False, max_iter: int = 10000,
+    ) -> NDArray[np.float64]:
+        r'''
+        Get the spectral function of the surface of a semi-infinite crystal,
+
+        .. math::
+
+            A_s(\mathbf{k}_\parallel, E) = -\frac{1}{\pi}\,
+            \mathrm{Im}\,\mathrm{Tr}\, G_{00}(\mathbf{k}_\parallel, E + i\eta)\, ,
+
+        with :math:`G_{00}` the Green's function of the outermost unit cell:
+        the crystal fills the cells :math:`n\,\mathbf{a}_d`,
+        :math:`n = 0, 1, 2, \dots` along the primitive vector
+        :math:`\mathbf{a}_d` (``lat.prim_vec[direction]``), times *side*, and
+        is periodic along the others. It comes from the Lopez Sancho-Rubio
+        decimation (see *transport.surface_green*) of the chain of principal
+        layers (as many cells as the longest hopping along
+        :math:`\mathbf{a}_d` spans), so the crystal is truly semi-infinite: no
+        finite slab, and no states of the opposite surface. It is the
+        tight-binding picture of an ARPES map -- surface states (edge states,
+        in 2D; the end state of a 1D chain) show up as sharp lines inside the
+        bulk gaps. With *bulk*, the same quantity for a unit cell deep inside
+        the crystal: the bulk bands projected on the surface Brillouin zone.
+
+        :param ks: Real array, shape (nk, dim). k-points, in the coordinates
+            of *get_ham* (e.g. from a *k_path* of the surface Brillouin zone).
+            Only :math:`\mathbf{k}_\parallel` matters: the result does not
+            depend on the component along the reciprocal vector
+            :math:`\mathbf{b}_d`.
+        :param energies: Real number or real array. Energies :math:`E`.
+        :param direction: Integer, between 0 and dim-1. The primitive vector
+            normal to the surface (the one along which the crystal is
+            semi-infinite).
+        :param side: +1 or -1. Default value 1. The crystal extends along
+            :math:`+\mathbf{a}_d` (the surface faces :math:`-\mathbf{a}_d`) or
+            along :math:`-\mathbf{a}_d` (the opposite surface).
+        :param eta: Positive real. Default value 1e-2. Broadening: the
+            width of the lines, and the decay length (about :math:`v/\eta`
+            cells) over which the bulk is resolved.
+        :param bulk: Boolean. Default value False. If True, the spectral
+            function of a bulk unit cell instead of the surface one.
+        :param max_iter: Positive integer. Default value 10000. Maximum
+            number of decimation steps.
+
+        :returns:
+            * **A** -- Real ndarray, shape (nk, len(energies)).
+
+        Example usage::
+
+            # the (001) surface of a 3D model, along a path of the surface zone
+            A = ks.surface_spectral_function(k_path, np.linspace(-1, 1, 201), direction=2)
+        '''
+        error_handling.no_overlap(self._overlap_hop)
+        ks = np.atleast_2d(np.asarray(ks, dtype='f8'))
+        error_handling.ks(ks, self.dim)
+        error_handling.frequencies(energies, 'energies')
+        energies = np.atleast_1d(np.asarray(energies, dtype='f8'))
+        error_handling.direction(direction, self.dim)
+        error_handling.surface_side(side)
+        error_handling.positive_real(eta, 'eta')
+        error_handling.boolean(bulk, 'bulk')
+        error_handling.positive_int(max_iter, 'max_iter')
+        # H_m(k): the hoppings from a cell to the cell m a_d away, with the
+        # phase of their in-plane part only (independent of k along b_d)
+        a_dir = np.array(self.lat.prim_vec[direction], dtype='f8')
+        layers = {}
+        for (i, j, n, t), (_, _, R, _) in zip(self._hop_cells(), self._hop):
+            layers.setdefault(n[direction], []).append((i, j, R - n[direction] * a_dir, t))
+        k_cart = ks @ self.k_basis.T
+        blocks = {m: self._bloch_sum(hops, k_cart)[0] for m, hops in layers.items()}
+        blocks[0] = blocks.get(0, 0.) + (np.diag(self.onsite) + self._onsite_offdiag)[None]
+        width = max([abs(m) for m in layers] + [1])
+        norb, nk = self.norb, len(ks)
+
+        def layer(shift):
+            # block (p, q) couples cell p of a principal layer to cell q of
+            # the layer *shift* cells further into the crystal
+            out = np.zeros((nk, width, norb, width, norb), 'c16')
+            for p in range(width):
+                for q in range(width):
+                    m = side * (q - p + shift)
+                    if m in blocks:
+                        out[:, p, :, q, :] = blocks[m]
+            return out.reshape(nk, width * norb, width * norb)
+        h0, alpha, beta = layer(0), layer(width), layer(-width)
+        spec = np.empty((nk, len(energies)))
+        for n in range(nk):
+            gs, gb = _green_surface_bulk(energies + 1j * eta, h0[n], alpha[n], beta[n], 1e-12,
+                                                       max_iter, 'surface_spectral_function')
+            g = gb if bulk else gs
+            spec[n] = -np.trace(g[:, :norb, :norb], axis1=1, axis2=2).imag / PI
+        return spec
+
     def plot_dos(
         self,
         nk: int | tuple[int, int] = 30,

{tbkit-0.4.1 → tbkit-0.4.2}/tbkit/transport.py

@@ -77,33 +77,94 @@ def surface_green(
     error_handling.positive_real(eta, 'eta')
     error_handling.positive_real(tol, 'tol')
     error_handling.positive_int(max_iter, 'max_iter')
+    gs, _ = _green_surface_bulk(np.array([energy + 1j * eta]), h0, v, v.conj().T, tol, max_iter,
+                                             'surface_green')
+    return gs[0]
+
+
+def _green_surface_bulk(
+    z: NDArray[np.complex128], h0: NDArray[np.complex128], alpha: NDArray[np.complex128],
+    beta: NDArray[np.complex128], tol: float, max_iter: int, name: str,
+) -> tuple[NDArray[np.complex128], NDArray[np.complex128]]:
+    r'''
+    Private function. The surface and bulk Green's functions of one cell
+    of the semi-infinite chain of *_decimation* (*h0*, *alpha*, *beta* of
+    shape (m, m)) at the complex energies *z*, shapes (nz, m, m).
+
+    The first decimation step inverts :math:`z - h_0`: at an energy equal to
+    an eigenvalue of :math:`h_0` (E = 0 for a plain chain) that is
+    :math:`\sim1/\eta`, and the precision is lost. Regrouping n = 1, 2 or 3
+    cells into one (the same chain) moves those energies: at each energy,
+    the best-conditioned grouping is used.
+    '''
     m = len(h0)
-    # The first decimation step inverts E + i eta - h0: at an energy equal to
-    # an eigenvalue of h0 (E = 0 for a plain chain) that is ~1/eta, and the
-    # precision is lost. Regrouping n = 1, 2 or 3 cells into one (the same
-    # lead) moves those energies: use the best-conditioned grouping.
-    best = None
-    for n in (1, 2, 3):
-        hn = np.kron(np.eye(n), h0) + np.kron(np.eye(n, k=1), v) + np.kron(np.eye(n, k=-1), v.conj().T)
-        vn = np.kron(np.eye(n, k=1 - n), v) if n > 1 else v.copy()
-        smin = np.linalg.svd((energy + 1j * eta) * np.eye(n * m) - hn, compute_uv=False)[-1]
-        if best is None or smin > best[0] * (1. + 1e-12):
-            best = (smin, hn, vn)
-    _, hn, vn = best
-    z = (energy + 1j * eta) * np.eye(len(hn))
-    eps_s, eps = hn.copy(), hn.copy()
-    alpha, beta = vn.copy(), vn.conj().T.copy()
+    # Scaling cell n by r**n is a similarity transform that leaves the
+    # Green's function of every cell unchanged: balancing the couplings of a
+    # non-reciprocal chain keeps the renormalized ones from overflowing
+    # (r = 1 when beta = alpha^dagger).
+    n_a, n_b = np.linalg.norm(alpha), np.linalg.norm(beta)
+    if n_a > 0 and n_b > 0:
+        r = np.sqrt(n_b / n_a)
+        alpha, beta = alpha * r, beta / r
+    groups, best, choice = [], None, np.zeros(len(z), int)
+    for c, n in enumerate((1, 2, 3)):
+        hn = (np.kron(np.eye(n), h0) + np.kron(np.eye(n, k=1), alpha)
+               + np.kron(np.eye(n, k=-1), beta))
+        an = np.kron(np.eye(n, k=1 - n), alpha)
+        bn = np.kron(np.eye(n, k=n - 1), beta)
+        groups.append((hn, an, bn))
+        smin = np.linalg.svd(z[:, None, None] * np.eye(n * m)[None] - hn, compute_uv=False)[:, -1]
+        if best is None:
+            best = smin
+        else:
+            better = smin > best * (1. + 1e-12)
+            choice[better], best = c, np.where(better, smin, best)
+    gs, gb = np.empty((len(z), m, m), 'c16'), np.empty((len(z), m, m), 'c16')
+    for c, (hn, an, bn) in enumerate(groups):
+        sel = choice == c
+        if np.any(sel):
+            s_, b_ = _decimation(z[sel], hn, an, bn, tol, max_iter, name)
+            gs[sel], gb[sel] = s_[:, :m, :m], b_[:, :m, :m]
+    return gs, gb
+
+
+def _decimation(
+    z: NDArray[np.complex128], h0: NDArray[np.complex128], alpha: NDArray[np.complex128],
+    beta: NDArray[np.complex128], tol: float, max_iter: int, name: str,
+) -> tuple[NDArray[np.complex128], NDArray[np.complex128]]:
+    r'''
+    Private function. The Lopez Sancho-Rubio decimation of a semi-infinite
+    chain of cells :math:`0, 1, 2, \dots` (:math:`H_{nn} = h_0`,
+    :math:`H_{n,n+1} = \alpha`, :math:`H_{n+1,n} = \beta`, with
+    :math:`\beta = \alpha^\dagger` unless the chain is non-reciprocal) at
+    many complex energies *z* (shape (nz,)) at once; *h0*, *alpha* and *beta*
+    have shape (m, m) or (nz, m, m). Used by *surface_green* and
+    *KSpace.surface_spectral_function*, which validate the arguments. It
+    stops when the renormalized couplings are below *tol* at every energy
+    (a RuntimeError naming *name* after *max_iter* iterations).
+
+    :returns:
+        * **gs** -- Complex ndarray, shape (nz, m, m). Surface Green's function (cell 0).
+        * **gb** -- Complex ndarray, shape (nz, m, m). Bulk Green's function
+          (one cell of the infinite chain).
+    '''
+    m = h0.shape[-1]
+    zi = np.asarray(z, dtype='c16')[:, None, None] * np.eye(m)[None]
+    eps_s = np.broadcast_to(h0, zi.shape).astype('c16')
+    eps = eps_s.copy()
+    alpha = np.broadcast_to(alpha, zi.shape).astype('c16')
+    beta = np.broadcast_to(beta, zi.shape).astype('c16')
     for _ in range(max_iter):
-        g = LA.inv(z - eps)
+        g = np.linalg.inv(zi - eps)
         ag, bg = alpha @ g, beta @ g
         eps_s = eps_s + ag @ beta
         eps = eps + ag @ beta + bg @ alpha
         alpha, beta = ag @ alpha, bg @ beta
-        if np.linalg.norm(alpha) + np.linalg.norm(beta) < tol:
+        if np.all(np.linalg.norm(alpha, axis=(1, 2)) + np.linalg.norm(beta, axis=(1, 2)) < tol):
             break
     else:
-        error_handling.converged(False, 'surface_green')
-    return LA.inv(z - eps_s)[:m, :m]
+        error_handling.converged(False, name)
+    return np.linalg.inv(zi - eps_s), np.linalg.inv(zi - eps)
 
 
 def lead_from_kspace(ks, direction: int = 1) -> tuple[NDArray[np.complex128], NDArray[np.complex128]]:

{tbkit-0.4.1 → tbkit-0.4.2/tbkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tbkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: A Python package to build and solve Tight-Binding models.
 Author-email: Charles Poli <cpoli374@gmail.com>
 Maintainer-email: cpoli <cpoli374@gmail.com>
@@ -97,6 +97,9 @@ topology alongside superconductivity.
   Kane-Mele) and Zeeman splitting.
 * **Edge states**: cut a ribbon (periodic in one direction, finite in the
   other) out of any periodic model, to see edge/surface physics.
+* **Surface spectral functions** of semi-infinite crystals (iterative
+  surface Green's function): edge and surface states, e.g. the surface
+  Dirac cone of a 3D topological insulator, without a finite slab.
 * **Density of states**, Gaussian- or Lorentzian-broadened, from either a
   real-space spectrum or a Brillouin-zone mesh.
 * A small library of ready-made lattices (chain, square, triangular,
@@ -116,7 +119,7 @@ topology alongside superconductivity.
 |----------------------------|---------------------------------------------------------|
 | `tbkit.Lattice`             | Define and manipulate site positions and sublattices.   |
 | `tbkit.System`              | Build the real-space Hamiltonian from a `Lattice` and solve it. |
-| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, DOS. |
+| `tbkit.KSpace`              | Build and solve the Bloch Hamiltonian of a periodic `Lattice`; bands, Berry curvature/Chern numbers, anomalous and spin Hall conductivities, ribbons, surface spectral functions, DOS. |
 | `tbkit.Plot`                | Plot lattices, spectra, eigenstates, and the density of states. |
 | `tbkit.Propagation`         | Time-evolve a wavepacket.                               |
 | `tbkit.Save`                | Save figures/animations to disk.                        |
@@ -292,6 +295,7 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`topology/plot_tknn_hofstadter.py`](examples/topology/plot_tknn_hofstadter.py) | TKNN: Chern numbers of the Hofstadter bands from magnetic supercells, and the Diophantine equation. |
 | [`topology/plot_kane_mele_z2.py`](examples/topology/plot_kane_mele_z2.py) | The Kane-Mele Z2 invariant from Wannier-centre flow. |
 | [`topology/plot_fu_kane_parity.py`](examples/topology/plot_fu_kane_parity.py) | The Fu-Kane parity criterion on the BHZ model, checked against the Wannier flow. |
+| [`topology/plot_3d_topological_insulator.py`](examples/topology/plot_3d_topological_insulator.py) | 3D topological insulators: the strong index and the surface Dirac cone, from the surface spectral function of a semi-infinite crystal. |
 | [`topology/plot_quantum_geometry.py`](examples/topology/plot_quantum_geometry.py) | The quantum metric and Berry curvature of a Bloch band. |
 | [`topology/plot_tenfold_way.py`](examples/topology/plot_tenfold_way.py) | Symmetry classes of tight-binding models: the tenfold way. |
 | [`topology/plot_local_chern_marker.py`](examples/topology/plot_local_chern_marker.py) | The local Chern marker of a finite, disordered Haldane flake. |
@@ -345,6 +349,8 @@ Rendered docs (tutorial, API reference, example gallery): https://cpoli.github.i
   each one linked to the corresponding **tbkit** functionality and example
   above.
 * `docs/source/tbkit.rst` -- the API reference (auto-generated from docstrings).
+* [`ROADMAP.md`](ROADMAP.md) -- what is planned next, and what tbkit
+  does not do yet (compared with Kwant and PythTB).
 
 Build the HTML docs with `cd docs && make html` (output in `docs/build/html`).
 

{tbkit-0.4.1 → tbkit-0.4.2}/tbkit.egg-info/SOURCES.txt

@@ -60,6 +60,7 @@ tests/test_plot.py
 tests/test_propagation.py
 tests/test_regressions.py
 tests/test_save.py
+tests/test_surface_spectral.py
 tests/test_system.py
 tests/test_three_d.py
 tests/test_topology.py

tbkit-0.4.2/tests/test_surface_spectral.py

@@ -0,0 +1,182 @@
+"""
+Surface spectral functions of semi-infinite crystals (KSpace.surface_spectral_function).
+"""
+import unittest
+
+import numpy as np
+
+import tbkit.lattices as lattices
+from tbkit.lattice import Lattice
+from tbkit.kspace import KSpace, PAULI, ribbon
+
+CUBIC = [(1., 0., 0.), (0., 1., 0.), (0., 0., 1.)]
+SIGMA = [PAULI['x'], PAULI['y'], PAULI['z']]
+# Haldane-like model with a third-neighbour-cell bond along a1, so the
+# principal layer normal to a2 is one cell and normal to a1 two cells
+T2 = 0.2j
+HONEY_HOPS = [{'i': 0, 'j': 1, 'R': (0, 0), 't': 1.}, {'i': 0, 'j': 1, 'R': (-1, 0), 't': 1.},
+                        {'i': 0, 'j': 1, 'R': (0, -1), 't': 1.},
+                        {'i': 0, 'j': 0, 'R': (1, 0), 't': T2}, {'i': 0, 'j': 0, 'R': (0, -1), 't': T2},
+                        {'i': 0, 'j': 0, 'R': (-1, 1), 't': T2},
+                        {'i': 1, 'j': 1, 'R': (1, 0), 't': -T2}, {'i': 1, 'j': 1, 'R': (0, -1), 't': -T2},
+                        {'i': 1, 'j': 1, 'R': (-1, 1), 't': -T2},
+                        {'i': 0, 'j': 0, 'R': (2, 0), 't': 0.1}]
+HONEY_ONSITE = {'a': 0.3, 'b': -0.3}
+
+
+def chain(t=1.):
+    ks = KSpace(lattices.chain())
+    ks.set_hopping([{'i': 0, 'j': 0, 'R': (1,), 't': t}])
+    return ks
+
+
+def ti_hops():
+    '''Hoppings of the cubic 3D topological insulator m(k) tau_z + sum_i sin k_i tau_x sigma_i.'''
+    hops = []
+    for d in range(3):
+        R = tuple(int(x) for x in np.eye(3, dtype=int)[d])
+        hops += [{'i': 0, 'j': 0, 'R': R, 't': PAULI['0']}, {'i': 1, 'j': 1, 'R': R, 't': -PAULI['0']},
+                     {'i': 0, 'j': 1, 'R': R, 't': -0.5j * SIGMA[d]},
+                     {'i': 1, 'j': 0, 'R': R, 't': -0.5j * SIGMA[d]}]
+    return hops
+
+
+def ti_onsite(M):
+    return {'s': (M - 6) * PAULI['0'], 'p': -(M - 6) * PAULI['0']}
+
+
+TI_LAT = Lattice(unit_cell=[{'tag': 's', 'r0': (0., 0., 0.)}, {'tag': 'p', 'r0': (0., 0., 0.)}],
+                         prim_vec=CUBIC)
+
+
+def topological_insulator(M):
+    ks = KSpace(TI_LAT, spin=True)
+    ks.set_hopping(ti_hops())
+    ks.set_onsite(ti_onsite(M))
+    return ks
+
+
+def slab_spectral(H, rows, energies, eta):
+    '''-Im Tr G / pi over the orbitals *rows* of a finite slab Hamiltonian.'''
+    n = len(H)
+    return np.array([-np.trace(np.linalg.inv((e + 1j * eta) * np.eye(n) - H)[np.ix_(rows, rows)]).imag
+                             for e in energies]) / np.pi
+
+
+class TestSurfaceSpectralFunction(unittest.TestCase):
+
+    def test_chain_end_and_bulk(self):
+        # semi-infinite chain: A_s = sqrt(4 - E^2)/(2 pi), A_b = 1/(pi sqrt(4 - E^2)),
+        # including E = 0, where the cell Hamiltonian is singular
+        ch = chain()
+        E = np.linspace(-1.9, 1.9, 9)
+        for eta in (1e-6, 1e-9):
+            A = ch.surface_spectral_function([[0.]], E, 0, eta=eta)[0]
+            self.assertTrue(np.allclose(A, np.sqrt(4 - E ** 2) / (2 * np.pi), atol=1e-6))
+            B = ch.surface_spectral_function([[0.]], E, 0, eta=eta, bulk=True)[0]
+            self.assertTrue(np.allclose(B, 1 / (np.pi * np.sqrt(4 - E ** 2)), atol=1e-5))
+        # both ends alike; nothing outside the band; one number for a scalar energy
+        self.assertTrue(np.allclose(ch.surface_spectral_function([[0.]], E, 0, side=-1, eta=1e-6)[0],
+                                                np.sqrt(4 - E ** 2) / (2 * np.pi), atol=1e-6))
+        self.assertLess(ch.surface_spectral_function([[0.]], 2.5, 0, eta=1e-6)[0, 0], 1e-5)
+        self.assertEqual(ch.surface_spectral_function([0.], 0.5, 0).shape, (1, 1))
+
+    def test_spectral_sum_rule(self):
+        # int A_s dE = number of orbitals of the surface cell
+        ch = chain()
+        E = np.linspace(-60., 60., 24001)
+        A = ch.surface_spectral_function([[0.]], E, 0, eta=0.05)[0]
+        self.assertAlmostEqual(np.sum(A) * (E[1] - E[0]), 1., delta=2e-3)
+
+    def test_matches_thick_ribbon(self):
+        # the outer cell of a wide ribbon (eta resolves ~ 1/eta cells) is the
+        # semi-infinite surface, on both edges, normal to either primitive vector
+        lat = lattices.honeycomb()
+        ks = KSpace(lat)
+        ks.set_hopping(HONEY_HOPS)
+        ks.set_onsite(HONEY_ONSITE)
+        E = np.linspace(-3., 3., 13)
+        eta, width = 0.05, 200
+        k = np.array([0.37, 0.61]) @ ks.rec_vec_k
+        for direction in (0, 1):
+            rib = ribbon(lat, HONEY_HOPS, width, direction=direction, onsite=HONEY_ONSITE)
+            a_par = np.array(lat.prim_vec[1 - direction])
+            H = rib.get_ham([k @ a_par / np.linalg.norm(a_par)])
+            for side, rows in ((1, [0, 1]), (-1, [len(H) - 2, len(H) - 1])):
+                A = ks.surface_spectral_function([k], E, direction, side, eta=eta)[0]
+                self.assertTrue(np.allclose(A, slab_spectral(H, rows, E, eta), atol=1e-10))
+                # only k along the surface matters
+                A2 = ks.surface_spectral_function([k + 0.3 * ks.rec_vec_k[direction]], E, direction,
+                                                                   side, eta=eta)[0]
+                self.assertTrue(np.allclose(A, A2, atol=1e-12))
+
+    def test_matches_thick_slab_3d(self):
+        # a spinful 3D model against slabs cut normal to a2 (slab k = (k_x, k_z))
+        # and to a3 (slab k = (k_x, k_y)): the four orbitals of the outer cell
+        ti = topological_insulator(2.)
+        E, eta = np.linspace(-3., 3., 13), 0.1
+        for direction, k_slab, k in ((1, [0.4, -0.3], [0.4, 1.3, -0.3]), (2, [0.2, -0.1], [0.2, -0.1, 0.])):
+            slab = ribbon(TI_LAT, ti_hops(), 120, direction=direction, onsite=ti_onsite(2.), spin=True)
+            A = ti.surface_spectral_function([k], E, direction, eta=eta)[0]
+            ref = slab_spectral(slab.get_ham(k_slab), [0, 1, 2, 3], E, eta)
+            self.assertTrue(np.allclose(A, ref, atol=1e-10))
+
+    def test_topological_insulator_surface_dirac_cone(self):
+        kx = np.linspace(-0.6, 0.6, 121)
+        ks = np.column_stack([kx, 0 * kx, 0 * kx])
+        E = np.array([-0.4, 0., 0.2, 0.4])
+        ti = topological_insulator(2.)
+        A = ti.surface_spectral_function(ks, E, 2, eta=0.02)
+        bulk = ti.surface_spectral_function(ks, E, 2, eta=0.02, bulk=True)
+        self.assertLess(bulk.max(), 0.05)  # all four energies in the bulk gap
+        self.assertGreater(A[60, 1], 10.)  # the Dirac point at the zone centre
+        for n, e in ((2, 0.2), (3, 0.4), (0, -0.4)):
+            # exactly two peaks, at k = +-|E| (velocity 1)
+            col = A[:, n]
+            peaks = [i for i in range(1, len(kx) - 1)
+                         if col[i] > col[i - 1] and col[i] > col[i + 1] and col[i] > 1.]
+            self.assertEqual(len(peaks), 2)
+            self.assertTrue(np.allclose(np.abs(kx[peaks]), abs(e), atol=0.02))
+        # no surface states in the gap of the trivial insulator
+        trivial = topological_insulator(-2.)
+        self.assertLess(trivial.surface_spectral_function(ks, E, 2, eta=0.02).max(), 0.05)
+
+    def test_non_reciprocal_chain(self):
+        # Hatano-Nelson: the surface Green's function obeys g = 1/(z - tR tL g),
+        # that of a Hermitian chain with t = sqrt(tR tL)
+        hn = KSpace(lattices.chain())
+        hn.set_hopping([{'i': 0, 'j': 0, 'R': (1,), 't': 2.}, {'i': 0, 'j': 0, 'R': (-1,), 't': 0.5}],
+                              hermitian=False)
+        E = np.linspace(-1.5, 1.5, 7)
+        self.assertTrue(np.allclose(hn.surface_spectral_function([[0.]], E, 0, eta=1e-3),
+                                                chain().surface_spectral_function([[0.]], E, 0, eta=1e-3)))
+
+    def test_decoupled_layers(self):
+        # no hopping along the surface normal: each layer is an isolated chain
+        lat = lattices.square()
+        ks = KSpace(lat)
+        ks.set_hopping([{'i': 0, 'j': 0, 'R': (1, 0), 't': 1.}])
+        kx, E = 0.7, np.linspace(-3., 3., 7)
+        A = ks.surface_spectral_function([[kx, 0.]], E, 1, eta=0.1)[0]
+        e0 = 2 * np.cos(kx)
+        self.assertTrue(np.allclose(A, 0.1 / np.pi / ((E - e0) ** 2 + 0.01)))
+
+    def test_errors(self):
+        ch = chain()
+        f = ch.surface_spectral_function
+        self.assertRaises(ValueError, f, [[0., 0.]], 0., 0)
+        self.assertRaises(TypeError, f, [[0.]], [0.1j], 0)
+        self.assertRaises(ValueError, f, [[0.]], [], 0)
+        self.assertRaises(ValueError, f, [[0.]], 0., 1)
+        self.assertRaises(TypeError, f, [[0.]], 0., 0.)
+        self.assertRaises(ValueError, f, [[0.]], 0., 0, 0)
+        self.assertRaises(ValueError, f, [[0.]], 0., 0, True)
+        self.assertRaises(ValueError, f, [[0.]], 0., 0, 1, -1.)
+        self.assertRaises(TypeError, f, [[0.]], 0., 0, 1, 0.1, 1)
+        self.assertRaises(RuntimeError, f, [[0.]], 0.5, 0, 1, 1e-9, False, 2)
+        ch.set_overlap([{'i': 0, 'j': 0, 'R': (1,), 't': 0.1}])
+        self.assertRaises(ValueError, f, [[0.]], 0., 0)
+
+
+if __name__ == '__main__':
+    unittest.main()