physicskit 0.1.0__py3-none-any.whl

physicskit/fluids/utils/spectral_analysis.py

@@ -0,0 +1,142 @@
+"""Turbulent kinetic energy spectra and the Kolmogorov -5/3 law.
+
+A turbulent velocity field is usefully summarized not by its detailed
+pointwise structure but by how its kinetic energy is distributed across
+length scales -- the energy spectrum :math:`E(k)`, defined so that
+:math:`\\int E(k)\\,dk` is the total kinetic energy per unit mass.
+Kolmogorov's 1941 theory predicts a universal power law,
+:math:`E(k)\\propto k^{-5/3}`, in the "inertial range" of scales small
+enough to have forgotten how the turbulence was forced but large enough not
+to feel viscosity yet -- one of the most-tested predictions in all of
+classical physics, and the standard first check that a simulated 2D or 3D
+flow (e.g. the output of
+:class:`physicskit.fluids.systems.navier_stokes.NavierStokes2D`) is
+resolving a genuine turbulent cascade.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = ["energy_spectrum", "kolmogorov_reference_slope"]
+
+
+def energy_spectrum(u: NDArray[np.float64], v: NDArray[np.float64], length: float) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Isotropic (azimuthally averaged) kinetic energy spectrum of a 2D velocity field.
+
+    Computes :math:`\\hat{u}(\\mathbf{k})` and :math:`\\hat{v}(\\mathbf{k})`
+    by FFT, forms the kinetic energy density
+    :math:`\\tfrac{1}{2}(|\\hat{u}|^2+|\\hat{v}|^2)` at each wavevector, and
+    sums it over the discrete annulus of wavevectors with
+    :math:`k \\le |\\mathbf{k}| < k+1` (in grid-index units) to give
+    :math:`E(k)`, normalized so that :math:`\\sum_k E(k) \\approx` the
+    domain-averaged kinetic energy per unit mass (Parseval's theorem).
+
+    Parameters
+    ----------
+    u, v : ndarray of float, shape (n, n)
+        Velocity components on a doubly periodic grid, e.g. from
+        :meth:`physicskit.fluids.systems.navier_stokes.NavierStokes2D.velocity`.
+    length : float
+        Physical domain size.
+
+    Returns
+    -------
+    k : ndarray of float, shape (n // 2,)
+        Wavenumber bins (angular, :math:`2\\pi/\\lambda` convention).
+    E : ndarray of float, shape (n // 2,)
+        Kinetic energy spectral density at each wavenumber bin.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `u` and `v` are not the same shape, or are not square.
+
+    See Also
+    --------
+    kolmogorov_reference_slope : The -5/3 reference line to compare `E` against.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> n, length = 64, 2 * np.pi
+    >>> x = np.linspace(0, length, n, endpoint=False)
+    >>> X, Y = np.meshgrid(x, x, indexing="ij")
+    >>> u, v = np.sin(Y), np.sin(X)  # a single-mode flow
+    >>> k, E = energy_spectrum(u, v, length)
+    >>> bool(np.argmax(E) == 1)  # all the energy sits at the single k=1 mode
+    True
+    """
+    if u.shape != v.shape:
+        raise InvalidParameterError("u and v must have the same shape")
+    if u.shape[0] != u.shape[1]:
+        raise InvalidParameterError("u and v must be square (n, n) arrays")
+    n = u.shape[0]
+    u_hat = np.fft.fft2(u) / n**2
+    v_hat = np.fft.fft2(v) / n**2
+    energy_density = 0.5 * (np.abs(u_hat) ** 2 + np.abs(v_hat) ** 2) * n**2
+
+    kfreq = np.fft.fftfreq(n, d=length / n) * 2.0 * np.pi
+    KX, KY = np.meshgrid(kfreq, kfreq, indexing="ij")
+    kmag_index = np.round(np.sqrt(KX**2 + KY**2) / (2.0 * np.pi / length)).astype(int)
+
+    n_bins = n // 2
+    E = np.zeros(n_bins)
+    for shell in range(n_bins):
+        mask = kmag_index == shell
+        E[shell] = energy_density[mask].sum()
+    k = np.arange(n_bins) * (2.0 * np.pi / length)
+    return k, E
+
+
+def kolmogorov_reference_slope(k: NDArray[np.float64], k0: float, E0: float) -> NDArray[np.float64]:
+    """A Kolmogorov :math:`k^{-5/3}` reference line, anchored at one point.
+
+    Kolmogorov's K41 theory predicts that, in the inertial range, the
+    energy spectrum depends only on the wavenumber `k` and the (scale-independent)
+    energy dissipation rate, and dimensional analysis alone then fixes the
+    power law:
+
+    .. math::
+
+        E(k) = E_0 \\left(\\frac{k}{k_0}\\right)^{-5/3}.
+
+    Plotting this line through one point ``(k0, E0)`` of a measured
+    spectrum (see :func:`energy_spectrum`) on log-log axes is the standard
+    visual check for an inertial range: a genuine turbulent cascade runs
+    parallel to this line over at least a decade of `k`.
+
+    Parameters
+    ----------
+    k : ndarray of float
+        Wavenumbers at which to evaluate the reference line.
+    k0 : float
+        Anchor wavenumber; must be positive.
+    E0 : float
+        Spectral energy density at `k0`.
+
+    Returns
+    -------
+    ndarray of float
+        Reference spectral density :math:`E_0(k/k_0)^{-5/3}` at each `k`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `k0` is not positive.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> k = np.array([1.0, 2.0, 4.0])
+    >>> ref = kolmogorov_reference_slope(k, k0=1.0, E0=1.0)
+    >>> round(float(ref[1]), 4)
+    0.315
+    """
+    if k0 <= 0:
+        raise InvalidParameterError(f"k0 must be positive, got {k0}")
+    k = np.asarray(k, dtype=np.float64)
+    return E0 * (k / k0) ** (-5.0 / 3.0)

