:orphan:

Examples
========

Runnable demonstrations of General Relativity's classic results, from the
Schwarzschild and Kerr black-hole solutions through cosmology and
gravitational-wave astrophysics.

Each script in this gallery is self-contained and can be run directly with
``python examples/relativity/<section>/<script>.py``. Every script also
carries an RST module docstring as its title/description and uses ``# %%``
markers to split narrative text from code, which is exactly what
Sphinx-Gallery renders into the pages below -- the script *is* the source of
truth for what you see, not a copy of it.

Sections
--------

- **schwarzschild** -- the non-rotating black hole: light bending and the
  photon-sphere shadow, perihelion precession (the anomaly that first
  confirmed General Relativity), tidal "spaghettification," and the GPS
  relativistic correction you carry in your pocket.
- **kerr** -- the rotating black hole: frame dragging, the ergosphere, the
  Penrose process, and the Kerr shadow and redshift.
- **spacetime_geometry** -- curvature itself: validating the curvature engine
  against Einstein's vacuum field equations, Flamm's paraboloid (gravity as
  curved geometry rather than a force), and Kruskal-Szekeres/Penrose-Carter
  diagrams of spacetime's true shape.
- **lensing** -- Einstein rings, multiple images, and microlensing.
- **neutron_star** -- solving the TOV equations for the neutron-star maximum
  mass.
- **cosmology** -- the expanding universe: Hubble's law and the Friedmann
  equations.
- **gravitational_waves** -- the Hulse-Taylor binary pulsar's orbital decay,
  the first (indirect) evidence for gravitational waves, and the GW150914
  binary-merger chirp, the first direct detection.
- **interactive** -- interactive Plotly visualizations of orbits and the
  black-hole shadow.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Cosmology
----------

FLRW cosmic expansion and the distance-redshift relation.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In 1929, Edwin Hubble found that distant galaxies recede from us at a rate proportional to their distance -- direct observational evidence that the universe is expanding, exactly as Einstein&#x27;s field equations (applied to a homogeneous, isotropic universe by Friedmann and Lemaitre) had already predicted. Plugging the Friedmann-Lemaitre-Robertson-Walker metric into Einstein&#x27;s equations for a universe filled with radiation, matter, spatial curvature, and a cosmological constant \Lambda gives the Friedmann equation for the expansion rate H(a) = \dot a / a in terms of the scale factor a (normalized to a=1 today):">

.. only:: html

  .. image:: /api/gallery/relativity/cosmology/images/thumb/sphx_glr_plot_flrw_expansion_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/cosmology/plot_flrw_expansion`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The expanding universe: Hubble's law and the Friedmann equations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Gravitational waves
---------------------

Binary black hole and binary neutron star inspiral chirps and ringdown.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="On September 14, 2015, LIGO detected a gravitational wave chirp from two black holes (roughly 36 and 29 solar masses) spiraling together and merging 1.3 billion light-years away -- the first direct detection of gravitational waves, a phenomenon predicted by Einstein in 1916 that took a century to observe. This example generates a toy inspiral-merger-ringdown (IMR) waveform for a comparable system using the leading-order (Newtonian quadrupole) inspiral formula, in which the gravitational-wave frequency sweeps upward as">

.. only:: html

  .. image:: /api/gallery/relativity/gravitational_waves/images/thumb/sphx_glr_plot_binary_merger_chirp_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/gravitational_waves/plot_binary_merger_chirp`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">GW150914: the first direct detection of gravitational waves</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="On 17 August 2017, LIGO and Virgo detected the inspiral of two neutron stars -- far lighter than any binary black hole seen before, and correspondingly slower-chirping: the signal remained in the detectors&#x27; sensitive band for over a minute, instead of the fraction of a second GW150914&#x27;s ~30-solar-mass black holes took. The measured chirp mass,">

