tbkit 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tbkit
-Version: 0.4.0
+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.                        |
@@ -130,7 +133,12 @@ topology alongside superconductivity.
 | `tbkit.meanfield`           | The Hubbard model in (unrestricted Hartree-Fock) mean field. |
 | `tbkit.bdg`                 | Bogoliubov-de Gennes Hamiltonians and pairings.         |
 | `tbkit.exceptional`         | Exceptional and diabolical points of 2D bands: vorticity, discriminant winding, EP finder, Fermi arcs, encircling. |
+| `tbkit.higher_order`        | Higher-order topology: nested Wilson loops, Wannier-sector polarizations, the BBH quadrupole moment, corner charges. |
+| `tbkit.moire`               | Supercells, band unfolding and spectral functions, commensurate twisted bilayers. |
 | `tbkit.floquet`             | Floquet theory; `FloquetKSpace`/`DrivenKSpace` for driven Bloch models, `step_drive`, and the winding number of anomalous Floquet phases. |
+| `tbkit.neighbours`          | Neighbour shells of a periodic lattice; `KSpace.set_hopping` by neighbour order, angle and sublattice pair, as in `System`. |
+| `tbkit.bridges`             | Move a model between `System` and `KSpace` (open samples and tori). |
+| `tbkit.io`                  | Save and load `Lattice`/`System`/`KSpace` models (`.npz`); import Wannier90 `_hr.dat` models. |
 
 ## Install
 
@@ -287,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. |
@@ -309,10 +318,24 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`hall_effects/plot_anomalous_hall_effect.py`](examples/hall_effects/plot_anomalous_hall_effect.py) | The anomalous Hall effect: sigma_xy(E_F) of the Haldane model, quantized at C in the gap, not in the bands. |
 | [`hall_effects/plot_anomalous_hall_disorder.py`](examples/hall_effects/plot_anomalous_hall_disorder.py) | The anomalous Hall plateau of a disordered Haldane torus, by the Kubo-Bastin kernel polynomial method. |
 | [`hall_effects/plot_intrinsic_spin_hall_effect.py`](examples/hall_effects/plot_intrinsic_spin_hall_effect.py) | The intrinsic spin Hall effect: the Kane-Mele plateau at e/2pi, and its departure from quantization under Rashba coupling. |
-
-The `examples/` directory also has five older Jupyter notebooks (graphene
-flakes, kagome/Lieb/dumbbell lattices, disorder, strain, time propagation)
-predating the 0.2 API refresh below.
+| [`models/plot_neighbour_hoppings.py`](examples/models/plot_neighbour_hoppings.py) | Hoppings by neighbour order in k-space: third-nearest-neighbour graphene with overlaps. |
+| [`models/plot_pipeline_bridges.py`](examples/models/plot_pipeline_bridges.py) | From real space to k-space and back: the Haldane model's torus spectrum equals its mesh bands. |
+| [`models/plot_save_load.py`](examples/models/plot_save_load.py) | Saving and reloading models: identical Hamiltonians after a round trip through disk. |
+| [`models/plot_maximally_localized_wannier_functions.py`](examples/models/plot_maximally_localized_wannier_functions.py) | Maximally localized Wannier functions: graphene's pi bands from a Wannier90 `_hr.dat` file. |
+| [`higher_order/plot_quadrupole_insulator.py`](examples/higher_order/plot_quadrupole_insulator.py) | The BBH quadrupole insulator: nested Wilson loop, q_xy = 1/2, four corner states and corner charges +-1/2. |
+| [`moire/plot_band_unfolding.py`](examples/moire/plot_band_unfolding.py) | Band unfolding: exact for a pristine supercell, coherence factors, and A(k, omega) of a disordered graphene supercell. |
+| [`moire/plot_magic_angle_twisted_bilayer.py`](examples/moire/plot_magic_angle_twisted_bilayer.py) | Twisted bilayer graphene: Bistritzer-MacDonald velocity and flat bands at the magic alpha. |
+| [`superconductivity/plot_bcs_gap_equation.py`](examples/superconductivity/plot_bcs_gap_equation.py) | The real-space BCS gap equation: Delta(T), Delta(0)/T_c = 1.764, and the proximity effect. |
+| [`correlations/plot_noncollinear_120_degree_order.py`](examples/correlations/plot_noncollinear_120_degree_order.py) | Non-collinear mean field: the 120-degree order of the half-filled triangular Hubbard model. |
+| [`tight_binding/plot_building_finite_lattices.py`](examples/tight_binding/plot_building_finite_lattices.py) | Building finite lattices: cuts, dangling sites, lattice arithmetic, rotations. |
+| [`tight_binding/plot_defects_and_impurities.py`](examples/tight_binding/plot_defects_and_impurities.py) | A vacancy zero mode and an impurity bound state in a graphene flake. |
+| [`dynamics/plot_wavepacket_interference.py`](examples/dynamics/plot_wavepacket_interference.py) | Wave propagation: Aharonov-Bohm caging on a ring and a state trapped at a domain wall. |
+
+The five pre-0.2 Jupyter notebooks were replaced by the gallery scripts
+`tight_binding/plot_building_finite_lattices.py`,
+`tight_binding/plot_defects_and_impurities.py` and
+`dynamics/plot_wavepacket_interference.py` (their other content is covered
+by the strain, correlations and non-Hermitian examples).
 
 ## Documentation
 
