physicskit 0.1.0__py3-none-any.whl

physicskit/relativity/tests/test_schwarzschild.py

@@ -0,0 +1,126 @@
+import numpy as np
+import pytest
+
+from physicskit.relativity.chapters.schwarzschild import SchwarzschildBlackHole
+
+
+def test_key_radii():
+    bh = SchwarzschildBlackHole(M=2.0)
+    assert bh.horizon_radius == pytest.approx(4.0)
+    assert bh.photon_sphere_radius == pytest.approx(6.0)
+    assert bh.isco_radius == pytest.approx(12.0)
+    assert bh.critical_impact_parameter == pytest.approx(2.0 * 3.0 * np.sqrt(3.0))
+
+
+def test_circular_orbit_angular_velocity_is_keplerian():
+    bh = SchwarzschildBlackHole(M=1.0)
+    r = 100.0
+    assert bh.circular_orbit_angular_velocity(r) == pytest.approx(np.sqrt(1.0 / r**3))
+
+
+def test_circular_orbit_stays_at_constant_radius():
+    bh = SchwarzschildBlackHole(M=1.0)
+    y0 = bh.circular_orbit_initial_state(r0=10.0)
+    traj = bh.integrate_geodesic(y0, dtau=0.02, n_steps=2000)
+    assert np.allclose(traj["r"], 10.0, atol=1e-6)
+
+
+def test_light_deflection_converges_to_weak_field_formula():
+    bh = SchwarzschildBlackHole(M=1.0)
+    b = 50.0
+    y0 = bh.null_geodesic_initial_state(r0=2.0e5, impact_parameter=b, ingoing=True)
+    traj = bh.integrate_geodesic(y0, dtau=2.0, n_steps=300000)
+    measured = (traj["phi"][-1] - traj["phi"][0]) - np.pi
+    assert measured == pytest.approx(bh.light_deflection_angle(b), rel=0.1)
+
+
+def test_light_capture_near_photon_sphere():
+    bh = SchwarzschildBlackHole(M=1.0)
+    # impact parameter well below the critical value: photon should plunge in
+    y0 = bh.null_geodesic_initial_state(r0=100.0, impact_parameter=3.0, ingoing=True)
+    traj = bh.integrate_geodesic(y0, dtau=0.05, n_steps=20000)
+    assert traj["r"].min() < bh.horizon_radius * 1.05
+
+
+def test_light_escape_above_critical_impact_parameter():
+    bh = SchwarzschildBlackHole(M=1.0)
+    y0 = bh.null_geodesic_initial_state(r0=1000.0, impact_parameter=30.0, ingoing=True)
+    traj = bh.integrate_geodesic(y0, dtau=0.5, n_steps=20000)
+    assert traj["r"].min() > bh.photon_sphere_radius
+    assert traj["r"][-1] > traj["r"].min()
+
+
+def test_perihelion_precession_is_empty_for_too_short_a_trajectory():
+    bh = SchwarzschildBlackHole(M=1.0)
+    y0 = bh.eccentric_orbit_initial_state(r0=100.0, eccentricity_boost=0.03)
+    traj = bh.integrate_geodesic(y0, dtau=0.05, n_steps=50)  # fewer than 2 periapsis passages
+    prec = bh.perihelion_precession(traj)
+    assert prec.shape == (0,)
+
+
+def test_weak_field_precession_converges_for_wide_low_eccentricity_orbit():
+    bh = SchwarzschildBlackHole(M=1.0)
+    y0 = bh.eccentric_orbit_initial_state(r0=100.0, eccentricity_boost=0.03)
+    traj = bh.integrate_geodesic(y0, dtau=0.05, n_steps=300000)
+    prec = bh.perihelion_precession(traj)
+    assert len(prec) > 0
+    e_est = (traj["r"].max() - traj["r"].min()) / (traj["r"].max() + traj["r"].min())
+    a_semi = (traj["r"].max() + traj["r"].min()) / 2.0
+    weak_field = bh.weak_field_precession_per_orbit(a_semi, e_est)
+    assert np.mean(prec) == pytest.approx(weak_field, rel=0.15)
+    assert np.mean(prec) > 0.0  # perihelion precesses forward, as GR predicts
+
+
+def test_shapiro_delay_positive_and_increases_with_smaller_impact_parameter():
+    bh = SchwarzschildBlackHole(M=1.0)
+    delay_far = bh.shapiro_delay(r1=1000.0, r2=1000.0, impact_parameter=100.0)
+    delay_close = bh.shapiro_delay(r1=1000.0, r2=1000.0, impact_parameter=10.0)
+    assert delay_far > 0.0
+    assert delay_close > delay_far
+
+
+def test_effective_potential_has_stable_and_unstable_extrema_above_isco_momentum():
+    bh = SchwarzschildBlackHole(M=1.0)
+    # for L modestly above the ISCO value L^2=12M^2, V_eff should show both an
+    # unstable maximum (between the photon sphere and the ISCO) and a stable
+    # minimum (outside the ISCO) -- the two circular-orbit branches merging
+    # into the single ISCO inflection as L -> sqrt(12)*M from above.
+    L = np.sqrt(12.0) * 1.05
+    r = np.linspace(3.5, 20.0, 2000)
+    V = bh.effective_potential(r, L)
+    idx_max = np.argmax(V[r < 6.0])
+    idx_min = np.argmin(V[r > 6.0])
+    r_unstable = r[r < 6.0][idx_max]
+    r_stable = r[r > 6.0][idx_min]
+    assert bh.photon_sphere_radius < r_unstable < bh.isco_radius
+    assert r_stable > bh.isco_radius
+
+
+def test_disk_redshift_factor_doppler_asymmetry():
+    bh = SchwarzschildBlackHole(M=1.0)
+    r = 10.0
+    g_receding = bh.disk_redshift_factor(r, impact_parameter=-5.0)
+    g_none = bh.disk_redshift_factor(r, impact_parameter=0.0)
+    g_approaching = bh.disk_redshift_factor(r, impact_parameter=5.0)
+    assert g_receding < g_none < g_approaching
+    assert g_none < 1.0  # b=0: purely gravitational + orbital time dilation, no Doppler boost
+
+
+def test_disk_redshift_factor_approaches_one_far_from_the_black_hole():
+    bh = SchwarzschildBlackHole(M=1.0)
+    assert bh.disk_redshift_factor(1.0e6, impact_parameter=0.0) == pytest.approx(1.0, abs=1.0e-4)
+
+
+def test_tidal_acceleration_stretches_radially_compresses_transversely():
+    bh = SchwarzschildBlackHole(M=1.0)
+    radial, transverse = bh.tidal_acceleration(r=6.0, proper_separation=1.0)
+    assert radial > 0.0
+    assert transverse < 0.0
+    assert radial == pytest.approx(-2.0 * transverse)  # 2M/r^3 vs -M/r^3: exactly a factor of 2
+
+
+def test_tidal_acceleration_grows_closer_to_the_black_hole():
+    bh = SchwarzschildBlackHole(M=1.0)
+    radial_far, _ = bh.tidal_acceleration(r=20.0, proper_separation=1.0)
+    radial_near, _ = bh.tidal_acceleration(r=4.0, proper_separation=1.0)
+    assert radial_near > radial_far