.. only:: html

  .. image:: /api/gallery/relativity/gravitational_waves/images/thumb/sphx_glr_plot_gw170817_neutron_star_merger_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/gravitational_waves/plot_gw170817_neutron_star_merger`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">GW170817: the first binary neutron star merger</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Long before LIGO&#x27;s 2015 direct detection, Hulse and Taylor&#x27;s 1974 discovery of the binary pulsar PSR B1913+16 gave the first evidence that gravitational waves are real: the pair&#x27;s orbital period has been measured to shrink at almost exactly the rate General Relativity predicts for energy loss to gravitational radiation, accumulating to a spectacular match after decades of radio timing -- work that earned the 1993 Nobel Prize in Physics. Peters (1964) showed that a binary of masses m_1, m_2 and eccentricity e on a semi-major axis a shrinks at a rate">

.. only:: html

  .. image:: /api/gallery/relativity/gravitational_waves/images/thumb/sphx_glr_plot_hulse_taylor_decay_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/gravitational_waves/plot_hulse_taylor_decay`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Hulse-Taylor binary pulsar: the first (indirect) evidence for gravitational waves</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Interactive Plotly visualizations
-----------------------------------

Pan/zoom/rotate-enabled 3D orbits and shadow images.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Every other visualizer in physicskit is Matplotlib-based: static, ideal for publication figures and this documentation&#x27;s gallery. physicskit.relativity.visualizers.interactive offers the same information as pan/zoom/rotate-enabled Plotly figures instead, convenient for interactively exploring a 3D orbit or a ray-traced shadow image in a Jupyter notebook. This example builds two such figures: a precessing, eccentric timelike geodesic around a Schwarzschild black hole of mass M, obtained by integrating the geodesic equation">

.. only:: html

  .. image:: /api/gallery/relativity/interactive/images/thumb/sphx_glr_plot_interactive_orbit_and_shadow_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/interactive/plot_interactive_orbit_and_shadow`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Interactive Plotly visualizations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Kerr black holes
-----------------

Frame dragging, the ergosphere, and the Penrose process.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A rotating (Kerr) black hole of mass M and spin parameter a = J/M \in [0, M), found by Roy Kerr in 1963, drags spacetime itself around with it. Outside the horizon r_+ = M + \sqrt{M^2-a^2}, in the ergosphere">

.. only:: html

  .. image:: /api/gallery/relativity/kerr/images/thumb/sphx_glr_plot_ergosphere_and_penrose_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/kerr/plot_ergosphere_and_penrose`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Frame dragging and the ergosphere of a Kerr black hole</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A rotating black hole&#x27;s shadow is not a perfect circle like Schwarzschild&#x27;s: frame dragging shifts and flattens it along the direction of rotation, and the accretion disk&#x27;s approaching side is Doppler-boosted bright while the receding side dims -- exactly the asymmetric brightness pattern seen in the 2019 Event Horizon Telescope image of M87*. This example ray-traces the full (non-equatorial) Kerr null geodesic equations -- using Carter&#x27;s separated equations of motion in Mino time -- to render the shadow of a black hole of mass M and spin parameter a at increasing spin, and shades a thin, circularly orbiting equatorial accretion disk by its combined gravitational and Doppler redshift">

.. only:: html

  .. image:: /api/gallery/relativity/kerr/images/thumb/sphx_glr_plot_kerr_shadow_and_redshift_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/kerr/plot_kerr_shadow_and_redshift`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Kerr shadow: a rotating black hole's asymmetric silhouette</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Roger Penrose realized in 1969 that the ergosphere of a rotating (Kerr) black hole -- see plot_ergosphere_and_penrose -- is not just a region where no observer can sit still, but a genuine energy resource. Inside it, the t-Killing vector associated with time-translation symmetry becomes spacelike, so a particle there can have negative energy as measured by an observer at infinity. If a particle entering the ergosphere splits in two, with one negative-energy fragment falling into the horizon, energy conservation forces the escaping fragment to carry away more energy than the original particle had -- extracting rotational energy from the black hole itself. The process is capped by Hawking&#x27;s area theorem: the hole&#x27;s irreducible mass can never decrease, limiting the maximum extractable fraction to">

.. only:: html

  .. image:: /api/gallery/relativity/kerr/images/thumb/sphx_glr_plot_penrose_energy_extraction_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/kerr/plot_penrose_energy_extraction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Penrose process: extracting a black hole's rotational energy</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The static, side-by-side spin comparison in plot_kerr_shadow_and_redshift already shows that a black hole&#x27;s shadow shrinks and its accretion disk creeps inward as the spin a increases -- but a continuous sweep makes the mechanism far more vivid: watch the innermost stable circular orbit (ISCO) contract from 6M (Schwarzschild) down toward M (extremal Kerr, prograde), dragging the disk&#x27;s bright inner edge inward with it, while the shadow itself flattens and shifts off-center from frame dragging.">

.. only:: html

  .. image:: /api/gallery/relativity/kerr/images/thumb/sphx_glr_plot_shadow_spin_sweep_animation_thumb.gif
    :alt:

  :doc:`/api/gallery/relativity/kerr/plot_shadow_spin_sweep_animation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Animating the shadow: a black hole spun up from rest</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Gravitational lensing
