Merge pull request #1 from BlackHolePerturbationToolkit/animation

Plotting and Animation Improvements

.github/workflows/python-package.yml

@@ -27,7 +27,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install scipy numpy matplotlib
+        python -m pip install scipy numpy matplotlib tqdm
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Test with unittest
       run: |

README.md

@@ -1,3 +1,7 @@
+# KerrGeoPy
+
+KerrGeoPy is a python implementation of the [KerrGeodesics](https://bhptoolkit.org/KerrGeodesics/) Mathematica library. It is intended for use in computing orbital trajectories for extreme-mass-ratio inspirals (EMRIs). It implements the analytical solutions for plunging orbits from [Dyson and van de Meent](https://arxiv.org/abs/2302.03704), as well as solutions for stable orbits from [Fujita and Hikida](https://arxiv.org/abs/0906.1420). The library also provides a set of methods for computing constants of motion and orbital frequencies.
+
 ## Installation
 
 Install the latest version of kerrgeopy using pip
@@ -9,7 +13,7 @@ pip install kerrgeopy
 
 Kerrgeopy computes orbits in Boyer-Lindquist coordinates $(t,r,\theta,\phi)$. Let $M$ to represent the mass of the primary body and let $J$ represent its angular momentum. Working in geometrized units where $G=c=1$, stable bound orbits are parametrized using the following variables:
 
-$a$ - spin of the primary body 
+$a$ - spin of the primary body
 <br>
 $p$ - orbital semilatus rectum
 <br>
@@ -275,4 +279,4 @@ plt.ylabel(r"$\phi(\lambda)$")
 ## Authors
 
 * Seyong Park
-* Zach Nasipak
+* Zach Nasipak

docs/environment.yml

@@ -5,6 +5,7 @@ channels:
 dependencies:
   - ipython
   - sphinx
+  - tqdm
   - scipy
   - numpy
   - matplotlib

docs/source/conf.py

@@ -22,7 +22,7 @@
 author = 'Seyong Park'
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+release = '0.9.1'
 
 
 # -- General configuration ---------------------------------------------------
@@ -33,7 +33,8 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "myst_nb"
+    "myst_nb",
+    "sphinx.ext.viewcode"
 ]
 myst_enable_extensions = ["dollarmath", "amsmath"]
 nb_execution_mode = "off"
@@ -57,7 +58,7 @@
 html_theme = 'sphinx_book_theme'
 
 html_theme_options = {
-    "repository_url": "https://github.com/syp2001/KerrGeoPy",
+    "repository_url": "https://github.com/BlackHolePerturbationToolkit/KerrGeoPy",
     "use_repository_button": True,
     "navbar_end": ["navbar-icon-links"],
 }

docs/source/index.rst

@@ -10,13 +10,17 @@ Overview
 It implements the analytical solutions for plunging orbits from `Dyson and van de Meent <https://arxiv.org/abs/2302.03704>`_, as well as solutions for stable orbits from `Fujita and Hikida <https://arxiv.org/abs/0906.1420>`_. 
 The library also provides a set of methods for computing constants of motion and orbital frequencies, and can generate plots and animations like those shown below.
 
-.. image:: images/orbit.png
+.. image:: images/thumbnail.png
     :align: left
     :width: 45%
 
-.. image:: images/orbit.gif
-   :align: right
-   :width: 45%
+.. https://github.com/sphinx-doc/sphinx/issues/823
+
+.. raw:: html
+
+   <video width="45%" autoplay loop>
+      <source src="https://raw.githubusercontent.com/BlackHolePerturbationToolkit/KerrGeoPy/main/docs/source/notebooks/animation4.mp4" type="video/mp4">
+   </video>
 
 .. _Installation:
 
@@ -50,7 +54,7 @@ API Reference
    :caption: API Reference
    :hidden:
 
-   Full List of Modules <https://kerrgeopy.readthedocs.io/en/latest/_autosummary/kerrgeopy.html>
+   Modules <https://kerrgeopy.readthedocs.io/en/latest/_autosummary/kerrgeopy.html>
 
 .. autosummary::
    :toctree: _autosummary

kerrgeopy/constants.py

@@ -104,7 +104,7 @@ def stable_polar_roots(a,p,e,x,constants=None):
     :param constants: dimensionless constants of motion for the orbit
     :type constants: tuple(double, double, double)
 
-    :return: tuple of roots in the form :math:`(z_-, z_+)`
+    :return: tuple of roots :math:`(z_-, z_+)`
     :rtype: tuple(double, double, double, double)
     """
     if constants is None: constants = constants_of_motion(a,p,e,x)
@@ -326,7 +326,7 @@ def constants_of_motion(a,p,e,x):
     :param x: cosine of the orbital inclination (must satisfy 0 <= x^2 <= 1)
     :type x: double
     
-    :return: tuple of constants in the form :math:`(E, L, Q)`
+    :return: tuple of constants of motion :math:`(E, L, Q)`
     :rtype: tuple(double, double, double)
     """
     E = energy(a,p,e,x)
@@ -350,7 +350,7 @@ def apex_from_constants(a,E,L,Q):
     :return: tuple of orbital parameters :math:`(a,p,e,x)`
     :rtype: tuple(double,double,double,double)
     """
-    # radial polynomial written in terms of z = cos^2(theta)
+    # Radial polynomial
     R = Polynomial([-a**2*Q, 2*L**2+2*Q+2*a**2*E**2-4*a*E*L, a**2*E**2-L**2-Q-a**2, 2, E**2-1])
     radial_roots = R.roots()
     # numpy returns roots in increasing order