physicskit/fluids/visualizers/__init__.py

@@ -0,0 +1,14 @@
+from physicskit.fluids.visualizers import theme
+from physicskit.fluids.visualizers.compressible import plot_shock_tube_profiles
+from physicskit.fluids.visualizers.flow_fields import plot_streamlines, plot_vorticity_field
+from physicskit.fluids.visualizers.potential_flow import plot_pressure_coefficient
+from physicskit.fluids.visualizers.spectra import plot_energy_spectrum
+
+__all__ = [
+    "plot_energy_spectrum",
+    "plot_pressure_coefficient",
+    "plot_shock_tube_profiles",
+    "plot_streamlines",
+    "plot_vorticity_field",
+    "theme",
+]

physicskit/fluids/visualizers/compressible.py

@@ -0,0 +1,39 @@
+"""Shock-tube profile plots."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+from numpy.typing import NDArray
+
+from physicskit.fluids.visualizers import theme
+
+__all__ = ["plot_shock_tube_profiles"]
+
+
+def plot_shock_tube_profiles(x: NDArray[np.float64], rho: NDArray[np.float64], u: NDArray[np.float64], p: NDArray[np.float64]) -> tuple[Figure, NDArray]:
+    """Plot density, velocity, and pressure profiles from a shock-tube solution.
+
+    Parameters
+    ----------
+    x : ndarray of float
+        Spatial grid.
+    rho, u, p : ndarray of float
+        Density, velocity, and pressure profiles, e.g. from
+        :func:`physicskit.fluids.systems.compressible_flow.sod_shock_tube`.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    axes : ndarray of matplotlib.axes.Axes, shape (3,)
+    """
+    fig, axes = plt.subplots(3, 1, figsize=(7, 8), sharex=True)
+    for ax, field, label in zip(axes, (rho, u, p), (r"$\rho$", "u", "p")):
+        ax.plot(x, field, color=theme.PRIMARY, lw=1.2)
+        ax.set_ylabel(label)
+        ax.grid(alpha=0.3)
+    axes[-1].set_xlabel("x")
+    fig.suptitle("Sod shock tube")
+    fig.tight_layout()
+    return fig, axes

physicskit/fluids/visualizers/flow_fields.py

@@ -0,0 +1,252 @@
+"""Streamline and vorticity-field plots, the workhorse visualizations of this package."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import NDArray
+
+from physicskit.fluids.systems.instabilities import simulate_kelvin_helmholtz, simulate_rayleigh_taylor
+from physicskit.fluids.visualizers import theme
+
+__all__ = ["plot_streamlines", "plot_vorticity_field", "animate_kelvin_helmholtz", "animate_rayleigh_taylor"]
+
+
+def plot_streamlines(
+    X: NDArray[np.float64], Y: NDArray[np.float64], u: NDArray[np.float64], v: NDArray[np.float64], ax: Axes | None = None, **streamplot_kwargs: Any
+) -> tuple[Figure, Axes]:
+    """Plot velocity-field streamlines.
+
+    Parameters
+    ----------
+    X, Y : ndarray of float, shape (n, n)
+        Real-space coordinate grids.
+    u, v : ndarray of float, shape (n, n)
+        Velocity components.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    **streamplot_kwargs
+        Additional keyword arguments forwarded to ``ax.streamplot``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+    kwargs: dict[str, Any] = {"color": theme.STRUCTURE, "linewidth": 0.8, "density": 1.2}
+    kwargs.update(streamplot_kwargs)
+    ax.streamplot(X.T, Y.T, u.T, v.T, **kwargs)
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.set_aspect("equal")
+    return fig, ax
+
+
+def plot_vorticity_field(
+    X: NDArray[np.float64],
+    Y: NDArray[np.float64],
+    omega: NDArray[np.float64],
+    u: NDArray[np.float64] | None = None,
+    v: NDArray[np.float64] | None = None,
+    ax: Axes | None = None,
+    **pcolormesh_kwargs: Any,
+) -> tuple[Figure, Axes]:
+    """Plot a vorticity field as a heatmap, optionally overlaid with velocity streamlines.
+
+    Parameters
+    ----------
+    X, Y : ndarray of float, shape (n, n)
+        Real-space coordinate grids.
+    omega : ndarray of float, shape (n, n)
+        Vorticity field.
+    u, v : ndarray of float, shape (n, n), optional
+        Velocity components; if given, streamlines are overlaid on the heatmap.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    **pcolormesh_kwargs
+        Additional keyword arguments forwarded to ``ax.pcolormesh``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+    vmax = np.max(np.abs(omega)) or 1.0
+    kwargs: dict[str, Any] = {"cmap": theme.VORTICITY_CMAP, "shading": "auto", "vmin": -vmax, "vmax": vmax}
+    kwargs.update(pcolormesh_kwargs)
+    im = ax.pcolormesh(X, Y, omega, **kwargs)
+    fig.colorbar(im, ax=ax, label="vorticity")
+    if u is not None and v is not None:
+        ax.streamplot(X.T, Y.T, u.T, v.T, color=theme.STRUCTURE, linewidth=0.6, density=1.0)
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.set_aspect("equal")
+    return fig, ax
+
+
+def _animate_vorticity_snapshots(
+    X: NDArray[np.float64], Y: NDArray[np.float64], snapshots: list[NDArray[np.float64]], title: str, interval: int, label: str = "vorticity"
+) -> FuncAnimation:
+    """Shared heatmap animator: redraws a vorticity-like (signed, diverging) field over a sequence of snapshots."""
+    fig, ax = plt.subplots(figsize=(6, 6))
+    vmax = max(float(np.max(np.abs(s))) for s in snapshots) or 1.0
+    im = ax.pcolormesh(X, Y, snapshots[0], cmap=theme.VORTICITY_CMAP, shading="auto", vmin=-vmax, vmax=vmax)
+    fig.colorbar(im, ax=ax, label=label)
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.set_aspect("equal")
+    ax.set_title(title)
+
+    def update(frame):
+        im.set_array(snapshots[frame].ravel())
+        return (im,)
+
+    return FuncAnimation(fig, update, frames=len(snapshots), interval=interval, blit=True)
+
+
+def animate_kelvin_helmholtz(
+    omega0: NDArray[np.float64], nu: float, dt: float, steps_per_frame: int, n_frames: int, length: float, interval: int = 60
+) -> FuncAnimation:
+    """Animate a Kelvin-Helmholtz shear layer rolling up into its characteristic vortex row.
+
+    Repeatedly calls
+    :func:`physicskit.fluids.systems.instabilities.simulate_kelvin_helmholtz`
+    for ``steps_per_frame`` RK4 steps at a time, using each call's final
+    vorticity as the next call's initial condition, and animates the
+    resulting vorticity-field snapshots.
+
+    Parameters
+    ----------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field, e.g. from
+        :func:`physicskit.fluids.systems.instabilities.kelvin_helmholtz_ic`.
+    nu : float
+        Kinematic viscosity; must be positive.
+    dt : float
+        Time step per sub-step.
+    steps_per_frame : int
+        Number of RK4 steps advanced between animation frames.
+    n_frames : int
+        Number of animation frames.
+    length : float
+        Physical domain size.
+    interval : int, default=60
+        Delay between frames in milliseconds.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+
+    See Also
+    --------
+    physicskit.fluids.systems.instabilities.simulate_kelvin_helmholtz : Supplies the vorticity snapshots animated here.
+    animate_rayleigh_taylor : The companion buoyancy-driven instability animator.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.fluids.systems.instabilities import kelvin_helmholtz_ic
+    >>> n, length = 64, 2 * np.pi
+    >>> omega0 = kelvin_helmholtz_ic(n, length, shear_width=0.1, perturbation_amplitude=0.05)
+    >>> anim = animate_kelvin_helmholtz(omega0, nu=0.001, dt=0.0025, steps_per_frame=10, n_frames=4, length=length)
+    >>> len(list(anim.new_frame_seq()))
+    4
+    """
+    n = omega0.shape[0]
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    omega = np.asarray(omega0, dtype=float)
+    snapshots = [omega.copy()]
+    for _ in range(n_frames - 1):
+        result = simulate_kelvin_helmholtz(omega, nu, dt, steps_per_frame, length)
+        omega = result["omega"]
+        snapshots.append(omega.copy())
+    return _animate_vorticity_snapshots(X, Y, snapshots, title="Kelvin-Helmholtz instability", interval=interval)
+
+
+def animate_rayleigh_taylor(
+    omega0: NDArray[np.float64],
+    buoyancy0: NDArray[np.float64],
+    nu: float,
+    kappa: float,
+    g: float,
+    dt: float,
+    steps_per_frame: int,
+    n_frames: int,
+    length: float,
+    interval: int = 60,
+) -> FuncAnimation:
+    """Animate the Rayleigh-Taylor instability's mushroom plumes growing from a rippled density interface.
+
+    Repeatedly calls
+    :func:`physicskit.fluids.systems.instabilities.simulate_rayleigh_taylor`
+    for ``steps_per_frame`` RK4 steps at a time, using each call's final
+    state as the next call's initial condition, and animates the resulting
+    buoyancy-field snapshots (the field in which the rising light plumes
+    and falling heavy fingers are most visually distinct).
+
+    Parameters
+    ----------
+    omega0, buoyancy0 : ndarray of float, shape (n, n)
+        Initial vorticity and buoyancy fields, e.g. from
+        :func:`physicskit.fluids.systems.instabilities.rayleigh_taylor_ic`.
+    nu : float
+        Kinematic viscosity; must be positive.
+    kappa : float
+        Buoyancy diffusivity; must be positive.
+    g : float
+        Gravitational acceleration; must be positive.
+    dt : float
+        Time step per sub-step.
+    steps_per_frame : int
+        Number of RK4 steps advanced between animation frames.
+    n_frames : int
+        Number of animation frames.
+    length : float
+        Physical domain size.
+    interval : int, default=60
+        Delay between frames in milliseconds.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+
+    See Also
+    --------
+    physicskit.fluids.systems.instabilities.simulate_rayleigh_taylor : Supplies the buoyancy snapshots animated here.
+    animate_kelvin_helmholtz : The companion shear-driven instability animator.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.fluids.systems.instabilities import rayleigh_taylor_ic
+    >>> n, length = 64, 2 * np.pi
+    >>> omega0, buoyancy0 = rayleigh_taylor_ic(n, length, atwood_number=0.3, perturbation_amplitude=0.01)
+    >>> anim = animate_rayleigh_taylor(omega0, buoyancy0, nu=0.002, kappa=0.002, g=1.0, dt=0.01, steps_per_frame=10, n_frames=4, length=length)
+    >>> len(list(anim.new_frame_seq()))
+    4
+    """
+    n = omega0.shape[0]
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    omega = np.asarray(omega0, dtype=float)
+    buoyancy = np.asarray(buoyancy0, dtype=float)
+    snapshots = [buoyancy.copy()]
+    for _ in range(n_frames - 1):
+        result = simulate_rayleigh_taylor(omega, buoyancy, nu, kappa, g, dt, steps_per_frame, length)
+        omega, buoyancy = result["omega"], result["buoyancy"]
+        snapshots.append(buoyancy.copy())
+    return _animate_vorticity_snapshots(X, Y, snapshots, title="Rayleigh-Taylor instability (buoyancy)", interval=interval, label="buoyancy")

