physicskit 0.1.0__py3-none-any.whl

physicskit/fluids/tests/test_static_visualizers.py

@@ -0,0 +1,91 @@
+"""Coverage for physicskit.fluids.visualizers's static plotting functions
+(previously entirely untested): plot_shock_tube_profiles, plot_streamlines,
+plot_vorticity_field, plot_pressure_coefficient, plot_energy_spectrum --
+including the ax=<given> branch and the optional-overlay branches. All pure
+matplotlib, small inputs -- fast."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+
+from physicskit.fluids.systems.compressible_flow import sod_shock_tube
+from physicskit.fluids.systems.potential_flow import pressure_coefficient
+from physicskit.fluids.utils.spectral_analysis import energy_spectrum
+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
+
+
+def test_plot_shock_tube_profiles_returns_three_axes():
+    result = sod_shock_tube(nx=50, t_final=0.15)
+    fig, axes = plot_shock_tube_profiles(result["x"], result["rho"], result["u"], result["p"])
+    assert isinstance(fig, Figure)
+    assert len(axes) == 3
+    for ax in axes:
+        assert len(ax.lines) == 1
+
+
+def test_plot_streamlines_default_and_given_ax():
+    x = np.linspace(-1, 1, 10)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    u, v = -Y, X
+    fig0, ax0 = plot_streamlines(X, Y, u, v)
+    assert isinstance(fig0, Figure)
+
+    fig, ax = plt.subplots()
+    _, ax_given = plot_streamlines(X, Y, u, v, ax=ax)
+    assert ax_given is ax
+
+
+def test_plot_vorticity_field_given_ax_and_with_streamline_overlay():
+    x = np.linspace(-1, 1, 10)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    omega = np.sin(X) * np.cos(Y)
+    u, v = -Y, X
+
+    fig0, ax0 = plot_vorticity_field(X, Y, omega)
+    assert isinstance(fig0, Figure)
+
+    fig, ax = plt.subplots()
+    _, ax_given = plot_vorticity_field(X, Y, omega, ax=ax)
+    assert ax_given is ax
+    assert len(ax.lines) == 0  # no streamlines without u, v
+
+    fig2, ax2 = plt.subplots()
+    _, ax2_given = plot_vorticity_field(X, Y, omega, u=u, v=v, ax=ax2)
+    assert ax2_given is ax2
+    assert ax2.lines or ax2.collections  # streamplot overlay was drawn
+
+
+def test_plot_pressure_coefficient_given_ax():
+    theta = np.linspace(0, 2 * np.pi, 30)
+    Cp = pressure_coefficient(u=np.cos(theta), v=np.sin(theta), U_inf=1.0)
+    fig0, ax0 = plot_pressure_coefficient(theta, Cp)
+    assert isinstance(fig0, Figure)
+
+    fig, ax = plt.subplots()
+    _, ax_given = plot_pressure_coefficient(theta, Cp, ax=ax)
+    assert ax_given is ax
+
+
+def test_plot_energy_spectrum_given_ax_and_without_kolmogorov_line():
+    n, length = 32, 2 * np.pi
+    x = np.linspace(0, length, n, endpoint=False)
+    X, Y = np.meshgrid(x, x, indexing="ij")
+    u, v = np.sin(3 * Y), np.sin(3 * X)
+    k, E = energy_spectrum(u, v, length)
+
+    fig0, ax0 = plot_energy_spectrum(k, E)
+    assert isinstance(fig0, Figure)
+
+    fig, ax = plt.subplots()
+    _, ax_given = plot_energy_spectrum(k, E, ax=ax)
+    assert ax_given is ax
+    assert len(ax.lines) == 2  # spectrum + Kolmogorov reference
+
+    fig2, ax2 = plt.subplots()
+    plot_energy_spectrum(k, E, ax=ax2, show_kolmogorov=False)
+    assert len(ax2.lines) == 1  # spectrum only

physicskit/fluids/tests/test_utils.py

@@ -0,0 +1,100 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.utils.dimensionless import (
+    froude_number,
+    mach_number,
+    reynolds_number,
+    strouhal_number,
+    weber_number,
+)
+from physicskit.fluids.utils.spectral_analysis import energy_spectrum, kolmogorov_reference_slope
+
+
+def test_reynolds_number_formula():
+    assert reynolds_number(velocity=2.0, length=0.1, nu=0.02) == pytest.approx(10.0)
+
+
+def test_reynolds_number_rejects_nonpositive_viscosity():
+    with pytest.raises(InvalidParameterError):
+        reynolds_number(velocity=1.0, length=1.0, nu=0.0)
+
+
+def test_reynolds_number_rejects_nonpositive_length():
+    with pytest.raises(InvalidParameterError):
+        reynolds_number(velocity=1.0, length=0.0, nu=1.0)
+
+
+def test_froude_number_rejects_nonpositive_length_and_g():
+    with pytest.raises(InvalidParameterError):
+        froude_number(velocity=1.0, length=0.0, g=9.81)
+    with pytest.raises(InvalidParameterError):
+        froude_number(velocity=1.0, length=1.0, g=0.0)
+
+
+def test_mach_number_rejects_nonpositive_speed_of_sound():
+    with pytest.raises(InvalidParameterError):
+        mach_number(velocity=100.0, speed_of_sound=0.0)
+
+
+def test_strouhal_number_rejects_nonpositive_velocity():
+    with pytest.raises(InvalidParameterError):
+        strouhal_number(frequency=5.0, length=0.02, velocity=0.0)
+
+
+def test_weber_number_rejects_nonpositive_surface_tension():
+    with pytest.raises(InvalidParameterError):
+        weber_number(rho=1000.0, velocity=1.0, length=0.001, surface_tension=0.0)
+
+
+def test_froude_number_formula():
+    U, L, g = 4.0, 2.0, 9.81
+    assert froude_number(U, L, g) == pytest.approx(U / np.sqrt(g * L))
+
+
+def test_mach_number_transonic_threshold():
+    assert mach_number(velocity=343.0, speed_of_sound=343.0) == pytest.approx(1.0)
+    assert mach_number(velocity=100.0, speed_of_sound=343.0) < 1.0
+
+
+def test_strouhal_number_formula():
+    assert strouhal_number(frequency=5.0, length=0.02, velocity=0.5) == pytest.approx(0.2)
+
+
+def test_weber_number_formula():
+    We = weber_number(rho=1000.0, velocity=2.0, length=0.002, surface_tension=0.072)
+    assert We == pytest.approx(1000.0 * 4.0 * 0.002 / 0.072)
+
+
+def test_energy_spectrum_is_isotropic_for_a_radially_symmetric_field():
+    """A single-wavenumber flow deposits essentially all its energy in the
+    shell matching |k|, regardless of the direction of the wavevector."""
+    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(3 * Y), np.sin(3 * X)  # |k| = 3
+    k, E = energy_spectrum(u, v, length)
+    assert np.argmax(E) == 3
+    assert E[3] > 100 * np.sum(E[np.arange(len(E)) != 3])
+
+
+def test_energy_spectrum_rejects_mismatched_shapes():
+    with pytest.raises(InvalidParameterError):
+        energy_spectrum(np.zeros((16, 16)), np.zeros((8, 8)), length=1.0)
+
+
+def test_energy_spectrum_rejects_non_square_arrays():
+    with pytest.raises(InvalidParameterError):
+        energy_spectrum(np.zeros((8, 16)), np.zeros((8, 16)), length=1.0)
+
+
+def test_kolmogorov_reference_slope_matches_power_law():
+    k = np.array([1.0, 8.0])
+    ref = kolmogorov_reference_slope(k, k0=1.0, E0=1.0)
+    assert ref[1] == pytest.approx(8.0 ** (-5.0 / 3.0))
+
+
+def test_kolmogorov_reference_slope_rejects_nonpositive_anchor():
+    with pytest.raises(InvalidParameterError):
+        kolmogorov_reference_slope(np.array([1.0]), k0=0.0, E0=1.0)

physicskit/fluids/tests/test_viscous_flow.py

@@ -0,0 +1,110 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+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,
+)
+
+
+def test_couette_profile_is_linear_and_matches_wall_speeds():
+    y = np.linspace(0, 2.0, 21)
+    u = couette_flow_velocity(y, U_wall=3.0, h=2.0)
+    assert u[0] == 0.0
+    assert u[-1] == pytest.approx(3.0)
+    np.testing.assert_allclose(np.diff(u), np.diff(u)[0])  # constant slope
+
+
+def test_poiseuille_flow_rate_matches_integral_of_velocity_profile():
+    dpdx, mu, h = -6.0, 0.8, 1.3
+    y = np.linspace(0, h, 20001)
+    u = poiseuille_flow_velocity(y, dpdx, mu, h)
+    Q_numeric = np.trapz(u, y) if hasattr(np, "trapz") else np.sum(u) * (y[1] - y[0])
+    Q_formula = poiseuille_flow_rate(dpdx, mu, h)
+    assert Q_numeric == pytest.approx(Q_formula, rel=1e-3)
+
+
+def test_stokes_drag_scales_linearly_with_velocity_and_radius():
+    F1 = stokes_drag(mu=1e-3, radius=1e-4, velocity=0.01)
+    F2 = stokes_drag(mu=1e-3, radius=1e-4, velocity=0.02)
+    assert F2 == pytest.approx(2 * F1)
+    F3 = stokes_drag(mu=1e-3, radius=2e-4, velocity=0.01)
+    assert F3 == pytest.approx(2 * F1)
+
+
+def test_blasius_wall_shear_matches_classic_constant():
+    """f''(0), the Blasius shooting solution's wall-curvature, is the
+    textbook constant ~0.332."""
+    result = blasius_solve()
+    assert result["fpp"][0] == pytest.approx(0.33206, abs=1e-4)
+
+
+def test_blasius_far_field_velocity_recovers_free_stream():
+    result = blasius_solve()
+    assert result["fp"][-1] == pytest.approx(1.0, abs=1e-6)
+
+
+def test_blasius_boundary_layer_thickness_grows_like_sqrt_x():
+    x = np.array([1.0, 4.0, 9.0])
+    delta = blasius_boundary_layer_thickness(x, U_inf=1.0, nu=1e-4)
+    ratios = delta / np.sqrt(x)
+    assert np.allclose(ratios, ratios[0], rtol=1e-8)
+
+
+def test_blasius_skin_friction_decreases_with_reynolds_number():
+    Re = np.array([1e3, 1e4, 1e5])
+    cf = blasius_skin_friction_coefficient(Re)
+    assert np.all(np.diff(cf) < 0)
+
+
+def test_viscous_flow_rejects_nonpositive_parameters():
+    with pytest.raises(InvalidParameterError):
+        couette_flow_velocity(y=0.5, U_wall=1.0, h=0.0)
+    with pytest.raises(InvalidParameterError):
+        stokes_drag(mu=-1.0, radius=1.0, velocity=1.0)
+    with pytest.raises(InvalidParameterError):
+        blasius_boundary_layer_thickness(x=-1.0, U_inf=1.0, nu=1e-4)
+
+
+def test_poiseuille_flow_velocity_rejects_nonpositive_mu_and_h():
+    with pytest.raises(InvalidParameterError):
+        poiseuille_flow_velocity(y=0.5, dpdx=-1.0, mu=0.0, h=1.0)
+    with pytest.raises(InvalidParameterError):
+        poiseuille_flow_velocity(y=0.5, dpdx=-1.0, mu=1.0, h=0.0)
+
+
+def test_poiseuille_flow_rate_rejects_nonpositive_mu_and_h():
+    with pytest.raises(InvalidParameterError):
+        poiseuille_flow_rate(dpdx=-1.0, mu=0.0, h=1.0)
+    with pytest.raises(InvalidParameterError):
+        poiseuille_flow_rate(dpdx=-1.0, mu=1.0, h=0.0)
+
+
+def test_stokes_drag_rejects_nonpositive_radius():
+    with pytest.raises(InvalidParameterError):
+        stokes_drag(mu=1.0, radius=0.0, velocity=1.0)
+
+
+def test_blasius_boundary_layer_thickness_rejects_nonpositive_u_inf_and_nu():
+    with pytest.raises(InvalidParameterError):
+        blasius_boundary_layer_thickness(x=1.0, U_inf=0.0, nu=1e-4)
+    with pytest.raises(InvalidParameterError):
+        blasius_boundary_layer_thickness(x=1.0, U_inf=1.0, nu=0.0)
+
+
+def test_blasius_skin_friction_coefficient_rejects_nonpositive_reynolds():
+    with pytest.raises(InvalidParameterError):
+        blasius_skin_friction_coefficient(reynolds_x=np.array([1e4, -1.0]))
+
+
+def test_blasius_solve_expands_bracket_when_default_guess_undershoots():
+    # eta_max=1.0 is too short for fpp0=1.0's shooting guess to reach f'=1,
+    # forcing the initial bracket-expansion loop before bisection.
+    result = blasius_solve(eta_max=1.0, n_points=50)
+    assert result["fp"][-1] == pytest.approx(1.0, abs=1e-6)

physicskit/fluids/tests/test_visualizers.py

@@ -0,0 +1,34 @@
+"""Animation smoke tests for physicskit.fluids.visualizers.flow_fields, previously untested
+(no visualizer in physicskit.fluids had any test coverage before this). These run headlessly
+(see conftest.py's Agg backend) and check that the Kelvin-Helmholtz and Rayleigh-Taylor
+animations build and save correctly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from matplotlib.animation import PillowWriter
+
+from physicskit.fluids.systems.instabilities import kelvin_helmholtz_ic, rayleigh_taylor_ic
+from physicskit.fluids.visualizers.flow_fields import animate_kelvin_helmholtz, animate_rayleigh_taylor
+
+
+@pytest.mark.slow
+def test_animate_kelvin_helmholtz_saves_to_gif(tmp_path):
+    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=20, n_frames=5, length=length)
+    out = tmp_path / "kelvin_helmholtz.gif"
+    anim.save(out, writer=PillowWriter(fps=10))
+    assert out.exists() and out.stat().st_size > 0
+
+
+@pytest.mark.slow
+def test_animate_rayleigh_taylor_saves_to_gif(tmp_path):
+    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=20, n_frames=5, length=length)
+    out = tmp_path / "rayleigh_taylor.gif"
+    anim.save(out, writer=PillowWriter(fps=10))
+    assert out.exists() and out.stat().st_size > 0

