physicskit 0.1.0__py3-none-any.whl

physicskit/fluids/systems/compressible_flow.py

@@ -0,0 +1,281 @@
+"""1D compressible flow: the Euler equations, normal shocks, and the Sod shock tube.
+
+Where potential and viscous flow assume incompressibility, this module
+drops that assumption entirely: the 1D Euler equations for an inviscid,
+compressible, ideal gas support genuinely discontinuous solutions (shocks
+and contact discontinuities) that no continuous velocity field can produce.
+:func:`rankine_hugoniot_jump_conditions` and :func:`normal_shock_relations`
+give the exact algebraic jump a shock must satisfy; :func:`sod_shock_tube`
+resolves that jump -- alongside a contact discontinuity and an expansion
+fan -- dynamically, by integrating the full nonlinear equations through a
+classic Riemann problem.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+from numpy.typing import NDArray
+
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = [
+    "rankine_hugoniot_jump_conditions",
+    "normal_shock_relations",
+    "sod_shock_tube",
+]
+
+
+def rankine_hugoniot_jump_conditions(rho1: float, u1: float, p1: float, rho2: float, u2: float, p2: float) -> dict[str, float]:
+    """Residuals of the Rankine-Hugoniot jump conditions across a stationary discontinuity.
+
+    A steady discontinuity in a 1D inviscid compressible flow (states 1
+    upstream, 2 downstream, in the frame where the discontinuity itself is
+    at rest) must conserve mass, momentum, and energy flux exactly:
+
+    .. math::
+
+        \\rho_1 u_1 = \\rho_2 u_2, \\qquad
+        p_1 + \\rho_1 u_1^2 = p_2 + \\rho_2 u_2^2, \\qquad
+        h_1 + \\tfrac{1}{2}u_1^2 = h_2 + \\tfrac{1}{2}u_2^2,
+
+    where :math:`h=\\gamma p/((\\gamma-1)\\rho)` is specific enthalpy (an
+    ideal gas is assumed only for the energy residual). Rankine (1870) first
+    wrote the mass and momentum conditions; Hugoniot (1887, 1889) added the
+    energy condition and the resulting relation between the shock's pressure
+    and density ratios now called the Hugoniot curve. This function returns
+    each condition's residual, primarily to *verify* a candidate jump (e.g.
+    the output of :func:`normal_shock_relations`) rather than to solve for
+    one directly.
+
+    Parameters
+    ----------
+    rho1, u1, p1 : float
+        Upstream density, velocity, and pressure.
+    rho2, u2, p2 : float
+        Downstream density, velocity, and pressure.
+
+    Returns
+    -------
+    dict
+        ``{"mass": ..., "momentum": ..., "energy": ...}`` residuals; all
+        zero for an exactly satisfied jump.
+
+    Examples
+    --------
+    >>> jump = normal_shock_relations(M1=2.0)
+    >>> residuals = rankine_hugoniot_jump_conditions(1.0, 2.0, 1.0 / 1.4, jump["rho2_rho1"], 2.0 / jump["rho2_rho1"], jump["p2_p1"] / 1.4)
+    >>> bool(max(abs(v) for v in residuals.values()) < 1e-10)
+    True
+    """
+    gamma = 1.4
+    mass = rho1 * u1 - rho2 * u2
+    momentum = (p1 + rho1 * u1**2) - (p2 + rho2 * u2**2)
+    h1 = gamma * p1 / ((gamma - 1.0) * rho1)
+    h2 = gamma * p2 / ((gamma - 1.0) * rho2)
+    energy = (h1 + 0.5 * u1**2) - (h2 + 0.5 * u2**2)
+    return {"mass": mass, "momentum": momentum, "energy": energy}
+
+
+def normal_shock_relations(M1: float, gamma: float = 1.4) -> dict[str, float]:
+    """Ideal-gas normal shock relations as a function of upstream Mach number.
+
+    Solving the Rankine-Hugoniot conditions
+    (:func:`rankine_hugoniot_jump_conditions`) for an ideal gas gives the
+    downstream state entirely in terms of the upstream Mach number
+    :math:`M_1 = u_1/c_1`:
+
+    .. math::
+
+        \\frac{p_2}{p_1} = 1 + \\frac{2\\gamma}{\\gamma+1}(M_1^2-1), \\qquad
+        \\frac{\\rho_2}{\\rho_1} = \\frac{(\\gamma+1)M_1^2}{(\\gamma-1)M_1^2+2}, \\qquad
+        M_2^2 = \\frac{1+\\tfrac{\\gamma-1}{2}M_1^2}{\\gamma M_1^2-\\tfrac{\\gamma-1}{2}}.
+
+    Only :math:`M_1 \\geq 1` gives a physically admissible (entropy-increasing)
+    shock; a supersonic upstream flow needs a mechanism, such as this jump,
+    to return to subsonic downstream, and no analogous jump exists in reverse.
+
+    Parameters
+    ----------
+    M1 : float
+        Upstream Mach number; must be at least 1.
+    gamma : float, default 1.4
+        Ratio of specific heats (1.4 for a diatomic ideal gas, e.g. air).
+
+    Returns
+    -------
+    dict
+        ``{"p2_p1": ..., "rho2_rho1": ..., "T2_T1": ..., "M2": ...}``.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `M1` is less than 1.
+
+    Examples
+    --------
+    >>> jump = normal_shock_relations(M1=1.0)
+    >>> [round(v, 6) for v in (jump["p2_p1"], jump["rho2_rho1"], jump["M2"])]
+    [1.0, 1.0, 1.0]
+    >>> jump = normal_shock_relations(M1=2.0)
+    >>> round(jump["p2_p1"], 3), round(jump["rho2_rho1"], 3), round(jump["M2"], 3)
+    (4.5, 2.667, 0.577)
+    """
+    if M1 < 1.0:
+        raise InvalidParameterError(f"M1 must be >= 1 for an admissible (entropy-increasing) shock, got {M1}")
+    p2_p1 = 1.0 + (2.0 * gamma / (gamma + 1.0)) * (M1**2 - 1.0)
+    rho2_rho1 = ((gamma + 1.0) * M1**2) / ((gamma - 1.0) * M1**2 + 2.0)
+    T2_T1 = p2_p1 / rho2_rho1
+    M2 = np.sqrt((1.0 + 0.5 * (gamma - 1.0) * M1**2) / (gamma * M1**2 - 0.5 * (gamma - 1.0)))
+    return {"p2_p1": float(p2_p1), "rho2_rho1": float(rho2_rho1), "T2_T1": float(T2_T1), "M2": float(M2)}
+
+
+@njit(cache=True)
+def _euler_flux(U: NDArray[np.float64], gamma: float) -> NDArray[np.float64]:
+    """Physical flux of the 1D Euler equations in conservative variables.
+
+    Parameters
+    ----------
+    U : ndarray of float, shape (3,)
+        Conservative state ``(rho, rho*u, E)``.
+    gamma : float
+        Ratio of specific heats.
+
+    Returns
+    -------
+    ndarray of float, shape (3,)
+        Flux ``(rho*u, rho*u^2 + p, u*(E + p))``.
+    """
+    rho, mom, E = U[0], U[1], U[2]
+    u = mom / rho
+    p = (gamma - 1.0) * (E - 0.5 * rho * u * u)
+    flux = np.empty(3)
+    flux[0] = mom
+    flux[1] = mom * u + p
+    flux[2] = u * (E + p)
+    return flux
+
+
+@njit(cache=True)
+def _lax_friedrichs_evolve(U0: NDArray[np.float64], dx: float, dt: float, gamma: float, steps: int) -> NDArray[np.float64]:
+    """Evolve the 1D Euler equations with the Lax-Friedrichs finite-volume scheme.
+
+    Parameters
+    ----------
+    U0 : ndarray of float, shape (nx, 3)
+        Initial conservative state at each cell.
+    dx : float
+        Cell width.
+    dt : float
+        Time step (assumed to already satisfy the CFL condition).
+    gamma : float
+        Ratio of specific heats.
+    steps : int
+        Number of time steps to advance.
+
+    Returns
+    -------
+    ndarray of float, shape (nx, 3)
+        Conservative state after `steps` steps. The two boundary cells are
+        held fixed at their initial (far-field) values, approximating an
+        open/transmissive boundary over the short times these simulations run.
+    """
+    nx = U0.shape[0]
+    U = U0.copy()
+    lam = dt / dx
+    for _ in range(steps):
+        U_new = U.copy()
+        for i in range(1, nx - 1):
+            fL = _euler_flux(U[i - 1], gamma)
+            fR = _euler_flux(U[i + 1], gamma)
+            U_new[i] = 0.5 * (U[i - 1] + U[i + 1]) - 0.5 * lam * (fR - fL)
+        U = U_new
+    return U
+
+
+def sod_shock_tube(nx: int = 400, x0: float = 0.5, t_final: float = 0.2, gamma: float = 1.4, cfl: float = 0.5) -> dict[str, NDArray[np.float64]]:
+    """Solve the classic Sod shock-tube problem with a Lax-Friedrichs finite-volume scheme.
+
+    The Sod (1978) problem is the standard test Riemann problem for a
+    compressible-flow solver: a diaphragm at `x0` initially separates high
+    pressure/density gas (left, at rest) from low pressure/density gas
+    (right, at rest); removing the diaphragm at :math:`t=0` produces, for
+    :math:`t>0`, exactly three simple waves fanning out from `x0` -- a
+    left-running rarefaction (expansion) fan, a right-running contact
+    discontinuity (a density jump with continuous pressure and velocity),
+    and a right-running shock satisfying
+    :func:`rankine_hugoniot_jump_conditions` -- against which any
+    finite-volume scheme's numerical diffusion and shock-capturing behavior
+    can be judged. The domain is ``[0, 1]``; the classic Sod initial
+    condition is ``(rho, u, p) = (1, 0, 1)`` for ``x < x0`` and
+    ``(0.125, 0, 0.1)`` for ``x >= x0``.
+
+    Parameters
+    ----------
+    nx : int, default 400
+        Number of finite-volume cells.
+    x0 : float, default 0.5
+        Initial diaphragm location.
+    t_final : float, default 0.2
+        Time to integrate to.
+    gamma : float, default 1.4
+        Ratio of specific heats.
+    cfl : float, default 0.5
+        Courant number; the time step is chosen adaptively each macro-chunk
+        of the integration as ``cfl * dx / max(|u| + c)``, and must satisfy
+        ``0 < cfl <= 1`` for the explicit scheme to be stable.
+
+    Returns
+    -------
+    dict
+        ``{"x": ..., "rho": ..., "u": ..., "p": ...}`` at `t_final`, each an
+        array of length `nx`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `nx` is smaller than 4, `t_final` is not positive, or `cfl` is
+        not in ``(0, 1]``.
+
+    Examples
+    --------
+    >>> result = sod_shock_tube(nx=200, t_final=0.15)
+    >>> result["rho"].shape
+    (200,)
+    >>> bool(result["rho"][0] > result["rho"][-1] > 0)  # left state denser than right
+    True
+    """
+    if nx < 4:
+        raise InvalidParameterError(f"nx must be at least 4, got {nx}")
+    if t_final <= 0:
+        raise InvalidParameterError(f"t_final must be positive, got {t_final}")
+    if not 0.0 < cfl <= 1.0:
+        raise InvalidParameterError(f"cfl must be in (0, 1], got {cfl}")
+
+    dx = 1.0 / nx
+    x = (np.arange(nx) + 0.5) * dx
+    rho = np.where(x < x0, 1.0, 0.125)
+    u = np.zeros(nx)
+    p = np.where(x < x0, 1.0, 0.1)
+
+    U = np.empty((nx, 3))
+    U[:, 0] = rho
+    U[:, 1] = rho * u
+    U[:, 2] = p / (gamma - 1.0) + 0.5 * rho * u**2
+
+    t = 0.0
+    while t < t_final:
+        rho_now = U[:, 0]
+        u_now = U[:, 1] / rho_now
+        p_now = (gamma - 1.0) * (U[:, 2] - 0.5 * rho_now * u_now**2)
+        c_now = np.sqrt(gamma * p_now / rho_now)
+        dt = cfl * dx / np.max(np.abs(u_now) + c_now)
+        dt = min(dt, t_final - t)
+        chunk_steps = 1
+        U = _lax_friedrichs_evolve(U, dx, dt, gamma, chunk_steps)
+        t += dt
+
+    rho = U[:, 0]
+    u = U[:, 1] / rho
+    p = (gamma - 1.0) * (U[:, 2] - 0.5 * rho * u**2)
+    return {"x": x, "rho": rho, "u": u, "p": p}

physicskit/fluids/systems/instabilities.py

@@ -0,0 +1,343 @@
+"""Shear and buoyancy-driven instabilities: Kelvin-Helmholtz and Rayleigh-Taylor.
+
+Both instabilities turn a smooth base state (a shear layer, a stratified
+interface) into vigorous mixing given only an infinitesimal perturbation --
+the base state is *linearly unstable*, not just occasionally disturbed into
+instability. This module pairs each initial condition with the linear
+growth-rate law that predicts how fast its seeding ripple should grow, and
+with a full nonlinear simulation (built on
+:mod:`physicskit.fluids.systems.navier_stokes`) that grows it well past the
+point where the linear theory stops applying, into the rolled-up vortices
+(Kelvin-Helmholtz) or mushroom-shaped plumes (Rayleigh-Taylor) these
+instabilities are named for.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from physicskit.fluids.core.timestepping import integrate_boussinesq, integrate_vorticity_streamfunction
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = [
+    "kelvin_helmholtz_ic",
+    "kelvin_helmholtz_growth_rate",
+    "simulate_kelvin_helmholtz",
+    "rayleigh_taylor_ic",
+    "rayleigh_taylor_growth_rate",
+    "simulate_rayleigh_taylor",
+]
+
+
+def kelvin_helmholtz_ic(n: int, length: float, shear_width: float = 0.1, perturbation_amplitude: float = 0.05) -> NDArray[np.float64]:
+    """Vorticity initial condition for the Kelvin-Helmholtz shear-layer instability.
+
+    A thin vortex sheet at mid-domain, with a small sinusoidal ripple that
+    seeds the instability: under
+    :class:`physicskit.fluids.systems.navier_stokes.NavierStokes2D`, the
+    ripple's amplitude grows -- initially at the rate predicted by
+    :func:`kelvin_helmholtz_growth_rate` -- as the shear layer rolls up into
+    a row of discrete "cat's eye" vortices.
+
+    Parameters
+    ----------
+    n : int
+        Number of grid points along each axis.
+    length : float
+        Physical domain size.
+    shear_width : float, default 0.1
+        Thickness of the vortex sheet.
+    perturbation_amplitude : float, default 0.05
+        Amplitude of the seeding sinusoidal ripple.
+
+    Returns
+    -------
+    ndarray of float, shape (n, n)
+        Vorticity field.
+
+    Examples
+    --------
+    >>> omega0 = kelvin_helmholtz_ic(64, 2 * 3.141592653589793)
+    >>> omega0.shape
+    (64, 64)
+    >>> bool(omega0.max() > 0)
+    True
+    """
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    y0 = length / 2
+    base = (1.0 / shear_width) / np.cosh((Y - y0) / shear_width) ** 2
+    ripple = perturbation_amplitude * np.sin(2 * np.pi * X / length) * np.exp(-(((Y - y0) / (length / 4)) ** 2))
+    return base + ripple
+
+
+def kelvin_helmholtz_growth_rate(k: float, delta_u: float) -> float:
+    """Inviscid linear growth rate of a Kelvin-Helmholtz-unstable vortex sheet.
+
+    For a vortex sheet (an infinitesimally thin shear layer with a velocity
+    jump `delta_u` across it), linear stability analysis of the Euler
+    equations gives a perturbation of wavenumber `k` growing as
+    :math:`e^{\\sigma t}` with
+
+    .. math::
+
+        \\sigma(k) = \\frac{k\\,\\Delta u}{2},
+
+    unstable at *every* wavenumber with no threshold velocity -- unlike,
+    say, the Rayleigh-Taylor instability below, which is stabilized at short
+    wavelength by surface tension or diffusion. A shear layer of finite
+    thickness `shear_width` (as built by :func:`kelvin_helmholtz_ic`)
+    instead has a fastest-growing wavelength comparable to the layer
+    thickness, with growth cut off entirely for :math:`k\\,(\\text{shear
+    width})` large (Michalke, 1964); this vortex-sheet limit is the
+    thin-layer, small-``k`` approximation to that fuller theory, and is what
+    the shear-layer roll-up in :func:`kelvin_helmholtz_ic` grows at
+    initially, before finite-thickness and nonlinear effects take over.
+
+    Parameters
+    ----------
+    k : float
+        Perturbation wavenumber (angular, :math:`2\\pi/\\lambda`).
+    delta_u : float
+        Velocity jump across the shear layer.
+
+    Returns
+    -------
+    float
+        Growth rate :math:`\\sigma`, in units of inverse time.
+
+    Examples
+    --------
+    >>> round(kelvin_helmholtz_growth_rate(k=1.0, delta_u=2.0), 6)
+    1.0
+    """
+    return 0.5 * k * delta_u
+
+
+def simulate_kelvin_helmholtz(omega0: NDArray[np.float64], nu: float, dt: float, steps: int, length: float) -> dict[str, NDArray[np.float64]]:
+    """Time-step the 2D incompressible Kelvin-Helmholtz shear layer with RK4.
+
+    A thin wrapper around
+    :func:`physicskit.fluids.core.timestepping.integrate_vorticity_streamfunction`
+    -- the same pseudo-spectral vorticity-streamfunction Navier-Stokes
+    engine :func:`simulate_rayleigh_taylor` builds its Boussinesq extension
+    on -- evolving :func:`kelvin_helmholtz_ic` through the roll-up of its
+    seeded ripple into the characteristic "cat's-eye" vortex row, well past
+    the point :func:`kelvin_helmholtz_growth_rate`'s linear-theory
+    exponential growth stops applying.
+
+    Parameters
+    ----------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field, as from :func:`kelvin_helmholtz_ic`.
+    nu : float
+        Kinematic viscosity; must be positive.
+    dt : float
+        Time step.
+    steps : int
+        Number of RK4 steps to advance.
+    length : float
+        Physical domain size.
+
+    Returns
+    -------
+    dict
+        ``{"omega": ..., "psi": ..., "u": ..., "v": ...}`` at the final time.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `nu` is not positive.
+
+    See Also
+    --------
+    kelvin_helmholtz_ic : Builds the initial condition consumed here.
+    kelvin_helmholtz_growth_rate : The linear-theory prediction this simulation exceeds nonlinearly.
+    simulate_rayleigh_taylor : The companion buoyancy-driven instability, built on the same engine.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> n, length = 96, 2 * np.pi
+    >>> omega0 = kelvin_helmholtz_ic(n, length, shear_width=0.1, perturbation_amplitude=0.05)
+    >>> result = simulate_kelvin_helmholtz(omega0, nu=0.001, dt=0.0025, steps=50, length=length)
+    >>> result["omega"].shape
+    (96, 96)
+    """
+    if nu <= 0:
+        raise InvalidParameterError(f"nu (kinematic viscosity) must be positive, got {nu}")
+    return integrate_vorticity_streamfunction(omega0, nu, dt, steps, length)
+
+
+def rayleigh_taylor_ic(
+    n: int, length: float, atwood_number: float, perturbation_amplitude: float = 0.02, interface_position: float | None = None
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Vorticity and buoyancy initial condition for the Rayleigh-Taylor instability.
+
+    A denser fluid layer sits atop a lighter one (heavy-on-top is exactly
+    the unstable arrangement), separated by an interface at mid-domain with
+    a small sinusoidal ripple, evolved through
+    :func:`simulate_rayleigh_taylor`. Vorticity starts at exactly zero: in
+    the Boussinesq system, all vorticity generation comes from the
+    baroclinic torque acting on the rippled density interface once gravity
+    is switched on (see :func:`physicskit.fluids.core.timestepping.buoyant_vorticity_rhs`).
+
+    Parameters
+    ----------
+    n : int
+        Number of grid points along each axis.
+    length : float
+        Physical domain size.
+    atwood_number : float
+        The Atwood number :math:`A=(\\rho_{heavy}-\\rho_{light})/(\\rho_{heavy}+\\rho_{light})`,
+        :math:`0 < A < 1`, setting the buoyancy jump across the interface.
+    perturbation_amplitude : float, default 0.02
+        Amplitude of the seeding sinusoidal ripple on the interface.
+    interface_position : float, optional
+        Vertical position of the unperturbed interface; defaults to
+        ``length / 2``.
+
+    Returns
+    -------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field (identically zero).
+    buoyancy0 : ndarray of float, shape (n, n)
+        Initial buoyancy field: :math:`+A` below the interface (light fluid),
+        :math:`-A` above it (heavy fluid), smoothed over one grid cell so the
+        spectral derivatives it feeds resolve without ringing.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `atwood_number` is not in ``(0, 1)``.
+
+    Examples
+    --------
+    >>> omega0, buoyancy0 = rayleigh_taylor_ic(64, 2 * 3.141592653589793, atwood_number=0.3)
+    >>> bool(np.all(omega0 == 0.0))
+    True
+    >>> bool(buoyancy0.max() > 0 > buoyancy0.min())
+    True
+    """
+    if not 0.0 < atwood_number < 1.0:
+        raise InvalidParameterError(f"atwood_number must be in (0, 1), got {atwood_number}")
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    y0 = length / 2 if interface_position is None else interface_position
+    smoothing = length / n
+    ripple = perturbation_amplitude * np.cos(2 * np.pi * X / length)
+    buoyancy0 = -atwood_number * np.tanh((Y - y0 - ripple) / smoothing)
+    omega0 = np.zeros_like(X)
+    return omega0, buoyancy0
+
+
+def rayleigh_taylor_growth_rate(k: float, atwood_number: float, g: float = 1.0) -> float:
+    """Linear growth rate of the Rayleigh-Taylor instability.
+
+    For two inviscid, semi-infinite fluid layers (heavy density
+    :math:`\\rho_2` on top of light density :math:`\\rho_1`, gravity `g`
+    pointing from the heavy into the light layer), a perturbation of
+    wavenumber `k` on the interface grows as :math:`e^{\\sigma t}` with
+
+    .. math::
+
+        \\sigma(k) = \\sqrt{A\\,g\\,k}, \\qquad
+        A = \\frac{\\rho_2-\\rho_1}{\\rho_2+\\rho_1}
+
+    (Rayleigh, 1883; Taylor, 1950), unstable at every wavenumber in the
+    idealized inviscid limit -- real fluids are cut off at short wavelength
+    by viscosity and surface tension, which :func:`simulate_rayleigh_taylor`
+    supplies dynamically via its buoyancy diffusivity.
+
+    Parameters
+    ----------
+    k : float
+        Perturbation wavenumber (angular, :math:`2\\pi/\\lambda`).
+    atwood_number : float
+        The Atwood number :math:`A`, :math:`0 < A < 1`.
+    g : float, default 1.0
+        Gravitational acceleration, pointing from the heavy layer into the light one.
+
+    Returns
+    -------
+    float
+        Growth rate :math:`\\sigma`, in units of inverse time.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `atwood_number` is not in ``(0, 1)`` or `k` is negative.
+
+    Examples
+    --------
+    >>> round(rayleigh_taylor_growth_rate(k=2.0, atwood_number=0.5, g=1.0), 6)
+    1.0
+    """
+    if not 0.0 < atwood_number < 1.0:
+        raise InvalidParameterError(f"atwood_number must be in (0, 1), got {atwood_number}")
+    if k < 0:
+        raise InvalidParameterError(f"k must be non-negative, got {k}")
+    return float(np.sqrt(atwood_number * g * k))
+
+
+def simulate_rayleigh_taylor(
+    omega0: NDArray[np.float64],
+    buoyancy0: NDArray[np.float64],
+    nu: float,
+    kappa: float,
+    g: float,
+    dt: float,
+    steps: int,
+    length: float,
+) -> dict[str, NDArray[np.float64]]:
+    """Time-step the Boussinesq Rayleigh-Taylor system with RK4.
+
+    Evolves the coupled vorticity-buoyancy equations of
+    :func:`physicskit.fluids.core.timestepping.buoyant_vorticity_rhs`
+    (scaled by the gravitational acceleration `g`) starting from
+    :func:`rayleigh_taylor_ic`, through the roll-up of the rippled interface
+    into the characteristic Rayleigh-Taylor mushroom plumes.
+
+    Parameters
+    ----------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field, as from :func:`rayleigh_taylor_ic`.
+    buoyancy0 : ndarray of float, shape (n, n)
+        Initial buoyancy field, as from :func:`rayleigh_taylor_ic`.
+    nu : float
+        Kinematic viscosity; must be positive.
+    kappa : float
+        Buoyancy (density) diffusivity; must be positive.
+    g : float
+        Gravitational acceleration; must be positive.
+    dt : float
+        Time step.
+    steps : int
+        Number of RK4 steps to advance.
+    length : float
+        Physical domain size.
+
+    Returns
+    -------
+    dict
+        ``{"omega": ..., "buoyancy": ..., "psi": ..., "u": ..., "v": ...}`` at
+        the final time.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `nu`, `kappa`, or `g` is not positive.
+
+    See Also
+    --------
+    rayleigh_taylor_ic : Builds the initial condition consumed here.
+    rayleigh_taylor_growth_rate : The linear-theory prediction this simulation exceeds nonlinearly.
+    """
+    if nu <= 0:
+        raise InvalidParameterError(f"nu (kinematic viscosity) must be positive, got {nu}")
+    if kappa <= 0:
+        raise InvalidParameterError(f"kappa (buoyancy diffusivity) must be positive, got {kappa}")
+    if g <= 0:
+        raise InvalidParameterError(f"g (gravitational acceleration) must be positive, got {g}")
+    return integrate_boussinesq(omega0, buoyancy0, nu, kappa, g, dt, steps, length)