physicskit/fluids/visualizers/potential_flow.py

@@ -0,0 +1,51 @@
+"""Pressure-coefficient plots for potential flow."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import NDArray
+
+from physicskit.fluids.visualizers import theme
+
+__all__ = ["plot_pressure_coefficient"]
+
+
+def plot_pressure_coefficient(theta: NDArray[np.float64], Cp: NDArray[np.float64], ax: Axes | None = None, **plot_kwargs: Any) -> tuple[Figure, Axes]:
+    """Plot the surface pressure coefficient :math:`C_p(\\theta)` around a body.
+
+    Parameters
+    ----------
+    theta : ndarray of float
+        Angular position around the body (radians), typically ``[0, 2*pi]``.
+    Cp : ndarray of float
+        Pressure coefficient at each `theta`, e.g. from
+        :func:`physicskit.fluids.systems.potential_flow.pressure_coefficient`
+        evaluated on a circle.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    **plot_kwargs
+        Additional keyword arguments forwarded to ``ax.plot``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 4))
+    else:
+        fig = cast(Figure, ax.figure)
+    kwargs: dict[str, Any] = {"color": theme.PRIMARY}
+    kwargs.update(plot_kwargs)
+    ax.plot(np.degrees(theta), Cp, **kwargs)
+    ax.axhline(0.0, color=theme.MUTED, lw=0.8, ls="--")
+    ax.invert_yaxis()
+    ax.set_xlabel(r"$\theta$ (degrees)")
+    ax.set_ylabel(r"$C_p$")
+    ax.set_title("Surface pressure coefficient")
+    return fig, ax