@@ -326,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`).
 
@@ -343,9 +368,7 @@ cleaned up the API:
 
 For continuity, the pre-0.2 lowercase class names (`lattice`, `system`,
 `plot`, `propagation`, `save`) remain available as aliases of the new
-classes, so `from tbkit.lattice import lattice` still works. Example
-notebooks predating 0.2 still use byte-string tags (`b'a'`) and will need
-that one mechanical change to run on the current version.
+classes, so `from tbkit.lattice import lattice` still works.
 
 ## License
 

{tbkit-0.4.0 → 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.                        |
@@ -102,7 +105,12 @@ topology alongside superconductivity.
 | `tbkit.meanfield`           | The Hubbard model in (unrestricted Hartree-Fock) mean field. |
 | `tbkit.bdg`                 | Bogoliubov-de Gennes Hamiltonians and pairings.         |
 | `tbkit.exceptional`         | Exceptional and diabolical points of 2D bands: vorticity, discriminant winding, EP finder, Fermi arcs, encircling. |
+| `tbkit.higher_order`        | Higher-order topology: nested Wilson loops, Wannier-sector polarizations, the BBH quadrupole moment, corner charges. |
+| `tbkit.moire`               | Supercells, band unfolding and spectral functions, commensurate twisted bilayers. |
 | `tbkit.floquet`             | Floquet theory; `FloquetKSpace`/`DrivenKSpace` for driven Bloch models, `step_drive`, and the winding number of anomalous Floquet phases. |
+| `tbkit.neighbours`          | Neighbour shells of a periodic lattice; `KSpace.set_hopping` by neighbour order, angle and sublattice pair, as in `System`. |
+| `tbkit.bridges`             | Move a model between `System` and `KSpace` (open samples and tori). |
+| `tbkit.io`                  | Save and load `Lattice`/`System`/`KSpace` models (`.npz`); import Wannier90 `_hr.dat` models. |
 
 ## Install
 
@@ -259,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. |
@@ -281,10 +290,24 @@ thumbnailed example gallery under `docs/source/api/gallery/`.
 | [`hall_effects/plot_anomalous_hall_effect.py`](examples/hall_effects/plot_anomalous_hall_effect.py) | The anomalous Hall effect: sigma_xy(E_F) of the Haldane model, quantized at C in the gap, not in the bands. |
 | [`hall_effects/plot_anomalous_hall_disorder.py`](examples/hall_effects/plot_anomalous_hall_disorder.py) | The anomalous Hall plateau of a disordered Haldane torus, by the Kubo-Bastin kernel polynomial method. |
 | [`hall_effects/plot_intrinsic_spin_hall_effect.py`](examples/hall_effects/plot_intrinsic_spin_hall_effect.py) | The intrinsic spin Hall effect: the Kane-Mele plateau at e/2pi, and its departure from quantization under Rashba coupling. |
-
-The `examples/` directory also has five older Jupyter notebooks (graphene
-flakes, kagome/Lieb/dumbbell lattices, disorder, strain, time propagation)
-predating the 0.2 API refresh below.
+| [`models/plot_neighbour_hoppings.py`](examples/models/plot_neighbour_hoppings.py) | Hoppings by neighbour order in k-space: third-nearest-neighbour graphene with overlaps. |
+| [`models/plot_pipeline_bridges.py`](examples/models/plot_pipeline_bridges.py) | From real space to k-space and back: the Haldane model's torus spectrum equals its mesh bands. |
+| [`models/plot_save_load.py`](examples/models/plot_save_load.py) | Saving and reloading models: identical Hamiltonians after a round trip through disk. |
+| [`models/plot_maximally_localized_wannier_functions.py`](examples/models/plot_maximally_localized_wannier_functions.py) | Maximally localized Wannier functions: graphene's pi bands from a Wannier90 `_hr.dat` file. |
+| [`higher_order/plot_quadrupole_insulator.py`](examples/higher_order/plot_quadrupole_insulator.py) | The BBH quadrupole insulator: nested Wilson loop, q_xy = 1/2, four corner states and corner charges +-1/2. |
+| [`moire/plot_band_unfolding.py`](examples/moire/plot_band_unfolding.py) | Band unfolding: exact for a pristine supercell, coherence factors, and A(k, omega) of a disordered graphene supercell. |
+| [`moire/plot_magic_angle_twisted_bilayer.py`](examples/moire/plot_magic_angle_twisted_bilayer.py) | Twisted bilayer graphene: Bistritzer-MacDonald velocity and flat bands at the magic alpha. |
+| [`superconductivity/plot_bcs_gap_equation.py`](examples/superconductivity/plot_bcs_gap_equation.py) | The real-space BCS gap equation: Delta(T), Delta(0)/T_c = 1.764, and the proximity effect. |
+| [`correlations/plot_noncollinear_120_degree_order.py`](examples/correlations/plot_noncollinear_120_degree_order.py) | Non-collinear mean field: the 120-degree order of the half-filled triangular Hubbard model. |
+| [`tight_binding/plot_building_finite_lattices.py`](examples/tight_binding/plot_building_finite_lattices.py) | Building finite lattices: cuts, dangling sites, lattice arithmetic, rotations. |
+| [`tight_binding/plot_defects_and_impurities.py`](examples/tight_binding/plot_defects_and_impurities.py) | A vacancy zero mode and an impurity bound state in a graphene flake. |
+| [`dynamics/plot_wavepacket_interference.py`](examples/dynamics/plot_wavepacket_interference.py) | Wave propagation: Aharonov-Bohm caging on a ring and a state trapped at a domain wall. |
+
+The five pre-0.2 Jupyter notebooks were replaced by the gallery scripts
+`tight_binding/plot_building_finite_lattices.py`,
+`tight_binding/plot_defects_and_impurities.py` and
+`dynamics/plot_wavepacket_interference.py` (their other content is covered
+by the strain, correlations and non-Hermitian examples).
 
 ## Documentation
 
@@ -298,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`).
 
