physicskit 0.1.0__py3-none-any.whl

physicskit/relativity/chapters/kerr.py

@@ -0,0 +1,371 @@
+"""The Kerr black hole: frame dragging, the ergosphere, and the Penrose process.
+
+Roy Kerr's 1963 exact solution describes a rotating black hole, characterized
+by mass :math:`M` and spin parameter :math:`a = J/M \\in [0, M)`. Rotation
+drags spacetime itself around with it (frame dragging / the Lense-Thirring
+effect), creates a region outside the horizon -- the ergosphere -- where no
+observer can remain stationary, and permits Penrose's remarkable 1969
+proposal: a particle that splits inside the ergosphere can send one fragment
+into the black hole with *negative* energy (as measured at infinity), so the
+other fragment escapes carrying away more energy than the original particle
+had -- extracting rotational energy from the black hole itself.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.relativity.core.geodesics import integrate_kerr_equatorial_geodesic
+
+__all__ = ["KerrBlackHole"]
+
+
+class KerrBlackHole:
+    """A rotating black hole of mass ``M`` and spin parameter ``a``, in geometrized units.
+
+    Parameters
+    ----------
+    M : float, default=1.0
+        Mass, in geometrized length units.
+    a : float, default=0.0
+        Spin parameter :math:`a = J/M`, with :math:`0 \\le a < M`.
+        ``a=0`` recovers Schwarzschild.
+    """
+
+    def __init__(self, M=1.0, a=0.0):
+        if not (0.0 <= a < M):
+            raise ValueError("spin parameter a must satisfy 0 <= a < M")
+        self.M = M
+        self.a = a
+
+    @property
+    def outer_horizon_radius(self):
+        """Event horizon radius, :math:`r_+ = M + \\sqrt{M^2 - a^2}`."""
+        return self.M + np.sqrt(self.M**2 - self.a**2)
+
+    @property
+    def inner_horizon_radius(self):
+        """Inner (Cauchy) horizon radius, :math:`r_- = M - \\sqrt{M^2 - a^2}`."""
+        return self.M - np.sqrt(self.M**2 - self.a**2)
+
+    @property
+    def dimensionless_spin(self):
+        """Dimensionless spin :math:`a_* = a/M \\in [0, 1)`."""
+        return self.a / self.M
+
+    def ergosphere_radius(self, theta):
+        """Static-limit (ergosphere outer boundary) radius at polar angle ``theta``.
+
+        .. math::
+
+            r_E(\\theta) = M + \\sqrt{M^2 - a^2\\cos^2\\theta}
+
+        The ergosphere is the region :math:`r_+ < r < r_E(\\theta)`, where
+        the ``t``-Killing vector becomes spacelike: no observer can remain
+        at fixed :math:`(r, \\theta, \\phi)` there, no matter how powerful
+        their rocket -- they are inevitably dragged around in :math:`\\phi`
+        by the rotating spacetime itself.
+
+        Parameters
+        ----------
+        theta : float or array_like
+            Polar angle (``pi/2`` is the equator, where the ergosphere is
+            widest, :math:`r_E = 2M`).
+
+        Returns
+        -------
+        float or ndarray
+        """
+        theta = np.asarray(theta, dtype=np.float64)
+        return self.M + np.sqrt(self.M**2 - self.a**2 * np.cos(theta) ** 2)
+
+    def is_inside_ergosphere(self, r, theta):
+        """Whether a point :math:`(r, \\theta)` lies inside the ergosphere.
+
+        Parameters
+        ----------
+        r : float
+            Radial coordinate.
+        theta : float
+            Polar angle.
+
+        Returns
+        -------
+        bool
+        """
+        return self.outer_horizon_radius < r < self.ergosphere_radius(theta)
+
+    def isco_radius(self, prograde=True):
+        """Innermost stable circular equatorial orbit radius (Bardeen-Press-Teukolsky 1972).
+
+        .. math::
+
+            Z_1 = 1 + (1-a_*^2)^{1/3}\\left[(1+a_*)^{1/3} + (1-a_*)^{1/3}\\right], \\quad
+            Z_2 = \\sqrt{3a_*^2 + Z_1^2}
+
+        .. math::
+
+            \\frac{r_{\\text{ISCO}}}{M} = 3 + Z_2 \\mp
+                \\sqrt{(3-Z_1)(3+Z_1+2Z_2)}
+
+        with the :math:`-` sign for a prograde (co-rotating) orbit and
+        :math:`+` for retrograde. Prograde ISCOs shrink toward the horizon
+        as spin increases (:math:`r_{\\text{ISCO}} \\to M` as
+        :math:`a \\to M`); retrograde ISCOs grow toward :math:`9M`.
+
+        Parameters
+        ----------
+        prograde : bool, default=True
+            Whether the orbit co-rotates with the black hole.
+
+        Returns
+        -------
+        float
+        """
+        a_star = self.dimensionless_spin
+        Z1 = 1.0 + (1.0 - a_star**2) ** (1.0 / 3.0) * ((1.0 + a_star) ** (1.0 / 3.0) + (1.0 - a_star) ** (1.0 / 3.0))
+        Z2 = np.sqrt(3.0 * a_star**2 + Z1**2)
+        sign = -1.0 if prograde else 1.0
+        return self.M * (3.0 + Z2 + sign * np.sqrt((3.0 - Z1) * (3.0 + Z1 + 2.0 * Z2)))
+
+    def frame_dragging_angular_velocity(self, r):
+        """Angular velocity of a zero-angular-momentum observer (ZAMO) in the equatorial plane.
+
+        .. math::
+
+            \\omega(r) = -\\frac{g_{t\\phi}}{g_{\\phi\\phi}}
+                       = \\frac{2Ma}{r^3 + a^2 r + 2Ma^2}
+
+        The rate at which locally non-rotating observers are swept around
+        in :math:`\\phi` purely by the geometry -- frame dragging. At large
+        :math:`r` this falls off as :math:`2Ma/r^3`, the classic
+        Lense-Thirring precession rate; it rises sharply approaching the
+        ergosphere, where even a photon fired against the rotation is
+        dragged forward.
+
+        Parameters
+        ----------
+        r : float or array_like
+            Equatorial radial coordinate, :math:`r > r_+`.
+
+        Returns
+        -------
+        float or ndarray
+        """
+        r = np.asarray(r, dtype=np.float64)
+        M, a = self.M, self.a
+        return 2.0 * M * a / (r**3 + a**2 * r + 2.0 * M * a**2)
+
+    def irreducible_mass(self):
+        """Irreducible mass, :math:`M_{\\text{irr}} = \\sqrt{M r_+ / 2}`.
+
+        The irreducible mass can never decrease in any classical process
+        (Hawking's area theorem: it is proportional to
+        :math:`\\sqrt{\\text{horizon area}}`), which is what caps how much
+        rotational energy the Penrose process can extract.
+
+        Returns
+        -------
+        float
+        """
+        return np.sqrt(self.M * self.outer_horizon_radius / 2.0)
+
+    def max_penrose_efficiency(self):
+        """Maximum fraction of the black hole's mass extractable via the Penrose process.
+
+        .. math::
+
+            \\eta_{\\max} = 1 - \\frac{M_{\\text{irr}}}{M}
+                          = 1 - \\sqrt{\\frac{r_+}{2M}}
+
+        Rises from 0 at :math:`a=0` to :math:`1 - 1/\\sqrt{2} \\approx
+        29.3\\%` for an extremal (:math:`a \\to M`) black hole.
+
+        Returns
+        -------
+        float
+        """
+        return 1.0 - self.irreducible_mass() / self.M
+
+    def penrose_energy_gain(self, initial_energy, fragment_energy_infalling):
+        """Energy gained by the escaping fragment in a Penrose-process split.
+
+        A particle of specific energy ``initial_energy`` (measured at
+        infinity) splits, inside the ergosphere, into two fragments. If one
+        fragment falls into the horizon with negative specific energy
+        ``fragment_energy_infalling`` (possible only inside the ergosphere,
+        where the ``t``-Killing vector is spacelike), energy conservation at
+        the split point requires the escaping fragment to carry away
+
+        .. math::
+
+            E_{\\text{out}} = E_{\\text{in}} - E_{\\text{infalling}} > E_{\\text{in}}
+
+        Parameters
+        ----------
+        initial_energy : float
+            Specific energy of the infalling particle before it splits.
+        fragment_energy_infalling : float
+            Specific energy of the fragment that falls into the horizon;
+            must be negative for energy to be extracted.
+
+        Returns
+        -------
+        float
+            Specific energy of the escaping fragment.
+
+        Examples
+        --------
+        >>> bh = KerrBlackHole(M=1.0, a=0.9)
+        >>> e_out = bh.penrose_energy_gain(initial_energy=1.0, fragment_energy_infalling=-0.05)
+        >>> e_out > 1.0
+        True
+        """
+        if fragment_energy_infalling >= 0.0:
+            raise ValueError("a Penrose process requires a negative-energy infalling fragment")
+        return initial_energy - fragment_energy_infalling
+
+    def circular_orbit_conserved_quantities(self, r0, prograde=True):
+        """Conserved specific energy and angular momentum of a circular equatorial orbit.
+
+        Standard Bardeen-Press-Teukolsky (1972) result:
+
+        .. math::
+
+            E = \\frac{r^{3/2} - 2Mr^{1/2} + a M^{1/2}}
+                     {r^{3/4}\\sqrt{r^{3/2} - 3Mr^{1/2} + 2aM^{1/2}}}, \\qquad
+            L = \\frac{M^{1/2}\\left(r^2 - 2aM^{1/2}r^{1/2} + a^2\\right)}
+                     {r^{3/4}\\sqrt{r^{3/2} - 3Mr^{1/2} + 2aM^{1/2}}}
+
+        with :math:`a \\to -a` for a retrograde orbit.
+
+        Parameters
+        ----------
+        r0 : float
+            Orbital radius; should exceed the appropriate
+            :meth:`isco_radius` for the orbit to be stable.
+        prograde : bool, default=True
+            Whether the orbit co-rotates with the black hole.
+
+        Returns
+        -------
+        E : float
+            Specific energy.
+        L : float
+            Specific angular momentum.
+        """
+        M = self.M
+        a_eff = self.a if prograde else -self.a
+        r = r0
+        denom = r**0.75 * np.sqrt(r**1.5 - 3.0 * M * r**0.5 + 2.0 * a_eff * M**0.5)
+        E = (r**1.5 - 2.0 * M * r**0.5 + a_eff * M**0.5) / denom
+        L = np.sqrt(M) * (r**2 - 2.0 * a_eff * np.sqrt(M) * r**0.5 + a_eff**2) / denom
+        return E, L
+
+    def integrate_equatorial_geodesic(self, r0, E, L, mu2, dtau, n_steps):
+        """Integrate an equatorial Kerr geodesic of conserved energy ``E`` and momentum ``L``.
+
+        Parameters
+        ----------
+        r0 : float
+            Initial radius.
+        E : float
+            Conserved specific energy.
+        L : float
+            Conserved specific angular momentum.
+        mu2 : float
+            ``1.0`` for a timelike geodesic, ``0.0`` for a null (photon) geodesic.
+        dtau : float
+            Affine-parameter (or proper-time) step size.
+        n_steps : int
+            Maximum number of steps.
+
+        Returns
+        -------
+        dict of str -> ndarray
+            Keys ``"t"``, ``"r"``, ``"phi"``, ``"ur"``, plus ``"norm"``: the
+            four-velocity normalization :math:`g_{\\mu\\nu}u^\\mu u^\\nu`
+            at every step (should stay close to :math:`-\\mu^2`; its spread
+            measures integration error).
+        """
+        M, a = self.M, self.a
+        Delta0 = r0**2 - 2.0 * M * r0 + a**2
+        A0 = E * (r0**2 + a**2) - L * a
+        ur0 = np.sqrt(max((A0**2 - Delta0 * (mu2 * r0**2 + (L - a * E) ** 2)) / r0**4, 0.0))
+        y0 = np.array([0.0, r0, 0.0, -ur0])
+
+        trajectory, n_valid = integrate_kerr_equatorial_geodesic(y0, E, L, a, M, mu2, dtau, n_steps)
+        trajectory = trajectory[: n_valid + 1]
+        t, r, phi, ur = trajectory.T
+
+        Delta = r**2 - 2.0 * M * r + a**2
+        A = E * (r**2 + a**2) - L * a
+        ut = (-a * (a * E - L) + (r**2 + a**2) * A / Delta) / r**2
+        uphi = (-(a * E - L) + a * A / Delta) / r**2
+
+        g_tt = -(1.0 - 2.0 * M / r)
+        g_tphi = -2.0 * M * a / r
+        g_rr = r**2 / Delta
+        g_phiphi = r**2 + a**2 + 2.0 * M * a**2 / r
+        norm = g_tt * ut**2 + 2.0 * g_tphi * ut * uphi + g_rr * ur**2 + g_phiphi * uphi**2
+
+        return {"t": t, "r": r, "phi": phi, "ur": ur, "ut": ut, "uphi": uphi, "norm": norm}
+
+    def keplerian_angular_velocity(self, r, prograde=True):
+        """Coordinate angular velocity of a circular equatorial geodesic orbit.
+
+        .. math::
+
+            \\Omega(r) = \\pm\\frac{\\sqrt{M}}{r^{3/2} \\pm a\\sqrt{M}}
+
+        with the upper sign for a prograde (co-rotating) orbit. Reduces to
+        the Keplerian :math:`\\sqrt{M/r^3}` at :math:`a=0`.
+
+        Parameters
+        ----------
+        r : float or array_like
+            Orbital radius.
+        prograde : bool, default=True
+            Whether the orbit co-rotates with the black hole.
+
+        Returns
+        -------
+        float or ndarray
+        """
+        r = np.asarray(r, dtype=np.float64)
+        sign = 1.0 if prograde else -1.0
+        return sign * np.sqrt(self.M) / (r**1.5 + sign * self.a * np.sqrt(self.M))
+
+    def disk_redshift_factor(self, r, impact_parameter, prograde=True):
+        """Combined gravitational + Doppler redshift factor for a circularly orbiting disk emitter.
+
+        Same construction as
+        :meth:`physicskit.relativity.chapters.schwarzschild.SchwarzschildBlackHole.disk_redshift_factor`,
+        :math:`g = 1/[u^t(1 - b\\Omega)]`, using the Kerr equatorial metric
+        and :meth:`keplerian_angular_velocity` in place of their
+        Schwarzschild counterparts.
+
+        Parameters
+        ----------
+        r : float or array_like
+            Disk radius at emission.
+        impact_parameter : float or array_like
+            The received photon's impact parameter :math:`b = L_{\\text{ph}}/E_{\\text{ph}}`.
+        prograde : bool, default=True
+            Whether the disk co-rotates with the black hole.
+
+        Returns
+        -------
+        float or ndarray
+            The redshift factor :math:`g`.
+        """
+        r = np.asarray(r, dtype=np.float64)
+        b = np.asarray(impact_parameter, dtype=np.float64)
+        M, a = self.M, self.a
+        Omega = self.keplerian_angular_velocity(r, prograde=prograde)
+
+        g_tt = -(1.0 - 2.0 * M / r)
+        g_tphi = -2.0 * M * a / r
+        g_phiphi = r**2 + a**2 + 2.0 * M * a**2 / r
+        u_t = 1.0 / np.sqrt(-(g_tt + 2.0 * g_tphi * Omega + g_phiphi * Omega**2))
+        return 1.0 / (u_t * (1.0 - b * Omega))

physicskit/relativity/chapters/lensing.py

@@ -0,0 +1,196 @@
+"""Point-source gravitational lensing: Einstein rings and multiple images.
+
+When a point source, a point (or compact) lens, and an observer are exactly
+aligned, the source's light is bent symmetrically around the lens into a
+complete ring -- an Einstein ring, predicted by Einstein in 1936 (though he
+believed it would never be observable) and first imaged for a galaxy-scale
+lens in 1988. For any other alignment, a point lens splits a single source
+into exactly two images, one on each side of the lens, with a combined
+brightness that can be dramatically magnified -- the basis of gravitational
+microlensing surveys used to detect exoplanets and dark, compact objects.
+This module solves the thin-lens equation analytically in the weak-field
+(point-mass) limit, and provides the exact (numerically integrated)
+deflection angle for exploring strong-field corrections near the photon
+sphere.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["PointMassLens", "exact_deflection_angle"]
+
+
+class PointMassLens:
+    """A point-mass (weak-field) gravitational lens: Einstein ring, images, and magnification.
+
+    Uses the thin-lens approximation with the leading-order deflection
+    angle :math:`\\hat\\alpha(b) = 4M/b`, valid whenever the source is not
+    aligned so closely that its image angle approaches the photon sphere
+    (see :func:`exact_deflection_angle` for the strong-field case).
+
+    Parameters
+    ----------
+    M : float
+        Lens mass, in geometrized units.
+    D_L : float
+        Observer-lens distance, in the same geometrized length units as ``M``.
+    D_S : float
+        Observer-source distance (:math:`D_S > D_L`), in the same units as ``M``.
+
+    Notes
+    -----
+    Every formula here is a ratio of ``M``, ``D_L``, ``D_S`` (angles and
+    magnifications, not an absolute strain), so it is scale-invariant: a
+    normalized convention (``M=1``, distances "in units of M") gives
+    exactly the same angles as real SI-consistent geometrized values would.
+    Unlike :class:`~physicskit.relativity.chapters.gw_merger.BinaryMerger`,
+    there is no absolute-scale trap here -- any self-consistent unit choice
+    works.
+
+    Attributes
+    ----------
+    D_LS : float
+        Lens-source distance, :math:`D_S - D_L` (flat-space subtraction;
+        this is a local, non-cosmological thin-lens treatment).
+    """
+
+    def __init__(self, M, D_L, D_S):
+        if D_S <= D_L:
+            raise ValueError("D_S must exceed D_L (the source must be behind the lens)")
+        self.M = M
+        self.D_L = D_L
+        self.D_S = D_S
+        self.D_LS = D_S - D_L
+
+    def einstein_angle(self):
+        """Einstein ring angular radius, :math:`\\theta_E = \\sqrt{4M D_{LS}/(D_L D_S)}`.
+
+        The angular radius at which a perfectly aligned (:math:`\\beta=0`)
+        point source appears as a complete ring.
+
+        Returns
+        -------
+        float
+        """
+        return np.sqrt(4.0 * self.M * self.D_LS / (self.D_L * self.D_S))
+
+    def image_angles(self, beta):
+        """Angular positions of the two images of a source at angular offset ``beta``.
+
+        Solves the thin-lens equation
+        :math:`\\beta = \\theta - \\theta_E^2/\\theta` (equivalent to a
+        quadratic in :math:`\\theta`) exactly:
+
+        .. math::
+
+            \\theta_\\pm = \\frac{\\beta \\pm \\sqrt{\\beta^2 + 4\\theta_E^2}}{2}
+
+        Parameters
+        ----------
+        beta : float
+            True (unlensed) angular offset of the source from the lens.
+
+        Returns
+        -------
+        theta_plus : float
+            Position of the primary image, on the same side as the source
+            (:math:`\\theta_+ > 0`).
+        theta_minus : float
+            Position of the secondary image, on the opposite side
+            (:math:`\\theta_- < 0`), closer to the lens and fainter.
+
+        Examples
+        --------
+        >>> lens = PointMassLens(M=1.0, D_L=1000.0, D_S=2000.0)
+        >>> theta_plus, theta_minus = lens.image_angles(beta=0.0)
+        >>> bool(np.isclose(theta_plus, lens.einstein_angle()))
+        True
+        >>> bool(np.isclose(theta_minus, -lens.einstein_angle()))
+        True
+        """
+        theta_E = self.einstein_angle()
+        discriminant = np.sqrt(beta**2 + 4.0 * theta_E**2)
+        theta_plus = (beta + discriminant) / 2.0
+        theta_minus = (beta - discriminant) / 2.0
+        return theta_plus, theta_minus
+
+    def magnification(self, beta):
+        """Magnification of each image, and their sum (total observed brightening).
+
+        Standard point-lens (Paczynski 1986) result, with
+        :math:`u = \\beta/\\theta_E`:
+
+        .. math::
+
+            \\mu_\\pm = \\frac{1}{2}\\left[\\frac{u^2+2}{u\\sqrt{u^2+4}} \\pm 1\\right]
+
+        Parameters
+        ----------
+        beta : float
+            True angular offset of the source from the lens (``beta != 0``).
+
+        Returns
+        -------
+        mu_plus : float
+            Magnification of the primary image (always :math:`> 1`).
+        mu_minus : float
+            Magnification of the secondary image (its absolute value is
+            :math:`< 1`; it has opposite parity, conventionally signed
+            negative).
+        total : float
+            Total observed magnification, :math:`|\\mu_+| + |\\mu_-|`.
+        """
+        theta_E = self.einstein_angle()
+        u = beta / theta_E
+        base = (u**2 + 2.0) / (u * np.sqrt(u**2 + 4.0))
+        mu_plus = 0.5 * (base + 1.0)
+        mu_minus = 0.5 * (base - 1.0)
+        return mu_plus, mu_minus, abs(mu_plus) + abs(mu_minus)
+
+
+def exact_deflection_angle(bh, impact_parameter, r_far=2.0e5, dtau=None, n_steps=300000):
+    """Exact (numerically integrated) Schwarzschild light deflection angle.
+
+    Unlike the weak-field :math:`4M/b` formula used by
+    :class:`PointMassLens`, this integrates the actual null geodesic from
+    far away, through closest approach, and back out to far away, and
+    measures the total bending directly -- valid arbitrarily close to the
+    photon sphere (where the deflection formally diverges as
+    :math:`b \\to b_c = 3\\sqrt{3}M`).
+
+    Parameters
+    ----------
+    bh : SchwarzschildBlackHole
+        The lensing black hole.
+    impact_parameter : float
+        Impact parameter :math:`b`; must exceed
+        ``bh.critical_impact_parameter`` for the photon to escape.
+    r_far : float, default=2e5
+        Starting (and target ending) radius, used to approximate "infinity."
+    dtau : float, optional
+        Affine-parameter step size. Defaults to ``3 * r_far / n_steps``, which
+        comfortably covers the round trip to and from ``r_far`` while still
+        resolving the near-photon-sphere region for impact parameters not
+        too close to critical.
+    n_steps : int, default=300000
+        Maximum integration steps.
+
+    Returns
+    -------
+    float
+        The deflection angle, in radians.
+
+    Examples
+    --------
+    >>> from physicskit.relativity.chapters.schwarzschild import SchwarzschildBlackHole
+    >>> bh = SchwarzschildBlackHole(M=1.0)
+    >>> delta = exact_deflection_angle(bh, impact_parameter=50.0)
+    >>> bool(abs(delta - bh.light_deflection_angle(50.0)) < 0.01)
+    True
+    """
+    if dtau is None:
+        dtau = 3.0 * r_far / n_steps
+    y0 = bh.null_geodesic_initial_state(r0=r_far, impact_parameter=impact_parameter, ingoing=True)
+    traj = bh.integrate_geodesic(y0, dtau=dtau, n_steps=n_steps)
+    return (traj["phi"][-1] - traj["phi"][0]) - np.pi