physicskit/fluids/visualizers/spectra.py

@@ -0,0 +1,62 @@
+"""Turbulent energy-spectrum plots."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import NDArray
+
+from physicskit.fluids.utils.spectral_analysis import kolmogorov_reference_slope
+from physicskit.fluids.visualizers import theme
+
+__all__ = ["plot_energy_spectrum"]
+
+
+def plot_energy_spectrum(
+    k: NDArray[np.float64], E: NDArray[np.float64], ax: Axes | None = None, show_kolmogorov: bool = True, **plot_kwargs: Any
+) -> tuple[Figure, Axes]:
+    """Log-log plot of a kinetic energy spectrum, with an optional Kolmogorov -5/3 reference line.
+
+    Parameters
+    ----------
+    k : ndarray of float
+        Wavenumbers, e.g. from :func:`physicskit.fluids.utils.spectral_analysis.energy_spectrum`.
+    E : ndarray of float
+        Spectral energy density at each `k`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    show_kolmogorov : bool, default True
+        If True, overlay a :math:`k^{-5/3}` reference line anchored at the
+        lowest plotted (nonzero-energy) wavenumber.
+    **plot_kwargs
+        Additional keyword arguments forwarded to ``ax.loglog`` for the
+        measured spectrum.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 5))
+    else:
+        fig = cast(Figure, ax.figure)
+    k = np.asarray(k, dtype=np.float64)
+    E = np.asarray(E, dtype=np.float64)
+    mask = (k > 0) & (E > 0)
+    kwargs: dict[str, Any] = {"color": theme.PRIMARY, "marker": "o", "markersize": 3, "label": "E(k)"}
+    kwargs.update(plot_kwargs)
+    ax.loglog(k[mask], E[mask], **kwargs)
+    if show_kolmogorov and np.any(mask):
+        k0 = k[mask][0]
+        E0 = E[mask][0]
+        ax.loglog(k[mask], kolmogorov_reference_slope(k[mask], k0, E0), color=theme.ACCENT, ls="--", label=r"$k^{-5/3}$")
+    ax.set_xlabel("k")
+    ax.set_ylabel("E(k)")
+    ax.set_title("Kinetic energy spectrum")
+    ax.legend()
+    return fig, ax

