physicskit 0.1.0__py3-none-any.whl

physicskit/fluids/core/grid.py

@@ -0,0 +1,165 @@
+"""Doubly-periodic pseudo-spectral grid and Poisson solve.
+
+The shared spatial machinery behind every grid-based solver in
+:mod:`physicskit.fluids`: a real-space/wavenumber grid pair on the doubly
+periodic domain ``[0, length) x [0, length)``, an exact spectral Poisson
+solve (used to recover a streamfunction from a vorticity field), and the
+spectral velocity recovery that follows from it. Because differentiation is
+exact multiplication by ``i*k`` in Fourier space, every derivative used here
+is exact up to machine precision and aliasing, with none of a finite
+difference's truncation error -- the standard reason pseudo-spectral methods
+are the tool of choice for smooth, periodic 2D flow.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = [
+    "spectral_grid",
+    "poisson_solve_streamfunction",
+    "velocity_from_streamfunction",
+    "vorticity_from_velocity",
+]
+
+
+def spectral_grid(n: int, length: float) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Build a doubly periodic real-space and wavenumber grid.
+
+    Parameters
+    ----------
+    n : int
+        Number of grid points along each axis. Must be at least 8, so that
+        the FFT-based derivatives resolve at least a few wavelengths of the
+        lowest nonzero mode.
+    length : float
+        Physical domain size (the domain is ``[0, length) x [0, length)``).
+
+    Returns
+    -------
+    X, Y : ndarray of float, shape (n, n)
+        Real-space coordinate grids.
+    KX, KY : ndarray of float, shape (n, n)
+        Wavenumber grids (angular, i.e. :math:`2\\pi/\\lambda` convention).
+    K2 : ndarray of float, shape (n, n)
+        :math:`K_X^2 + K_Y^2`, with the zero mode set to 1 to make Poisson
+        division safe (the zero mode of a vorticity field is always 0 for a
+        physical flow, so this entry is unused downstream).
+
+    Raises
+    ------
+    InvalidParameterError
+        If `n` is smaller than 8 or `length` is not positive.
+
+    Examples
+    --------
+    >>> X, Y, KX, KY, K2 = spectral_grid(64, 2 * 3.141592653589793)
+    >>> X.shape
+    (64, 64)
+    >>> bool(K2[0, 0] == 1.0)
+    True
+    """
+    if n < 8:
+        raise InvalidParameterError(f"n must be >= 8 for a usable doubly periodic spectral grid, got {n}")
+    if length <= 0:
+        raise InvalidParameterError(f"length must be positive, got {length}")
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    k = 2 * np.pi * np.fft.fftfreq(n, d=length / n)
+    KX, KY = np.meshgrid(k, k, indexing="ij")
+    K2 = KX**2 + KY**2
+    K2 = K2.copy()
+    K2[0, 0] = 1.0
+    return X, Y, KX, KY, K2
+
+
+def poisson_solve_streamfunction(omega: NDArray[np.float64], K2: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Solve :math:`\\nabla^2 \\psi = -\\omega` for the streamfunction via FFT.
+
+    Parameters
+    ----------
+    omega : ndarray of float, shape (n, n)
+        Vorticity field.
+    K2 : ndarray of float, shape (n, n)
+        Squared wavenumber grid from :func:`spectral_grid`.
+
+    Returns
+    -------
+    ndarray of float, shape (n, n)
+        Streamfunction :math:`\\psi`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> X, Y, KX, KY, K2 = spectral_grid(64, 2 * np.pi)
+    >>> omega = np.sin(X) * np.sin(Y)
+    >>> psi = poisson_solve_streamfunction(omega, K2)
+    >>> expected = 0.5 * np.sin(X) * np.sin(Y)
+    >>> bool(np.max(np.abs(psi - expected)) < 1e-10)
+    True
+    """
+    omega_hat = np.fft.fft2(omega)
+    psi_hat = omega_hat / K2
+    psi_hat[0, 0] = 0.0
+    return np.real(np.fft.ifft2(psi_hat))
+
+
+def velocity_from_streamfunction(psi: NDArray[np.float64], KX: NDArray[np.float64], KY: NDArray[np.float64]) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Recover the incompressible velocity field from a streamfunction.
+
+    Parameters
+    ----------
+    psi : ndarray of float, shape (n, n)
+        Streamfunction.
+    KX, KY : ndarray of float, shape (n, n)
+        Wavenumber grids from :func:`spectral_grid`.
+
+    Returns
+    -------
+    u, v : ndarray of float, shape (n, n)
+        Velocity components :math:`u=\\partial_y\\psi`, :math:`v=-\\partial_x\\psi`,
+        which satisfy :math:`\\nabla\\cdot\\mathbf{u}=0` identically.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> X, Y, KX, KY, K2 = spectral_grid(64, 2 * np.pi)
+    >>> psi = 0.5 * np.sin(X) * np.sin(Y)
+    >>> u, v = velocity_from_streamfunction(psi, KX, KY)
+    >>> curl = vorticity_from_velocity(u, v, KX, KY)
+    >>> bool(np.max(np.abs(curl - np.sin(X) * np.sin(Y))) < 1e-10)
+    True
+    """
+    psi_hat = np.fft.fft2(psi)
+    u = np.real(np.fft.ifft2(1j * KY * psi_hat))
+    v = np.real(np.fft.ifft2(-1j * KX * psi_hat))
+    return u, v
+
+
+def vorticity_from_velocity(u: NDArray[np.float64], v: NDArray[np.float64], KX: NDArray[np.float64], KY: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Compute the vorticity :math:`\\omega=\\partial_x v-\\partial_y u` spectrally.
+
+    The inverse of :func:`velocity_from_streamfunction` followed by a curl;
+    mainly useful for validating that a velocity field is consistent with
+    some streamfunction, or for measuring the vorticity of a field built
+    directly (e.g. by superposing elementary potential-flow solutions)
+    rather than evolved from one.
+
+    Parameters
+    ----------
+    u, v : ndarray of float, shape (n, n)
+        Velocity components.
+    KX, KY : ndarray of float, shape (n, n)
+        Wavenumber grids from :func:`spectral_grid`.
+
+    Returns
+    -------
+    ndarray of float, shape (n, n)
+        Vorticity field :math:`\\omega`.
+    """
+    u_hat = np.fft.fft2(u)
+    v_hat = np.fft.fft2(v)
+    return np.real(np.fft.ifft2(1j * KX * v_hat - 1j * KY * u_hat))

physicskit/fluids/core/timestepping.py

@@ -0,0 +1,231 @@
+"""Pseudo-spectral RK4 time-stepping for advection-diffusion transport on the spectral grid.
+
+The right-hand side of the vorticity-transport equation involves an FFT at
+every evaluation (to invert the Laplacian for the streamfunction, and to
+differentiate the advected field), so -- unlike
+:mod:`physicskit.chaos.core.integrators` -- these steppers are plain NumPy
+rather than Numba ``@njit`` functions: Numba's ``nopython`` mode does not
+support ``numpy.fft``. What *is* shared and reused here is the algorithm:
+one classical 4th-order Runge-Kutta step applied to the pseudo-spectrally
+evaluated right-hand side, exactly as :mod:`physicskit.chaos.core.integrators`
+does with its Numba-jitted right-hand sides.
+
+:func:`vorticity_rhs` and :func:`integrate_vorticity_streamfunction` are the
+single-field (pure vorticity-transport) engine reused, unmodified, by
+:mod:`physicskit.fluids.systems.navier_stokes` as the package's
+general-purpose incompressible-flow workhorse, and in turn by
+:mod:`physicskit.fluids.systems.instabilities` to grow a Kelvin-Helmholtz
+shear layer. :func:`buoyant_vorticity_rhs` and
+:func:`integrate_boussinesq` extend the same scheme with a passively
+advected buoyancy (density) field and its baroclinic torque on vorticity --
+the minimal addition needed to grow a Rayleigh-Taylor instability, which
+requires two fluid layers of different density and therefore cannot be
+represented by vorticity alone.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from physicskit.fluids.core.grid import poisson_solve_streamfunction, spectral_grid, velocity_from_streamfunction
+
+__all__ = [
+    "vorticity_rhs",
+    "integrate_vorticity_streamfunction",
+    "buoyant_vorticity_rhs",
+    "integrate_boussinesq",
+]
+
+
+def vorticity_rhs(
+    omega: NDArray[np.float64],
+    KX: NDArray[np.float64],
+    KY: NDArray[np.float64],
+    K2: NDArray[np.float64],
+    nu: float,
+) -> NDArray[np.float64]:
+    """Right-hand side of the vorticity transport equation, evaluated pseudo-spectrally.
+
+    Parameters
+    ----------
+    omega : ndarray of float, shape (n, n)
+        Vorticity field.
+    KX, KY, K2 : ndarray of float, shape (n, n)
+        Wavenumber grids from :func:`physicskit.fluids.core.grid.spectral_grid`.
+    nu : float
+        Kinematic viscosity.
+
+    Returns
+    -------
+    ndarray of float, shape (n, n)
+        :math:`-(\\mathbf{u}\\cdot\\nabla)\\omega + \\nu\\nabla^2\\omega`.
+    """
+    psi = poisson_solve_streamfunction(omega, K2)
+    u, v = velocity_from_streamfunction(psi, KX, KY)
+    omega_hat = np.fft.fft2(omega)
+    domega_dx = np.real(np.fft.ifft2(1j * KX * omega_hat))
+    domega_dy = np.real(np.fft.ifft2(1j * KY * omega_hat))
+    advection = -(u * domega_dx + v * domega_dy)
+    diffusion = np.real(np.fft.ifft2(-nu * K2 * omega_hat))
+    return advection + diffusion
+
+
+def integrate_vorticity_streamfunction(omega0: NDArray[np.float64], nu: float, dt: float, steps: int, length: float) -> dict[str, NDArray[np.float64]]:
+    """Time-step the 2D incompressible vorticity-streamfunction equations with RK4.
+
+    Parameters
+    ----------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field on a doubly periodic ``[0, length)^2`` domain.
+    nu : float
+        Kinematic viscosity.
+    dt : float
+        Time step.
+    steps : int
+        Number of RK4 steps to advance.
+    length : float
+        Physical domain size.
+
+    Returns
+    -------
+    dict
+        ``{"omega": final vorticity, "psi": final streamfunction, "u": ..., "v": ...}``.
+
+    See Also
+    --------
+    physicskit.fluids.systems.navier_stokes.NavierStokes2D : Validated, documented wrapper.
+    """
+    n = omega0.shape[0]
+    _, _, KX, KY, K2 = spectral_grid(n, length)
+    omega = np.array(omega0, dtype=float, copy=True)
+    for _ in range(steps):
+        k1 = vorticity_rhs(omega, KX, KY, K2, nu)
+        k2 = vorticity_rhs(omega + dt / 2 * k1, KX, KY, K2, nu)
+        k3 = vorticity_rhs(omega + dt / 2 * k2, KX, KY, K2, nu)
+        k4 = vorticity_rhs(omega + dt * k3, KX, KY, K2, nu)
+        omega = omega + dt / 6 * (k1 + 2 * k2 + 2 * k3 + k4)
+    psi = poisson_solve_streamfunction(omega, K2)
+    u, v = velocity_from_streamfunction(psi, KX, KY)
+    return {"omega": omega, "psi": psi, "u": u, "v": v}
+
+
+def buoyant_vorticity_rhs(
+    omega: NDArray[np.float64],
+    buoyancy: NDArray[np.float64],
+    KX: NDArray[np.float64],
+    KY: NDArray[np.float64],
+    K2: NDArray[np.float64],
+    nu: float,
+    kappa: float,
+    g: float,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Right-hand side of the Boussinesq vorticity-buoyancy system.
+
+    Extends :func:`vorticity_rhs` with a passively advected-and-diffused
+    dimensionless buoyancy field :math:`b = -\\delta\\rho/\\rho_0` (positive
+    `b` means locally lighter than the reference density) and its
+    baroclinic torque on vorticity, :math:`g\\,\\partial_x b`, which is
+    exactly the term through which a horizontal density gradient generates
+    vorticity under gravity -- the mechanism behind the Rayleigh-Taylor
+    instability.
+
+    .. math::
+
+        \\partial_t \\omega + (\\mathbf{u}\\cdot\\nabla)\\omega
+            = \\nu \\nabla^2 \\omega + g\\,\\partial_x b \\\\
+        \\partial_t b + (\\mathbf{u}\\cdot\\nabla) b = \\kappa \\nabla^2 b
+
+    Parameters
+    ----------
+    omega : ndarray of float, shape (n, n)
+        Vorticity field.
+    buoyancy : ndarray of float, shape (n, n)
+        Dimensionless buoyancy field :math:`b`.
+    KX, KY, K2 : ndarray of float, shape (n, n)
+        Wavenumber grids from :func:`physicskit.fluids.core.grid.spectral_grid`.
+    nu : float
+        Kinematic viscosity (vorticity diffusivity).
+    kappa : float
+        Molecular (or eddy) diffusivity of the buoyancy field.
+    g : float
+        Gravitational acceleration, pointing from ``+y`` toward ``-y``.
+
+    Returns
+    -------
+    domega_dt, dbuoyancy_dt : ndarray of float, shape (n, n)
+        Time derivatives of vorticity and buoyancy.
+    """
+    psi = poisson_solve_streamfunction(omega, K2)
+    u, v = velocity_from_streamfunction(psi, KX, KY)
+
+    omega_hat = np.fft.fft2(omega)
+    domega_dx = np.real(np.fft.ifft2(1j * KX * omega_hat))
+    domega_dy = np.real(np.fft.ifft2(1j * KY * omega_hat))
+    diffusion_omega = np.real(np.fft.ifft2(-nu * K2 * omega_hat))
+
+    b_hat = np.fft.fft2(buoyancy)
+    db_dx = np.real(np.fft.ifft2(1j * KX * b_hat))
+    db_dy = np.real(np.fft.ifft2(1j * KY * b_hat))
+    diffusion_b = np.real(np.fft.ifft2(-kappa * K2 * b_hat))
+
+    domega_dt = -(u * domega_dx + v * domega_dy) + diffusion_omega + g * db_dx
+    dbuoyancy_dt = -(u * db_dx + v * db_dy) + diffusion_b
+    return domega_dt, dbuoyancy_dt
+
+
+def integrate_boussinesq(
+    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 coupled Boussinesq vorticity-buoyancy equations with RK4.
+
+    Parameters
+    ----------
+    omega0 : ndarray of float, shape (n, n)
+        Initial vorticity field on a doubly periodic ``[0, length)^2`` domain.
+    buoyancy0 : ndarray of float, shape (n, n)
+        Initial buoyancy field.
+    nu : float
+        Kinematic viscosity.
+    kappa : float
+        Buoyancy diffusivity.
+    g : float
+        Gravitational acceleration.
+    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.
+
+    See Also
+    --------
+    physicskit.fluids.systems.instabilities.simulate_rayleigh_taylor : Validated, documented wrapper.
+    """
+    n = omega0.shape[0]
+    _, _, KX, KY, K2 = spectral_grid(n, length)
+    omega = np.array(omega0, dtype=float, copy=True)
+    buoyancy = np.array(buoyancy0, dtype=float, copy=True)
+    for _ in range(steps):
+        k1o, k1b = buoyant_vorticity_rhs(omega, buoyancy, KX, KY, K2, nu, kappa, g)
+        k2o, k2b = buoyant_vorticity_rhs(omega + dt / 2 * k1o, buoyancy + dt / 2 * k1b, KX, KY, K2, nu, kappa, g)
+        k3o, k3b = buoyant_vorticity_rhs(omega + dt / 2 * k2o, buoyancy + dt / 2 * k2b, KX, KY, K2, nu, kappa, g)
+        k4o, k4b = buoyant_vorticity_rhs(omega + dt * k3o, buoyancy + dt * k3b, KX, KY, K2, nu, kappa, g)
+        omega = omega + dt / 6 * (k1o + 2 * k2o + 2 * k3o + k4o)
+        buoyancy = buoyancy + dt / 6 * (k1b + 2 * k2b + 2 * k3b + k4b)
+    psi = poisson_solve_streamfunction(omega, K2)
+    u, v = velocity_from_streamfunction(psi, KX, KY)
+    return {"omega": omega, "buoyancy": buoyancy, "psi": psi, "u": u, "v": v}

physicskit/fluids/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exception hierarchy for physicskit.fluids.
+
+All exceptions physicskit.fluids raises intentionally (as opposed to
+exceptions that bubble up unexpectedly from a dependency) inherit from
+:class:`FluidskitError`, so callers can catch "any physicskit.fluids-raised
+problem" with a single ``except FluidskitError``. Each concrete exception
+also inherits from the closest matching built-in exception type (e.g.
+:class:`InvalidParameterError` is also a :class:`ValueError`), so existing
+code that catches the built-in type continues to work unchanged.
+"""
+
+from __future__ import annotations
+
+
+class FluidskitError(Exception):
+    """Base class for all exceptions raised intentionally by physicskit.fluids."""
+
+
+class InvalidParameterError(FluidskitError, ValueError):
+    """A system or tool was constructed or called with a physically invalid parameter.
+
+    Examples include a non-positive Reynolds number or viscosity, a grid
+    size incompatible with the doubly-periodic pseudo-spectral method's FFT
+    assumptions, a cylinder radius too large to fit its sampling grid, or an
+    explicit time step that violates a CFL/Courant stability bound.
+    """

physicskit/fluids/systems/__init__.py

@@ -0,0 +1,70 @@
+from physicskit.fluids.systems.compressible_flow import (
+    normal_shock_relations,
+    rankine_hugoniot_jump_conditions,
+    sod_shock_tube,
+)
+from physicskit.fluids.systems.instabilities import (
+    kelvin_helmholtz_growth_rate,
+    kelvin_helmholtz_ic,
+    rayleigh_taylor_growth_rate,
+    rayleigh_taylor_ic,
+    simulate_rayleigh_taylor,
+)
+from physicskit.fluids.systems.navier_stokes import NavierStokes2D, simulate_vorticity_streamfunction
+from physicskit.fluids.systems.potential_flow import (
+    PotentialFlow,
+    doublet_potential,
+    flow_past_cylinder,
+    kutta_joukowski_lift,
+    point_vortex_potential,
+    pressure_coefficient,
+    source_potential,
+    uniform_flow_potential,
+)
+from physicskit.fluids.systems.viscous_flow import (
+    blasius_boundary_layer_thickness,
+    blasius_skin_friction_coefficient,
+    blasius_solve,
+    couette_flow_velocity,
+    poiseuille_flow_rate,
+    poiseuille_flow_velocity,
+    stokes_drag,
+)
+from physicskit.fluids.systems.vortex_dynamics import (
+    VON_KARMAN_SPACING_RATIO,
+    PointVortexSystem,
+    point_vortex_velocities,
+    von_karman_vortex_street,
+)
+
+__all__ = [
+    "VON_KARMAN_SPACING_RATIO",
+    "NavierStokes2D",
+    "PointVortexSystem",
+    "PotentialFlow",
+    "blasius_boundary_layer_thickness",
+    "blasius_skin_friction_coefficient",
+    "blasius_solve",
+    "couette_flow_velocity",
+    "doublet_potential",
+    "flow_past_cylinder",
+    "kelvin_helmholtz_growth_rate",
+    "kelvin_helmholtz_ic",
+    "kutta_joukowski_lift",
+    "normal_shock_relations",
+    "point_vortex_potential",
+    "point_vortex_velocities",
+    "poiseuille_flow_rate",
+    "poiseuille_flow_velocity",
+    "pressure_coefficient",
+    "rankine_hugoniot_jump_conditions",
+    "rayleigh_taylor_growth_rate",
+    "rayleigh_taylor_ic",
+    "simulate_rayleigh_taylor",
+    "simulate_vorticity_streamfunction",
+    "sod_shock_tube",
+    "source_potential",
+    "stokes_drag",
+    "uniform_flow_potential",
+    "von_karman_vortex_street",
+]