physicskit/fluids/tests/test_vortex_dynamics.py

@@ -0,0 +1,88 @@
+import numpy as np
+import pytest
+
+from physicskit.fluids.exceptions import InvalidParameterError
+from physicskit.fluids.systems.vortex_dynamics import (
+    PointVortexSystem,
+    point_vortex_velocities,
+    von_karman_vortex_street,
+)
+
+
+def test_two_equal_vortices_orbit_at_the_analytic_angular_velocity():
+    """Two point vortices of equal strength Gamma separated by distance d
+    rotate rigidly about their midpoint at angular velocity Omega = Gamma / (pi d^2)."""
+    Gamma, d = 1.0, 1.0
+    positions0 = np.array([[d / 2, 0.0], [-d / 2, 0.0]])
+    system = PointVortexSystem(positions=positions0, circulations=[Gamma, Gamma])
+    omega_expected = Gamma / (np.pi * d**2)
+    t_final = 0.2
+    dt, n_steps = 1e-4, round(t_final / 1e-4)
+    _, trajectory = system.trajectory(dt=dt, n_steps=n_steps)
+    final = trajectory[-1]
+    d_final = np.hypot(*(final[0] - final[1]))
+    assert d_final == pytest.approx(d, rel=1e-3)  # separation is conserved
+    angle_final = np.arctan2(final[0, 1], final[0, 0])
+    assert angle_final == pytest.approx(omega_expected * t_final, abs=1e-3)
+
+
+def test_opposite_sign_vortex_pair_translates_without_rotating():
+    """A vortex dipole (equal and opposite circulation) advects itself in a
+    straight line at constant velocity Gamma / (2 pi d), rather than orbiting."""
+    Gamma, d = 1.0, 1.0
+    positions0 = np.array([[0.0, d / 2], [0.0, -d / 2]])
+    system = PointVortexSystem(positions=positions0, circulations=[Gamma, -Gamma])
+    dt, n_steps = 1e-3, 200
+    _, trajectory = system.trajectory(dt=dt, n_steps=n_steps)
+    displacement = trajectory[-1] - trajectory[0]
+    # both vortices move by (nearly) the same vector: rigid translation
+    np.testing.assert_allclose(displacement[0], displacement[1], atol=1e-3)
+    speed_expected = Gamma / (2 * np.pi * d)
+    speed_numeric = np.hypot(*displacement[0]) / (dt * n_steps)
+    assert speed_numeric == pytest.approx(speed_expected, rel=1e-2)
+
+
+def test_point_vortex_velocities_rejects_mismatched_lengths():
+    with pytest.raises(InvalidParameterError):
+        point_vortex_velocities(positions=[[0.0, 0.0], [1.0, 0.0]], circulations=[1.0])
+
+
+def test_point_vortex_system_rejects_mismatched_lengths():
+    with pytest.raises(InvalidParameterError):
+        PointVortexSystem(positions=[[0.0, 0.0], [1.0, 0.0]], circulations=[1.0])
+
+
+def test_point_vortex_system_velocities_matches_module_function():
+    positions = [[0.0, 0.0], [1.0, 0.0]]
+    circulations = [1.0, -1.0]
+    system = PointVortexSystem(positions=positions, circulations=circulations)
+    np.testing.assert_allclose(system.velocities(), point_vortex_velocities(positions, circulations))
+
+
+def test_point_vortex_system_repr():
+    system = PointVortexSystem(positions=[[0.0, 0.0]], circulations=[2.0])
+    assert repr(system) == "PointVortexSystem(n_vortices=1, circulations=array([2.]))"
+
+
+def test_von_karman_street_rejects_nonpositive_spacing():
+    with pytest.raises(InvalidParameterError):
+        von_karman_vortex_street(n_pairs=3, spacing_l=0.0)
+
+
+def test_von_karman_street_alternates_sign_across_rows():
+    positions, circulations = von_karman_vortex_street(n_pairs=4, spacing_l=1.0)
+    top_row = circulations[0::2]
+    bottom_row = circulations[1::2]
+    np.testing.assert_allclose(top_row, -bottom_row)
+
+
+def test_von_karman_street_uses_the_stable_spacing_ratio_by_default():
+    spacing_l = 2.0
+    positions, _ = von_karman_vortex_street(n_pairs=3, spacing_l=spacing_l)
+    h = positions[0, 1] - positions[1, 1]
+    assert h / spacing_l == pytest.approx(0.2805, abs=1e-4)
+
+
+def test_von_karman_street_rejects_too_few_pairs():
+    with pytest.raises(InvalidParameterError):
+        von_karman_vortex_street(n_pairs=1, spacing_l=1.0)