physicskit/fluids/visualizers/theme.py

@@ -0,0 +1,38 @@
+"""Shared color constants for physicskit.fluids's Matplotlib visualizers.
+
+Re-exports the same palette :mod:`physicskit.chaos.visualizers.theme` defines,
+so a plot moving between the two packages (e.g. a von Karman street built
+from :mod:`physicskit.fluids.systems.vortex_dynamics` next to a chaotic
+trajectory) reads as one consistent visual language rather than two
+accidentally different ones. Every visualizer still accepts its own
+color/colormap keyword arguments to override these, so nothing here is
+load-bearing.
+"""
+
+from __future__ import annotations
+
+from physicskit.chaos.visualizers.theme import (
+    ACCENT,
+    DIVERGING_CMAP,
+    MUTED,
+    PRIMARY,
+    QUALITATIVE_CMAP,
+    SEQUENTIAL_CMAP,
+    STRUCTURE,
+)
+
+__all__ = [
+    "PRIMARY",
+    "ACCENT",
+    "STRUCTURE",
+    "MUTED",
+    "QUALITATIVE_CMAP",
+    "SEQUENTIAL_CMAP",
+    "DIVERGING_CMAP",
+    "VORTICITY_CMAP",
+]
+
+#: Diverging colormap for vorticity fields (signed, centered at zero): an
+#: alias for :data:`DIVERGING_CMAP`, named for its most common use in this
+#: package.
+VORTICITY_CMAP: str = DIVERGING_CMAP

