physicskit 0.1.0__py3-none-any.whl

physicskit/condensed/topology.py

@@ -0,0 +1,217 @@
+"""Berry curvature, Chern numbers, Zak phase, and Z2 invariants.
+
+The workhorse here is the Fukui-Hatsugai-Suzuki (FHS) lattice algorithm,
+which computes an exactly quantized, gauge-invariant Chern number from a
+finite grid of Bloch eigenvectors -- no smooth gauge choice required. The
+per-plaquette flux accumulation is numba-jitted since it is the inner loop
+of a double sum over the whole Brillouin-zone grid.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+__all__ = ["compute_berry_curvature", "compute_chern_number", "zak_phase", "z2_invariant"]
+
+
+def _bloch_eigensystem(hamiltonian_func, grid_size: int):
+    """Diagonalize ``hamiltonian_func`` on a closed (grid_size+1)^2 k-grid.
+
+    The extra row/column closes the discretized Brillouin-zone torus so
+    that plaquette (a, n) reuses the same eigenvectors as plaquette (a, 0).
+    """
+    n = grid_size
+    sample = np.asarray(hamiltonian_func(0.0, 0.0), dtype=complex)
+    norb = sample.shape[0]
+    U = np.empty((n + 1, n + 1, norb, norb), dtype=complex)
+    for a in range(n + 1):
+        k1 = 2 * np.pi * a / n
+        for b in range(n + 1):
+            k2 = 2 * np.pi * b / n
+            H = np.asarray(hamiltonian_func(k1, k2), dtype=complex)
+            _, v = np.linalg.eigh(H)
+            U[a, b] = v.T  # U[a, b, band, :] is the band-th eigenvector (contiguous)
+    return U
+
+
+@njit(cache=True)
+def _fhs_curvature_grid(U, n, band):
+    F = np.zeros((n, n))
+    for a in range(n):
+        for b in range(n):
+            v00 = U[a, b, band, :]
+            v10 = U[a + 1, b, band, :]
+            v11 = U[a + 1, b + 1, band, :]
+            v01 = U[a, b + 1, band, :]
+            u1 = np.vdot(v00, v10)
+            u1 = u1 / abs(u1)
+            u2 = np.vdot(v10, v11)
+            u2 = u2 / abs(u2)
+            u3 = np.vdot(v11, v01)
+            u3 = u3 / abs(u3)
+            u4 = np.vdot(v01, v00)
+            u4 = u4 / abs(u4)
+            F[a, b] = np.angle(u1 * u2 * u3 * u4)
+    return F
+
+
+def compute_berry_curvature(hamiltonian_func, grid_size: int = 50, band_index: int = 0) -> np.ndarray:
+    """Compute the discretized Berry curvature of one band over the Brillouin zone.
+
+    Uses the Fukui-Hatsugai-Suzuki (FHS) link-variable formula, which is
+    gauge invariant plaquette by plaquette and needs no smooth choice of
+    eigenvector phase.
+
+    Parameters
+    ----------
+    hamiltonian_func : callable
+        A function ``H(k1, k2)`` returning the ``(N, N)`` complex Bloch
+        Hamiltonian at reduced crystal momentum ``(k1, k2)``, each
+        periodic on :math:`[0, 2\\pi)` (see :mod:`physicskit.condensed.tight_binding`).
+    grid_size : int, default=50
+        Number of plaquettes along each of :math:`k_1, k_2`.
+    band_index : int, default=0
+        Band index (0 = lowest energy) to compute the curvature for.
+
+    Returns
+    -------
+    ndarray, shape (grid_size, grid_size)
+        Berry flux through each plaquette, in :math:`(-\\pi, \\pi]`. Summing
+        and dividing by :math:`2\\pi` gives the band's Chern number.
+
+    See Also
+    --------
+    compute_chern_number : Integrates this curvature over the full zone for every band.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import haldane_model
+    >>> H_func = lambda k1, k2: haldane_model(k1, k2, t=1.0, t2=0.2, phi=np.pi / 2, M=0.0)
+    >>> F = compute_berry_curvature(H_func, grid_size=30, band_index=0)
+    >>> F.shape
+    (30, 30)
+    >>> round(float(F.sum() / (2 * np.pi)))
+    1
+    """
+    U = _bloch_eigensystem(hamiltonian_func, grid_size)
+    return _fhs_curvature_grid(U, grid_size, band_index)
+
+
+def compute_chern_number(hamiltonian_func, grid_size: int = 50) -> list:
+    """Compute the Chern number of every band using the Fukui-Hatsugai-Suzuki method.
+
+    Parameters
+    ----------
+    hamiltonian_func : callable
+        A function ``H(k1, k2)`` returning an ``(N, N)`` complex Bloch
+        Hamiltonian, using the reduced-momentum convention of
+        :mod:`physicskit.condensed.tight_binding`.
+    grid_size : int, default=50
+        Discretization resolution for :math:`k_1` and :math:`k_2` across
+        :math:`[0, 2\\pi)`.
+
+    Returns
+    -------
+    list of int
+        Chern integer for each energy band, ordered from lowest to highest energy.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import haldane_model
+    >>> H_func = lambda k1, k2: haldane_model(k1, k2, t=1.0, t2=0.2, phi=np.pi / 2, M=0.0)
+    >>> chern_numbers = compute_chern_number(H_func, grid_size=30)
+    >>> print(chern_numbers)
+    [1, -1]
+    """
+    U = _bloch_eigensystem(hamiltonian_func, grid_size)
+    norb = U.shape[-1]
+    return [int(round(_fhs_curvature_grid(U, grid_size, band).sum() / (2 * np.pi))) for band in range(norb)]
+
+
+def zak_phase(hamiltonian_func_1d, grid_size: int = 200, band_index: int = 0) -> float:
+    """Compute the Zak phase of a 1D band: the Berry phase accumulated across the BZ.
+
+    Parameters
+    ----------
+    hamiltonian_func_1d : callable
+        A function ``H(k)`` returning the ``(N, N)`` complex Bloch Hamiltonian
+        at reduced momentum ``k``, periodic on :math:`[0, 2\\pi)`.
+    grid_size : int, default=200
+        Number of discretization steps around the 1D Brillouin zone.
+    band_index : int, default=0
+        Band index (0 = lowest energy).
+
+    Returns
+    -------
+    float
+        The Zak phase, wrapped to :math:`(-\\pi, \\pi]`. For a chiral-symmetric
+        model such as SSH, this is quantized to :math:`0` (trivial) or
+        :math:`\\pi` (topological).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import ssh_hamiltonian
+    >>> topological = lambda k: ssh_hamiltonian(k, v=0.5, w=1.0)
+    >>> trivial = lambda k: ssh_hamiltonian(k, v=1.0, w=0.5)
+    >>> round(abs(zak_phase(topological)), 4)
+    3.1416
+    >>> round(abs(zak_phase(trivial)), 4)
+    0.0
+    """
+    n = grid_size
+    vecs = np.empty((n + 1, hamiltonian_func_1d(0.0).shape[0]), dtype=complex)
+    for i in range(n + 1):
+        k = 2 * np.pi * i / n
+        _, v = np.linalg.eigh(np.asarray(hamiltonian_func_1d(k), dtype=complex))
+        vecs[i] = v[:, band_index]
+    prod = 1.0 + 0j
+    for i in range(n):
+        overlap = np.vdot(vecs[i], vecs[i + 1])
+        prod *= overlap / abs(overlap)
+    return float(-np.angle(prod))
+
+
+def z2_invariant(hamiltonian_func, grid_size: int = 30, spin_block: tuple = (0, 2)) -> int:
+    """Compute the :math:`\\mathbb{Z}_2` invariant of an :math:`s_z`-conserving spinful model.
+
+    Valid whenever ``hamiltonian_func`` is block-diagonal in spin (e.g. the
+    Kane-Mele or BHZ models with Rashba coupling set to zero), in which case
+    the :math:`\\mathbb{Z}_2` invariant reduces to the spin-up sector's Chern
+    number modulo 2 (Sheng et al. / spin-Chern-number approach).
+
+    Parameters
+    ----------
+    hamiltonian_func : callable
+        A function ``H(k1, k2)`` returning the full ``(2N, 2N)`` Bloch
+        Hamiltonian with the spin-up block occupying ``spin_block``.
+    grid_size : int, default=30
+        Discretization resolution for the Chern-number calculation.
+    spin_block : tuple of int, default=(0, 2)
+        ``(start, stop)`` slice selecting the spin-up block's rows/columns.
+
+    Returns
+    -------
+    int
+        :math:`\\mathbb{Z}_2` invariant, 0 (trivial) or 1 (topological).
+
+    Examples
+    --------
+    >>> from physicskit.condensed.models import kane_mele_hamiltonian
+    >>> trivial = lambda k1, k2: kane_mele_hamiltonian(k1, k2, lambda_so=0.0)
+    >>> topological = lambda k1, k2: kane_mele_hamiltonian(k1, k2, lambda_so=0.06)
+    >>> z2_invariant(trivial, grid_size=20)
+    0
+    >>> z2_invariant(topological, grid_size=20)
+    1
+    """
+    lo, hi = spin_block
+
+    def h_up(k1, k2):
+        return np.asarray(hamiltonian_func(k1, k2), dtype=complex)[lo:hi, lo:hi]
+
+    chern_up = compute_chern_number(h_up, grid_size)
+    return int(chern_up[0]) % 2

physicskit/condensed/visualizers.py

@@ -0,0 +1,296 @@
+"""Plotting helpers: band structures, Berry curvature heatmaps, edge-state densities, Fermi surfaces.
+
+Matplotlib is used for 2D plots (band structures, Berry-curvature heatmaps,
+real-space wavefunction density), and Plotly for interactive 3D Fermi-surface
+isosurfaces. Every function returns its figure object rather than calling
+``show()``, so it composes cleanly into larger figures or headless pipelines.
+"""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+import plotly.graph_objects as go
+
+__all__ = [
+    "plot_band_structure",
+    "plot_berry_curvature",
+    "plot_edge_state_density",
+    "plot_lattice_structure",
+    "plot_fermi_surface_3d",
+]
+
+
+def plot_band_structure(hamiltonian_func, path_points, labels=None, n_per_segment: int = 100, ax=None):
+    """Plot bands along a piecewise-linear path through the Brillouin zone.
+
+    Parameters
+    ----------
+    hamiltonian_func : callable
+        A function ``H(k1, k2)`` returning the Bloch Hamiltonian.
+    path_points : sequence of tuple(float, float)
+        High-symmetry points (e.g. :math:`\\Gamma, K, M, \\Gamma`) in reduced
+        crystal momentum, connected by straight segments.
+    labels : sequence of str, optional
+        Tick labels for each point in ``path_points``.
+    n_per_segment : int, default=100
+        Number of sampled k-points per segment.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import graphene_hamiltonian
+    >>> path = [(0, 0), (2 * np.pi / 3, 4 * np.pi / 3), (2 * np.pi / 3, 2 * np.pi / 3), (0, 0)]
+    >>> fig, ax = plot_band_structure(lambda k1, k2: graphene_hamiltonian(k1, k2), path, labels=["G", "K", "M", "G"])
+    >>> isinstance(fig, plt.Figure)
+    True
+    >>> sum(1 for line in ax.lines if line.get_color() == "C0")
+    2
+    """
+    path_points = [np.asarray(p, dtype=float) for p in path_points]
+    ks, distance, ticks = [], [0.0], [0.0]
+    for p0, p1 in zip(path_points[:-1], path_points[1:], strict=True):
+        for s in np.linspace(0, 1, n_per_segment, endpoint=False):
+            ks.append(p0 + s * (p1 - p0))
+        seg_len = np.linalg.norm(p1 - p0)
+        distance.append(distance[-1] + seg_len)
+        ticks.append(distance[-1])
+    ks.append(path_points[-1])
+
+    d = [0.0]
+    for k0, k1 in zip(ks[:-1], ks[1:], strict=True):
+        d.append(d[-1] + np.linalg.norm(k1 - k0))
+
+    energies = np.array([np.linalg.eigvalsh(np.asarray(hamiltonian_func(*k), dtype=complex)) for k in ks])
+
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+    for band in range(energies.shape[1]):
+        ax.plot(d, energies[:, band], color="C0")
+    for t in ticks:
+        ax.axvline(t, color="gray", linewidth=0.5)
+    if labels is not None:
+        ax.set_xticks(ticks)
+        ax.set_xticklabels(labels)
+    ax.set_ylabel("Energy")
+    return fig, ax
+
+
+def plot_berry_curvature(curvature: np.ndarray, ax=None):
+    """Plot a Berry-curvature field over the Brillouin zone as a heatmap.
+
+    Parameters
+    ----------
+    curvature : ndarray, shape (grid_size, grid_size)
+        Per-plaquette Berry curvature, as returned by
+        :func:`physicskit.condensed.topology.compute_berry_curvature`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import haldane_model
+    >>> from physicskit.condensed.topology import compute_berry_curvature
+    >>> H = lambda k1, k2: haldane_model(k1, k2, phi=np.pi / 2)
+    >>> F = compute_berry_curvature(H, grid_size=20, band_index=0)
+    >>> fig, ax = plot_berry_curvature(F)
+    >>> isinstance(fig, plt.Figure)
+    True
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+    im = ax.imshow(curvature.T, origin="lower", extent=[0, 2 * np.pi, 0, 2 * np.pi], aspect="auto", cmap="RdBu_r")
+    fig.colorbar(im, ax=ax, label="Berry curvature")
+    ax.set_xlabel("$k_1$")
+    ax.set_ylabel("$k_2$")
+    return fig, ax
+
+
+def plot_edge_state_density(ribbon_hamiltonian_func, k_parallel, ax=None):
+    """Plot the real-space density of the mid-gap eigenstate closest to zero energy.
+
+    Useful for visualizing the exponential localization
+    :math:`|\\psi(x)|^2 \\sim e^{-2x/\\xi}` of topological edge states exposed
+    by :func:`physicskit.condensed.tight_binding.build_ribbon`.
+
+    Parameters
+    ----------
+    ribbon_hamiltonian_func : callable
+        A function ``H(k_parallel)`` returning the finite ribbon Hamiltonian,
+        as produced by :func:`~physicskit.condensed.tight_binding.build_ribbon`.
+    k_parallel : array_like
+        Momentum along the periodic direction(s) at which to evaluate the ribbon.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    density : ndarray
+        Per-site probability density of the closest-to-zero eigenstate.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import ssh_lattice_hamiltonian
+    >>> from physicskit.condensed.tight_binding import build_ribbon
+    >>> H = ssh_lattice_hamiltonian(v=0.5, w=1.0)
+    >>> H_wire = build_ribbon(H, open_direction=0, n_cells=15)
+    >>> fig, ax, density = plot_edge_state_density(H_wire, k_parallel=[])
+    >>> bool(density[0] > density[len(density) // 2])
+    True
+    """
+    H = ribbon_hamiltonian_func(k_parallel)
+    eigenvalues, eigenvectors = np.linalg.eigh(H)
+    idx = int(np.argmin(np.abs(eigenvalues)))
+    psi = eigenvectors[:, idx]
+    density = np.abs(psi) ** 2
+
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+    ax.plot(np.arange(len(density)), density, marker="o")
+    ax.set_xlabel("Site index")
+    ax.set_ylabel(r"$|\psi(x)|^2$")
+    ax.set_title(f"Closest-to-zero eigenstate, E={eigenvalues[idx]:.4f}")
+    return fig, ax, density
+
+
+def plot_lattice_structure(positions, bonds, weights=None, ax=None, cmap: str = "viridis", bond_linewidth_scale: float = 3.0):
+    """Draw a finite tight-binding cluster's real-space structure: atoms and bonds.
+
+    Renders the actual geometry of a finite lattice -- e.g. the output of
+    :func:`physicskit.condensed.tight_binding.build_finite_cluster` -- rather
+    than an abstract site-index plot: bonds as line segments (linewidth
+    proportional to hopping strength, so e.g. SSH's alternating strong/weak
+    dimerization is directly visible), atoms as markers optionally colored
+    and sized by a per-site weight such as edge-state probability density.
+
+    Parameters
+    ----------
+    positions : array_like, shape (n_sites, dim)
+        Cartesian coordinates of each site, ``dim`` in ``{1, 2}``.
+    bonds : sequence of tuple(int, int, complex)
+        Real-space hoppings ``(i, j, amplitude)`` indexing into ``positions``.
+    weights : array_like, shape (n_sites,), optional
+        Per-site scalar (e.g. :math:`|\\psi|^2`) mapped to marker color and
+        size. Defaults to uniform, unweighted markers.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    cmap : str, default="viridis"
+        Colormap used when ``weights`` is given.
+    bond_linewidth_scale : float, default=3.0
+        Bonds are drawn with linewidth ``bond_linewidth_scale * |amplitude|
+        / max(|amplitude|)``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.condensed.models import ssh_lattice_hamiltonian
+    >>> from physicskit.condensed.tight_binding import build_finite_cluster
+    >>> H, positions, bonds = build_finite_cluster(ssh_lattice_hamiltonian(v=0.5, w=1.0), n_cells=3)
+    >>> _, states = np.linalg.eigh(H)
+    >>> density = np.abs(states[:, 0]) ** 2
+    >>> fig, ax = plot_lattice_structure(positions, bonds, weights=density)
+    >>> isinstance(fig, plt.Figure)
+    True
+    """
+    positions = np.atleast_2d(np.asarray(positions, dtype=float))
+    x = positions[:, 0]
+    y = positions[:, 1] if positions.shape[1] > 1 else np.zeros(len(positions))
+
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+
+    amplitudes = np.array([abs(amp) for _, _, amp in bonds])
+    max_amp = amplitudes.max() if amplitudes.size else 1.0
+    for (i, j, _amp), a in zip(bonds, amplitudes, strict=True):
+        lw = bond_linewidth_scale * a / max_amp if max_amp > 0 else bond_linewidth_scale
+        ax.plot(x[[i, j]], y[[i, j]], color="gray", linewidth=lw, zorder=1, solid_capstyle="round")
+
+    if weights is None:
+        ax.scatter(x, y, s=80, color="C0", edgecolor="k", linewidth=0.6, zorder=2)
+    else:
+        weights = np.asarray(weights, dtype=float)
+        max_w = weights.max()
+        sizes = 30 + 300 * weights / max_w if max_w > 0 else np.full_like(weights, 30.0)
+        sc = ax.scatter(x, y, s=sizes, c=weights, cmap=cmap, edgecolor="k", linewidth=0.6, zorder=2)
+        fig.colorbar(sc, ax=ax, label="weight")
+
+    ax.set_aspect("equal")
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    return fig, ax
+
+
+def plot_fermi_surface_3d(dispersion_func, mu: float = 0.0, grid_size: int = 40, k_range: float = np.pi):
+    """Render a 3D Fermi-surface isosurface :math:`\\varepsilon(\\mathbf{k}) = \\mu`.
+
+    Parameters
+    ----------
+    dispersion_func : callable
+        A function ``eps(kx, ky, kz)`` returning the band energy.
+    mu : float, default=0.0
+        Chemical potential (Fermi energy) defining the isosurface.
+    grid_size : int, default=40
+        Number of samples along each of :math:`k_x, k_y, k_z`.
+    k_range : float, default=pi
+        Half-width of the cubic sampling box, ``[-k_range, k_range]``.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        A figure containing a single ``Isosurface`` trace.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> eps = lambda kx, ky, kz: -2 * (np.cos(kx) + np.cos(ky) + np.cos(kz))
+    >>> fig = plot_fermi_surface_3d(eps, mu=0.0, grid_size=20)
+    >>> fig.data[0].type
+    'isosurface'
+    """
+    grid = np.linspace(-k_range, k_range, grid_size)
+    kx, ky, kz = np.meshgrid(grid, grid, grid, indexing="ij")
+    values = dispersion_func(kx, ky, kz)
+    fig = go.Figure(
+        data=go.Isosurface(
+            x=kx.flatten(),
+            y=ky.flatten(),
+            z=kz.flatten(),
+            value=values.flatten(),
+            isomin=mu,
+            isomax=mu,
+            surface_count=1,
+            colorscale="Viridis",
+            showscale=False,
+        )
+    )
+    fig.update_layout(scene={"xaxis_title": "kx", "yaxis_title": "ky", "zaxis_title": "kz"})
+    return fig

