physicskit 0.1.0__py3-none-any.whl

physicskit/classical/visualizers/modal_analysis.py

@@ -0,0 +1,97 @@
+"""Live normal-mode energy diagnostics for lattice chains.
+
+Wraps :meth:`physicskit.classical.systems.chains._ChainBase.modal_energies` in a bar
+chart and a Matplotlib ``FuncAnimation`` that updates it frame-by-frame
+-- the standard way to visualize the FPUT recurrence: energy initially
+concentrated in a single low mode, spreading across many modes, and
+then returning almost exactly to the starting mode.
+"""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+__all__ = ["plot_modal_energy_bars", "animate_modal_energies"]
+
+
+def plot_modal_energy_bars(system, q: np.ndarray, p: np.ndarray, ax=None, **kwargs):
+    """Static bar chart of E_k for each normal mode k at one instant.
+
+    Parameters
+    ----------
+    system : object
+        A lattice-chain system exposing ``modal_energies(q, p)``, e.g.
+        :class:`~physicskit.classical.systems.chains.HarmonicChain` or
+        :class:`~physicskit.classical.systems.chains.FPUTChain`.
+    q, p : ndarray
+        State to evaluate.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+    **kwargs
+        Forwarded to ``ax.bar``.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots()
+    energies = system.modal_energies(q, p)
+    modes = np.arange(1, len(energies) + 1)
+    ax.bar(modes, energies, **kwargs)
+    ax.set_xlabel("normal mode k")
+    ax.set_ylabel("$E_k$")
+    ax.set_title("Modal energy distribution")
+    return ax
+
+
+def animate_modal_energies(system, result, stride: int = 1, interval: int = 30, fig=None, ax=None):
+    """Animate the modal-energy bar chart across a full trajectory.
+
+    Parameters
+    ----------
+    system : object
+        A lattice-chain system exposing ``modal_energies(q, p)``.
+    result : physicskit.classical.core.base_system.SimulationResult
+        Output of ``system.integrate(...)``.
+    stride : int
+        Render only every ``stride``-th recorded sample (for long runs).
+    interval : int
+        Delay between frames, in milliseconds.
+    fig : matplotlib.figure.Figure, optional
+        Figure to draw on; inferred from ``ax`` or created if omitted.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    elif fig is None:
+        fig = ax.figure
+
+    n_modes = result.q.shape[1]
+    modes = np.arange(1, n_modes + 1)
+    e0 = system.modal_energies(result.q[0], result.p[0])
+    bars = ax.bar(modes, e0)
+    ax.set_xlabel("normal mode k")
+    ax.set_ylabel("$E_k$")
+    y_max = max(1e-12, np.sum(e0)) * 1.1
+    ax.set_ylim(0, y_max)
+    title = ax.set_title(f"Modal energy at t = {result.t[0]:.3f}")
+
+    frame_indices = np.arange(0, len(result.t), stride)
+
+    def update(frame_i):
+        idx = frame_indices[frame_i]
+        energies = system.modal_energies(result.q[idx], result.p[idx])
+        for bar, e in zip(bars, energies):
+            bar.set_height(e)
+        title.set_text(f"Modal energy at t = {result.t[idx]:.3f}")
+        return list(bars) + [title]
+
+    return FuncAnimation(fig, update, frames=len(frame_indices), interval=interval, blit=False)

physicskit/classical/visualizers/phase_space.py