physicskit/relativity/tests/test_shadow_render.py

@@ -0,0 +1,81 @@
+import numpy as np
+import pytest
+
+from physicskit.relativity.core.raytracer import OUTCOME_CAPTURED, OUTCOME_DISK
+from physicskit.relativity.visualizers.shadow_render import (
+    _redshift_factor,
+    plot_black_hole_shadow,
+    render_black_hole_image,
+)
+
+
+def test_a_zero_uses_schwarzschild_backend_and_a_positive_uses_kerr():
+    result_s = render_black_hole_image(M=1.0, a=0.0, ny=40, nx=40)
+    result_k = render_black_hole_image(M=1.0, a=0.5, ny=40, nx=40)
+    assert result_s["a"] == 0.0
+    assert result_k["a"] == 0.5
+    assert result_s["outcomes"].shape == (40, 40)
+    assert result_k["outcomes"].shape == (40, 40)
+
+
+def test_default_disk_inner_radius_is_isco():
+    from physicskit.relativity.chapters.kerr import KerrBlackHole
+
+    result_s = render_black_hole_image(M=1.0, a=0.0, ny=20, nx=20)
+    assert result_s["r_disk_inner"] == pytest.approx(6.0)
+
+    result_k = render_black_hole_image(M=1.0, a=0.9, ny=20, nx=20)
+    expected = KerrBlackHole(M=1.0, a=0.9).isco_radius(prograde=True)
+    assert result_k["r_disk_inner"] == pytest.approx(expected)
+
+
+def test_L_phi_grid_is_linear_in_alpha_and_antisymmetric():
+    # At theta_o=pi/2 (edge-on), L_phi = z-component of (ray_origin x view_dir)
+    # is exactly proportional to alpha (verified: coefficient +1 for the
+    # Schwarzschild camera_basis convention, which need not match the sign
+    # convention of the independent Kerr (alpha,beta)->(L,Q) parametrization
+    # -- each is internally self-consistent, but the two are not required to
+    # agree in handedness).
+    result = render_black_hole_image(M=1.0, a=0.0, ny=21, nx=21, inclination=np.pi / 2.0, screen_half_width=10.0)
+    alpha_row = np.linspace(-10.0, 10.0, 21)
+    L_phi_row = result["L_phi"][10, :]
+    assert np.allclose(L_phi_row, alpha_row, atol=1.0e-8) or np.allclose(L_phi_row, -alpha_row, atol=1.0e-8)
+    assert L_phi_row[0] == pytest.approx(-L_phi_row[-1])
+
+
+def test_redshift_factor_is_finite_and_asymmetric():
+    result = render_black_hole_image(M=1.0, a=0.0, ny=80, nx=80, r_disk_inner=6.0, r_disk_outer=20.0)
+    disk_mask = result["outcomes"] == OUTCOME_DISK
+    assert np.any(disk_mask)
+    g = _redshift_factor(result, disk_mask)
+    assert np.all(np.isfinite(g[disk_mask]))
+    assert np.all(g[disk_mask] > 0.0)
+
+    nx = result["outcomes"].shape[1]
+    left_mask = disk_mask.copy()
+    left_mask[:, nx // 2 :] = False
+    right_mask = disk_mask.copy()
+    right_mask[:, : nx // 2] = False
+    assert g[left_mask].mean() != pytest.approx(g[right_mask].mean(), rel=1.0e-3)
+
+
+def test_plot_black_hole_shadow_runs_with_and_without_redshift():
+    import matplotlib
+
+    matplotlib.use("Agg")
+    result = render_black_hole_image(M=1.0, a=0.0, ny=30, nx=30)
+    ax1 = plot_black_hole_shadow(result, redshift=False)
+    ax2 = plot_black_hole_shadow(result, redshift=True)
+    assert ax1 is not None
+    assert ax2 is not None
+
+
+def test_captured_pixels_are_black_regardless_of_redshift_option():
+    import matplotlib
+
+    matplotlib.use("Agg")
+    result = render_black_hole_image(M=1.0, a=0.0, ny=40, nx=40, r_disk_inner=1.0, r_disk_outer=0.0)
+    ax = plot_black_hole_shadow(result, redshift=True)
+    image = ax.images[0].get_array()
+    captured_mask = result["outcomes"] == OUTCOME_CAPTURED
+    assert np.allclose(np.asarray(image)[captured_mask][:, :3], 0.0)

physicskit/relativity/tests/test_tensors.py

@@ -0,0 +1,86 @@
+import numpy as np
+import pytest
+
+from physicskit.relativity.core.tensors import (
+    alcubierre_metric,
+    christoffel_symbols,
+    einstein_tensor,
+    flrw_metric,
+    kerr_metric_bl,
+    reissner_nordstrom_metric,
+    ricci_scalar,
+    schwarzschild_metric,
+)
+
+
+def test_schwarzschild_metric_signature_and_symmetry():
+    coords = np.array([0.0, 10.0, np.pi / 2.0, 0.3])
+    g = schwarzschild_metric(coords, M=1.0)
+    assert g.shape == (4, 4)
+    assert np.allclose(g, g.T)
+    assert g[0, 0] < 0.0  # timelike direction
+    assert g[1, 1] > 0.0 and g[2, 2] > 0.0 and g[3, 3] > 0.0
+
+
+def test_kerr_reduces_to_schwarzschild_at_zero_spin():
+    coords = np.array([0.0, 10.0, 1.1, 0.3])
+    g_kerr = kerr_metric_bl(coords, M=1.0, a=0.0)
+    g_schw = schwarzschild_metric(coords, M=1.0)
+    assert np.allclose(g_kerr, g_schw, atol=1e-10)
+
+
+def test_kerr_metric_has_frame_dragging_cross_term():
+    coords = np.array([0.0, 10.0, np.pi / 2.0, 0.0])
+    g = kerr_metric_bl(coords, M=1.0, a=0.9)
+    assert g[0, 3] != 0.0
+    assert g[0, 3] == pytest.approx(g[3, 0])
+
+
+def test_reissner_nordstrom_reduces_to_schwarzschild_at_zero_charge():
+    coords = np.array([0.0, 10.0, np.pi / 2.0, 0.3])
+    g_rn = reissner_nordstrom_metric(coords, M=1.0, Q=0.0)
+    g_schw = schwarzschild_metric(coords, M=1.0)
+    assert np.allclose(g_rn, g_schw)
+
+
+def test_flrw_metric_flat_matter_dominated():
+    a_func = lambda t: (1.0 + t) ** (2.0 / 3.0)
+    coords = np.array([0.0, 1.0, np.pi / 2.0, 0.0])
+    g = flrw_metric(coords, a_func, k=0.0)
+    assert g[0, 0] == pytest.approx(-1.0)
+    assert g[1, 1] == pytest.approx(a_func(0.0) ** 2)
+
+
+def test_flrw_metric_closed_and_open_use_sin_and_sinh_of_chi():
+    a_func = lambda t: 1.0
+    coords = np.array([0.0, 0.5, np.pi / 2.0, 0.0])
+    g_closed = flrw_metric(coords, a_func, k=1.0)
+    g_open = flrw_metric(coords, a_func, k=-1.0)
+    assert g_closed[2, 2] == pytest.approx(a_func(0.0) ** 2 * np.sin(0.5) ** 2)
+    assert g_open[2, 2] == pytest.approx(a_func(0.0) ** 2 * np.sinh(0.5) ** 2)
+
+
+def test_alcubierre_metric_is_flat_far_from_the_bubble():
+    coords = np.array([0.0, 1000.0, 1000.0, 1000.0])
+    g = alcubierre_metric(coords, v_s=2.0, sigma=8.0, R=1.0)
+    minkowski = np.diag([-1.0, 1.0, 1.0, 1.0])
+    assert np.allclose(g, minkowski, atol=1e-6)
+
+
+def test_christoffel_symbols_are_symmetric_in_lower_indices():
+    coords = np.array([0.0, 10.0, np.pi / 2.0, 0.0])
+    Gamma = christoffel_symbols(schwarzschild_metric, coords, {"M": 1.0})
+    assert Gamma.shape == (4, 4, 4)
+    assert np.allclose(Gamma, np.transpose(Gamma, (0, 2, 1)), atol=1e-8)
+
+
+def test_schwarzschild_vacuum_einstein_tensor_is_zero():
+    coords = np.array([0.0, 10.0, np.pi / 2.0, 0.3])
+    G = einstein_tensor(schwarzschild_metric, coords, {"M": 1.0})
+    assert np.max(np.abs(G)) < 1e-2
+
+
+def test_schwarzschild_ricci_scalar_is_zero():
+    coords = np.array([0.0, 8.0, 1.2, 0.0])
+    R = ricci_scalar(schwarzschild_metric, coords, {"M": 1.0})
+    assert abs(R) < 1e-2

physicskit/relativity/tests/test_timekeeping.py

@@ -0,0 +1,51 @@
+import pytest
+
+from physicskit.relativity.chapters.timekeeping import (
+    EARTH_RADIUS_M,
+    GPS_ORBITAL_RADIUS_M,
+    clock_rate_factor,
+    earth_mass_geometrized,
+    gps_relativistic_offset_per_day,
+)
+
+
+def test_earth_mass_geometrized_is_a_few_millimeters():
+    # GM_earth/c^2 is about 4.4 mm
+    M = earth_mass_geometrized()
+    assert pytest.approx(0.004435, abs=0.0002) == M
+
+
+def test_clock_rate_factor_defaults_m_to_earth_mass_geometrized():
+    rate_default = clock_rate_factor(EARTH_RADIUS_M, angular_velocity_si=0.0)
+    rate_explicit = clock_rate_factor(EARTH_RADIUS_M, angular_velocity_si=0.0, M=earth_mass_geometrized())
+    assert rate_default == pytest.approx(rate_explicit)
+
+
+def test_clock_rate_factor_static_is_pure_gravitational_redshift():
+    M = earth_mass_geometrized()
+    rate = clock_rate_factor(EARTH_RADIUS_M, angular_velocity_si=0.0, M=M)
+    expected = (1.0 - 2.0 * M / EARTH_RADIUS_M) ** 0.5
+    assert rate == pytest.approx(expected)
+
+
+def test_clock_rate_factor_less_than_one_and_decreases_with_rotation():
+    M = earth_mass_geometrized()
+    rate_static = clock_rate_factor(GPS_ORBITAL_RADIUS_M, 0.0, M=M)
+    rate_rotating = clock_rate_factor(GPS_ORBITAL_RADIUS_M, angular_velocity_si=1.0e-4, M=M)
+    assert rate_static < 1.0
+    assert rate_rotating < rate_static
+
+
+def test_gps_offset_matches_the_well_known_38_microseconds_per_day():
+    offset = gps_relativistic_offset_per_day()
+    assert offset == pytest.approx(38.6, abs=1.0)
+
+
+def test_gps_offset_is_positive_satellite_runs_fast():
+    assert gps_relativistic_offset_per_day() > 0.0
+
+
+def test_higher_orbit_increases_the_gravitational_advantage():
+    offset_low = gps_relativistic_offset_per_day(r_satellite=1.0e7)
+    offset_high = gps_relativistic_offset_per_day(r_satellite=4.0e7)
+    assert offset_high > offset_low

physicskit/relativity/tests/test_visualizers_misc.py

@@ -0,0 +1,115 @@
+"""Coverage for previously entirely untested plotting/interactive modules in
+physicskit.relativity.visualizers: spacetime_3d, spacetime_diagrams,
+wave_plots, interactive.interactive_shadow_image, and
+shadow_render.animate_shadow_spin_sweep. All built/drawn directly without
+GIF-saving, so fast except where noted @pytest.mark.slow (ray tracing)."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+from matplotlib.axes import Axes
+
+from physicskit.relativity.chapters.gw_merger import BinaryMerger
+from physicskit.relativity.visualizers.interactive import interactive_shadow_image
+from physicskit.relativity.visualizers.shadow_render import animate_shadow_spin_sweep, render_black_hole_image
+from physicskit.relativity.visualizers.spacetime_3d import flamm_paraboloid, plot_flamm_paraboloid
+from physicskit.relativity.visualizers.spacetime_diagrams import (
+    kruskal_coordinates,
+    penrose_carter_coordinates,
+    plot_kruskal_diagram,
+    plot_penrose_diagram,
+)
+from physicskit.relativity.visualizers.wave_plots import animate_wave_ripple, plot_strain_waveform, plot_wave_ripple
+
+
+def test_flamm_paraboloid_and_plot_given_and_default_ax():
+    M = 1.0
+    X, Y, Z = flamm_paraboloid(M, n_r=10, n_phi=10)
+    assert X.shape == Y.shape == Z.shape == (10, 10)
+    assert np.all(Z >= 0.0)
+
+    ax0 = plot_flamm_paraboloid(M)
+    assert isinstance(ax0, Axes)
+
+    fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
+    ax_given = plot_flamm_paraboloid(M, ax=ax)
+    assert ax_given is ax
+
+
+def test_kruskal_and_penrose_coordinates_map_horizon_to_light_cone():
+    M = 1.0
+    X, T = kruskal_coordinates(t=0.0, r=2.0 * M, M=M)
+    assert X == pytest.approx(0.0, abs=1e-8)
+    assert T == pytest.approx(0.0, abs=1e-8)
+
+    space, time = penrose_carter_coordinates(t=0.0, r=2.0 * M, M=M)
+    assert space == pytest.approx(0.0, abs=1e-8)
+    assert time == pytest.approx(0.0, abs=1e-8)
+
+
+def test_plot_kruskal_diagram_default_and_given_ax():
+    ax0 = plot_kruskal_diagram(M=1.0)
+    assert isinstance(ax0, Axes)
+
+    fig, ax = plt.subplots()
+    ax_given = plot_kruskal_diagram(M=1.0, ax=ax)
+    assert ax_given is ax
+
+
+def test_plot_penrose_diagram_default_and_given_ax():
+    ax0 = plot_penrose_diagram(M=1.0)
+    assert isinstance(ax0, Axes)
+
+    fig, ax = plt.subplots()
+    ax_given = plot_penrose_diagram(M=1.0, ax=ax)
+    assert ax_given is ax
+
+
+def test_plot_strain_waveform_default_ax_with_cross_polarization_and_merger_marker():
+    t = np.linspace(-10, 10, 50)
+    h_plus = np.sin(t)
+    h_cross = np.cos(t)
+    ax = plot_strain_waveform(t, h_plus, h_cross=h_cross, t_merger=0.0)
+    assert isinstance(ax, Axes)
+    assert len(ax.lines) == 3  # h_plus, h_cross, merger marker
+
+
+def test_plot_wave_ripple_default_and_given_ax():
+    merger = BinaryMerger(m1=30.0, m2=30.0, distance=1000.0)
+    ax0 = plot_wave_ripple(merger, t=0.0, t_merger=0.0, grid_size=20)
+    assert isinstance(ax0, Axes)
+
+    fig, ax = plt.subplots()
+    ax_given = plot_wave_ripple(merger, t=0.0, t_merger=0.0, ax=ax, grid_size=20)
+    assert ax_given is ax
+
+
+def test_animate_wave_ripple_builds_and_draws_a_frame():
+    merger = BinaryMerger(m1=30.0, m2=30.0, distance=1000.0)
+    t_values = np.linspace(-5.0, 5.0, 3)
+    anim = animate_wave_ripple(merger, t_merger=0.0, t_values=t_values, grid_size=15)
+    anim._draw_frame(1)
+    assert anim._fig.axes[0].get_title() == f"t={t_values[1]:.1f}"
+
+
+def test_interactive_shadow_image_returns_heatmap_figure():
+    result = render_black_hole_image(M=1.0, ny=10, nx=10)
+    fig = interactive_shadow_image(result)
+    assert fig.data[0].type == "heatmap"
+
+
+@pytest.mark.slow
+def test_animate_shadow_spin_sweep_builds_and_draws_a_frame():
+    a_values = np.array([0.0, 0.3])
+    anim = animate_shadow_spin_sweep(M=1.0, a_values=a_values, ny=10, nx=10)
+    anim._draw_frame(1)
+    assert f"a = {a_values[1]:.2f}" in anim._fig.axes[0].get_title()
+
+
+@pytest.mark.slow
+def test_animate_shadow_spin_sweep_default_a_values():
+    anim = animate_shadow_spin_sweep(M=1.0, ny=6, nx=6)
+    anim._draw_frame(0)
+    assert anim._fig.axes[0].get_title().startswith("a = 0.00")

physicskit/relativity/utils/__init__.py

@@ -0,0 +1 @@
+"""Physical constants and the geometrized (G=c=1) unit system."""

physicskit/relativity/utils/constants.py

@@ -0,0 +1,232 @@
+"""Physical constants and the geometrized unit system used throughout physicskit.relativity.
+
+Every calculation in this package is done in **geometrized units**
+(:math:`G = c = 1`), the standard convention in numerical relativity. In
+these units, mass, length, and time all share the same dimension: a mass
+:math:`M` (in kilograms) corresponds to a length
+:math:`GM/c^2` and a time :math:`GM/c^3`. Concretely, a Schwarzschild black
+hole of mass :math:`M` (in geometrized length units) has its horizon at
+:math:`r = 2M`, its photon sphere at :math:`r = 3M`, and its innermost
+stable circular orbit at :math:`r = 6M` -- clean numbers that would carry
+awkward factors of :math:`G` and :math:`c` in SI units.
+
+Use :func:`solar_masses_to_geometrized` to convert a physical mass (in solar
+masses) into this geometrized length, and :func:`geometrized_to_seconds` /
+:func:`geometrized_to_meters` to convert results back to physical units for
+reporting.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from physicskit import constants as _const
+
+__all__ = [
+    "C_SI",
+    "G_SI",
+    "PARSEC_M",
+    "SOLAR_MASS_KG",
+    "check_geometrized_distance",
+    "check_geometrized_mass",
+    "geometrized_to_meters",
+    "geometrized_to_seconds",
+    "geometrized_to_solar_masses",
+    "seconds_to_geometrized",
+    "solar_masses_to_geometrized",
+]
+
+#: Newton's gravitational constant, in m^3 kg^-1 s^-2.
+G_SI = _const.G
+
+#: Speed of light in vacuum, in m/s.
+C_SI = _const.C
+
+#: Solar mass, in kg.
+SOLAR_MASS_KG = _const.SOLAR_MASS_KG
+
+#: One parsec, in meters.
+PARSEC_M = _const.PARSEC_M
+
+
+def solar_masses_to_geometrized(mass_solar):
+    """Convert a mass in solar masses to geometrized length units (meters).
+
+    .. math::
+
+        M_{\\text{geom}} = \\frac{G M_\\odot}{c^2} \\times \\left(\\frac{M}{M_\\odot}\\right)
+
+    Parameters
+    ----------
+    mass_solar : float or array_like
+        Mass in units of the Sun's mass.
+
+    Returns
+    -------
+    float or ndarray
+        Mass expressed as a geometrized length, in meters. For example,
+        this is the horizon radius (up to the factor of 2) of a
+        Schwarzschild black hole of that mass.
+
+    Examples
+    --------
+    >>> round(float(solar_masses_to_geometrized(1.0)), 2)
+    1476.67
+    """
+    return np.asarray(mass_solar) * G_SI * SOLAR_MASS_KG / C_SI**2
+
+
+def geometrized_to_meters(length_geom):
+    """Identity conversion: geometrized lengths are already in meters.
+
+    Provided for symmetry and readability at call sites (e.g.
+    ``geometrized_to_meters(r_isco)``); geometrized *length* units coincide
+    with SI meters by construction (:math:`G = c = 1`).
+    """
+    return np.asarray(length_geom)
+
+
+def geometrized_to_seconds(length_geom):
+    """Convert a geometrized length (or time expressed as a length, :math:`ct`) to seconds.
+
+    Parameters
+    ----------
+    length_geom : float or array_like
+        A geometrized quantity with dimensions of length, e.g. :math:`c
+        t` for a geometrized time.
+
+    Returns
+    -------
+    float or ndarray
+        Time in seconds.
+    """
+    return np.asarray(length_geom) / C_SI
+
+
+def seconds_to_geometrized(time_s):
+    """Convert a time in seconds to a geometrized length (:math:`ct`, in meters)."""
+    return np.asarray(time_s) * C_SI
+
+
+def geometrized_to_solar_masses(mass_geom):
+    """Convert a geometrized mass (length, in meters) back to solar masses.
+
+    Parameters
+    ----------
+    mass_geom : float or array_like
+        Mass expressed as a geometrized length (meters).
+
+    Returns
+    -------
+    float or ndarray
+        Mass in units of the Sun's mass.
+
+    Examples
+    --------
+    >>> round(float(geometrized_to_solar_masses(solar_masses_to_geometrized(30.0))), 6)
+    30.0
+    """
+    return np.asarray(mass_geom) * C_SI**2 / (G_SI * SOLAR_MASS_KG)
+
+
+#: Below this, a mass argument is almost certainly an unconverted physical
+#: value rather than a geometrized length: it's lighter than any known or
+#: theorized neutron star (~1 solar mass ~ 1477 m), let alone a black hole.
+_MIN_PLAUSIBLE_COMPACT_OBJECT_MASS_M = 100.0
+
+#: Below this, a distance argument is almost certainly an unconverted
+#: physical value: it's many orders of magnitude short of even 1 AU
+#: (~1.5e11 m), let alone an astrophysical source distance.
+_MIN_PLAUSIBLE_ASTROPHYSICAL_DISTANCE_M = 1.0e9
+
+
+def check_geometrized_mass(value, name="mass"):
+    """Warn if `value` looks like an unconverted physical mass rather than a geometrized length.
+
+    Intended for classes that require an *absolute* geometrized mass with
+    no normalized (``M=1``) convention available -- :class:`~physicskit.relativity.chapters.gw_merger.BinaryMerger`
+    is the motivating case: its radiated strain amplitude depends on the
+    true physical scale, so silently passing a raw solar-mass count (e.g.
+    ``36.0`` instead of ``solar_masses_to_geometrized(36.0)``) doesn't
+    raise an error -- it just produces a "chirp" that never actually
+    accumulates any phase, an easy mistake to miss since nothing crashes.
+
+    This is a heuristic plausibility check, not a unit system: it only
+    catches the common case of a compact-object mass that's wildly too
+    small to be a geometrized length. It does not (and cannot, without
+    real unit tracking) catch every possible mis-conversion.
+
+    Parameters
+    ----------
+    value : float
+        The mass argument to check, in whatever units the caller passed.
+    name : str, default="mass"
+        Parameter name to mention in the warning message.
+
+    Examples
+    --------
+    >>> import warnings
+    >>> with warnings.catch_warnings(record=True) as w:
+    ...     warnings.simplefilter("always")
+    ...     check_geometrized_mass(36.0, name="m1")  # raw solar masses -- wrong
+    ...     len(w)
+    1
+    >>> with warnings.catch_warnings(record=True) as w:
+    ...     warnings.simplefilter("always")
+    ...     check_geometrized_mass(solar_masses_to_geometrized(36.0), name="m1")  # correct
+    ...     len(w)
+    0
+    """
+    if 0.0 < value < _MIN_PLAUSIBLE_COMPACT_OBJECT_MASS_M:
+        warnings.warn(
+            f"{name}={value!r} is implausibly small for a geometrized-unit mass "
+            f"(1 solar mass is ~{solar_masses_to_geometrized(1.0):.1f} m; even the "
+            f"lightest known neutron star is a large fraction of that). Did you "
+            f"forget to convert with solar_masses_to_geometrized()? If this value "
+            f"is intentional (e.g. a sub-solar-mass primordial black hole), ignore "
+            f"this warning.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+
+def check_geometrized_distance(value, name="distance"):
+    """Warn if `value` looks like an unconverted physical distance rather than a geometrized length.
+
+    Same rationale as :func:`check_geometrized_mass`, for distance
+    arguments: a raw parsec/Mpc count (e.g. ``410.0`` instead of
+    ``410.0 * PARSEC_M * 1e6``) is many orders of magnitude too small to
+    be a real geometrized distance, but doesn't raise an error on its own.
+
+    Parameters
+    ----------
+    value : float
+        The distance argument to check, in whatever units the caller passed.
+    name : str, default="distance"
+        Parameter name to mention in the warning message.
+
+    Examples
+    --------
+    >>> import warnings
+    >>> with warnings.catch_warnings(record=True) as w:
+    ...     warnings.simplefilter("always")
+    ...     check_geometrized_distance(410.0, name="distance")  # raw Mpc -- wrong
+    ...     len(w)
+    1
+    >>> with warnings.catch_warnings(record=True) as w:
+    ...     warnings.simplefilter("always")
+    ...     check_geometrized_distance(410.0e6 * PARSEC_M, name="distance")  # correct
+    ...     len(w)
+    0
+    """
+    if 0.0 < value < _MIN_PLAUSIBLE_ASTROPHYSICAL_DISTANCE_M:
+        warnings.warn(
+            f"{name}={value!r} is implausibly small for a geometrized-unit distance "
+            f"(1 parsec is ~{PARSEC_M:.3e} m). Did you forget to convert, e.g. "
+            f"distance_mpc * 1e6 * PARSEC_M? If this value is intentional (e.g. a "
+            f"laboratory- or Earth-orbit-scale distance), ignore this warning.",
+            UserWarning,
+            stacklevel=3,
+        )