physicskit/fluids/utils/__init__.py

@@ -0,0 +1,18 @@
+from physicskit.fluids.utils.dimensionless import (
+    froude_number,
+    mach_number,
+    reynolds_number,
+    strouhal_number,
+    weber_number,
+)
+from physicskit.fluids.utils.spectral_analysis import energy_spectrum, kolmogorov_reference_slope
+
+__all__ = [
+    "energy_spectrum",
+    "froude_number",
+    "kolmogorov_reference_slope",
+    "mach_number",
+    "reynolds_number",
+    "strouhal_number",
+    "weber_number",
+]

physicskit/fluids/utils/dimensionless.py

@@ -0,0 +1,239 @@
+"""Dimensionless numbers: Reynolds, Froude, Mach, Strouhal, and Weber.
+
+Fluid mechanics is governed by ratios, not absolute scales: two flows with
+the same dimensionless numbers behave identically regardless of their size,
+speed, or fluid, which is what makes wind-tunnel testing of a model
+airplane meaningful for a full-size one. Each function here computes one
+such ratio, and each result's magnitude is what determines which regime
+(and which module of this package) actually applies -- a low Reynolds
+number licenses :func:`physicskit.fluids.systems.viscous_flow.stokes_drag`,
+a high one calls for
+:class:`physicskit.fluids.systems.navier_stokes.NavierStokes2D` or the
+turbulence tools in :mod:`physicskit.fluids.utils.spectral_analysis`.
+"""
+
+from __future__ import annotations
+
+from physicskit.fluids.exceptions import InvalidParameterError
+
+__all__ = [
+    "reynolds_number",
+    "froude_number",
+    "mach_number",
+    "strouhal_number",
+    "weber_number",
+]
+
+
+def reynolds_number(velocity: float, length: float, nu: float) -> float:
+    """The Reynolds number: inertial forces over viscous forces.
+
+    .. math::
+
+        Re = \\frac{U L}{\\nu}
+
+    Osborne Reynolds' 1883 pipe-flow experiments identified this ratio as
+    the single parameter controlling the transition from smooth (laminar)
+    to chaotic (turbulent) flow, regardless of the pipe's size or the
+    fluid's identity -- the founding result of dimensional-similarity
+    reasoning in fluid mechanics.
+
+    Parameters
+    ----------
+    velocity : float
+        Characteristic flow speed `U`.
+    length : float
+        Characteristic length scale `L`.
+    nu : float
+        Kinematic viscosity.
+
+    Returns
+    -------
+    float
+        Reynolds number `Re`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `length` or `nu` is not positive.
+
+    Examples
+    --------
+    >>> reynolds_number(velocity=2.0, length=0.5, nu=1e-6)
+    1000000.0
+    """
+    if length <= 0:
+        raise InvalidParameterError(f"length must be positive, got {length}")
+    if nu <= 0:
+        raise InvalidParameterError(f"nu must be positive, got {nu}")
+    return velocity * length / nu
+
+
+def froude_number(velocity: float, length: float, g: float = 9.81) -> float:
+    """The Froude number: inertial forces over gravitational forces.
+
+    .. math::
+
+        Fr = \\frac{U}{\\sqrt{gL}}
+
+    Governs free-surface (gravity wave) flows the way the Reynolds number
+    governs viscous ones: a ship model and its full-size counterpart make
+    the same waves, relative to their length, only if `Fr` matches. William
+    Froude's 1868 ship-hull towing-tank experiments established exactly
+    this scaling law.
+
+    Parameters
+    ----------
+    velocity : float
+        Characteristic flow speed `U`.
+    length : float
+        Characteristic length scale `L`.
+    g : float, default 9.81
+        Gravitational acceleration.
+
+    Returns
+    -------
+    float
+        Froude number `Fr`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `length` or `g` is not positive.
+
+    Examples
+    --------
+    >>> round(froude_number(velocity=3.0, length=9.81, g=9.81), 4)
+    0.3058
+    """
+    if length <= 0:
+        raise InvalidParameterError(f"length must be positive, got {length}")
+    if g <= 0:
+        raise InvalidParameterError(f"g must be positive, got {g}")
+    return velocity / (g * length) ** 0.5
+
+
+def mach_number(velocity: float, speed_of_sound: float) -> float:
+    """The Mach number: flow speed over the local speed of sound.
+
+    .. math::
+
+        M = \\frac{U}{c}
+
+    The single number that decides whether compressibility can be ignored
+    (:math:`M \\ll 1`, the regime of every other module in this package
+    except :mod:`physicskit.fluids.systems.compressible_flow`) or dominates
+    the flow (:math:`M \\gtrsim 1`, where :func:`~physicskit.fluids.systems.compressible_flow.normal_shock_relations`
+    applies).
+
+    Parameters
+    ----------
+    velocity : float
+        Flow speed `U`.
+    speed_of_sound : float
+        Local speed of sound `c`.
+
+    Returns
+    -------
+    float
+        Mach number `M`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `speed_of_sound` is not positive.
+
+    Examples
+    --------
+    >>> mach_number(velocity=340.0, speed_of_sound=340.0)
+    1.0
+    """
+    if speed_of_sound <= 0:
+        raise InvalidParameterError(f"speed_of_sound must be positive, got {speed_of_sound}")
+    return velocity / speed_of_sound
+
+
+def strouhal_number(frequency: float, length: float, velocity: float) -> float:
+    """The Strouhal number: a dimensionless vortex-shedding frequency.
+
+    .. math::
+
+        St = \\frac{f L}{U}
+
+    For flow past a bluff body shedding a
+    :func:`~physicskit.fluids.systems.vortex_dynamics.von_karman_vortex_street`
+    at frequency `f`, `St` stays remarkably constant (near 0.2 for a
+    circular cylinder) over a wide range of Reynolds number, letting a
+    single scaled model predict the shedding frequency at full scale.
+
+    Parameters
+    ----------
+    frequency : float
+        Vortex-shedding frequency `f`.
+    length : float
+        Characteristic length scale `L` (e.g. the body's cross-stream width).
+    velocity : float
+        Characteristic flow speed `U`.
+
+    Returns
+    -------
+    float
+        Strouhal number `St`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `velocity` is not positive.
+
+    Examples
+    --------
+    >>> round(strouhal_number(frequency=2.0, length=0.1, velocity=1.0), 4)
+    0.2
+    """
+    if velocity <= 0:
+        raise InvalidParameterError(f"velocity must be positive, got {velocity}")
+    return frequency * length / velocity
+
+
+def weber_number(rho: float, velocity: float, length: float, surface_tension: float) -> float:
+    """The Weber number: inertial forces over surface-tension forces.
+
+    .. math::
+
+        We = \\frac{\\rho U^2 L}{\\sigma}
+
+    Governs whether a free liquid surface (a droplet, a jet, a bubble)
+    deforms and breaks up under its own inertia (:math:`We \\gg 1`) or is
+    held together by surface tension (:math:`We \\lesssim 1`) -- the
+    parameter that decides, for instance, whether a jet of liquid breaks
+    into droplets.
+
+    Parameters
+    ----------
+    rho : float
+        Fluid density.
+    velocity : float
+        Characteristic flow speed `U`.
+    length : float
+        Characteristic length scale `L` (e.g. a droplet diameter).
+    surface_tension : float
+        Surface tension coefficient :math:`\\sigma`.
+
+    Returns
+    -------
+    float
+        Weber number `We`.
+
+    Raises
+    ------
+    InvalidParameterError
+        If `surface_tension` is not positive.
+
+    Examples
+    --------
+    >>> round(weber_number(rho=1000.0, velocity=1.0, length=0.001, surface_tension=0.072), 4)
+    13.8889
+    """
+    if surface_tension <= 0:
+        raise InvalidParameterError(f"surface_tension must be positive, got {surface_tension}")
+    return rho * velocity**2 * length / surface_tension