physicskit 0.1.0__py3-none-any.whl

physicskit/semiclassical/core/wkb.py

@@ -0,0 +1,308 @@
+r"""1D WKB wavefunctions, classical turning points, and Bohr-Sommerfeld (EBK) quantization.
+
+The Wentzel-Kramers-Brillouin (WKB) approximation writes the wavefunction
+as :math:`\psi(x) \sim p(x)^{-1/2}\exp(\pm i\int p\,dx/\hbar)` -- an
+:math:`\hbar\to 0` asymptotic expansion valid wherever the local
+de Broglie wavelength :math:`2\pi\hbar/p(x)` varies slowly compared to
+itself. The prefactor :math:`p(x)^{-1/2}` is exactly the classical
+probability density of a particle oscillating in the potential (it spends
+more time, and so is more likely to be found, where it moves slowest);
+this is the one-dimensional seed of every semiclassical idea in
+:mod:`physicskit.semiclassical` -- the Van Vleck-Morette
+determinant in :mod:`~physicskit.semiclassical.core.propagators` is
+the same classical-probability prefactor for a propagator instead of a
+stationary state, and the periodic-orbit sum in
+:mod:`~physicskit.semiclassical.core.gutzwiller` is built from the
+same action integral used here for Bohr-Sommerfeld quantization.
+
+At each classical turning point the WKB approximation itself breaks down
+(:math:`p(x)\to 0`); matching the oscillatory interior solution through
+that breakdown region (via the Airy function connection formulas) costs
+each *soft* (linear) turning point a phase of :math:`\pi/4`. For a bound
+state with two such turning points, the round-trip quantization condition
+:math:`\oint p\,dx = 2\pi\hbar(n+\tfrac12)` -- equivalently
+:math:`\int_{x_1}^{x_2}p\,dx=(n+\tfrac12)\pi\hbar` -- is the
+one-dimensional Einstein-Brillouin-Keller (EBK) rule implemented by
+:func:`bohr_sommerfeld_energies`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.integrate import cumulative_trapezoid, quad
+from scipy.optimize import brentq
+
+from .._compat import trapz
+
+__all__ = [
+    "classical_momentum",
+    "turning_points",
+    "wkb_action",
+    "bohr_sommerfeld_energies",
+    "wkb_wavefunction",
+]
+
+
+def classical_momentum(E: float, V, x: np.ndarray, m: float = 1.0) -> np.ndarray:
+    r"""Classical momentum :math:`p(x) = \sqrt{2m(E-V(x))}` in the allowed region.
+
+    Parameters
+    ----------
+    E : float
+        Total energy.
+    V : callable
+        Potential energy function ``V(x)``.
+    x : ndarray
+        Positions at which to evaluate :math:`p(x)`.
+    m : float, default=1.0
+        Particle mass.
+
+    Returns
+    -------
+    ndarray
+        :math:`p(x)`, same shape as ``x``; ``nan`` wherever :math:`V(x)>E`
+        (the classically forbidden region, where WKB oscillates into a
+        real exponential instead).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> V = lambda x: 0.5 * x ** 2
+    >>> p = classical_momentum(E=2.0, V=V, x=np.array([0.0, 1.0, 3.0]))
+    >>> np.round(p, 4)
+    array([2.    , 1.7321,    nan])
+    """
+    x = np.asarray(x, dtype=float)
+    diff = 2.0 * m * (E - V(x))
+    return np.sqrt(np.where(diff >= 0, diff, np.nan))
+
+
+def turning_points(E: float, V, x_min: float, x_max: float, n_search: int = 4000) -> list:
+    r"""Locate the classical turning points (roots of :math:`E=V(x)`) in :math:`[x_{min},x_{max}]`.
+
+    Scans a fine grid for sign changes of :math:`E-V(x)` and refines each
+    with Brent's method; returns every turning point found, not just the
+    innermost pair, so multi-well potentials are handled correctly.
+
+    Parameters
+    ----------
+    E : float
+        Total energy.
+    V : callable
+        Potential energy function ``V(x)``.
+    x_min, x_max : float
+        Search domain (should extend into the classically forbidden
+        region on both sides of the state of interest).
+    n_search : int, default=4000
+        Number of grid points used to bracket the roots; increase for
+        potentials with closely spaced turning points.
+
+    Returns
+    -------
+    list of float
+        Turning points, ascending.
+
+    See Also
+    --------
+    wkb_action : Integrates :func:`classical_momentum` between two turning points.
+
+    Examples
+    --------
+    >>> V = lambda x: 0.5 * x ** 2
+    >>> [round(t, 4) for t in turning_points(E=2.0, V=V, x_min=-10, x_max=10)]
+    [-2.0, 2.0]
+    """
+    xs = np.linspace(x_min, x_max, n_search)
+    f = E - V(xs)
+    roots = []
+    for i in range(n_search - 1):
+        if f[i] == 0:
+            roots.append(float(xs[i]))
+        elif f[i] * f[i + 1] < 0:
+            roots.append(brentq(lambda x: E - V(x), xs[i], xs[i + 1]))
+    return roots
+
+
+def wkb_action(E: float, V, m: float, x1: float, x2: float, hbar: float = 1.0) -> float:
+    r"""WKB action integral :math:`S(E)=\int_{x_1}^{x_2} p(x)\,dx` between two turning points.
+
+    This is the classical action accumulated on one traversal of the
+    classically allowed region -- half of the full round-trip action
+    :math:`\oint p\,dx`, and (as a function of :math:`E`) exactly the
+    Hamilton principal function whose energy derivative gives the
+    classical period, :math:`T(E)=dS/dE`, used by
+    :func:`physicskit.semiclassical.core.gutzwiller.classical_period`.
+
+    Parameters
+    ----------
+    E : float
+        Total energy.
+    V : callable
+        Potential energy function ``V(x)``.
+    m : float
+        Particle mass.
+    x1, x2 : float
+        The two turning points (e.g. from :func:`turning_points`).
+    hbar : float, default=1.0
+        Value of :math:`\hbar` to use (only needed by callers converting
+        this to a phase; the integral itself is :math:`\hbar`-independent).
+
+    Returns
+    -------
+    float
+        The action :math:`S(E)`.
+
+    Examples
+    --------
+    For the harmonic oscillator, :math:`S(E)=\pi E/\omega` exactly:
+
+    >>> V = lambda x: 0.5 * x ** 2
+    >>> x1, x2 = turning_points(E=2.0, V=V, x_min=-10, x_max=10)
+    >>> round(wkb_action(E=2.0, V=V, m=1.0, x1=x1, x2=x2), 6)
+    6.283185
+    """
+
+    def integrand(x):
+        return float(np.nan_to_num(classical_momentum(E, V, np.array([x]), m)[0], nan=0.0))
+
+    result, _ = quad(integrand, x1, x2, limit=200)
+    return result
+
+
+def bohr_sommerfeld_energies(V, m: float, x_min: float, x_max: float, n_max: int, hbar: float = 1.0, E_min: float = 1e-3, E_max: float = 100.0) -> np.ndarray:
+    r"""Bohr-Sommerfeld (EBK) bound-state energies from the WKB quantization condition.
+
+    Solves :math:`\int_{x_1(E_n)}^{x_2(E_n)}p(x)\,dx=(n+\tfrac12)\pi\hbar`
+    for each :math:`n=0,\dots,n_{max}-1` by root-finding on :math:`E`,
+    re-locating the turning points at every trial energy. For the
+    harmonic oscillator this reproduces the exact spectrum
+    :math:`E_n=(n+\tfrac12)\hbar\omega` to machine precision, since the
+    WKB approximation is exact whenever the potential is exactly
+    quadratic.
+
+    Parameters
+    ----------
+    V : callable
+        Potential energy function ``V(x)``, with a single classically
+        allowed region containing its minimum for every energy searched.
+    m : float
+        Particle mass.
+    x_min, x_max : float
+        Search domain for :func:`turning_points`; must extend well into
+        the classically forbidden region at ``E_max``.
+    n_max : int
+        Number of levels to compute (:math:`n=0,\dots,n_{max}-1`).
+    hbar : float, default=1.0
+        Value of :math:`\hbar` to use.
+    E_min : float, default=1e-3
+        Lower bracket for the ground-state root search; must be small
+        enough that its turning points still resolve on the
+        :func:`turning_points` search grid.
+    E_max : float, default=100.0
+        Upper bracket for the highest level's root search.
+
+    Returns
+    -------
+    ndarray, shape (n_max,)
+        Quantized energies, ascending.
+
+    See Also
+    --------
+    wkb_action : The action integral this quantizes.
+    wkb_wavefunction : The corresponding approximate wavefunctions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> V = lambda x: 0.5 * x ** 2
+    >>> energies = bohr_sommerfeld_energies(V, m=1.0, x_min=-20, x_max=20, n_max=5)
+    >>> np.round(energies, 6)
+    array([0.5, 1.5, 2.5, 3.5, 4.5])
+    """
+    energies = np.empty(n_max)
+    for n in range(n_max):
+
+        def condition(E, n=n):
+            tp = turning_points(E, V, x_min, x_max)
+            x1, x2 = tp[0], tp[-1]
+            return wkb_action(E, V, m, x1, x2, hbar) - (n + 0.5) * np.pi * hbar
+
+        energies[n] = brentq(condition, E_min, E_max)
+    return energies
+
+
+def wkb_wavefunction(x: np.ndarray, E: float, V, m: float = 1.0, hbar: float = 1.0) -> np.ndarray:
+    r"""The (real-valued, standing-wave) WKB wavefunction in the classically allowed region.
+
+    .. math::
+
+       \psi(x) \approx \frac{C}{\sqrt{p(x)}}
+       \cos\!\left(\frac{1}{\hbar}\int_{x_1}^{x}p(x')\,dx' - \frac{\pi}{4}\right),
+
+    with the :math:`\pi/4` phase set by the Airy connection formula at
+    the left (soft) turning point :math:`x_1`, and :math:`C` fixed by
+    numerical normalization over the allowed region. Diverges (is not
+    valid) within a few de Broglie wavelengths of either turning point;
+    zero is returned in the classically forbidden region rather than the
+    (also invalid) naive imaginary-momentum continuation.
+
+    Parameters
+    ----------
+    x : ndarray
+        Positions at which to evaluate the wavefunction.
+    E : float
+        Energy (e.g. from :func:`bohr_sommerfeld_energies`, for a properly
+        quantized bound state).
+    V : callable
+        Potential energy function ``V(x)``.
+    m : float, default=1.0
+        Particle mass.
+    hbar : float, default=1.0
+        Value of :math:`\hbar` to use.
+
+    Returns
+    -------
+    ndarray
+        :math:`\psi(x)`, same shape as ``x``, normalized so
+        :math:`\int|\psi|^2\,dx=1` over ``x``'s range.
+
+    See Also
+    --------
+    bohr_sommerfeld_energies : Quantized energies this is evaluated at.
+
+    Examples
+    --------
+    The WKB wavefunction at the Bohr-Sommerfeld energy for quantum number
+    ``n`` has exactly ``n`` nodes, the standard node-counting theorem:
+
+    >>> import numpy as np
+    >>> V = lambda x: 0.5 * x ** 2
+    >>> E5 = bohr_sommerfeld_energies(V, m=1.0, x_min=-20, x_max=20, n_max=6)[5]
+    >>> x = np.linspace(-10, 10, 4000)
+    >>> psi = wkb_wavefunction(x, E5, V, m=1.0)
+    >>> nonzero = psi[psi != 0]
+    >>> int(np.sum(np.diff(np.sign(nonzero)) != 0))
+    5
+    """
+    x = np.asarray(x, dtype=float)
+    tp = turning_points(E, V, float(np.min(x)), float(np.max(x)))
+    x1, x2 = tp[0], tp[-1]
+    allowed = (x > x1) & (x < x2)
+
+    psi = np.zeros_like(x)
+    xa = x[allowed]
+    p = classical_momentum(E, V, xa, m)
+    order = np.argsort(xa)
+    xa_sorted = xa[order]
+    p_sorted = p[order]
+    phase_sorted = cumulative_trapezoid(p_sorted, xa_sorted, initial=0.0) / hbar
+    unsort = np.argsort(order)
+    phase = phase_sorted[unsort]
+
+    psi_allowed = np.cos(phase - np.pi / 4.0) / np.sqrt(p)
+    psi[allowed] = psi_allowed
+
+    norm = np.sqrt(trapz(psi**2, x))
+    if norm > 0:
+        psi = psi / norm
+    return psi

physicskit/semiclassical/systems/__init__.py

@@ -0,0 +1,13 @@
+from physicskit.semiclassical.systems.scarring import (
+    bouncing_ball_energies,
+    bouncing_ball_orbit_points,
+    husimi_projection_1d,
+    scar_enhancement,
+)
+
+__all__ = [
+    "bouncing_ball_energies",
+    "bouncing_ball_orbit_points",
+    "scar_enhancement",
+    "husimi_projection_1d",
+]

physicskit/semiclassical/systems/scarring.py

@@ -0,0 +1,278 @@
+r"""Quantum scars: eigenstate density concentrated on unstable classical periodic orbits.
+
+Heller (1984) discovered that individual eigenstates of a classically
+chaotic system are not always the featureless, ergodically-spread blobs
+random-matrix intuition suggests: a small but robust fraction instead
+show enhanced probability density in a tube around one particular
+unstable classical periodic orbit -- a *scar* -- even though almost
+every orbit nearby diverges from it exponentially fast. The bridge to
+:mod:`physicskit.semiclassical.core.gutzwiller` is direct: the same
+unstable periodic orbits that weight the Gutzwiller trace formula's
+oscillating sum are exactly the orbits that scar individual eigenstates,
+since eigenstates are (schematically) superpositions of trace-formula
+terms.
+
+:func:`bouncing_ball_energies` and :func:`bouncing_ball_orbit_points`
+concern the single most famous scarred family in the Bunimovich stadium
+billiard (:class:`physicskit.quantum.chapters.potentials.StadiumBilliard2D`):
+the "bouncing ball" orbits bouncing straight up and down between the
+flat top and bottom walls, which -- unlike a generic stadium orbit --
+are only marginally unstable, so many low-lying eigenstates concentrate
+along them. :func:`scar_enhancement` quantifies that concentration for
+any eigenstate density, and :func:`husimi_projection_1d` builds a
+non-periodic analog of :func:`physicskit.chaos.quantum.husimi.husimi_function`
+for viewing a 1D wavefunction slice (e.g. along the billiard's flat
+wall) in phase space.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "bouncing_ball_energies",
+    "bouncing_ball_orbit_points",
+    "scar_enhancement",
+    "husimi_projection_1d",
+]
+
+
+def bouncing_ball_energies(R: float, hbar: float = 1.0, m: float = 1.0, n_max: int = 6) -> np.ndarray:
+    r"""Predicted energies of the "bouncing ball" orbit family in a stadium billiard of cap radius ``R``.
+
+    A trajectory launched perpendicular to the flat top and bottom walls
+    of a Bunimovich stadium (see
+    :class:`physicskit.quantum.chapters.potentials.StadiumBilliard2D`)
+    bounces straight up and down forever, blind to the length ``L`` of
+    the central rectangle -- exactly the motion of a particle in a 1D
+    infinite square well of width :math:`2R`. Quantizing that 1D motion
+    gives a leading-order prediction for where "bouncing ball" states
+    (eigenstates concentrated on this orbit family) appear in the full
+    2D spectrum:
+
+    .. math::
+
+       E_n = \frac{(n\pi\hbar)^2}{2m(2R)^2}, \qquad n=1,2,3,\dots
+
+    Parameters
+    ----------
+    R : float
+        Radius of the stadium's semicircular end-caps (half-height of
+        the billiard).
+    hbar : float, default=1.0
+        Value of :math:`\hbar` to use.
+    m : float, default=1.0
+        Particle mass.
+    n_max : int, default=6
+        Number of levels to compute.
+
+    Returns
+    -------
+    ndarray, shape (n_max,)
+        Predicted bouncing-ball energies, ascending.
+
+    See Also
+    --------
+    bouncing_ball_orbit_points : The classical orbit these energies quantize.
+
+    Examples
+    --------
+    This is exactly the ordinary infinite-square-well spectrum for a
+    well of width :math:`2R`:
+
+    >>> import numpy as np
+    >>> R = 0.5
+    >>> energies = bouncing_ball_energies(R, n_max=3)
+    >>> exact = (np.arange(1, 4) * np.pi) ** 2 / (2 * (2 * R) ** 2)
+    >>> bool(np.allclose(energies, exact))
+    True
+    """
+    n = np.arange(1, n_max + 1)
+    return (n * np.pi * hbar) ** 2 / (2.0 * m * (2.0 * R) ** 2)
+
+
+def bouncing_ball_orbit_points(x0: float, R: float, n_bounces: int = 4) -> tuple:
+    r"""Trace the classical "bouncing ball" orbit at horizontal position ``x0`` in a stadium billiard.
+
+    A perpendicular launch from the bottom wall at :math:`(x_0,-R)`
+    reflects straight back and forth off the flat top (:math:`y=R`) and
+    bottom (:math:`y=-R`) walls, tracing the same vertical segment
+    forever -- returned here as a zig-zag list of points suitable for
+    overlaying on a density plot.
+
+    Parameters
+    ----------
+    x0 : float
+        Horizontal position of the orbit, with :math:`|x_0| < L/2`
+        (strictly inside the flat central section of the stadium).
+    R : float
+        Radius of the stadium's semicircular end-caps.
+    n_bounces : int, default=4
+        Number of full up-down traversals to trace.
+
+    Returns
+    -------
+    x, y : ndarray
+        Coordinates tracing the orbit, shape ``(2 * n_bounces + 1,)``.
+
+    See Also
+    --------
+    bouncing_ball_energies : Quantized energies of this orbit family.
+
+    Examples
+    --------
+    >>> x, y = bouncing_ball_orbit_points(x0=0.2, R=0.5, n_bounces=2)
+    >>> x
+    array([0.2, 0.2, 0.2, 0.2, 0.2])
+    >>> y
+    array([-0.5,  0.5, -0.5,  0.5, -0.5])
+    """
+    y = np.array([-R if i % 2 == 0 else R for i in range(2 * n_bounces + 1)])
+    x = np.full_like(y, x0)
+    return x, y
+
+
+def scar_enhancement(density: np.ndarray, X: np.ndarray, Y: np.ndarray, mask: np.ndarray, x0: float, half_width: float) -> float:
+    r"""Density enhancement in a tube around a vertical bouncing-ball orbit, relative to the billiard average.
+
+    .. math::
+
+       \eta = \frac{\langle|\psi|^2\rangle_{\text{tube}}}{\langle|\psi|^2\rangle_{\text{billiard}}},
+       \qquad \text{tube} = \{(x,y)\in\text{billiard} : |x-x_0|\le w\},
+
+    a simple, direct measure of scarring: :math:`\eta\approx1` for an
+    ergodically-spread (unscarred) state, since the tube then just
+    samples a representative fraction of the whole density, while
+    :math:`\eta\gg1` signals density piled up specifically along the
+    orbit at :math:`x_0`.
+
+    Parameters
+    ----------
+    density : ndarray
+        Probability density :math:`|\psi(x,y)|^2` on a grid.
+    X, Y : ndarray
+        Coordinate meshgrid matching ``density``.
+    mask : ndarray of bool
+        ``True`` inside the billiard (e.g. from
+        :meth:`physicskit.quantum.chapters.potentials.StadiumBilliard2D.mask`).
+    x0 : float
+        Horizontal position of the bouncing-ball orbit to test.
+    half_width : float
+        Half-width of the tube around ``x0``.
+
+    Returns
+    -------
+    float
+        The enhancement factor :math:`\eta`.
+
+    Examples
+    --------
+    A density sharply concentrated in a narrow ridge at ``x0`` is
+    strongly enhanced inside a tube covering that ridge:
+
+    >>> import numpy as np
+    >>> x = np.linspace(-2, 2, 400)
+    >>> y = np.linspace(-1, 1, 200)
+    >>> X, Y = np.meshgrid(x, y, indexing="ij")
+    >>> mask = np.ones_like(X, dtype=bool)
+    >>> density = np.exp(-(X - 0.3) ** 2 / (2 * 0.05 ** 2))
+    >>> eta = scar_enhancement(density, X, Y, mask, x0=0.3, half_width=0.15)
+    >>> bool(12.0 < eta < 14.0)
+    True
+
+    An (exactly) uniform density is not enhanced anywhere:
+
+    >>> uniform = np.ones_like(X)
+    >>> round(scar_enhancement(uniform, X, Y, mask, x0=0.3, half_width=0.15), 8)
+    1.0
+    """
+    tube = mask & (np.abs(X - x0) <= half_width)
+    return float(np.mean(density[tube]) / np.mean(density[mask]))
+
+
+def husimi_projection_1d(
+    psi: np.ndarray,
+    s: np.ndarray,
+    hbar: float = 1.0,
+    sigma: float | None = None,
+    resolution: int = 60,
+    s0_range: tuple | None = None,
+    p0_range: tuple | None = None,
+) -> tuple:
+    r"""Husimi (coherent-state) phase-space projection of a 1D wavefunction slice on an open interval.
+
+    The non-periodic counterpart of
+    :func:`physicskit.chaos.quantum.husimi.husimi_function`: overlaps
+    ``psi`` with ordinary (non-periodized) coherent states
+    :math:`g_{s_0,p_0}(s)=\exp[-(s-s_0)^2/2\sigma^2+ip_0(s-s_0)/\hbar]`
+    at every point of an :math:`(s_0,p_0)` grid, suited to a slice taken
+    along an open boundary -- e.g. the flat top wall of a stadium
+    billiard, where :func:`bouncing_ball_orbit_points` lives -- rather
+    than a periodic domain.
+
+    Parameters
+    ----------
+    psi : ndarray of complex
+        Wavefunction values sampled on ``s``.
+    s : ndarray
+        Uniform 1D coordinate grid ``psi`` is sampled on.
+    hbar : float, default=1.0
+        Value of :math:`\hbar` to use.
+    sigma : float, optional
+        Coherent-state position width. Defaults to :math:`\sqrt{\hbar}`
+        (the minimum-uncertainty, equal-spread-in-natural-units choice).
+    resolution : int, default=60
+        Number of grid points along each of the :math:`s_0`, :math:`p_0` axes.
+    s0_range : (float, float), optional
+        Range of :math:`s_0` to scan. Defaults to ``(s.min(), s.max())``.
+    p0_range : (float, float), optional
+        Range of :math:`p_0` to scan. Defaults to
+        :math:`\pm\pi\hbar/\Delta s` (the grid's Nyquist momentum).
+
+    Returns
+    -------
+    S0, P0 : ndarray, shape (resolution, resolution)
+        Phase-space grid (``indexing="ij"``).
+    husimi : ndarray, shape (resolution, resolution)
+        The Husimi distribution, normalized to a peak value of 1.
+
+    See Also
+    --------
+    scar_enhancement : A simpler, single-number scarring diagnostic in
+        position space rather than phase space.
+
+    Examples
+    --------
+    A Gaussian wave packet's Husimi projection peaks at its own
+    position and momentum:
+
+    >>> import numpy as np
+    >>> s = np.linspace(-10, 10, 2000)
+    >>> s0_true, p0_true, w = 2.0, 3.0, 1.0
+    >>> psi = np.exp(-(s - s0_true) ** 2 / (2 * w ** 2)) * np.exp(1j * p0_true * s / 1.0)
+    >>> S0, P0, H = husimi_projection_1d(psi, s, hbar=1.0, sigma=w, resolution=80, s0_range=(-2, 6), p0_range=(-2, 8))
+    >>> i, j = np.unravel_index(np.argmax(H), H.shape)
+    >>> bool(abs(S0[i, j] - s0_true) < 0.2 and abs(P0[i, j] - p0_true) < 0.2)
+    True
+    """
+    s = np.asarray(s, dtype=float)
+    ds = s[1] - s[0]
+    if sigma is None:
+        sigma = np.sqrt(hbar)
+    if s0_range is None:
+        s0_range = (float(s.min()), float(s.max()))
+    if p0_range is None:
+        p_max = np.pi * hbar / ds
+        p0_range = (-p_max, p_max)
+
+    s0 = np.linspace(s0_range[0], s0_range[1], resolution)
+    p0 = np.linspace(p0_range[0], p0_range[1], resolution)
+    S0, P0 = np.meshgrid(s0, p0, indexing="ij")
+
+    ds_grid = s[None, None, :] - S0[:, :, None]
+    coherent = np.exp(-(ds_grid**2) / (2.0 * sigma**2) + 1j * P0[:, :, None] * ds_grid / hbar)
+    overlap = np.tensordot(np.conj(coherent), psi, axes=([2], [0])) * ds
+
+    husimi = np.abs(overlap) ** 2
+    husimi /= husimi.max()
+    return S0, P0, husimi

