physicskit 0.1.0__py3-none-any.whl

physicskit/classical/systems/chains.py

@@ -0,0 +1,334 @@
+"""Coupled-oscillator and soliton lattice chains.
+
+All three chains are 1D lattices of N particles with fixed
+(wall-anchored) boundary conditions, i.e. q_0 = q_{N+1} = 0. Each is a
+separable Hamiltonian system H = sum_i p_i^2/(2m) + V(q), with the
+force computed by a hand-written ``@njit`` loop over lattice sites (the
+"lattice loops" the project brief calls out for mandatory Numba
+acceleration) rather than through the symbolic engine, since the
+physics is fixed and the loop structure is identical for every N.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from numba import njit
+
+from physicskit.classical.core.base_system import HamiltonianSystem
+
+__all__ = ["HarmonicChain", "FPUTChain", "SineGordonChain"]
+
+
+# ---------------------------------------------------------------------------
+# Harmonic chain: V = sum_i k/2 (q_{i+1} - q_i)^2, fixed ends
+# ---------------------------------------------------------------------------
+
+
+@njit(cache=True)
+def _harmonic_force(q, k):
+    n = q.shape[0]
+    out = np.empty(n)
+    for i in range(n):
+        left = q[i - 1] if i > 0 else 0.0
+        right = q[i + 1] if i < n - 1 else 0.0
+        out[i] = k * (left - 2.0 * q[i] + right)
+    return out
+
+
+@lru_cache(maxsize=64)
+def _make_harmonic_force(k: float):
+    @njit(cache=True)
+    def force(q, t):
+        return _harmonic_force(q, k)
+
+    return force
+
+
+class _ChainBase(HamiltonianSystem):
+    separable = True
+
+    def __init__(self, q0, p0, m=1.0, k=1.0):
+        self.m, self.k = m, k
+        self.mass_inv = 1.0 / m
+        super().__init__(q0, p0)
+
+    def kinetic_energy(self, p: np.ndarray) -> float:
+        return 0.5 * float(np.sum(p * p)) / self.m
+
+    def normal_mode_frequencies(self) -> np.ndarray:
+        """Angular frequencies omega_k of the N linear normal modes of a fixed-fixed harmonic chain.
+
+        Returns
+        -------
+        ndarray, shape (n,)
+            omega_k for k = 1..N.
+        """
+        n = self.ndof
+        modes = np.arange(1, n + 1)
+        return 2.0 * np.sqrt(self.k / self.m) * np.sin(modes * np.pi / (2.0 * (n + 1)))
+
+    def normal_mode_coords(self, q: np.ndarray = None, p: np.ndarray = None):
+        """Transform (q, p) to normal-mode coordinates (Q_k, P_k).
+
+        Via the discrete sine transform appropriate for fixed-fixed
+        boundaries: ``Q_k = sqrt(2/(N+1)) * sum_i q_i sin(i*k*pi/(N+1))``,
+        ``i, k = 1..N``.
+
+        Parameters
+        ----------
+        q, p : ndarray, optional
+            State to transform; defaults to the current state.
+
+        Returns
+        -------
+        Q, P : ndarray, shape (n,)
+        """
+        q = self.q if q is None else q
+        p = self.p if p is None else p
+        n = self.ndof
+        i = np.arange(1, n + 1)
+        k = np.arange(1, n + 1)
+        S = np.sqrt(2.0 / (n + 1)) * np.sin(np.outer(i, k) * np.pi / (n + 1))
+        Q = S.T @ q
+        P = S.T @ p
+        return Q, P
+
+    def modal_energies(self, q: np.ndarray = None, p: np.ndarray = None) -> np.ndarray:
+        """Energy stored in each normal mode.
+
+        ``E_k = 0.5*(P_k^2/m + m*omega_k^2*Q_k^2)`` -- the diagnostic
+        used to show non-ergodic recurrence (the FPUT paradox) in
+        :class:`FPUTChain`.
+
+        Parameters
+        ----------
+        q, p : ndarray, optional
+            State to evaluate; defaults to the current state.
+
+        Returns
+        -------
+        ndarray, shape (n,)
+            E_k for k = 1..N.
+        """
+        Q, P = self.normal_mode_coords(q, p)
+        omega = self.normal_mode_frequencies()
+        return 0.5 * (P**2) / self.m + 0.5 * self.m * (omega**2) * (Q**2)
+
+
+class HarmonicChain(_ChainBase):
+    """Linear chain of N masses coupled by identical springs k, both
+    ends fixed to walls -- the exactly-solvable reference lattice whose
+    normal modes are the sine waves used to analyze the non-linear
+    :class:`FPUTChain` below.
+
+    Parameters
+    ----------
+    q0, p0 : array-like, shape (n,)
+        Initial displacements and momenta.
+    m, k : float
+        Mass and spring constant (uniform across the chain).
+    """
+
+    def __init__(self, q0, p0, m=1.0, k=1.0):
+        super().__init__(q0, p0, m=m, k=k)
+        self._force_njit = _make_harmonic_force(k)
+
+    def potential_energy(self, q: np.ndarray) -> float:
+        n = q.shape[0]
+        ext = np.empty(n + 2)
+        ext[0] = 0.0
+        ext[-1] = 0.0
+        ext[1:-1] = q
+        return 0.5 * self.k * float(np.sum(np.diff(ext) ** 2))
+
+
+# ---------------------------------------------------------------------------
+# FPUT beta-lattice: V(r) = k/2 r^2 + beta/4 r^4
+# ---------------------------------------------------------------------------
+
+
+@njit(cache=True)
+def _fput_force(q, k, beta):
+    n = q.shape[0]
+    out = np.empty(n)
+    for i in range(n):
+        left = q[i - 1] if i > 0 else 0.0
+        right = q[i + 1] if i < n - 1 else 0.0
+        r_right = right - q[i]
+        r_left = q[i] - left
+        f_right = k * r_right + beta * r_right**3
+        f_left = k * r_left + beta * r_left**3
+        out[i] = f_right - f_left
+    return out
+
+
+@lru_cache(maxsize=64)
+def _make_fput_force(k: float, beta: float):
+    @njit(cache=True)
+    def force(q, t):
+        return _fput_force(q, k, beta)
+
+    return force
+
+
+class FPUTChain(_ChainBase):
+    """Fermi-Pasta-Ulam-Tsingou beta-lattice: N masses (default 32) with
+    the quartic non-linear coupling potential
+    V(r) = (k/2) r^2 + (beta/4) r^4, r = q_{i+1} - q_i.
+
+    Famous for its "paradox": exciting a single low-order normal mode
+    does *not* thermalize energy across all modes as naive ergodic
+    reasoning predicts; instead the energy in :meth:`modal_energies`
+    returns almost exactly to the initially excited mode after a
+    characteristic recurrence time (the FPUT recurrence).
+
+    Parameters
+    ----------
+    n : int
+        Number of masses.
+    m, k : float
+        Mass and (linear) spring constant.
+    beta : float
+        Quartic non-linearity coefficient.
+    mode : int
+        Which normal mode to excite initially.
+    amplitude : float
+        Initial amplitude of that mode.
+    """
+
+    def __init__(self, n=32, m=1.0, k=1.0, beta=0.0, mode=1, amplitude=1.0):
+        self.beta = beta
+        q0 = amplitude * np.sin(np.arange(1, n + 1) * mode * np.pi / (n + 1))
+        p0 = np.zeros(n)
+        super().__init__(q0, p0, m=m, k=k)
+        self._force_njit = _make_fput_force(k, beta)
+
+    def potential_energy(self, q: np.ndarray) -> float:
+        n = q.shape[0]
+        ext = np.empty(n + 2)
+        ext[0] = 0.0
+        ext[-1] = 0.0
+        ext[1:-1] = q
+        r = np.diff(ext)
+        return float(np.sum(0.5 * self.k * r**2 + 0.25 * self.beta * r**4))
+
+
+# ---------------------------------------------------------------------------
+# Discrete Sine-Gordon chain (Frenkel-Kontorova): kink/antikink solitons
+# ---------------------------------------------------------------------------
+
+
+@njit(cache=True)
+def _sine_gordon_force(q, k):
+    n = q.shape[0]
+    out = np.empty(n)
+    for i in range(n):
+        left = q[i - 1] if i > 0 else q[i]
+        right = q[i + 1] if i < n - 1 else q[i]
+        out[i] = k * (left - 2.0 * q[i] + right) - np.sin(q[i])
+    return out
+
+
+@lru_cache(maxsize=64)
+def _make_sine_gordon_force(k: float):
+    @njit(cache=True)
+    def force(q, t):
+        return _sine_gordon_force(q, k)
+
+    return force
+
+
+class SineGordonChain(_ChainBase):
+    """Discretized pendulum chain (Frenkel-Kontorova model): N coupled
+    pendulums, V = sum_i [k/2 (q_{i+1}-q_i)^2 + (1 - cos q_i)], with
+    free (Neumann-like) boundary conditions so a topological kink can
+    propagate off either end without an artificial restoring wall.
+
+    Continuum-limit kink initial data from :meth:`kink`
+    (q_i = 4*atan(exp((i - i0)/width)), width=1 for the default m=1,
+    k=1) launches a soliton that propagates and scatters off other
+    kinks/antikinks -- the discrete analogue of the exact sine-Gordon
+    soliton solutions.
+
+    Parameters
+    ----------
+    n : int
+        Number of pendulums.
+    m, k : float
+        Mass and coupling constant.
+    q0, p0 : array-like, shape (n,), optional
+        Initial displacements and momenta; defaults to all zeros. Use
+        :meth:`kink` to build soliton initial data instead.
+    """
+
+    def __init__(self, n=200, m=1.0, k=1.0, q0=None, p0=None):
+        if q0 is None:
+            q0 = np.zeros(n)
+        if p0 is None:
+            p0 = np.zeros(n)
+        super().__init__(q0, p0, m=m, k=k)
+        self._force_njit = _make_sine_gordon_force(k)
+
+    def potential_energy(self, q: np.ndarray) -> float:
+        r = np.diff(q)  # free boundaries: no coupling to phantom exterior sites
+        return float(0.5 * self.k * np.sum(r**2) + np.sum(1.0 - np.cos(q)))
+
+    @staticmethod
+    def kink(n: int, center: float, width: float = 1.0, velocity: float = 0.0, polarity: int = 1) -> tuple:
+        """Continuum-limit single-kink (or antikink, polarity=-1) initial
+        condition, optionally boosted to move at ``velocity`` (sites per
+        unit time; to the right for positive ``velocity``, assuming the
+        default ``m=1, k=1`` -- i.e. a natural wave/"light" speed
+        ``c = sqrt(k/m) = 1``, the sine-Gordon equation's exact
+        Lorentz-invariance scale, so ``|velocity| < 1`` is required).
+
+        ``width`` is *not* a free shape knob: q_xx = sin(q) (the
+        continuum equation this chain approximates, with the default
+        m=1, k=1) is solved by q=4*atan(exp(x)) only for exactly unit
+        width. Passing a different ``width`` here without also scaling
+        ``k``/``m`` to match (``width = sqrt(k/m)``) gives a profile
+        that visibly relaxes/radiates under the true dynamics instead
+        of propagating as a clean, stable soliton.
+
+        The exact traveling-wave solution of the continuum sine-Gordon
+        equation is the *Lorentz-contracted* profile
+        ``q(x, t) = polarity * 4*atan(exp(gamma * (x - center - v*t) / width))``,
+        ``gamma = 1 / sqrt(1 - v**2)`` -- both the spatial profile at t=0
+        and its time derivative must be boosted together (not just the
+        momentum on top of the unboosted static profile, which is only
+        a small-v approximation and becomes badly wrong as ``|v|`` approaches 1).
+
+        Parameters
+        ----------
+        n : int
+            Chain length.
+        center : float
+            Lattice site the kink is centered on at t=0.
+        width : float
+            Soliton width; must equal ``sqrt(k/m)`` (1, for the default
+            m=1, k=1) for a genuine soliton solution.
+        velocity : float
+            Boost velocity, ``|velocity| < 1``.
+        polarity : {1, -1}
+            +1 for a kink, -1 for an antikink.
+
+        Returns
+        -------
+        q0, p0 : ndarray, shape (n,)
+            Initial displacements and momenta.
+
+        Raises
+        ------
+        ValueError
+            If ``abs(velocity) >= 1``.
+        """
+        if abs(velocity) >= 1.0:
+            raise ValueError("|velocity| must be < 1 (the natural wave speed sqrt(k/m), default 1) for a valid moving kink")
+        gamma = 1.0 / np.sqrt(1.0 - velocity**2)
+        i = np.arange(n)
+        u = gamma * (i - center) / width
+        q0 = polarity * 4.0 * np.arctan(np.exp(u))
+        p0 = -polarity * velocity * (2.0 * gamma / width) / np.cosh(u)
+        return q0, p0

physicskit/classical/systems/hamiltonian.py

@@ -0,0 +1,215 @@
+"""Hamiltonian phase-space systems illustrating Liouville mechanics.
+
+:class:`HenonHeilesSystem` is the classic 2-DOF non-linear oscillator
+whose Poincare sections show the breakdown of KAM tori as energy
+increases. :class:`PendulumSwarm` evolves an ensemble of independent
+phase points under identical 1-DOF pendulum dynamics to visually
+demonstrate Liouville's theorem (phase-space volume/area is conserved
+by Hamiltonian flow, even though the occupied region shears and
+filaments). :func:`pendulum_action_angle` computes the action J(E) and
+period of a simple pendulum via elliptic integrals, the archetypal
+worked example of action-angle variables.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from numba import njit
+from scipy import special
+
+from physicskit.classical.core.base_system import HamiltonianSystem
+
+__all__ = ["HenonHeilesSystem", "PendulumSwarm", "pendulum_action_angle"]
+
+
+@njit(cache=True)
+def _henon_heiles_force(q, t):
+    x, y = q[0], q[1]
+    out = np.empty(2)
+    out[0] = -(x + 2.0 * x * y)
+    out[1] = -(y + x * x - y * y)
+    return out
+
+
+class HenonHeilesSystem(HamiltonianSystem):
+    """H = (px^2 + py^2)/2 + (x^2 + y^2)/2 + x^2*y - y^3/3.
+
+    A non-integrable 2-DOF oscillator (originally a model of stellar
+    orbits in an axisymmetric galactic potential). Below E ~ 1/6 the
+    Poincare section (x, px) at y=0 is dominated by smooth KAM tori;
+    as E approaches and exceeds 1/6 the tori progressively break up
+    into chaotic seas.
+
+    Parameters
+    ----------
+    q0, p0 : array-like, shape (2,)
+        Initial position ``(x, y)`` and momentum ``(px, py)``.
+    """
+
+    separable = True
+    mass_inv = 1.0
+
+    def __init__(self, q0, p0):
+        self._force_njit = _henon_heiles_force
+        super().__init__(q0, p0)
+
+    def kinetic_energy(self, p: np.ndarray) -> float:
+        return 0.5 * float(np.dot(p, p))
+
+    def potential_energy(self, q: np.ndarray) -> float:
+        x, y = q[0], q[1]
+        return 0.5 * (x * x + y * y) + x * x * y - (y**3) / 3.0
+
+
+@lru_cache(maxsize=64)
+def _make_pendulum_force(g_over_l: float):
+    @njit(cache=True)
+    def force(q, t):
+        return -g_over_l * np.sin(q)
+
+    return force
+
+
+class PendulumSwarm(HamiltonianSystem):
+    """An ensemble of N independent, identical simple pendulums,
+    H_i = p_i^2 / 2 - (g/l) cos(q_i) for each i = 1..N.
+
+    The pendulums are mutually decoupled (each is its own 1-DOF
+    Hamiltonian system) but are integrated together as one N-DOF
+    separable Hamiltonian so a whole ensemble can be evolved with a
+    single Yoshida4/Verlet call. Seeding N points inside a small
+    (dq, dp) box and watching the occupied phase-space patch shear
+    over time -- its area invariant even as its shape stretches into a
+    filament -- is the standard visual proof of Liouville's theorem.
+
+    Parameters
+    ----------
+    q0, p0 : array-like, shape (n,)
+        Initial angles and momenta, one pair per pendulum in the ensemble.
+    g_over_l : float
+        Ratio g/l shared by every pendulum.
+    """
+
+    separable = True
+
+    def __init__(self, q0, p0, g_over_l: float = 1.0):
+        self.g_over_l = g_over_l
+        self.mass_inv = 1.0
+        self._force_njit = _make_pendulum_force(g_over_l)
+        super().__init__(q0, p0)
+
+    @classmethod
+    def from_box(cls, q_center: float, p_center: float, dq: float, dp: float, n: int = 1000, g_over_l: float = 1.0, seed: int = 0):
+        """Seed N phase points uniformly inside a (dq x dp) box centered at (q_center, p_center).
+
+        Parameters
+        ----------
+        q_center, p_center : float
+            Box center.
+        dq, dp : float
+            Box width and height.
+        n : int
+            Number of phase points to seed.
+        g_over_l : float
+            Ratio g/l shared by every pendulum.
+        seed : int
+            Random seed for reproducibility.
+
+        Returns
+        -------
+        PendulumSwarm
+        """
+        rng = np.random.default_rng(seed)
+        q0 = q_center + (rng.random(n) - 0.5) * dq
+        p0 = p_center + (rng.random(n) - 0.5) * dp
+        return cls(q0, p0, g_over_l=g_over_l)
+
+    def kinetic_energy(self, p: np.ndarray) -> float:
+        return 0.5 * float(np.sum(p * p))
+
+    def potential_energy(self, q: np.ndarray) -> float:
+        return -self.g_over_l * float(np.sum(np.cos(q)))
+
+    def per_particle_energy(self, q: np.ndarray = None, p: np.ndarray = None) -> np.ndarray:
+        """Energy of each individual pendulum, used to color/track the swarm.
+
+        Conserved per-particle since the ensemble is decoupled.
+
+        Parameters
+        ----------
+        q, p : ndarray, optional
+            State to evaluate; defaults to the current state.
+
+        Returns
+        -------
+        ndarray, shape (n,)
+        """
+        q = self.q if q is None else q
+        p = self.p if p is None else p
+        return 0.5 * p * p - self.g_over_l * np.cos(q)
+
+    def phase_space_area(self, q: np.ndarray = None, p: np.ndarray = None) -> float:
+        """Convex-hull area of the current swarm's (q, p) point cloud.
+
+        A practical proxy for the occupied phase-space volume.
+
+        Parameters
+        ----------
+        q, p : ndarray, optional
+            State to evaluate; defaults to the current state.
+
+        Returns
+        -------
+        float
+        """
+        from scipy.spatial import ConvexHull
+
+        q = self.q if q is None else q
+        p = self.p if p is None else p
+        pts = np.column_stack([q, p])
+        return float(ConvexHull(pts).volume)  # 'volume' is the 2D area for a 2D hull
+
+
+def pendulum_action_angle(E: float, g_over_l: float = 1.0):
+    """Action J(E) and period T(E) for a simple pendulum H = p^2/2 - (g/l)cos(q).
+
+    For librating orbits (-g/l < E < g/l), uses the standard elliptic-integral
+    closed form: with k^2 = (E + g/l) / (2 g/l),
+
+        J(E) = (8/pi) * sqrt(g/l) * [E_ellip(k) - (1 - k^2) * K_ellip(k)]
+        T(E) = 4 * K_ellip(k) / sqrt(g/l)
+
+    where K, E are the complete elliptic integrals of the first/second
+    kind (SciPy's ``special.ellipk``/``ellipe`` take the parameter
+    m = k^2, not the modulus k).
+
+    Parameters
+    ----------
+    E : float
+        Energy, with ``-g_over_l < E < g_over_l`` (librating orbits only).
+    g_over_l : float
+        Ratio g/l.
+
+    Returns
+    -------
+    J : float
+        Action.
+    T : float
+        Orbital period.
+
+    Raises
+    ------
+    ValueError
+        If ``E`` is outside the librating range.
+    """
+    w0 = np.sqrt(g_over_l)
+    if -g_over_l >= E or g_over_l <= E:
+        raise ValueError("pendulum_action_angle only supports librating orbits (-g/l < E < g/l)")
+    m = (E + g_over_l) / (2.0 * g_over_l)  # = k^2
+    K = special.ellipk(m)
+    Eei = special.ellipe(m)
+    J = (8.0 / np.pi) * w0 * (Eei - (1.0 - m) * K)
+    T = 4.0 * K / w0
+    return float(J), float(T)