physicskit/condensed/weyl.py

@@ -0,0 +1,180 @@
+r"""Weyl semimetals (2011-2015): momentum-space monopoles and Fermi arcs.
+
+Wan, Turner, Vishwanath, and Savrasov predicted that breaking either
+inversion or time-reversal symmetry in a 3D Dirac material splits each
+doubly-degenerate Dirac point into a pair of nondegenerate Weyl nodes of
+opposite chirality -- momentum-space sources and sinks of Berry curvature,
+each the direct 3D generalization of the 2D TKNN invariant
+(:func:`physicskit.condensed.topology.compute_chern_number`) evaluated on a
+small sphere surrounding it. Xu, Lv, and coworkers confirmed the prediction
+by ARPES in TaAs in 2015, directly imaging both the bulk Weyl nodes and the
+open, non-closed "Fermi arcs" of surface states connecting the surface
+projections of opposite-chirality nodes -- a bulk-boundary signature with
+no two-dimensional analogue.
+
+This module implements the minimal two-band lattice model with this
+physics, a cubic-lattice generalization of the same Dirac-matrix
+construction used for the 3D topological insulator
+(:mod:`physicskit.condensed.topological_insulator_3d`), reduced from four
+bands to two since a genuine (as opposed to symmetry-protected) Weyl node
+only needs a two-level crossing:
+
+.. math::
+
+   H(\mathbf{k}) = \sin k_x\,\sigma_x + \sin k_y\,\sigma_y +
+   \left(m - t\sum_{i=x,y,z}\cos k_i\right)\sigma_z .
+
+For :math:`1 < m/t < 3` the mass term vanishes at exactly two points on the
+:math:`k_z` axis, :math:`\mathbf{k}=(0,0,\pm k_0)` with
+:math:`\cos k_0 = m/t - 2` -- a pair of Weyl nodes of opposite chirality.
+Between them, each fixed-:math:`k_z` slice is a 2D Chern insulator; outside
+them, it is trivial. Opening the lattice along ``x`` exposes exactly the
+surface signature of that alternation: a single chiral edge mode crossing
+zero energy for :math:`|k_z| < k_0`, and a full gap for :math:`|k_z| > k_0`
+-- the lattice-model fingerprint of the Fermi arc.
+
+Uses the same natural-unit convention (:math:`\hbar=e=1`) as the rest of
+:mod:`physicskit.condensed`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["weyl_semimetal_hamiltonian", "weyl_node_locations", "weyl_semimetal_slab_hamiltonian"]
+
+_SIGMA_X = np.array([[0, 1], [1, 0]], dtype=complex)
+_SIGMA_Y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+_SIGMA_Z = np.array([[1, 0], [0, -1]], dtype=complex)
+
+
+def weyl_semimetal_hamiltonian(kx: float, ky: float, kz: float, m: float, t: float = 1.0) -> np.ndarray:
+    r"""Bloch Hamiltonian of the minimal two-band cubic-lattice Weyl semimetal.
+
+    Parameters
+    ----------
+    kx, ky, kz : float
+        Reduced crystal momenta, each periodic on :math:`[0, 2\pi)`.
+    m : float
+        Band mass. Two Weyl nodes exist on the :math:`k_z` axis for
+        :math:`1 < m/t < 3` (see :func:`weyl_node_locations`); outside that
+        window the model is fully gapped.
+    t : float, default=1.0
+        Hopping amplitude setting the bulk bandwidth.
+
+    Returns
+    -------
+    ndarray, shape (2, 2)
+        Hermitian Bloch Hamiltonian.
+
+    See Also
+    --------
+    weyl_node_locations : Exact :math:`k_z` positions of the two Weyl nodes.
+    weyl_semimetal_slab_hamiltonian : Open-boundary slab exposing Fermi-arc surface states.
+
+    Examples
+    --------
+    At ``m/t = 2`` the two nodes sit at :math:`k_z = \pm\pi/2`, where the
+    bulk gap closes exactly:
+
+    >>> import numpy as np
+    >>> H = weyl_semimetal_hamiltonian(0.0, 0.0, np.pi / 2, m=2.0, t=1.0)
+    >>> np.round(np.linalg.eigvalsh(H), 8)
+    array([0., 0.])
+    >>> H_away = weyl_semimetal_hamiltonian(np.pi, np.pi, np.pi, m=2.0, t=1.0)
+    >>> np.round(np.linalg.eigvalsh(H_away), 8)
+    array([-5.,  5.])
+    """
+    mass = m - t * (np.cos(kx) + np.cos(ky) + np.cos(kz))
+    return np.sin(kx) * _SIGMA_X + np.sin(ky) * _SIGMA_Y + mass * _SIGMA_Z
+
+
+def weyl_node_locations(m: float, t: float = 1.0) -> tuple:
+    r"""Exact :math:`k_z` positions of the two Weyl nodes on the :math:`k_z` axis.
+
+    Solves :math:`m - t(2 + \cos k_z) = 0` -- the mass term of
+    :func:`weyl_semimetal_hamiltonian` at :math:`k_x=k_y=0` -- for
+    :math:`k_z`.
+
+    Parameters
+    ----------
+    m : float
+        Band mass.
+    t : float, default=1.0
+        Hopping amplitude.
+
+    Returns
+    -------
+    tuple of float or None
+        ``(-k0, +k0)`` with :math:`k_0 \in (0, \pi)`, or ``None`` if
+        :math:`m/t` lies outside :math:`(1, 3)` (no nodes on this axis).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> k0 = weyl_node_locations(m=2.0, t=1.0)
+    >>> np.round(k0, 8)
+    array([-1.57079633,  1.57079633])
+    >>> weyl_node_locations(m=4.0, t=1.0) is None
+    True
+    """
+    ratio = m / t - 2.0
+    if not (-1.0 < ratio < 1.0):
+        return None
+    k0 = float(np.arccos(ratio))
+    return np.array([-k0, k0])
+
+
+def weyl_semimetal_slab_hamiltonian(ky: float, kz: float, n_layers: int, m: float, t: float = 1.0) -> np.ndarray:
+    r"""Slab Hamiltonian: periodic in ``y`` and ``z``, open (finite) along ``x``.
+
+    Truncating the ``x`` direction exposes two open surfaces whose surface
+    Brillouin zone is the :math:`(k_y, k_z)` plane the two Weyl nodes
+    project onto at :math:`(0, \pm k_0)`. Diagonalizing at fixed
+    :math:`k_z` and scanning :math:`k_y` reveals, for
+    :math:`|k_z| < k_0`, a single chiral mode crossing zero energy
+    (the Fermi arc), and a full gap for :math:`|k_z| > k_0`.
+
+    Parameters
+    ----------
+    ky, kz : float
+        Reduced crystal momenta, periodic on :math:`[0, 2\pi)`.
+    n_layers : int
+        Number of layers stacked along ``x``.
+    m : float
+        Band mass (see :func:`weyl_semimetal_hamiltonian`).
+    t : float, default=1.0
+        Hopping amplitude.
+
+    Returns
+    -------
+    ndarray, shape (2 * n_layers, 2 * n_layers)
+        Hermitian, open-boundary slab Hamiltonian.
+
+    Examples
+    --------
+    Between the two Weyl nodes (:math:`k_z=0`), a thick slab has a state
+    pinned near zero energy at some :math:`k_y` -- the Fermi-arc surface
+    mode -- absent outside the node range (:math:`k_z=\pi`):
+
+    >>> import numpy as np
+    >>> ky_grid = np.linspace(0, 2 * np.pi, 200, endpoint=False)
+    >>> gaps_inside = [np.min(np.abs(np.linalg.eigvalsh(weyl_semimetal_slab_hamiltonian(ky, 0.0, 40, m=2.0)))) for ky in ky_grid]
+    >>> bool(min(gaps_inside) < 1e-6)
+    True
+    >>> gaps_outside = [np.min(np.abs(np.linalg.eigvalsh(weyl_semimetal_slab_hamiltonian(ky, np.pi, 40, m=2.0)))) for ky in ky_grid]
+    >>> bool(min(gaps_outside) > 0.5)
+    True
+    """
+    mass_yz = m - t * (np.cos(ky) + np.cos(kz))
+    H0 = np.sin(ky) * _SIGMA_Y + mass_yz * _SIGMA_Z
+    Tx = -0.5j * _SIGMA_X - 0.5 * t * _SIGMA_Z
+
+    N = n_layers
+    H = np.zeros((2 * N, 2 * N), dtype=complex)
+    for layer in range(N):
+        H[2 * layer : 2 * layer + 2, 2 * layer : 2 * layer + 2] = H0
+    for layer in range(N - 1):
+        H[2 * layer : 2 * layer + 2, 2 * (layer + 1) : 2 * (layer + 1) + 2] = Tx
+        H[2 * (layer + 1) : 2 * (layer + 1) + 2, 2 * layer : 2 * layer + 2] = Tx.conj().T
+    return H