:orphan:

Examples
========

This gallery walks through ``physicskit.astro``'s worked examples: orbital
mechanics, N-body dynamics, stellar structure, galactic dynamics and dark
matter, cosmic-web structure formation, and the stellar dynamo -- one
section per corresponding subpackage module.

See also the narrative tutorials:

- :doc:`/tutorials/polytropic_stellar_models`
- :doc:`/tutorials/nbody_orbits_and_galactic_rotation_curves`

Each script in this gallery is self-contained and can be run directly with
``python examples/astro/<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
--------

- **orbital_mechanics** -- Kepler's laws, Newton's inverse-square gravity,
  Gauss's orbit-determination problem, and the Hohmann transfer.
- **nbody** -- Poincare's sensitive dependence in the three-body problem,
  the figure-eight choreography, the virial theorem, and long-term
  symplectic stability.
- **stellar_structure** -- Lane-Emden polytropes, the Chandrasekhar mass
  limit, the Eddington mass-luminosity relation, and the pp-chain/CNO-cycle
  energy release behind stellar nucleosynthesis.
- **galactic_dynamics** -- Oort's constants, flat rotation curves and the
  dark-matter mass discrepancy, the NFW halo profile, and Chandrasekhar's
  dynamical friction.
- **cosmic_web** -- the Zel'dovich approximation: a uniform particle grid
  collapsing into the filaments, sheets, and nodes of the cosmic web.
- **stellar_dynamo** -- 2D Boussinesq convective rolls, and the linearized
  alpha-omega mean-field dynamo wave that reproduces the solar butterfly
  diagram.


.. 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>

Cosmic-web formation
----------------------

The Zel'dovich (1970) approximation: how an initially uniform grid of
matter collapses into the filaments, sheets, and nodes of the cosmic web.


.. 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="Zel&#x27;dovich (1970, &quot;Gravitational instability: An approximate theory for large density perturbations&quot;) showed that, to leading order, a fluid element of dark matter simply free-streams away from its initial (&quot;Lagrangian&quot;) position \mathbf{q} in a fixed direction set by the gradient of a displacement potential \Phi(\mathbf{q}):">

.. only:: html

  .. image:: /api/gallery/astro/cosmic_web/images/thumb/sphx_glr_plot_zeldovich_pancakes_thumb.png
    :alt:

  :doc:`/api/gallery/astro/cosmic_web/plot_zeldovich_pancakes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Cosmic-web formation: the Zel'dovich approximation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Galactic dynamics
-------------------

Oort and Lindblad's differential rotation, Rubin and Ford's flat rotation
curves, the Navarro-Frenk-White halo profile, and Chandrasekhar's dynamical
friction -- the rotation-curve and dark-matter machinery in
:mod:`physicskit.astro.galactic_dynamics`.


.. 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="Lindblad argued the Milky Way could not rotate rigidly; Oort (1927) supplied the observational test: if the Galaxy rotates differentially, nearby stars&#x27; radial velocities and proper motions vary with Galactic longitude l in a double-sine pattern set by just two numbers,">

.. only:: html

  .. image:: /api/gallery/astro/galactic_dynamics/images/thumb/sphx_glr_plot_01_oort_constants_thumb.png
    :alt:

  :doc:`/api/gallery/astro/galactic_dynamics/plot_01_oort_constants`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Oort and Lindblad's differential rotation: the Oort constants</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Three results form one chain. Oort (1932) and Zwicky (1933) applied the virial theorem to stellar and galaxy-cluster velocities and found implied masses far exceeding the visible matter. Rubin and Ford (1970), confirmed and extended through the 1970s by Roberts, Whitehurst, Bosma, and others, measured spiral-galaxy rotation curves that stayed flat far beyond the visible disk rather than falling off as Keplerian motion around a centrally concentrated mass predicts. Navarro, Frenk, and White (1996-1997) found that cosmological dark-matter halos collapse onto a single near-universal density profile,">

.. only:: html

  .. image:: /api/gallery/astro/galactic_dynamics/images/thumb/sphx_glr_plot_02_rotation_curves_and_dark_matter_thumb.png
    :alt:

  :doc:`/api/gallery/astro/galactic_dynamics/plot_02_rotation_curves_and_dark_matter`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Rotation curves, the NFW halo, and the dark-matter mass discrepancy</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Chandrasekhar (1943) showed that a massive body moving through a sea of much lighter field stars feels a systematic drag, built up from the cumulative small-angle gravitational deflections of every star it passes:">

.. only:: html

  .. image:: /api/gallery/astro/galactic_dynamics/images/thumb/sphx_glr_plot_03_dynamical_friction_thumb.png
    :alt:

  :doc:`/api/gallery/astro/galactic_dynamics/plot_03_dynamical_friction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Chandrasekhar's dynamical friction: a satellite spiraling inward</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

N-body dynamics
-----------------

Direct-summation gravity in :mod:`physicskit.astro.nbody`: the sensitive
dependence on initial conditions Poincare discovered in the three-body
problem, the figure-eight choreography, the virial theorem, and the
long-term stability that symplectic integration buys N-body simulation.