@@ -0,0 +1,214 @@
+"""Phase-space diagnostics: (q, p) portraits, Poincare sections, and the
+SO(3) angular-momentum (Casimir) sphere for rigid bodies.
+"""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = [
+    "plot_phase_portrait",
+    "plot_phase_swarm",
+    "poincare_section",
+    "plot_poincare_section",
+    "plot_so3_momentum_sphere",
+]
+
+
+def plot_phase_portrait(q: np.ndarray, p: np.ndarray, ax=None, label=None, **kwargs):
+    """Plot a single (q, p) trajectory in phase space.
+
+    Parameters
+    ----------
+    q, p : ndarray
+        1D (a single degree of freedom over time) or 2D
+        (``(n_steps, ndof)``, in which case each column is drawn as
+        its own curve).
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+    label : str, optional
+        Legend label (per-DOF suffix added automatically for 2D input).
+    **kwargs
+        Forwarded to ``ax.plot``.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots()
+    q = np.asarray(q)
+    p = np.asarray(p)
+    if q.ndim == 1:
+        ax.plot(q, p, label=label, **kwargs)
+    else:
+        for i in range(q.shape[1]):
+            ax.plot(q[:, i], p[:, i], label=f"{label} dof {i}" if label else f"dof {i}", **kwargs)
+    ax.set_xlabel("q")
+    ax.set_ylabel("p")
+    ax.set_title("Phase portrait")
+    if label:
+        ax.legend()
+    return ax
+
+
+def plot_phase_swarm(q: np.ndarray, p: np.ndarray, ax=None, s=4, **kwargs):
+    """Scatter an ensemble of phase points.
+
+    E.g. a :class:`physicskit.classical.systems.hamiltonian.PendulumSwarm` snapshot,
+    the standard way to visualize Liouville-theorem shearing of a
+    phase-space patch.
+
+    Parameters
+    ----------
+    q, p : ndarray, shape (n,)
+        Phase-point positions and momenta.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+    s : float
+        Marker size, forwarded to ``ax.scatter``.
+    **kwargs
+        Forwarded to ``ax.scatter``.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots()
+    ax.scatter(q, p, s=s, **kwargs)
+    ax.set_xlabel("q")
+    ax.set_ylabel("p")
+    ax.set_title("Phase-space swarm")
+    return ax
+
+
+def poincare_section(q: np.ndarray, p: np.ndarray, section_q: np.ndarray, section_p: np.ndarray, value: float = 0.0, direction: int = 1):
+    """Compute Poincare-section crossing points.
+
+    Records ``(q, p)`` each time ``section_q`` crosses ``value`` moving
+    in the sign given by ``direction`` (+1 for increasing, -1 for
+    decreasing), linearly interpolating between the bracketing samples
+    for sub-step accuracy. Typical usage for Henon-Heiles: pass y as
+    ``section_q``, take the section at y=0 with py>0 (direction=+1),
+    and record (x, px) crossings.
+
+    Parameters
+    ----------
+    q, p : ndarray
+        Coordinates to record at each crossing.
+    section_q, section_p : ndarray
+        The coordinate (and its conjugate momentum) whose crossings of
+        ``value`` define the section; same length as ``q``/``p``.
+    value : float
+        Crossing threshold.
+    direction : {1, -1}
+        +1 to record crossings where ``section_q`` is increasing
+        through ``value``, -1 for decreasing.
+
+    Returns
+    -------
+    crossings_q, crossings_p : ndarray
+        Interpolated ``(q, p)`` at each crossing.
+    """
+    section_q = np.asarray(section_q)
+    section_p = np.asarray(section_p)
+    crossings_q = []
+    crossings_p = []
+    for i in range(len(section_q) - 1):
+        y0, y1 = section_q[i] - value, section_q[i + 1] - value
+        crosses = (y0 <= 0 < y1) if direction > 0 else (y0 >= 0 > y1)
+        if not crosses:
+            continue
+        if section_p[i] * direction < 0:
+            continue
+        frac = -y0 / (y1 - y0) if y1 != y0 else 0.0
+        crossings_q.append(q[i] + frac * (q[i + 1] - q[i]))
+        crossings_p.append(p[i] + frac * (p[i + 1] - p[i]))
+    return np.array(crossings_q), np.array(crossings_p)
+
+
+def plot_poincare_section(q, p, section_q, section_p, value=0.0, direction=1, ax=None, **kwargs):
+    """Scatter-plot the Poincare-section crossings of a trajectory.
+
+    Parameters
+    ----------
+    q, p : ndarray
+        Coordinates to record at each crossing.
+    section_q, section_p : ndarray
+        The coordinate (and its conjugate momentum) whose crossings of
+        ``value`` define the section.
+    value : float
+        Crossing threshold.
+    direction : {1, -1}
+        Crossing direction; see :func:`poincare_section`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is created if omitted.
+    **kwargs
+        Forwarded to ``ax.scatter``.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    cq, cp = poincare_section(q, p, section_q, section_p, value=value, direction=direction)
+    if ax is None:
+        _, ax = plt.subplots()
+    ax.scatter(cq, cp, s=2, **kwargs)
+    ax.set_xlabel("q")
+    ax.set_ylabel("p")
+    ax.set_title("Poincare section")
+    return ax
+
+
+def plot_so3_momentum_sphere(omega_trajectory: np.ndarray, I1: float, I2: float, I3: float, ax=None, n_grid: int = 40):
+    """Plot a rigid body's body-frame angular-momentum trajectory on the Casimir sphere.
+
+    ``L(t) = (I1*w1, I2*w2, I3*w3)`` on the SO(3) Casimir sphere
+    ``|L| = |L(0)|``.
+
+    The wireframe sphere shown is the constant-``|L|`` Casimir surface; the
+    trajectory is additionally constrained to the (generally
+    non-spherical) constant-energy ellipsoid, so the two surfaces'
+    intersection traces out the actual admissible polhode curves --
+    this is the geometric picture behind the Intermediate Axis Theorem.
+
+    Parameters
+    ----------
+    omega_trajectory : ndarray, shape (n_steps, 3)
+        Body-frame angular velocity trajectory, e.g.
+        ``result.y[:, :3]`` from integrating an
+        :class:`~physicskit.classical.systems.rotations.EulerTop`.
+    I1, I2, I3 : float
+        Principal moments of inertia.
+    ax : mpl_toolkits.mplot3d.Axes3D, optional
+        Axes to draw on; a new 3D figure is created if omitted.
+    n_grid : int
+        Resolution of the wireframe sphere.
+
+    Returns
+    -------
+    mpl_toolkits.mplot3d.Axes3D
+    """
+    omega_trajectory = np.asarray(omega_trajectory)
+    L = np.column_stack([I1 * omega_trajectory[:, 0], I2 * omega_trajectory[:, 1], I3 * omega_trajectory[:, 2]])
+    radius = np.linalg.norm(L[0])
+
+    if ax is None:
+        fig = plt.figure()
+        ax = fig.add_subplot(111, projection="3d")
+
+    u = np.linspace(0, 2 * np.pi, n_grid)
+    v = np.linspace(0, np.pi, n_grid)
+    xs = radius * np.outer(np.cos(u), np.sin(v))
+    ys = radius * np.outer(np.sin(u), np.sin(v))
+    zs = radius * np.outer(np.ones_like(u), np.cos(v))
+    ax.plot_wireframe(xs, ys, zs, color="lightgray", linewidth=0.3, alpha=0.5)
+
+    ax.plot(L[:, 0], L[:, 1], L[:, 2], color="crimson", linewidth=1.2)
+    ax.set_xlabel("L1")
+    ax.set_ylabel("L2")
+    ax.set_zlabel("L3")
+    ax.set_title("Body-frame angular momentum on the Casimir sphere")
+    return ax

physicskit/condensed/__init__.py

@@ -0,0 +1,122 @@
+"""Condensed matter physics: tight-binding models, topological band theory, and correlated electrons.
+
+Typical usage::
+
+    import physicskit as pk
+    import numpy as np
+
+    H = lambda k1, k2: pk.condensed.haldane_model(k1, k2, phi=np.pi / 2)
+    chern_numbers = pk.condensed.compute_chern_number(H, grid_size=30)
+"""
+
+from .anderson_localization import (
+    anderson_chain_hamiltonian,
+    inverse_participation_ratio,
+    localization_length,
+)
+from .correlated import (
+    bdg_bcs_hamiltonian,
+    bdg_spectrum,
+    hubbard_1d_exact_diagonalization,
+    hubbard_spin_correlations,
+)
+from .ginzburg_landau import (
+    ginzburg_landau_parameter,
+    gl_coherence_length,
+    gl_equilibrium_order_parameter,
+    gl_free_energy_density,
+    gl_order_parameter_profile,
+    gl_penetration_depth,
+)
+from .landau_levels import (
+    cyclotron_frequency,
+    filling_factor,
+    landau_degeneracy,
+    landau_density_of_states,
+    landau_level_energies,
+    magnetic_length,
+)
+from .laughlin import laughlin_metropolis_sweep, laughlin_pair_correlation, laughlin_radial_density
+from .models import (
+    bhz_hamiltonian,
+    bhz_ribbon_hamiltonian,
+    graphene_hamiltonian,
+    graphene_lattice_hamiltonian,
+    haldane_lattice_hamiltonian,
+    haldane_model,
+    harper_hofstadter_hamiltonian,
+    kane_mele_hamiltonian,
+    kitaev_chain_bdg_real_space,
+    kitaev_chain_hamiltonian,
+    ssh_hamiltonian,
+    ssh_lattice_hamiltonian,
+)
+from .tight_binding import Hamiltonian, Lattice, apply_peierls_phase, build_ribbon
+from .topological_insulator_3d import (
+    surface_dirac_hamiltonian,
+    topological_insulator_3d_hamiltonian,
+    topological_insulator_3d_slab_hamiltonian,
+)
+from .topology import compute_berry_curvature, compute_chern_number, z2_invariant, zak_phase
+from .visualizers import (
+    plot_band_structure,
+    plot_berry_curvature,
+    plot_edge_state_density,
+    plot_fermi_surface_3d,
+)
+from .weyl import weyl_node_locations, weyl_semimetal_hamiltonian, weyl_semimetal_slab_hamiltonian
+
+__all__ = [
+    "Lattice",
+    "Hamiltonian",
+    "build_ribbon",
+    "apply_peierls_phase",
+    "ssh_hamiltonian",
+    "ssh_lattice_hamiltonian",
+    "graphene_hamiltonian",
+    "graphene_lattice_hamiltonian",
+    "haldane_model",
+    "haldane_lattice_hamiltonian",
+    "kane_mele_hamiltonian",
+    "bhz_hamiltonian",
+    "bhz_ribbon_hamiltonian",
+    "kitaev_chain_hamiltonian",
+    "kitaev_chain_bdg_real_space",
+    "harper_hofstadter_hamiltonian",
+    "compute_berry_curvature",
+    "compute_chern_number",
+    "zak_phase",
+    "z2_invariant",
+    "cyclotron_frequency",
+    "magnetic_length",
+    "landau_level_energies",
+    "landau_degeneracy",
+    "landau_density_of_states",
+    "filling_factor",
+    "laughlin_metropolis_sweep",
+    "laughlin_pair_correlation",
+    "laughlin_radial_density",
+    "gl_free_energy_density",
+    "gl_equilibrium_order_parameter",
+    "gl_coherence_length",
+    "gl_penetration_depth",
+    "ginzburg_landau_parameter",
+    "gl_order_parameter_profile",
+    "anderson_chain_hamiltonian",
+    "inverse_participation_ratio",
+    "localization_length",
+    "topological_insulator_3d_hamiltonian",
+    "topological_insulator_3d_slab_hamiltonian",
+    "surface_dirac_hamiltonian",
+    "bdg_bcs_hamiltonian",
+    "bdg_spectrum",
+    "hubbard_1d_exact_diagonalization",
+    "hubbard_spin_correlations",
+    "plot_band_structure",
+    "plot_berry_curvature",
+    "plot_edge_state_density",
+    "plot_fermi_surface_3d",
+    "weyl_semimetal_hamiltonian",
+    "weyl_node_locations",
+    "weyl_semimetal_slab_hamiltonian",
+]

physicskit/condensed/anderson_localization.py

@@ -0,0 +1,155 @@
+r"""Anderson localization: the 1958 discovery that disorder can halt diffusion entirely.
+
+Philip Anderson showed that a quantum particle hopping on a lattice with
+sufficiently strong, random (quenched) onsite disorder does not diffuse at
+all: interference between all the scattering paths off the random
+potential can exponentially localize *every* eigenstate, at any disorder
+strength, in one and two dimensions. This was the first demonstration that
+disorder is not merely a small perturbative correction to a metal's
+conductivity, but can drive a genuine transition -- absent in three
+dimensions only above a critical disorder (the "mobility edge") -- from
+extended, conducting states to localized, insulating ones. It underlies
+the disorder-driven physics that makes real quantum Hall plateaus finite in
+width (:mod:`physicskit.condensed.topology`) and the transport (or lack of
+it) in every real, imperfect crystal.
+
+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__ = ["anderson_chain_hamiltonian", "inverse_participation_ratio", "localization_length"]
+
+
+def anderson_chain_hamiltonian(n_sites: int, disorder_strength: float, t: float = 1.0, seed: int | None = None) -> np.ndarray:
+    r"""Real-space 1D Anderson model: a tight-binding chain with random onsite disorder.
+
+    .. math::
+
+       H = -t\sum_i \left(c_i^\dagger c_{i+1} + \text{h.c.}\right)
+       + \sum_i \epsilon_i\, c_i^\dagger c_i, \qquad
+       \epsilon_i \sim \text{Uniform}\!\left(-\tfrac{W}{2}, \tfrac{W}{2}\right),
+
+    with open boundary conditions.
+
+    Parameters
+    ----------
+    n_sites : int
+        Number of lattice sites.
+    disorder_strength : float
+        Disorder width :math:`W`. ``0`` recovers the clean chain.
+    t : float, default=1.0
+        Nearest-neighbor hopping amplitude.
+    seed : int, optional
+        Seed for the random onsite disorder, for reproducibility.
+
+    Returns
+    -------
+    ndarray, shape (n_sites, n_sites)
+        Real, symmetric Hamiltonian matrix.
+
+    Examples
+    --------
+    >>> H = anderson_chain_hamiltonian(n_sites=4, disorder_strength=0.0)
+    >>> H
+    array([[ 0., -1.,  0.,  0.],
+           [-1.,  0., -1.,  0.],
+           [ 0., -1.,  0., -1.],
+           [ 0.,  0., -1.,  0.]])
+    """
+    rng = np.random.default_rng(seed)
+    H = np.diag(rng.uniform(-disorder_strength / 2, disorder_strength / 2, size=n_sites))
+    idx = np.arange(n_sites - 1)
+    H[idx, idx + 1] = -t
+    H[idx + 1, idx] = -t
+    return H
+
+
+def inverse_participation_ratio(psi) -> float:
+    r"""Inverse participation ratio :math:`\text{IPR} = \sum_i|\psi_i|^4 / \left(\sum_i|\psi_i|^2\right)^2`.
+
+    A dimensionless measure of how many sites an eigenstate is spread
+    over: :math:`\text{IPR}\sim 1/N` for a state extended over all
+    :math:`N` sites, and :math:`\text{IPR} = O(1)`, independent of
+    :math:`N`, for a state localized on a handful of sites -- the
+    diagnostic Anderson used to distinguish the two regimes.
+
+    Parameters
+    ----------
+    psi : array_like
+        Eigenvector components (need not be pre-normalized).
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    A state spread equally over ``N`` sites has IPR = 1/N:
+
+    >>> import numpy as np
+    >>> psi = np.ones(10) / np.sqrt(10)
+    >>> round(inverse_participation_ratio(psi), 6)
+    0.1
+    >>> psi_localized = np.zeros(10); psi_localized[0] = 1.0
+    >>> inverse_participation_ratio(psi_localized)
+    1.0
+    """
+    psi = np.asarray(psi)
+    p = np.abs(psi) ** 2
+    return float(np.sum(p**2) / np.sum(p) ** 2)
+
+
+def localization_length(psi, positions=None) -> float:
+    r"""Estimate an eigenstate's localization length from the decay of its envelope.
+
+    Fits :math:`\log|\psi_i|^2` linearly against position on either side of
+    the state's peak and returns :math:`\xi = -2/\text{slope}`, averaged
+    over both sides -- the length scale over which a localized state's
+    probability density decays as :math:`|\psi(x)|^2 \sim e^{-2|x-x_0|/\xi}`.
+    Returns ``inf`` for a state too extended (flat/non-monotonic envelope)
+    for the fit to detect exponential decay.
+
+    Parameters
+    ----------
+    psi : array_like
+        Eigenvector components, indexed by site.
+    positions : array_like, optional
+        Site coordinates. Defaults to integer indices ``0, 1, ..., N-1``.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    An exactly exponential envelope recovers its localization length:
+
+    >>> import numpy as np
+    >>> x = np.arange(200)
+    >>> xi_true = 5.0
+    >>> psi = np.exp(-np.abs(x - 100) / xi_true)
+    >>> round(localization_length(psi), 4)
+    5.0
+    """
+    psi = np.asarray(psi)
+    positions = np.arange(len(psi)) if positions is None else np.asarray(positions, dtype=float)
+    log_density = np.log(np.abs(psi) ** 2 + 1e-300)
+    peak = int(np.argmax(log_density))
+
+    slopes = []
+    if peak > 1:
+        left_slope = np.polyfit(positions[: peak + 1], log_density[: peak + 1], 1)[0]
+        if left_slope > 0:
+            slopes.append(left_slope)
+    if peak < len(psi) - 2:
+        right_slope = np.polyfit(positions[peak:], log_density[peak:], 1)[0]
+        if right_slope < 0:
+            slopes.append(-right_slope)
+
+    if not slopes:
+        return float("inf")
+    return float(2.0 / np.mean(slopes))