@@ -315,9 +340,7 @@ cleaned up the API:
 
 For continuity, the pre-0.2 lowercase class names (`lattice`, `system`,
 `plot`, `propagation`, `save`) remain available as aliases of the new
-classes, so `from tbkit.lattice import lattice` still works. Example
-notebooks predating 0.2 still use byte-string tags (`b'a'`) and will need
-that one mechanical change to run on the current version.
+classes, so `from tbkit.lattice import lattice` still works.
 
 ## License
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tbkit"
-version = "0.4.0"
+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.0 → tbkit-0.4.2}/tbkit/__init__.py

@@ -6,7 +6,7 @@
 
 """tbkit: build and solve Tight-Binding models."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "Lattice", "System", "Plot", "Propagation", "Save", "KSpace",
@@ -33,3 +33,17 @@ from tbkit.floquet import FloquetKSpace, DrivenKSpace, StepDrive, step_drive
 from tbkit.meanfield import MeanFieldResult, hubbard_mean_field
 from tbkit.exceptional import ExceptionalPoints, Encircling, find_exceptional_points
 import tbkit.error_handling
+# Model I/O (tbkit.io): appended here to keep the list above untouched.
+from tbkit.io import save_model, load_model, read_wannier90
+__all__ += ["save_model", "load_model", "read_wannier90"]
+
+# Higher-order topology, moire supercells, self-consistent interactions
+from tbkit.higher_order import CornerCharges, quadrupole_moment, corner_charges
+__all__ += ["CornerCharges", "quadrupole_moment", "corner_charges"]
+from tbkit.moire import SupercellKSpace, MoireKSpace, supercell, twisted_bilayer
+__all__ += ["SupercellKSpace", "MoireKSpace", "supercell", "twisted_bilayer"]
+from tbkit.meanfield import NonCollinearResult, hubbard_mean_field_noncollinear
+from tbkit.bdg import GapResult, s_wave_gap
+__all__ += ["NonCollinearResult", "hubbard_mean_field_noncollinear", "GapResult", "s_wave_gap"]
+from tbkit.transport import RecursiveTransport
+__all__ += ["RecursiveTransport"]

{tbkit-0.4.0 → tbkit-0.4.2}/tbkit/bdg.py

@@ -161,3 +161,110 @@ def particle_hole(n: int) -> NDArray[np.float64]:
     '''
     error_handling.positive_int(n, 'n')
     return np.kron(np.array([[0., 1.], [1., 0.]]), np.eye(n))
+
+
+class GapResult():
+    r'''
+    Self-consistent s-wave pairing of *s_wave_gap*.
+
+    :ivar delta: Complex ndarray. Gap :math:`\Delta_i` on every site.
+    :ivar energies: Real ndarray, shape (2N,). Spectrum of the reduced BdG
+        Hamiltonian (symmetric, :math:`\pm E_n`).
+    :ivar states: Complex ndarray, shape (2N, 2N). Its eigenvectors
+        :math:`(u_n, v_n)` (columns).
+    :ivar iterations: Integer. Number of iterations.
+    '''
+
+    def __init__(self, delta, energies, states, iterations) -> None:
+        self.delta = delta
+        self.energies = energies
+        self.states = states
+        self.iterations = iterations
+
+    @property
+    def mean_gap(self) -> float:
+        r'''
+        Average :math:`|\Delta_i|` over the sites.
+        '''
+        return float(np.mean(np.abs(self.delta)))
+
+
+def s_wave_gap(
+    ham, V: float | NDArray, mu: float = 0., temperature: float = 0., delta0: complex | NDArray = 0.1,
+    mixing: float = 1., tol: float = 1e-8, max_iter: int = 10000,
+) -> GapResult:
+    r'''
+    Solve the real-space gap equation of an s-wave superconductor
+    self-consistently (the attractive Hubbard model
+    :math:`-\sum_iV_in_{i\uparrow}n_{i\downarrow}` in the BCS mean-field
+    approximation, de Gennes 1966). For a spin-independent *ham* the singlet
+    BdG Hamiltonian reduces to the Nambu basis
+    :math:`(c_{i\uparrow}, c^\dagger_{i\downarrow})`,
+
+    .. math::
+
+        H = \begin{pmatrix} h-\mu & \Delta\\ \Delta^* & -(h-\mu)^*\end{pmatrix}\, ,
+        \qquad \Delta = \mathrm{diag}(\Delta_i)\, ,
+
+    whose eigenvectors :math:`(u_n, v_n)`, :math:`E_n > 0`, give the gap
+    equation
+
+    .. math::
+
+        \Delta_i = V_i\,\langle c_{i\downarrow}c_{i\uparrow}\rangle
+        = V_i\sum_{E_n>0}u_n(i)\,v_n^*(i)\tanh\frac{E_n}{2T}\, ,
+
+    iterated (with linear mixing) until self-consistent. On a clean lattice
+    it is the BCS gap equation :math:`1 = \frac{V}{N}\sum_{\mathbf{k}}
+    \tanh(E_{\mathbf{k}}/2T)/2E_{\mathbf{k}}`, with
+    :math:`\Delta(T_c) = 0` at :math:`T_c \approx \Delta(0)/1.764` at weak
+    coupling. The chemical potential is fixed (the Hartree shift
+    :math:`-V_in_i/2` is left out, i.e. absorbed in :math:`\mu`). Near
+    :math:`T_c` the iteration slows down (the linearized map has an
+    eigenvalue close to 1): raise *max_iter* there.
+
+    :param ham: Square Hermitian matrix, (N, N), spin independent (e.g. *System.ham*).
+    :param V: Positive real, or array of N non-negative reals. Attraction.
+    :param mu: Real number. Default value 0. Chemical potential.
+    :param temperature: Positive real or zero. Default value 0.
+    :param delta0: Number, or array of N numbers. Default value 0.1.
+        Initial gap.
+    :param mixing: Real in (0, 1]. Default value 1 (plain iteration).
+    :param tol: Positive real. Default value 1e-8. Convergence threshold
+        on the largest change of :math:`\Delta_i`.
+    :param max_iter: Positive integer. Default value 10000.
+
+    :returns:
+        * **result** -- :class:`GapResult`.
+    '''
+    h = ham.toarray() if hasattr(ham, 'toarray') else np.asarray(ham)
+    error_handling.square_matrix(h, 'ham')
+    error_handling.hermitian_dense(h)
+    n = len(h)
+    error_handling.interaction(V, n)
+    error_handling.real_number(mu, 'mu')
+    error_handling.positive_real_zero(temperature, 'temperature')
+    error_handling.pairing_amplitudes(delta0, n)
+    error_handling.mixing(mixing)
+    error_handling.positive_real(tol, 'tol')
+    error_handling.positive_int(max_iter, 'max_iter')
+    V = np.broadcast_to(np.asarray(V, dtype='f8'), (n,))
+    delta = np.broadcast_to(np.asarray(delta0, dtype='c16'), (n,)).copy()
+    xi = h.astype('c16') - mu * np.eye(n)
+    big = np.zeros((2 * n, 2 * n), 'c16')
+    big[:n, :n], big[n:, n:] = xi, -xi.conj()
+    diag = np.arange(n)
+    for it in range(1, max_iter + 1):
+        big[diag, diag + n] = delta
+        big[diag + n, diag] = delta.conj()
+        en, vec = np.linalg.eigh(big)
+        pos = en > 0
+        weight = np.tanh(en[pos] / (2 * temperature)) if temperature > 0 else np.ones(pos.sum())
+        new = V * np.einsum('in,in,n->i', vec[:n, pos], vec[n:, pos].conj(), weight)
+        change = np.max(np.abs(new - delta))
+        delta = (1 - mixing) * delta + mixing * new
+        if change < tol:
+            break
+    else:
+        error_handling.converged(False, 's_wave_gap')
+    return GapResult(new, en, vec, it)

tbkit-0.4.2/tbkit/bridges.py

@@ -0,0 +1,264 @@
+r'''
+Bridges between the two pipelines of tbkit: the real-space *System* (a
+finite lattice, its sparse Hamiltonian) and the reciprocal-space *KSpace*
+(the Bloch Hamiltonian :math:`H(\mathbf{k})` of the infinite lattice).
+
+* *kspace_from_system* reads the Bloch model off a translation-invariant
+  *System* built the real-space way (*get_lattice*, *set_hopping* by
+  neighbour order, *set_onsite*, ...).
+* *finite_model* and *finite_system* cut a finite sample (open boundaries,
+  or a torus) out of a *KSpace* model: its sparse Hamiltonian with the site
+  positions, or a ready-to-use *System*.
+
+Both use the convention of *KSpace.finite_ham*: the hopping
+:math:`t_{ij}(\mathbf{R}) = \langle i,\mathbf{0}|H|j,\mathbf{R}\rangle`
+joins orbital *i* of every cell to orbital *j* of the cell :math:`\mathbf{R}`
+further. So, for the same model, the spectrum of a System on an
+:math:`N_1\times N_2` torus is the set of KSpace bands on the
+:math:`N_1\times N_2` Brillouin-zone mesh.
+'''
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+import scipy.sparse as sp
+
+import tbkit.error_handling as error_handling
+import tbkit.neighbours as neighbours
+from tbkit.kspace import KSpace
+from tbkit.lattice import Lattice
+from tbkit.orbital import OrbitalSystem
+from tbkit.system import System, HOP_DTYPE, ATOL, _upper
+
+
+def _coords(lat: Lattice) -> NDArray[np.float64]:
+    '''
+    Private function. Site coordinates of a finite lattice, shape (sites, space_dim).
+    '''
+    return np.stack([lat.coor[f] for f in ('x', 'y', 'z')[:lat.space_dim]], axis=1)
+
+
+def cell_orbitals(lat: Lattice) -> tuple[NDArray[np.int64], NDArray[np.int64]]:
+    r'''
+    Get, for every site of a finite lattice (*lat.coor*), the unit-cell
+    orbital it is a copy of and its cell: site *s* sits at
+    :math:`\boldsymbol\tau_{o_s} + \sum_k n_{s,k}\mathbf{a}_k`, with the tag
+    of orbital :math:`o_s` (within ``ATOL``).
+
+    :param lat: **Lattice** instance, after *get_lattice* (sites may have
+        been removed, but not moved).
+
+    :returns:
+        * **cells** -- Integer ndarray, shape (sites, dim). :math:`n_{s,k}`.
+        * **orbitals** -- Integer ndarray, shape (sites,). :math:`o_s`.
+    '''
+    error_handling.lat(lat)
+    error_handling.empty_coor(lat.coor)
+    a, tau, tags = neighbours._geometry(lat)
+    pos = _coords(lat)
+    pinv = np.linalg.pinv(a)
+    match = np.zeros((lat.sites, len(tau)), bool)
+    cells = np.zeros((lat.sites, len(tau), len(a)), int)
+    for o in range(len(tau)):
+        rel = pos - tau[o]
+        n = np.rint(rel @ pinv).astype(int)
+        match[:, o] = (np.linalg.norm(n @ a - rel, axis=1) < ATOL) & (lat.coor['tag'] == tags[o])
+        cells[:, o] = n
+    error_handling.lattice_sites(match.sum(axis=1))
+    orb = np.argmax(match, axis=1)
+    return cells[np.arange(lat.sites), orb], orb
+
+
+def kspace_from_system(sys: System, periodic: bool = False, tol: float = 1e-9) -> KSpace:
+    r'''
+    Get the Bloch Hamiltonian of a periodic model defined the real-space
+    way: every matrix element :math:`H_{ab}` of the finite *System* (built
+    by *get_ham*) joins orbital :math:`o_a` of cell :math:`\mathbf{n}_a` to
+    orbital :math:`o_b` of cell :math:`\mathbf{n}_b` (see *cell_orbitals*),
+    i.e. is the hopping :math:`t_{o_ao_b}(\mathbf{n}_b-\mathbf{n}_a)` of the
+    infinite lattice. Each such hopping must take the same value in every
+    cell where it appears (bonds cut by the boundary are simply missing).
+    The lattice must be large enough to hold every bond of the model.
+
+    A System on a torus (*periodic*, e.g. from *finite_system*) has bonds
+    that wrap around: their lattice vectors are then taken modulo the
+    :math:`N_1\times N_2\times\dots` cells of *get_lattice*, as the shortest
+    image (so the model's range must stay below half the torus).
+
+    A Hermitian hopping matrix gives a Hermitian model (one representative
+    per bond, *set_hopping* adding the conjugate); otherwise every matrix
+    element is kept, with ``hermitian=False``. Onsite energies are taken
+    orbital by orbital.
+
+    :param sys: **System** instance with its hoppings set (one orbital per site).
+    :param periodic: Boolean. Default value False. The System is a torus
+        of the *lat.n1* x *lat.n2* (x *lat.n3*) cells of *get_lattice*.
+    :param tol: Positive real number. Default value 1e-9. Largest allowed
+        difference between equivalent matrix elements.
+
+    :returns:
+        * **ks** -- **KSpace** instance (spinless), on a new **Lattice**
+          with the *unit_cell* and *prim_vec* of *sys.lat*.
+
+    Example usage::
+
+        lat = lattices.honeycomb()
+        lat.get_lattice(6, 6)
+        sys = System(lat)
+        sys.set_hopping([{'n': 1, 't': -1.}, {'n': 2, 't': 0.1}])
+        gra = kspace_from_system(sys)   # the Bloch model of the same graphene
+    '''
+    error_handling.sys(sys)
+    error_handling.not_orbital_system(sys, OrbitalSystem)
+    error_handling.boolean(periodic, 'periodic')
+    error_handling.positive_real(tol, 'tol')
+    sys.get_ham()
+    cells, orb = cell_orbitals(sys.lat)
+    ham = sys.ham.tocoo()
+    rows, cols, vals = ham.row, ham.col, ham.data.astype('c16')
+    R = cells[cols] - cells[rows]
+    if periodic:
+        sizes = np.array((sys.lat.n1, sys.lat.n2, sys.lat.n3)[:R.shape[1]])
+        R = (R + sizes // 2) % sizes - sizes // 2  # shortest image, in [-N/2, N/2)
+        error_handling.torus_range(R, sizes)
+    keys = np.column_stack([orb[rows], orb[cols], R])
+    uniq, first, inv = np.unique(keys, axis=0, return_index=True, return_inverse=True)
+    inv = inv.ravel()
+    values = vals[first]
+    error_handling.translation_invariant(float(np.abs(vals - values[inv]).max()), tol)
+    off = ham - sp.diags(ham.diagonal())
+    hermitian = bool(abs(off - off.conj().T).max() <= tol)
+    lat = Lattice(unit_cell=list(sys.lat.unit_cell), prim_vec=list(sys.lat.prim_vec))
+    ks = KSpace(lat)
+    list_hop = []
+    for key, t in zip(uniq, values):
+        i, j, R = int(key[0]), int(key[1]), tuple(int(n) for n in key[2:])
+        if i == j and not any(R):
+            ks.onsite[i] = t
+            continue
+        nonzero = [n for n in R if n != 0]
+        if hermitian and not ((nonzero and nonzero[0] > 0) or (not nonzero and i < j)):
+            continue  # the conjugate of a kept representative
+        list_hop.append({'i': i, 'j': j, 'R': R, 't': complex(t)})
+    ks.set_hopping(list_hop, hermitian=hermitian)
+    return ks
+
+
+def _finite_sites(ks: KSpace, n_cells: tuple[int, ...]) -> tuple[NDArray[np.float64], NDArray]:
+    '''
+    Private function. Positions and tags of the rows of *ks.finite_ham(n_cells)*.
+    '''
+    n_tot = int(np.prod(n_cells))
+    cells = np.array(np.unravel_index(np.arange(n_tot), n_cells, order='F')).T
+    a = np.array(ks.lat.prim_vec, dtype='f8')
+    pos = (cells @ a)[:, None, :] + ks.orbital_positions()[None, :, :]
+    tags = np.repeat(ks.tags, 2) if ks.spin else ks.tags
+    return pos.reshape(n_tot * ks.norb, ks.space_dim), np.tile(tags, n_tot)
+
+
+def finite_model(
+    ks: KSpace, n_cells: int | tuple[int, ...], periodic: bool = False,
+) -> tuple[sp.csr_matrix, NDArray[np.float64], NDArray]:
+    r'''
+    Get a finite sample of a *KSpace* model: its sparse Hamiltonian (that of
+    *KSpace.finite_ham*, open or periodic boundaries), with the position
+    and tag of every row. Spinful models are supported (the two spin
+    components of a site share its position).
+
+    :param ks: **KSpace** instance.
+    :param n_cells: Positive integer, or tuple of *dim* positive integers.
+        Number of unit cells along each primitive vector.
+    :param periodic: Boolean. Default value False. Periodic boundaries (a torus).
+
+    :returns:
+        * **ham** -- Complex CSR matrix, shape (N*norb, N*norb).
+        * **positions** -- Real ndarray, shape (N*norb, space_dim). Row
+          :math:`c\,\mathrm{norb}+o` sits at :math:`\boldsymbol\tau_o + \sum_k n_k\mathbf{a}_k`
+          (cell *c* has :math:`c = n_1 + N_1 n_2 + N_1N_2 n_3`).
+        * **tags** -- String ndarray, shape (N*norb,). Sublattice tags.
+    '''
+    error_handling.kspace(ks, KSpace)
+    error_handling.nk(n_cells, ks.dim)
+    error_handling.boolean(periodic, 'periodic')
+    n_cells = (n_cells,) * ks.dim if isinstance(n_cells, int) else n_cells
+    pos, tags = _finite_sites(ks, n_cells)
+    return ks.finite_ham(n_cells, periodic=periodic, sparse=True), pos, tags
+
+
+def finite_system(ks: KSpace, n_cells: int | tuple[int, ...], periodic: bool = False) -> System:
+    r'''
+    Build a finite *System* out of a (spinless) *KSpace* model: *lat.coor*
+    holds the sites of :math:`N_1\times N_2\times\dots` unit cells (in the
+    order of *finite_model*), and *sys.hop* / *sys.onsite* the model's
+    hoppings and onsite energies, so that *sys.get_ham()* gives
+    *ks.finite_ham(n_cells, periodic)*. Every real-space tool (*get_eig*,
+    *get_ldos*, *Plot*, disorder, ...) then applies.
+
+    In *sys.hop*, each bond is stored with the conventions of
+    *System.set_hopping*: a Hermitian model keeps one orientation per bond
+    (angle in [0, 180), *get_ham* adds the conjugate); a non-reciprocal
+    one keeps both, the missing direction with a zero amplitude. 'n' is the
+    neighbour order of the bond (0 for coinciding orbitals), 'tag' the
+    sublattice pair. On a torus, a bond that wraps around keeps its short
+    bond vector for its angle, and a hopping that wraps onto its own site
+    is added to the onsite energy.
+
+    :param ks: **KSpace** instance, with ``spin=False``.
+    :param n_cells: Positive integer, or tuple of *dim* positive integers.
+    :param periodic: Boolean. Default value False. Periodic boundaries (a torus).
+
+    :returns:
+        * **sys** -- **System** instance, with its hoppings set.
+
+    Example usage::
+
+        sys = finite_system(gra, (30, 30), periodic=True)
+        sys.get_ham()
+        sys.get_eig()   # = gra.mesh_bands((30, 30)), sorted
+    '''
+    error_handling.kspace(ks, KSpace)
+    error_handling.nk(n_cells, ks.dim)
+    error_handling.boolean(periodic, 'periodic')
+    error_handling.spinless(ks.spin)
+    n_cells = (n_cells,) * ks.dim if isinstance(n_cells, int) else n_cells
+    pos, tags = _finite_sites(ks, n_cells)
+    lat = Lattice(unit_cell=list(ks.lat.unit_cell), prim_vec=list(ks.lat.prim_vec))
+    coor = np.zeros(len(pos), dtype=lat.dtype)
+    for c, f in enumerate(('x', 'y', 'z')[:ks.space_dim]):
+        coor[f] = pos[:, c]
+    coor['tag'] = tags
+    lat.coor, lat.sites = coor, len(coor)
+    lat.n1, lat.n2, lat.n3 = (tuple(n_cells) + (1, 1))[:3]
+    sys = System(lat)
+    _, n_tot, entries = ks._finite_entries(n_cells, periodic)
+    tau = ks.orbital_positions()
+    rows = np.concatenate([np.zeros(0, int)] + [e[0] for e in entries])
+    cols = np.concatenate([np.zeros(0, int)] + [e[1] for e in entries])
+    t = np.concatenate([np.zeros(0, 'c16')] + [np.full(len(e[0]), e[6], 'c16') for e in entries])
+    d = np.concatenate([np.zeros((0, ks.space_dim))]
+                              + [np.repeat((e[5] + tau[e[3]] - tau[e[2]])[None], len(e[0]), axis=0)
+                                 for e in entries])
+    n_sites = len(pos)
+    diag = rows == cols
+    sys.onsite = np.tile(ks.onsite, n_tot) + (np.bincount(rows[diag], t[diag].real, n_sites)
+                                                               + 1j * np.bincount(rows[diag], t[diag].imag, n_sites))
+    rows, cols, t, d = rows[~diag], cols[~diag], t[~diag], d[~diag]
+    dist = np.linalg.norm(d, axis=1)
+    zero = dist <= ATOL
+    ang = neighbours._bond_angles(d)
+    up = np.where(zero, rows < cols, _upper(ang))
+    ang_up = np.where(zero, 0., np.maximum(np.where(up, ang, neighbours._bond_angles(-d)), 0.))
+    if ks._nonreciprocal:
+        i = np.concatenate([rows, cols])
+        j = np.concatenate([cols, rows])
+        t = np.concatenate([t, np.zeros(len(t), 'c16')])
+        ang = np.concatenate([np.where(up, ang_up, ang_up - 180.), np.where(up, ang_up - 180., ang_up)])
+        dist = np.concatenate([dist, dist])
+    else:
+        i, j, t, ang, dist = rows[up], cols[up], t[up], ang_up[up], dist[up]
+    hop = np.zeros(len(i), dtype=HOP_DTYPE)
+    hop['n'] = neighbours.shell_index(ks.lat, dist)
+    hop['i'], hop['j'], hop['t'], hop['ang'] = i, j, t, ang
+    hop['tag'] = np.char.add(tags[i], tags[j])
+    sys.hop = hop
+    return sys