.. 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="Studying the three-body problem for King Oscar II&#x27;s 1889 prize, Poincare found that no general closed-form solution exists at all: two trajectories starting arbitrarily close together can separate at an exponential rate, the first rigorous demonstration of what would later be called deterministic chaos. Lagrange (1772) found one very special three-body configuration that is exactly solvable -- three masses at the vertices of an equilateral triangle, rigidly rotating about their common center of mass -- but Routh (1875) showed its linear stability depends on the mass ratios (stable only when one mass strongly dominates, as for the Sun-Jupiter-Trojan system). For masses like 3, 4, and 5 (in G=1 units), it is deep in the unstable regime, and provides a numerically clean, close-encounter-free setting to watch Poincare&#x27;s sensitive dependence directly with NBodySystem, without needing to resolve the extreme close encounters of a genuinely colliding configuration.">

.. only:: html

  .. image:: /api/gallery/astro/nbody/images/thumb/sphx_glr_plot_01_three_body_sensitivity_thumb.png
    :alt:

  :doc:`/api/gallery/astro/nbody/plot_01_three_body_sensitivity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Poincare's discovery: sensitive dependence in the three-body problem</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For two centuries after Newton, every known periodic three-body solution demanded either a special mass ratio (Lagrange&#x27;s equilateral triangle) or a rigidly symmetric configuration (Euler&#x27;s collinear solutions). Moore found something qualitatively different in 1993: three equal masses chasing one another endlessly around a single figure-eight curve, a genuine choreography with no distinguished body -- proven to exist by Chenciner and Montgomery in 2000. figure_eight_initial_conditions returns exactly this initial condition; this example integrates it with NBodySystem, checks that the configuration is genuinely periodic by finding the time at which body 1 first returns closest to its own starting point, and checks that energy and angular momentum stay conserved over one full period.">

.. only:: html

  .. image:: /api/gallery/astro/nbody/images/thumb/sphx_glr_plot_02_figure_eight_choreography_thumb.png
    :alt:

  :doc:`/api/gallery/astro/nbody/plot_02_figure_eight_choreography`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The figure-eight three-body choreography</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Clausius (1870) showed that for any bounded system interacting through conservative forces, the time-averaged kinetic energy and the time-averaged virial of the forces are related; for a system bound purely by inverse-square gravity, this reduces to">

.. only:: html

  .. image:: /api/gallery/astro/nbody/images/thumb/sphx_glr_plot_03_virial_theorem_thumb.png
    :alt:

  :doc:`/api/gallery/astro/nbody/plot_03_virial_theorem`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Clausius's virial theorem for a bound gravitational orbit</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Wisdom and Holman (1991) showed that symplectic integrators -- of which the kick-drift-kick leapfrog scheme is the simplest example -- keep a conservative system&#x27;s numerically computed energy oscillating within a small bound forever, rather than drifting secularly away as an ordinary (non-symplectic) integrator&#x27;s does. This is exactly what made simulations at the scale of the Millennium Simulation&#x27;s billions of particles, evolved over cosmological timescales, numerically trustworthy at all. This example integrates the same eccentric two-body orbit with NBodySystem&#x27;s symplectic leapfrog_step for a thousand orbital periods, alongside a hand-written non-symplectic explicit-Euler stepper using the same force law (~physicskit.astro.nbody.gravitational_acceleration), and compares their energy error growth directly.">

.. only:: html

  .. image:: /api/gallery/astro/nbody/images/thumb/sphx_glr_plot_04_symplectic_long_term_stability_thumb.png
    :alt:

  :doc:`/api/gallery/astro/nbody/plot_04_symplectic_long_term_stability`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Symplectic integration and long-term N-body stability</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Orbital mechanics
-------------------

Kepler's laws, Newton's inverse-square gravity, Gauss's orbit-determination
problem, and Hohmann's minimum-energy transfer -- the two-body machinery in
:mod:`physicskit.astro.orbital_mechanics`.


.. 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="Kepler&#x27;s three empirical laws -- an elliptical orbit with the Sun at one focus, equal areas swept in equal times, and T^2\propto a^3 -- were purely descriptive when published (1609, 1619). Newton (1687) showed they follow as mathematical consequences of a single dynamical law, the inverse-square gravitational force">

.. only:: html

  .. image:: /api/gallery/astro/orbital_mechanics/images/thumb/sphx_glr_plot_01_kepler_newton_orbit_thumb.png
    :alt:

  :doc:`/api/gallery/astro/orbital_mechanics/plot_01_kepler_newton_orbit`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Kepler's laws and Newton's inverse-square gravity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="When Piazzi lost Ceres in the Sun&#x27;s glare after only a few weeks of observation, Gauss showed how to recover a complete set of orbital elements from as few as three observed positions and times. The modern version of the last step of that problem -- given a single Cartesian state (position and velocity) at one instant, recover the six classical orbital elements (a, e, i, \Omega, \omega, \nu) -- is exactly what orbital_elements_from_state does; state_from_orbital_elements is its inverse. This example starts from a chosen (inclined, eccentric) orbit, converts to a state vector as if it were an observation, and recovers the original elements exactly -- verifying the round trip in both directions, then re-derives the whole 3D orbit from the recovered elements alone.">

.. only:: html

  .. image:: /api/gallery/astro/orbital_mechanics/images/thumb/sphx_glr_plot_02_orbit_determination_thumb.png
    :alt:

  :doc:`/api/gallery/astro/orbital_mechanics/plot_02_orbit_determination`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Gauss's problem: recovering orbital elements from a state vector</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Hohmann (1925) showed that the cheapest way to move between two circular orbits is a transfer ellipse tangent to both, entered and left with a single impulsive burn at each tangent point:">

.. only:: html

  .. image:: /api/gallery/astro/orbital_mechanics/images/thumb/sphx_glr_plot_03_hohmann_transfer_thumb.png
    :alt:

  :doc:`/api/gallery/astro/orbital_mechanics/plot_03_hohmann_transfer`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Hohmann's minimum-energy transfer orbit</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Stellar convection and the magnetic dynamo
---------------------------------------------

2D convective rolls, and the alpha-omega mean-field dynamo wave behind
the solar butterfly diagram.


.. 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="The Sun&#x27;s large-scale magnetic field is not a fossil left over from formation -- it is continuously regenerated by turbulent convection acting together with differential rotation, the mechanism first proposed by Parker (1955) and still the standard textbook explanation of the 11-year solar cycle and its famous &quot;butterfly diagram&quot; of sunspots migrating from mid-latitudes toward the equator.">

.. only:: html

  .. image:: /api/gallery/astro/stellar_dynamo/images/thumb/sphx_glr_plot_convection_and_dynamo_wave_thumb.png
    :alt:

  :doc:`/api/gallery/astro/stellar_dynamo/plot_convection_and_dynamo_wave`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Stellar convection and the alpha-omega magnetic dynamo</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Stellar structure
-------------------

Polytropic gas spheres, the Chandrasekhar mass limit, the mass-luminosity
relation, and the nuclear reactions that power a star, from
:mod:`physicskit.astro.stellar_structure` (and, for nucleosynthesis,
:mod:`physicskit.particle.nuclear`).


.. 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="Lane (1870) first treated a star as a self-gravitating polytropic gas sphere, Ritter (1878-1889) generalized the analysis to arbitrary polytropic index n, and Emden (1907) systematized the resulting family of solutions to the dimensionless equation">

.. only:: html

  .. image:: /api/gallery/astro/stellar_structure/images/thumb/sphx_glr_plot_01_lane_emden_polytropes_thumb.png
    :alt:

  :doc:`/api/gallery/astro/stellar_structure/plot_01_lane_emden_polytropes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Lane-Emden polytropes: Lane, Ritter, and Emden's gas spheres</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Chandrasekhar (1931) showed that electron degeneracy pressure cannot support an arbitrarily massive white dwarf: as the star&#x27;s mass grows, the degenerate electrons are forced relativistic, softening the pressure-density relation until, above a critical mass, no equilibrium exists at all,">

