Start adding docs (GalacticDynamics#94)

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

.pre-commit-config.yaml

@@ -3,6 +3,10 @@ ci:
   autofix_commit_msg: "style: pre-commit fixes"
 
 repos:
+  - repo: meta
+    hooks:
+      - id: check-useless-excludes
+
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: "23.12.1"
     hooks:
@@ -20,15 +24,13 @@ repos:
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-merge-conflict
-      - id: check-symlinks
       - id: check-yaml
       - id: debug-statements
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: name-tests-test
         args: ["--pytest-test-first"]
         exclude: '^tests\/.*_helper\.py$'
-      - id: requirements-txt-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/pre-commit/pygrep-hooks
@@ -63,12 +65,7 @@ repos:
     rev: "v2.2.6"
     hooks:
       - id: codespell
-        exclude: notebooks
-
-  - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: "v0.9.0.6"
-    hooks:
-      - id: shellcheck
+        exclude: ^(?!.*\/notebooks\/)(?!.AUTHORS\.rst$).+$
 
   - repo: local
     hooks:

AUTHORS.rst

@@ -0,0 +1,30 @@
+**Main authors (alphabetical last name):**
+
+* Jacob Nibauer
+* Adrian Price-Whelan (`@adrn <https://github.com/adrn>`_)
+* Nathaniel Starkman (`@nstarman <https://github.com/nstarman>`_)
+
+
+All contributors to :mod:`galax` (alphabetical last name):
+
+* Jacob Nibauer
+* Nathaniel Starkman
+* Adrian Price-Whelan
+
+
+All contributors to :mod:`gala` (alphabetical last name):
+
+* Dan Foreman-Mackey
+* Nico Garavito-Camargo
+* Johnny Greco
+* Akeem Hart
+* Sergey Koposov
+* Daniel Lenz
+* Sophia Lilleengen
+* Pey Lian Lim
+* Syrtis Major
+* Semyeong Oh
+* Adrian Price-Whelan
+* Brigitta Sipőcz
+* Nathaniel Starkman
+* Tom Wagg

docs/getting_started.rst

@@ -0,0 +1,219 @@
+.. _galax-getting-started:
+
+***************
+Getting Started
+***************
+
+Welcome to the :mod:`galax` documentation!
+
+.. TODO: in the paragraph below, switch the matplotlib link to :mod:`matplotlib`
+.. when they add a top-level module definition
+
+For practical reasons, this documentation generally assumes that you are
+familiar with the Python programming language, including numerical and
+computational libraries like :mod:`numpy`, :mod:`scipy`, and `matplotlib
+<https://matplotlib.org/>`_. If you need a refresher on Python programming, we
+recommend starting with the `official Python tutorial
+<https://docs.python.org/3/tutorial/>`_, but many other good resources are
+available on the internet, such as tutorials and lectures specifically designed
+for `using Python for scientific applications <https://scipy-lectures.org/>`_.
+
+On this introductory page, we will demonstrate a few common use cases for :mod:`galax`
+and give an overview of the package functionality. For the examples
+below, we will assume that the following imports have already been executed
+because these packages will be generally required::
+
+    >>> import astropy.units as u
+    >>> import jax.numpy as jnp
+
+
+Computing your first stellar orbit
+==================================
+
+One of the most common use cases for :mod:`galax` is to compute an orbit for a star
+within a mass model for the Milky Way. To do this, we need to specify two
+things: (1) the model of the Milky Way that we would like to use to represent
+the mass distribution, and (2) the initial conditions of the star's orbit.
+
+Mass models in :mod:`galax` are specified using Python classes that represent
+standard gravitational potential models. For example, most of the standard,
+parametrized gravitational potential models introduced in :cite:`Binney2008` are
+available as classes in the :mod:`galax.potential` module. The standard Milky
+Way model recommended for use in :mod:`galax` is the
+:class:`~galax.potential.MilkyWayPotential`, which is a pre-defined,
+multi-component mass model with parameters set to fiducial values that match the
+rotation curve of the Galactic disk and the mass profile of the dark matter
+halo. We can create an instance of this model with the fiducial parameters by
+instantiating the :class:`~galax.potential.MilkyWayPotential` class without any
+input::
+
+    >>> import galax.potential as gp
+    >>> mw = gp.MilkyWayPotential()
+    >>> mw
+    MilkyWayPotential({'disk': MiyamotoNagaiPotential(...), 'halo': NFWPotential(...),
+                       'bulge': HernquistPotential(...), 'nucleus': HernquistPotential(...)})
+
+This model, by default, contains four distinct potential components as listed in
+the output above: disk, bulge, nucleus, and halo components. You can configure
+any of the parameters of these components, or create your own "composite"
+potential model using other potential models defined in :mod:`galax.potential`,
+but for now we will use the fiducial model as we defined it, the variable
+``mw``.
+
+All of the :mod:`galax.potential` class instances have a set of standard methods
+that enable fast calculations of computed or derived quantities. For example,
+we could compute the potential energy or the acceleration at a Cartesian
+position near the Sun::
+
+    >>> xyz = [-8., 0, 0] * u.kpc
+    >>> mw.potential_energy(xyz, t=0)
+    Array(-0.16440278, dtype=float64)
+    >>> mw.acceleration(xyz, t=0)
+    Array([ 0.00702259, -0.        , -0.        ], dtype=float64)
+
+The values that are returned by most methods in :mod:`galax` are provided as
+Astropy :class:`~astropy.units.Quantity` objects, which represent numerical data
+with associated physical units. :class:`~astropy.units.Quantity` objects can be
+re-represented in any equivalent units, so, for example, we could display the
+energy or acceleration in other units::
+
+    >>> mw.potential_energy(xyz, t=0)
+    Array(-0.16440278, dtype=float64)
+    >>> mw.acceleration(xyz, t=0)
+    Array([ 0.00702259, -0.        , -0.        ], dtype=float64)
+
+Now that we have a potential model, if we want to compute an orbit, we need to
+specify a set of initial conditions to initialize the numerical orbit
+integration. In :mod:`galax`, initial conditions and other positions in
+phase-space (locations in position and velocity space) are defined using the
+:class:`~galax.dynamics.PhaseSpacePosition` class. This class allows a number of
+possible inputs, but one of the most common inputs are Cartesian position and
+velocity vectors. As an example orbit, we will use a position and velocity that
+is close to the Sun's Galactocentric position and velocity::
+
+    >>> import galax.dynamics as gd
+    >>> w0 = gd.PhaseSpacePosition(q=[-8.1, 0, 0.02] * u.kpc,
+    ...                            p=[13, 245, 8.] * u.km/u.s)
+
+By convention, I typically use the variable ``w`` to represent phase-space
+positions, so here ``w0`` is meant to imply "initial conditions." Note that,
+when passing in Cartesian position and velocity values, we typically have to
+pass them in as :class:`~astropy.units.Quantity` objects (i.e., with units).
+This is required whenever the potential class you are using has a unit system,
+which you can check by calling the
+:obj:`~galax.potential.AbstractPotentialBase.units` attribute of your potential
+object::
+
+    >>> mw.units
+    UnitSystem(kpc, Myr, solMass, rad)
+
+Here, our Milky Way potential model has a unit system with dimensional units.
+Note that we could have used any length unit for the position and any velocity
+unit for the velocity, because :mod:`galax` handles the unit conversions
+internally.
+
+Now with a potential model defined and a set of initial conditions, we are set
+to compute an orbit! To do this, we use the numerical integration system defined
+in :mod:`galax.integrate`, but do so using the convenience interface available
+on any Potential object through the
+:func:`~galax.potential.AbstractPotential.integrate_orbit` method::
+
+    >>> t = jnp.arange(0, 2, step=1/1000) # Gyr
+    >>> orbit = mw.integrate_orbit(w0.qp, t=t)
+
+By default, this method uses Leapfrog integration , which is a fast, symplectic
+integration scheme. The returned object is an instance of the
+:class:`~galax.dynamics.Orbit` class, which is similar to the
+:class:`~galax.dynamics.PhaseSpacePosition` but represents a collection of
+phase-space positions at times::
+
+    >>> orbit
+    Orbit(
+      q=f64[2000,3], p=f64[2000,3], t=f64[2000], ...
+
+:class:`~galax.dynamics.Orbit` objects have many of their own useful methods for
+performing common tasks, like plotting an orbit::
+
+    >>> orbit.plot(['x', 'y'])  # doctest: +SKIP
+
+.. plot::
+    :align: center
+    :context: close-figs
+    :width: 60%
+
+    import astropy.units as u
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import galax.dynamics as gd
+    import galax.potential as gp
+
+    mw = gp.MilkyWayPotential()
+    w0 = gd.PhaseSpacePosition(pos=[-8.1, 0, 0.02] * u.kpc,
+                               vel=[13, 245, 8.] * u.km/u.s)
+    orbit = mw.integrate_orbit(w0, dt=1*u.Myr, t1=0, t2=2*u.Gyr)
+
+    orbit.plot(['x', 'y'])
+
+:class:`~galax.dynamics.Orbit` objects by default assume and use Cartesian
+coordinate representations, but these can also be transformed into other
+representations, like Cylindrical coordinates. For example, we could
+re-represent the orbit in cylindrical coordinates and then plot the orbit in the
+"meridional plane"::
+
+    >>> fig = orbit.cylindrical.plot(['rho', 'z'])  # doctest: +SKIP
+
+.. plot::
+    :align: center
+    :context: close-figs
+    :width: 60%
+
+    fig = orbit.cylindrical.plot(['rho', 'z'])
+
+.. TODO:
+.. Or estimate the pericenter, apocenter, and eccentricity of the orbit::
+
+..     >>> orbit.pericenter()
+..     <Quantity 8.00498069 kpc>
+..     >>> orbit.apocenter()
+..     <Quantity 9.30721946 kpc>
+..     >>> orbit.eccentricity()
+..     <Quantity 0.07522087>
+
+:mod:`galax.potential` ``Potential`` objects and :class:`~galax.dynamics.Orbit`
+objects have many more possibilities, so please do check out the narrative
+documentation for :mod:`galax.potential` and :mod:`galax.dynamics` if you would
+like to learn more!
+
+
+What else can ``galax`` do?
+===========================
+
+This page is meant to demonstrate a few initial things you may want to do with
+:mod:`galax`. There is much more functionality that you can discover either
+through the :ref:`tutorials <tutorials>` or by perusing the :ref:`user guide
+<galax-user-guide>`. Some other commonly-used functionality includes:
+
+* :ref:`Generating simulated "mock" stellar stream models <galax-mockstreams>`
+* :ref:`Stellar stream and great circle coordinate systems <galax-coordinates>`
+* :ref:`Transformations to action-angle coordinates <galax-actionangle>`
+* :ref:`Nonlinear dynamics and chaos indicators <galax-nonlinear-dynamics>`
+
+
+Where to go from here
+=====================
+
+The two places to learn more are the tutorials and the user guide:
+
+* The :ref:`galax-tutorials` are narrative demonstrations of functionality that
+  walk through simplified, real-world use cases for the tools available in
+  ``galax``.
+* The :ref:`galax-user-guide` contains more exhaustive descriptions of all of the
+  functions and classes available in ``galax``, and should be treated more like
+  reference material.
+
+
+Bibliography
+============
+
+.. bibliography::
+    :cited:

docs/index.rst

@@ -0,0 +1,58 @@
+.. include:: references.txt
+
+.. raw:: html
+
+   <img src="_static/Gala_Logo_RGB.png" width="50%"
+    style="margin-bottom: 32px;"/>
+
+.. module:: galax
+
+*****
+Galax
+*****
+
+Galactic Dynamics is the study of the formation, history, and evolution of
+galaxies using the *orbits* of objects — numerically-integrated trajectories of
+stars, dark matter particles, star clusters, or galaxies themselves.
+
+``galax`` is an Astropy-affiliated Python package that aims to provide efficient
+tools for performing common tasks needed in Galactic Dynamics research.  This
+library is written in JAX, a Python library for high-performance automatic
+differentiation and numerical computation.  Common operations include
+`gravitational potential and force evaluations <potential/index.html>`_, `orbit
+integrations <integrate/index.html>`_, `dynamical coordinate transformations
+<dynamics/index.html>`_, and computing `chaos indicators for nonlinear dynamics
+<dynamics/nonlinear.html>`_. ``galax`` heavily uses the units and astronomical
+coordinate systems defined in the Astropy core package (:ref:`astropy.units
+<astropy-units>` and :ref:`astropy.coordinates <astropy-coordinates>`).
+
+This package is being actively developed in `a public repository on GitHub
+<https://github.com/adrn/gala>`_, and we are always looking for new
+contributors! No contribution is too small, so if you have any trouble with this
+code, find a typo, or have requests for new content (tutorials or features),
+please `open an issue on GitHub <https://github.com/adrn/gala/issues>`_.
+
+.. ---------------------
+.. Nav bar (top of docs)
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   install
+   getting_started
+   tutorials
+   user_guide
+   contributing
+
+
+Contributors
+============
+
+.. include:: ../AUTHORS.rst
+
+
+Citation and Attribution
+========================
+
+WIP