physicskit/integrators/__init__.py

@@ -0,0 +1,52 @@
+"""Numba-accelerated ODE integrators shared across physicskit subpackages.
+
+Right-hand-side / force callbacks use the ``f(state_or_pos, t, params) ->
+ndarray`` convention throughout, so a single compiled callback can be reused
+across systems with different parameter values without recompiling (see
+:mod:`physicskit.integrators.fixed_step`).
+
+* :func:`rk4_integrate` -- classical 4th-order Runge-Kutta (not
+  energy-preserving).
+* :func:`leapfrog_integrate` (alias :func:`velocity_verlet_integrate`) --
+  2nd-order symplectic Stormer-Verlet, for separable systems
+  ``pos'' = force(pos, t)``.
+* :func:`yoshida4_integrate` -- 4th-order symplectic, built from three
+  leapfrog sub-steps.
+* :func:`dopri5_integrate` -- adaptive-step-size embedded Dormand-Prince
+  RK5(4), for non-conservative or accuracy-sensitive systems (see
+  :mod:`physicskit.integrators.adaptive` for why this isn't offered for the
+  symplectic integrators).
+
+:mod:`physicskit.classical.core.integrators` uses its own closure-based
+calling convention (``force_func(q, t)`` plus a per-instance ``mass_inv``)
+and :mod:`physicskit.statphys.core.md_engine` its own periodic-boundary,
+force-caching variant; both are documented at their own definitions rather
+than adapted to the convention here.
+"""
+
+from physicskit.integrators.adaptive import dopri5_integrate, dopri5_step
+from physicskit.integrators.fixed_step import (
+    RHSFunc,
+    leapfrog_integrate,
+    leapfrog_step,
+    rk4_integrate,
+    rk4_step,
+    velocity_verlet_integrate,
+    velocity_verlet_step,
+    yoshida4_integrate,
+    yoshida4_step,
+)
+
+__all__ = [
+    "RHSFunc",
+    "rk4_step",
+    "rk4_integrate",
+    "leapfrog_step",
+    "leapfrog_integrate",
+    "velocity_verlet_step",
+    "velocity_verlet_integrate",
+    "yoshida4_step",
+    "yoshida4_integrate",
+    "dopri5_step",
+    "dopri5_integrate",
+]