.. only:: html

  .. image:: /api/gallery/astro/stellar_structure/images/thumb/sphx_glr_plot_02_chandrasekhar_mass_thumb.png
    :alt:

  :doc:`/api/gallery/astro/stellar_structure/plot_02_chandrasekhar_mass`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Chandrasekhar's white dwarf mass limit</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Eddington (1924) showed that a main-sequence star&#x27;s luminosity is fixed almost entirely by its mass, regardless of what actually generates the star&#x27;s energy -- fifteen years before Bethe worked out the nuclear reactions responsible:">

.. only:: html

  .. image:: /api/gallery/astro/stellar_structure/images/thumb/sphx_glr_plot_03_eddington_mass_luminosity_thumb.png
    :alt:

  :doc:`/api/gallery/astro/stellar_structure/plot_03_eddington_mass_luminosity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Eddington's mass-luminosity relation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Fifteen years after Eddington&#x27;s mass-luminosity relation described the consequences of a star&#x27;s energy output without explaining its source, Bethe (1939) worked out the two nuclear fusion chains that actually power it: the proton-proton (pp) chain, dominant in Sun-like stars, and the carbon-nitrogen-oxygen (CNO) cycle, dominant in hotter, more massive stars. Both fuse four hydrogen nuclei into one helium-4 nucleus,">

.. only:: html

  .. image:: /api/gallery/astro/stellar_structure/images/thumb/sphx_glr_plot_04_bethe_nucleosynthesis_thumb.png
    :alt:

  :doc:`/api/gallery/astro/stellar_structure/plot_04_bethe_nucleosynthesis`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bethe's pp-chain and CNO cycle: the energy source of stars</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/astro/cosmic_web/index.rst
   /api/gallery/astro/galactic_dynamics/index.rst
   /api/gallery/astro/nbody/index.rst
   /api/gallery/astro/orbital_mechanics/index.rst
   /api/gallery/astro/stellar_dynamo/index.rst
   /api/gallery/astro/stellar_structure/index.rst



.. only:: html

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

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