-----------------------

Einstein rings, multiple images, and microlensing magnification.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="When a point source, a point (or compact) lens of mass M, and an observer are exactly aligned, gravitational lensing bends the source&#x27;s light into a complete ring of angular radius">

.. only:: html

  .. image:: /api/gallery/relativity/lensing/images/thumb/sphx_glr_plot_einstein_ring_and_microlensing_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/lensing/plot_einstein_ring_and_microlensing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Einstein rings, multiple images, and microlensing</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Neutron stars
--------------

The Tolman-Oppenheimer-Volkoff equations and the maximum neutron star mass.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Oppenheimer and Volkoff&#x27;s 1939 relativistic generalization of hydrostatic equilibrium predicts something Newtonian gravity cannot: a maximum possible mass for a neutron star. The star&#x27;s matter is modeled as a polytrope, P = K\rho_0^\Gamma, relating pressure to rest-mass density, with total energy density (rest mass plus internal energy) \varepsilon = \rho_0 + P/(\Gamma-1). Enclosed mass m(r) and pressure P(r) then obey the Tolman-Oppenheimer-Volkoff equations">

.. only:: html

  .. image:: /api/gallery/relativity/neutron_star/images/thumb/sphx_glr_plot_tov_mass_radius_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/neutron_star/plot_tov_mass_radius`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The neutron star maximum mass: solving the TOV equations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Schwarzschild black holes
--------------------------

Orbits, perihelion precession, light bending, the photon sphere, and a
radial infall's finite proper time to the horizon.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Every GPS satellite carries an atomic clock that runs measurably faster than an identical clock on the ground -- about 38 microseconds per day, a combination of gravitational blueshift (from sitting higher in Earth&#x27;s potential well) partially offset by special-relativistic time dilation (from orbital speed). A clock at radius r moving with angular velocity \Omega around a mass M (Earth, here) has a proper-to-coordinate time rate that combines both effects in one formula:">

.. only:: html

  .. image:: /api/gallery/relativity/schwarzschild/images/thumb/sphx_glr_plot_gps_relativistic_correction_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/schwarzschild/plot_gps_relativistic_correction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">GPS: General Relativity in your pocket</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Starlight grazing the Sun is deflected by \delta\phi \approx 4M/b -- twice the (wrong) Newtonian prediction -- confirmed by Eddington&#x27;s 1919 solar eclipse expedition and the observation that made Einstein a household name overnight. Push the impact parameter down toward the critical value b_c = 3\sqrt{3}M and deflection diverges: photons can orbit (unstably) forever at the photon sphere r=3M, and anything with b &lt; b_c is captured. This example traces individual light rays at a range of impact parameters, then renders the full 2D shadow silhouette by ray-tracing an entire camera image -- the calculation behind the 2019 Event Horizon Telescope image of M87*.">

.. only:: html

  .. image:: /api/gallery/relativity/schwarzschild/images/thumb/sphx_glr_plot_light_bending_and_shadow_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/schwarzschild/plot_light_bending_and_shadow`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Light bending, the photon sphere, and the black hole shadow</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Mercury&#x27;s orbit precesses by about 43 arcseconds per century more than Newtonian gravity (including the perturbations of the other planets) can account for -- a puzzle known since Le Verrier&#x27;s 1859 analysis. Einstein&#x27;s 1915 calculation of exactly this excess, from General Relativity alone with no free parameters, was his first observational triumph and a major reason the theory was taken seriously. Unlike a Newtonian ellipse, a bound Schwarzschild orbit of semi-major axis a and eccentricity e advances its periapsis by, at leading post-Newtonian order,">