physicskit/semiclassical/tests/test_gutzwiller.py

@@ -0,0 +1,35 @@
+"""Physics-correctness tests for physicskit.semiclassical.core.gutzwiller."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from scipy.signal import find_peaks
+
+from physicskit.semiclassical.core.gutzwiller import (
+    classical_period,
+    gutzwiller_amplitude_from_monodromy,
+    gutzwiller_density_of_states,
+)
+from physicskit.semiclassical.core.wkb import bohr_sommerfeld_energies
+
+
+@pytest.mark.slow
+def test_gutzwiller_trace_formula_peaks_match_bohr_sommerfeld_spectrum():
+    V = lambda x: 0.5 * x**2
+    E_grid = np.linspace(0.2, 4.5, 200)
+    dos = gutzwiller_density_of_states(E_grid, V, m=1.0, x_min=-20, x_max=20)
+    peak_idx, _ = find_peaks(dos, height=0.3 * dos.max())
+    exact = bohr_sommerfeld_energies(V, m=1.0, x_min=-20, x_max=20, n_max=4)
+    assert np.allclose(E_grid[peak_idx], exact, atol=0.05)
+
+
+def test_classical_period_matches_harmonic_oscillator():
+    V = lambda x: 0.5 * x**2
+    T = classical_period(E=3.0, V=V, m=1.0, x_min=-20, x_max=20)
+    assert abs(T - 2 * np.pi) < 1e-4
+
+
+def test_gutzwiller_amplitude_from_monodromy():
+    M = np.array([[2.0, 0.0], [0.0, 0.5]])
+    assert abs(gutzwiller_amplitude_from_monodromy(M) - 1.0 / np.sqrt(0.5)) < 1e-10