physicskit 0.1.0__py3-none-any.whl

physicskit/fluids/systems/vortex_dynamics.py

@@ -0,0 +1,304 @@
+"""Point-vortex N-body dynamics: the Biot-Savart law and the von Karman vortex street.
+
+Concentrating all of a 2D flow's vorticity into a finite set of
+infinitesimal points turns the vorticity-transport PDE into a system of
+ordinary differential equations: each point vortex simply advects with the
+velocity field induced by every *other* point vortex (a vortex induces no
+velocity on itself), via the 2D Biot-Savart law. This is an exact solution
+of the incompressible Euler equations for a singular vorticity distribution,
+not merely a discretization of the continuous vorticity-transport equation
+solved by :mod:`physicskit.fluids.systems.navier_stokes` -- and it is the
+setting in which Theodore von Karman analyzed the staggered, alternating
+vortex street shed behind a bluff body.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+from numpy.typing import ArrayLike, NDArray
+
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = [
+    "point_vortex_velocities",
+    "PointVortexSystem",
+    "von_karman_vortex_street",
+    "VON_KARMAN_SPACING_RATIO",
+]
+
+#: Theodore von Karman's spacing ratio ``h/l`` (row separation over
+#: along-row spacing) at which a doubly-infinite staggered vortex row is
+#: linearly stable to vortex-row perturbations (von Karman & Rubach, 1912).
+VON_KARMAN_SPACING_RATIO: float = 0.2805
+
+
+@njit(cache=True)
+def _point_vortex_velocities(positions: NDArray[np.float64], circulations: NDArray[np.float64], core: float) -> NDArray[np.float64]:
+    """Biot-Savart velocity induced on each point vortex by every other one.
+
+    Parameters
+    ----------
+    positions : ndarray of float, shape (n, 2)
+        Vortex positions ``(x, y)``.
+    circulations : ndarray of float, shape (n,)
+        Vortex circulations :math:`\\Gamma_i`.
+    core : float
+        Regularization (Rankine core) radius; keeps the induced velocity
+        finite if two vortices coincide.
+
+    Returns
+    -------
+    ndarray of float, shape (n, 2)
+        Velocity at each vortex's own position.
+    """
+    n = positions.shape[0]
+    velocities = np.zeros((n, 2))
+    core2 = core * core
+    for i in range(n):
+        vx, vy = 0.0, 0.0
+        xi, yi = positions[i, 0], positions[i, 1]
+        for j in range(n):
+            if i == j:
+                continue
+            dx = xi - positions[j, 0]
+            dy = yi - positions[j, 1]
+            r2 = dx * dx + dy * dy + core2
+            factor = circulations[j] / (2.0 * np.pi * r2)
+            vx -= factor * dy
+            vy += factor * dx
+        velocities[i, 0] = vx
+        velocities[i, 1] = vy
+    return velocities
+
+
+@njit(cache=True)
+def _point_vortex_rk4_integrate(
+    positions0: NDArray[np.float64], circulations: NDArray[np.float64], core: float, dt: float, n_steps: int
+) -> NDArray[np.float64]:
+    """Integrate the point-vortex system with RK4.
+
+    Parameters
+    ----------
+    positions0 : ndarray of float, shape (n, 2)
+        Initial vortex positions.
+    circulations : ndarray of float, shape (n,)
+        Vortex circulations.
+    core : float
+        Regularization core radius.
+    dt : float
+        Time step.
+    n_steps : int
+        Number of steps to advance.
+
+    Returns
+    -------
+    ndarray of float, shape (n_steps + 1, n, 2)
+        Vortex positions at each step, including the initial positions.
+    """
+    n = positions0.shape[0]
+    trajectory = np.empty((n_steps + 1, n, 2))
+    trajectory[0] = positions0
+    positions = positions0.copy()
+    for step in range(n_steps):
+        k1 = _point_vortex_velocities(positions, circulations, core)
+        k2 = _point_vortex_velocities(positions + 0.5 * dt * k1, circulations, core)
+        k3 = _point_vortex_velocities(positions + 0.5 * dt * k2, circulations, core)
+        k4 = _point_vortex_velocities(positions + dt * k3, circulations, core)
+        positions = positions + (dt / 6.0) * (k1 + 2.0 * k2 + 2.0 * k3 + k4)
+        trajectory[step + 1] = positions
+    return trajectory
+
+
+def point_vortex_velocities(positions: ArrayLike, circulations: ArrayLike, core: float = 1e-6) -> NDArray[np.float64]:
+    """Velocity induced on each point vortex by every other vortex (Biot-Savart law).
+
+    The 2D Biot-Savart law: an isolated point vortex of circulation
+    :math:`\\Gamma_j` at :math:`\\mathbf{r}_j` induces a purely azimuthal
+    velocity :math:`\\Gamma_j/(2\\pi r)` at distance `r`, and a system of `n`
+    vortices simply superposes these fields (Laplace's equation is linear,
+    just as in :mod:`physicskit.fluids.systems.potential_flow` -- indeed a
+    point vortex here *is* :func:`~physicskit.fluids.systems.potential_flow.point_vortex_potential`,
+    evaluated at every other vortex's location rather than on a field grid).
+
+    Parameters
+    ----------
+    positions : array_like of float, shape (n, 2)
+        Vortex positions ``(x, y)``.
+    circulations : array_like of float, shape (n,)
+        Vortex circulations :math:`\\Gamma_i` (positive counterclockwise).
+    core : float, default 1e-6
+        Regularization (Rankine core) radius, keeping the induced velocity
+        finite if two vortex cores coincide; negligible for any pair
+        separated by much more than `core`.
+
+    Returns
+    -------
+    ndarray of float, shape (n, 2)
+        Velocity at each vortex's own position, induced by all the others.
+
+    Examples
+    --------
+    A pair of counter-rotating vortices separated by distance `d` induces
+    equal and opposite velocities of magnitude :math:`\\Gamma/(2\\pi d)` on
+    each other, translating the pair sideways rather than rotating it:
+
+    >>> import numpy as np
+    >>> Gamma, d = 1.0, 2.0
+    >>> positions = np.array([[0.0, d / 2], [0.0, -d / 2]])
+    >>> circulations = np.array([Gamma, -Gamma])
+    >>> vel = point_vortex_velocities(positions, circulations)
+    >>> bool(np.allclose(vel[0], vel[1]))  # both translate together
+    True
+    >>> round(float(vel[0, 0]), 6) == round(Gamma / (2 * np.pi * d), 6)
+    True
+    """
+    positions = np.asarray(positions, dtype=np.float64)
+    circulations = np.asarray(circulations, dtype=np.float64)
+    if positions.shape[0] != circulations.shape[0]:
+        raise InvalidParameterError("positions and circulations must have the same number of vortices")
+    return _point_vortex_velocities(positions, circulations, core)
+
+
+class PointVortexSystem:
+    """A system of interacting 2D point vortices, advected by their mutual Biot-Savart field.
+
+    Parameters
+    ----------
+    positions : array_like of float, shape (n, 2)
+        Initial vortex positions ``(x, y)``.
+    circulations : array_like of float, shape (n,)
+        Vortex circulations :math:`\\Gamma_i`; fixed for the system's lifetime
+        (point vortices carry their circulation with them unchanged).
+    core : float, default 1e-6
+        Regularization core radius (see :func:`point_vortex_velocities`).
+
+    Attributes
+    ----------
+    positions : ndarray of float, shape (n, 2)
+        Current vortex positions.
+    circulations : ndarray of float, shape (n,)
+        Vortex circulations.
+    core : float
+        Regularization core radius.
+    n_vortices : int
+        Number of vortices, `n`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `positions` and `circulations` have inconsistent lengths.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> system = PointVortexSystem(positions=[[1.0, 0.0], [-1.0, 0.0]], circulations=[1.0, 1.0])
+    >>> t, trajectory = system.trajectory(dt=0.01, n_steps=10)
+    >>> trajectory.shape
+    (11, 2, 2)
+    """
+
+    def __init__(self, positions: ArrayLike, circulations: ArrayLike, core: float = 1e-6):
+        positions = np.asarray(positions, dtype=np.float64)
+        circulations = np.asarray(circulations, dtype=np.float64)
+        if positions.shape[0] != circulations.shape[0]:
+            raise InvalidParameterError("positions and circulations must have the same number of vortices")
+        self.positions = positions
+        self.circulations = circulations
+        self.core = float(core)
+        self.n_vortices = positions.shape[0]
+
+    def velocities(self) -> NDArray[np.float64]:
+        """Velocity currently induced on each vortex.
+
+        Returns
+        -------
+        ndarray of float, shape (n, 2)
+        """
+        return _point_vortex_velocities(self.positions, self.circulations, self.core)
+
+    def trajectory(self, dt: float = 0.01, n_steps: int = 1000) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+        """Integrate the vortex trajectories forward with RK4.
+
+        Parameters
+        ----------
+        dt : float, default 0.01
+            Time step.
+        n_steps : int, default 1000
+            Number of steps to advance.
+
+        Returns
+        -------
+        times : ndarray of float, shape (n_steps + 1,)
+        positions : ndarray of float, shape (n_steps + 1, n, 2)
+            Vortex positions at each step, including the current positions.
+        """
+        times = np.arange(n_steps + 1) * dt
+        trajectory = _point_vortex_rk4_integrate(self.positions, self.circulations, self.core, dt, n_steps)
+        return times, trajectory
+
+    def __repr__(self) -> str:
+        return f"PointVortexSystem(n_vortices={self.n_vortices}, circulations={self.circulations!r})"
+
+
+def von_karman_vortex_street(
+    n_pairs: int, spacing_l: float, spacing_ratio: float = VON_KARMAN_SPACING_RATIO
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Build a finite, doubly staggered von Karman vortex street.
+
+    Two parallel rows of point vortices, offset from each other by half the
+    along-row spacing `spacing_l` and by a row separation
+    ``h = spacing_ratio * spacing_l``, with alternating-sign circulation
+    within each row so that adjacent vortices across the two rows always
+    have *opposite* sign -- the staggered, alternating pattern observed in
+    the wake behind a bluff body. Von Karman showed that a doubly *infinite*
+    row of this form is linearly stable to vortex-row perturbations at
+    exactly one spacing ratio, :data:`VON_KARMAN_SPACING_RATIO`; any other
+    ratio (or any symmetric, unstaggered arrangement) grows unstable, which
+    is why the observed spacing behind real bluff bodies clusters so
+    consistently near this value.
+
+    Parameters
+    ----------
+    n_pairs : int
+        Number of vortex pairs (one from each row) to construct; must be at
+        least 2 to form a discernible street.
+    spacing_l : float
+        Spacing between same-row, same-sign vortices along the street.
+    spacing_ratio : float, default :data:`VON_KARMAN_SPACING_RATIO`
+        Row separation over along-row spacing, ``h / spacing_l``.
+
+    Returns
+    -------
+    positions : ndarray of float, shape (2*n_pairs, 2)
+        Vortex positions.
+    circulations : ndarray of float, shape (2*n_pairs,)
+        Vortex circulations, alternating in sign.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `n_pairs` is smaller than 2 or `spacing_l` is not positive.
+
+    Examples
+    --------
+    >>> positions, circulations = von_karman_vortex_street(n_pairs=6, spacing_l=1.0)
+    >>> positions.shape
+    (12, 2)
+    >>> bool(np.isclose(circulations.sum(), 0.0))  # equal and opposite in each row
+    True
+    """
+    if n_pairs < 2:
+        raise InvalidParameterError(f"n_pairs must be at least 2, got {n_pairs}")
+    if spacing_l <= 0:
+        raise InvalidParameterError(f"spacing_l must be positive, got {spacing_l}")
+    h = spacing_ratio * spacing_l
+    positions = np.empty((2 * n_pairs, 2))
+    circulations = np.empty(2 * n_pairs)
+    for i in range(n_pairs):
+        sign = 1.0 if i % 2 == 0 else -1.0
+        positions[2 * i] = [i * spacing_l, h / 2.0]
+        circulations[2 * i] = sign
+        positions[2 * i + 1] = [(i + 0.5) * spacing_l, -h / 2.0]
+        circulations[2 * i + 1] = -sign
+    return positions, circulations

physicskit/fluids/tests/conftest.py

@@ -0,0 +1,7 @@
+"""Test-session setup: force Matplotlib's non-interactive Agg backend
+before anything imports pyplot, so the suite (and CI, which has no
+display) can exercise the plotting/animation code headlessly."""
+
+import matplotlib
+
+matplotlib.use("Agg")

physicskit/fluids/tests/test_compressible_flow.py

@@ -0,0 +1,66 @@
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.systems.compressible_flow import (
+    normal_shock_relations,
+    rankine_hugoniot_jump_conditions,
+    sod_shock_tube,
+)
+
+
+def test_normal_shock_is_identity_at_mach_one():
+    jump = normal_shock_relations(M1=1.0)
+    assert jump["p2_p1"] == pytest.approx(1.0)
+    assert jump["rho2_rho1"] == pytest.approx(1.0)
+    assert jump["M2"] == pytest.approx(1.0)
+
+
+def test_normal_shock_downstream_mach_is_always_subsonic():
+    for M1 in (1.5, 2.0, 5.0, 10.0):
+        jump = normal_shock_relations(M1)
+        assert jump["M2"] < 1.0
+
+
+def test_normal_shock_satisfies_rankine_hugoniot_conditions():
+    gamma = 1.4
+    rho1, u1, p1 = 1.0, 3.0, 1.0 / gamma  # c1 = 1, so M1 = u1
+    jump = normal_shock_relations(M1=u1, gamma=gamma)
+    rho2 = rho1 * jump["rho2_rho1"]
+    u2 = rho1 * u1 / rho2
+    p2 = p1 * jump["p2_p1"]
+    residuals = rankine_hugoniot_jump_conditions(rho1, u1, p1, rho2, u2, p2)
+    assert max(abs(v) for v in residuals.values()) < 1e-10
+
+
+def test_normal_shock_rejects_subsonic_upstream():
+    with pytest.raises(InvalidParameterError):
+        normal_shock_relations(M1=0.5)
+
+
+def test_sod_shock_tube_conserves_left_and_right_far_field_states():
+    result = sod_shock_tube(nx=200, t_final=0.15)
+    assert result["rho"][0] == pytest.approx(1.0, abs=1e-2)
+    assert result["p"][0] == pytest.approx(1.0, abs=1e-2)
+    assert result["rho"][-1] == pytest.approx(0.125, abs=1e-2)
+    assert result["p"][-1] == pytest.approx(0.1, abs=1e-2)
+
+
+def test_sod_shock_tube_density_is_monotonically_decreasing_left_to_right():
+    """The Sod problem's three waves (rarefaction, contact, shock) all
+    connect the high state to the low state without an intermediate reversal."""
+    result = sod_shock_tube(nx=200, t_final=0.15)
+    # allow small non-monotonicity from numerical diffusion by smoothing lightly
+    rho = result["rho"]
+    assert rho[0] > rho[len(rho) // 2] > rho[-1]
+
+
+def test_sod_shock_tube_rejects_invalid_cfl():
+    with pytest.raises(InvalidParameterError):
+        sod_shock_tube(nx=100, cfl=1.5)
+
+
+def test_sod_shock_tube_rejects_too_few_cells_and_nonpositive_t_final():
+    with pytest.raises(InvalidParameterError):
+        sod_shock_tube(nx=3)
+    with pytest.raises(InvalidParameterError):
+        sod_shock_tube(nx=100, t_final=0.0)

physicskit/fluids/tests/test_instabilities.py

@@ -0,0 +1,115 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.systems.instabilities import (
+    kelvin_helmholtz_growth_rate,
+    kelvin_helmholtz_ic,
+    rayleigh_taylor_growth_rate,
+    rayleigh_taylor_ic,
+    simulate_kelvin_helmholtz,
+    simulate_rayleigh_taylor,
+)
+from physicskit.fluids.systems.navier_stokes import simulate_vorticity_streamfunction
+
+
+def test_kelvin_helmholtz_growth_rate_is_linear_in_k_and_delta_u():
+    assert kelvin_helmholtz_growth_rate(k=2.0, delta_u=3.0) == pytest.approx(3.0)
+    assert kelvin_helmholtz_growth_rate(k=4.0, delta_u=3.0) == pytest.approx(6.0)
+
+
+@pytest.mark.slow
+def test_kelvin_helmholtz_shear_layer_perturbation_grows():
+    n = 96
+    omega0 = kelvin_helmholtz_ic(n, 2 * np.pi, shear_width=0.1, perturbation_amplitude=0.05)
+    amps = []
+    omega = omega0.copy()
+    for _ in range(3):
+        result = simulate_vorticity_streamfunction(omega, nu=0.001, dt=0.0025, steps=100, length=2 * np.pi)
+        omega = result["omega"]
+        dev = omega - omega.mean(axis=0, keepdims=True)
+        amps.append(np.sqrt(np.mean(dev**2)))
+    assert amps[-1] > 2 * amps[0]
+
+
+def test_simulate_kelvin_helmholtz_matches_direct_vorticity_streamfunction_call():
+    n, length = 64, 2 * np.pi
+    omega0 = kelvin_helmholtz_ic(n, length, shear_width=0.1, perturbation_amplitude=0.05)
+    result_wrapper = simulate_kelvin_helmholtz(omega0, nu=0.001, dt=0.0025, steps=50, length=length)
+    result_direct = simulate_vorticity_streamfunction(omega0, nu=0.001, dt=0.0025, steps=50, length=length)
+    assert result_wrapper["omega"] == pytest.approx(result_direct["omega"])
+
+
+@pytest.mark.slow
+def test_simulate_kelvin_helmholtz_shear_layer_rolls_up():
+    n, length = 96, 2 * np.pi
+    omega0 = kelvin_helmholtz_ic(n, length, shear_width=0.1, perturbation_amplitude=0.05)
+    omega = omega0.copy()
+    amps = []
+    for _ in range(3):
+        result = simulate_kelvin_helmholtz(omega, nu=0.001, dt=0.0025, steps=100, length=length)
+        omega = result["omega"]
+        dev = omega - omega.mean(axis=0, keepdims=True)
+        amps.append(np.sqrt(np.mean(dev**2)))
+    assert amps[-1] > 2 * amps[0]
+
+
+def test_simulate_kelvin_helmholtz_rejects_nonpositive_viscosity():
+    omega0 = kelvin_helmholtz_ic(32, 2 * np.pi, shear_width=0.1, perturbation_amplitude=0.05)
+    with pytest.raises(InvalidParameterError):
+        simulate_kelvin_helmholtz(omega0, nu=-0.001, dt=0.0025, steps=1, length=2 * np.pi)
+
+
+def test_rayleigh_taylor_growth_rate_matches_sqrt_agk():
+    A, g, k = 0.3, 9.8, 2.0
+    assert rayleigh_taylor_growth_rate(k, A, g) == pytest.approx(np.sqrt(A * g * k))
+
+
+def test_rayleigh_taylor_growth_rate_rejects_invalid_atwood_number():
+    with pytest.raises(InvalidParameterError):
+        rayleigh_taylor_growth_rate(k=1.0, atwood_number=1.5, g=1.0)
+
+
+def test_rayleigh_taylor_growth_rate_rejects_negative_k():
+    with pytest.raises(InvalidParameterError):
+        rayleigh_taylor_growth_rate(k=-1.0, atwood_number=0.3, g=1.0)
+
+
+def test_rayleigh_taylor_ic_rejects_invalid_atwood_number():
+    with pytest.raises(InvalidParameterError):
+        rayleigh_taylor_ic(32, 2 * np.pi, atwood_number=1.5)
+
+
+def test_simulate_rayleigh_taylor_rejects_nonpositive_kappa_and_g():
+    omega0, buoyancy0 = rayleigh_taylor_ic(32, 2 * np.pi, atwood_number=0.2)
+    with pytest.raises(InvalidParameterError):
+        simulate_rayleigh_taylor(omega0, buoyancy0, nu=0.001, kappa=0.0, g=1.0, dt=0.01, steps=1, length=2 * np.pi)
+    with pytest.raises(InvalidParameterError):
+        simulate_rayleigh_taylor(omega0, buoyancy0, nu=0.001, kappa=0.001, g=0.0, dt=0.01, steps=1, length=2 * np.pi)
+
+
+def test_rayleigh_taylor_ic_starts_at_rest_with_heavy_fluid_on_top():
+    omega0, buoyancy0 = rayleigh_taylor_ic(64, 2 * np.pi, atwood_number=0.3)
+    assert np.all(omega0 == 0.0)
+    top_mean = buoyancy0[:, -1].mean()
+    bottom_mean = buoyancy0[:, 0].mean()
+    assert bottom_mean > 0 > top_mean  # bottom is light (positive b), top is heavy
+
+
+def test_rayleigh_taylor_interface_perturbation_grows_into_the_nonlinear_regime():
+    n, length = 64, 2 * np.pi
+    omega0, buoyancy0 = rayleigh_taylor_ic(n, length, atwood_number=0.3, perturbation_amplitude=0.01)
+    omega, buoyancy = omega0.copy(), buoyancy0.copy()
+    amps = []
+    for _ in range(10):
+        result = simulate_rayleigh_taylor(omega, buoyancy, nu=0.002, kappa=0.002, g=1.0, dt=0.01, steps=50, length=length)
+        omega, buoyancy = result["omega"], result["buoyancy"]
+        dev = buoyancy - buoyancy.mean(axis=0, keepdims=True)
+        amps.append(np.sqrt(np.mean(dev**2)))
+    assert amps[-1] > 3 * amps[0]
+
+
+def test_simulate_rayleigh_taylor_rejects_nonpositive_parameters():
+    omega0, buoyancy0 = rayleigh_taylor_ic(32, 2 * np.pi, atwood_number=0.2)
+    with pytest.raises(InvalidParameterError):
+        simulate_rayleigh_taylor(omega0, buoyancy0, nu=-1.0, kappa=0.001, g=1.0, dt=0.01, steps=1, length=2 * np.pi)

physicskit/fluids/tests/test_navier_stokes.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.core.grid import spectral_grid, vorticity_from_velocity
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.systems.navier_stokes import NavierStokes2D, simulate_vorticity_streamfunction
+
+
+def test_vorticity_from_velocity_matches_analytic_curl():
+    n, length = 48, 2 * np.pi
+    X, Y, KX, KY, K2 = spectral_grid(n, length)
+    u, v = np.sin(Y), np.zeros_like(X)
+    # omega = dv/dx - du/dy = 0 - cos(Y) = -cos(Y)
+    omega = vorticity_from_velocity(u, v, KX, KY)
+    np.testing.assert_allclose(omega, -np.cos(Y), atol=1e-10)
+
+
+def test_viscous_decay_reduces_peak_vorticity():
+    n, length = 48, 2 * np.pi
+    X, Y, KX, KY, K2 = spectral_grid(n, length)
+    omega0 = np.sin(X) * np.sin(Y)
+    result = simulate_vorticity_streamfunction(omega0, nu=0.05, dt=0.01, steps=50, length=length)
+    assert np.max(np.abs(result["omega"])) < np.max(np.abs(omega0))
+
+
+def test_navier_stokes_2d_class_matches_functional_api():
+    n, length, nu, dt, steps = 32, 2 * np.pi, 0.05, 0.01, 10
+    X, Y, KX, KY, K2 = spectral_grid(n, length)
+    omega0 = np.sin(X) * np.sin(Y)
+    solver = NavierStokes2D(n=n, length=length, nu=nu)
+    result_class = solver.simulate(omega0, dt=dt, steps=steps)
+    result_func = simulate_vorticity_streamfunction(omega0, nu=nu, dt=dt, steps=steps, length=length)
+    np.testing.assert_allclose(result_class["omega"], result_func["omega"], atol=1e-10)
+
+
+def test_velocity_field_is_divergence_free():
+    """The streamfunction formulation guarantees div(u) = 0 identically;
+    check it numerically to catch any sign/index error in the spectral derivatives."""
+    n, length = 48, 2 * np.pi
+    solver = NavierStokes2D(n=n, length=length, nu=0.01)
+    omega0 = np.sin(2 * solver.X) * np.cos(solver.Y) + np.cos(solver.X)
+    u, v = solver.velocity(omega0)
+    u_hat, v_hat = np.fft.fft2(u), np.fft.fft2(v)
+    divergence = np.real(np.fft.ifft2(1j * solver.KX * u_hat + 1j * solver.KY * v_hat))
+    assert np.max(np.abs(divergence)) < 1e-8
+
+
+def test_navier_stokes_rejects_nonpositive_viscosity():
+    with pytest.raises(InvalidParameterError):
+        NavierStokes2D(n=32, length=2 * np.pi, nu=0.0)
+    with pytest.raises(InvalidParameterError):
+        simulate_vorticity_streamfunction(np.zeros((16, 16)), nu=-0.1, dt=0.01, steps=1, length=2 * np.pi)
+
+
+def test_spectral_grid_rejects_too_coarse_resolution():
+    with pytest.raises(InvalidParameterError):
+        spectral_grid(n=4, length=1.0)
+
+
+def test_spectral_grid_rejects_nonpositive_length():
+    with pytest.raises(InvalidParameterError):
+        spectral_grid(n=32, length=0.0)
+
+
+def test_navier_stokes_2d_repr():
+    solver = NavierStokes2D(n=32, length=2 * np.pi, nu=0.05)
+    assert repr(solver) == "NavierStokes2D(n=32, length=6.283185307179586, nu=0.05)"

physicskit/fluids/tests/test_potential_flow.py

@@ -0,0 +1,92 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.systems.potential_flow import (
+    PotentialFlow,
+    flow_past_cylinder,
+    kutta_joukowski_lift,
+    pressure_coefficient,
+)
+
+
+def test_cylinder_surface_is_a_single_streamline():
+    """Uniform flow + doublet places a circular streamline exactly at the
+    doublet's radius; every point on that circle must share one streamfunction value."""
+    flow = flow_past_cylinder(U_inf=2.0, radius=1.5, circulation=3.0)
+    theta = np.linspace(0, 2 * np.pi, 37)
+    x, y = 1.5 * np.cos(theta), 1.5 * np.sin(theta)
+    psi = flow.streamfunction(x, y)
+    assert np.max(np.abs(psi - psi[0])) < 1e-6
+
+
+def test_cylinder_surface_speed_matches_classic_formula():
+    """On a lift-free cylinder, the tangential surface speed is exactly
+    2*U_inf*sin(theta) -- the textbook result, checked independently of the
+    velocity() finite-difference implementation via the surface Cp."""
+    U_inf, R = 1.0, 1.0
+    flow = flow_past_cylinder(U_inf=U_inf, radius=R, circulation=0.0)
+    theta = np.linspace(0.01, np.pi - 0.01, 25)  # avoid stagnation points
+    x, y = R * np.cos(theta), R * np.sin(theta)
+    Cp = flow.pressure_coefficient(x, y)
+    expected_speed = 2.0 * U_inf * np.sin(theta)
+    expected_Cp = 1.0 - (expected_speed / U_inf) ** 2
+    np.testing.assert_allclose(Cp, expected_Cp, atol=1e-4)
+
+
+def test_kutta_joukowski_lift_matches_cylinder_pressure_integral():
+    """Integrating Cp around the lifting cylinder's surface should reproduce
+    the Kutta-Joukowski lift, an independent cross-check of two different
+    ways to compute the same force."""
+    U_inf, R, rho, Gamma = 1.0, 1.0, 1.0, 1.0
+    flow = flow_past_cylinder(U_inf=U_inf, radius=R, circulation=Gamma)
+    theta = np.linspace(0, 2 * np.pi, 2000, endpoint=False)
+    x, y = R * np.cos(theta), R * np.sin(theta)
+    Cp = flow.pressure_coefficient(x, y)
+    p = Cp * (0.5 * rho * U_inf**2)
+    # Lift is -oint p * sin(theta) * R dtheta (normal force projected onto y);
+    # a plain Riemann sum over a uniform grid is exact for a periodic integrand.
+    dtheta = theta[1] - theta[0]
+    lift_numeric = -np.sum(p * np.sin(theta) * R) * dtheta
+    lift_theory = kutta_joukowski_lift(rho, U_inf, Gamma)
+    # the sign of the pressure-integral convention above is independent of
+    # the theorem itself; only the magnitude is being cross-checked here.
+    assert abs(lift_numeric) == pytest.approx(lift_theory, rel=0.02)
+
+
+def test_flow_past_cylinder_rejects_nonpositive_radius():
+    with pytest.raises(InvalidParameterError):
+        flow_past_cylinder(U_inf=1.0, radius=0.0)
+
+
+def test_flow_past_cylinder_rejects_nonpositive_u_inf():
+    with pytest.raises(InvalidParameterError):
+        flow_past_cylinder(U_inf=0.0, radius=1.0)
+
+
+def test_pressure_coefficient_is_one_at_stagnation():
+    """Cp = 1 exactly where the local speed vanishes (a stagnation point)."""
+    assert pressure_coefficient(u=0.0, v=0.0, U_inf=1.0) == 1.0
+
+
+def test_pressure_coefficient_rejects_nonpositive_u_inf():
+    with pytest.raises(InvalidParameterError):
+        pressure_coefficient(u=0.0, v=0.0, U_inf=0.0)
+
+
+def test_kutta_joukowski_lift_rejects_nonpositive_rho_and_u_inf():
+    with pytest.raises(InvalidParameterError):
+        kutta_joukowski_lift(rho=0.0, U_inf=1.0, circulation=1.0)
+    with pytest.raises(InvalidParameterError):
+        kutta_joukowski_lift(rho=1.2, U_inf=0.0, circulation=1.0)
+
+
+def test_source_and_sink_pair_has_zero_net_streamfunction_far_away():
+    """A source and an equal-strength sink placed symmetrically must produce
+    a flow that looks, from far away, like nothing at all (net source strength zero)."""
+    flow = PotentialFlow(U_inf=0.0)
+    flow.add_source(strength=5.0, x0=-0.1, y0=0.0)
+    flow.add_source(strength=-5.0, x0=0.1, y0=0.0)
+    far_x, far_y = 1000.0, 1000.0
+    u, v = flow.velocity(far_x, far_y)
+    assert np.hypot(u, v) < 1e-6