.. only:: html

  .. image:: /api/gallery/relativity/schwarzschild/images/thumb/sphx_glr_plot_orbit_precession_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/schwarzschild/plot_orbit_precession`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Perihelion precession: the anomaly that first confirmed General Relativity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Long before Penrose&#x27;s 1965 proof that trapped surfaces force geodesic incompleteness regardless of symmetry, a simpler, coordinate-dependent puzzle already hinted that something was wrong with treating Schwarzschild coordinate time t as a universal clock: a particle dropped from rest at radius R reaches the true singularity in finite proper time,">

.. only:: html

  .. image:: /api/gallery/relativity/schwarzschild/images/thumb/sphx_glr_plot_radial_infall_and_singularity_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/schwarzschild/plot_radial_infall_and_singularity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Penrose's singularity theorems: finite proper time, divergent coordinate time</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="An object falling toward a black hole isn&#x27;t crushed from all sides -- it is stretched along the radial direction (the near side is pulled harder than the far side) and squeezed along the two transverse directions. In the local orthonormal frame of a freely-falling observer, two points separated by a small proper length \ell experience a relative (geodesic deviation) acceleration">

.. only:: html

  .. image:: /api/gallery/relativity/schwarzschild/images/thumb/sphx_glr_plot_tidal_forces_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/schwarzschild/plot_tidal_forces`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spaghettification: tidal forces near a black hole</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Spacetime geometry
-------------------

Curvature, embedding diagrams, and the global causal structure of
Schwarzschild spacetime.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Einstein&#x27;s field equations, G_{\mu\nu} = 8\pi T_{\mu\nu}, reduce to G_{\mu\nu} = 0 in vacuum (no matter or energy present). Schwarzschild and Kerr describe the vacuum spacetime outside a mass, so their Einstein tensors must vanish identically everywhere outside the horizon -- despite the metrics themselves being far from flat. This example uses physicskit.relativity&#x27;s numerical (finite-difference) curvature engine to verify this directly for both metrics at several radii, and shows how the same engine reveals genuine matter content (a nonzero Einstein tensor) for a charged Reissner-Nordstrom black hole, whose electromagnetic field sources spacetime curvature even in the &quot;vacuum&quot; region outside the horizon.">

.. only:: html

  .. image:: /api/gallery/relativity/spacetime_geometry/images/thumb/sphx_glr_plot_curvature_engine_validation_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/spacetime_geometry/plot_curvature_engine_validation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Validating the curvature engine: Einstein's vacuum field equations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="General Relativity&#x27;s central insight is that gravity is not a force propagating through space, but the curvature of spacetime itself -- massive objects don&#x27;t pull on other objects, they bend the geometry that other objects move through in a straight line (a geodesic). Restricting the Schwarzschild metric to a constant-time, equatorial (\theta=\pi/2) slice leaves a curved 2D spatial geometry with proper length element">

.. only:: html

  .. image:: /api/gallery/relativity/spacetime_geometry/images/thumb/sphx_glr_plot_flamm_paraboloid_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/spacetime_geometry/plot_flamm_paraboloid`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Flamm's paraboloid: gravity as curved geometry, not a force</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Schwarzschild coordinates (t, r) blow up at the horizon r=2M -- a coordinate artifact, since nothing physical happens there (a free-falling observer notices nothing special crossing it). Kruskal and Szekeres found coordinates (X, T) that are perfectly smooth across the horizon: in the exterior (:math:`r&gt;2M`),">

.. only:: html

  .. image:: /api/gallery/relativity/spacetime_geometry/images/thumb/sphx_glr_plot_kruskal_penrose_diagrams_thumb.png
    :alt:

  :doc:`/api/gallery/relativity/spacetime_geometry/plot_kruskal_penrose_diagrams`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Kruskal-Szekeres and Penrose-Carter diagrams: the true shape of spacetime</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/relativity/cosmology/index.rst
   /api/gallery/relativity/gravitational_waves/index.rst
   /api/gallery/relativity/interactive/index.rst
   /api/gallery/relativity/kerr/index.rst
   /api/gallery/relativity/lensing/index.rst
   /api/gallery/relativity/neutron_star/index.rst
   /api/gallery/relativity/schwarzschild/index.rst
   /api/gallery/relativity/spacetime_geometry/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_