Reverting my debugging commits from today

This reverts commit 815eb14.

docs/faq/Time_Of_Periastron.ipynb

@@ -0,0 +1,139 @@
+{
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.5-final"
+  },
+  "orig_nbformat": 2,
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3",
+   "language": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2,
+ "cells": [
+  {
+   "source": [
+    "# $\\tau$ and Time of Periastron\n",
+    "\n",
+    "Here, we will discuss what exactly is $\\tau$, the parameter `orbitize!` uses to parametrize the epoch of periastron, and how it is related to other quantities of the epoch of periastron in the literature. \n",
+    "\n",
+    "## Time of Periastron and Motivation for $\\tau$\n",
+    "\n",
+    "The time (or epoch) of periastron is an important quantity for describing an orbit. It defines when the two orbiting bodies are closest to one another (i.e., when a planet is closest to its star). In many papers in the literature, the epoch of periastron is described by $t_p$, which is literally a date at which periastron occurs. This is a very important date because we use this date to anchor our orbit in time. \n",
+    "\n",
+    "The value of $t_p$ is well constrained when we know we observed periastron, which is often the case for radial velociy or transiting exoplanets when the orbital periods are short and our data covers a full orbital period. In those cases, we know approximately when $t_p$ should be in time, so it is easy to define prior bounds for it. However, in the case of direct imaging, many of our companions have orbital periods that are orders of magnitude larger than the current orbital coverage of the data where we do not really know if the next periastron is in years, decades, centuries, or even millennia. This is the motivation for $\\tau$. \n",
+    "\n",
+    "## Definition of $\\tau$\n",
+    "\n",
+    "$\\tau$ is a dimentionless quantity between 0 and 1 defined with respect to a reference epoch $t_{ref}$. For a planet that has a $t_p$ and an orbital period (P), then we define $\\tau$ as:\n",
+    "\n",
+    "$$\n",
+    "\\tau = \\frac{t_p - t_{ref}}{P}.\n",
+    "$$\n",
+    "\n",
+    "Because $\\tau$ is always between 0 and 1, it is easy to figure out the bounds of $\\tau$ whereas if the orbital period is highly uncertain, it may be difficult to put bounds on $t_p$ that would encompass all allowable bound orbits. \n",
+    "\n",
+    "## Relation to $t_p$\n",
+    "\n",
+    "As seen in the above equation, it is relatively straightforward to covert between orbital parameter sets that use $\\tau$ and $t_p$. You just need to know the orbital period and reference epoch. In `orbitize!`, both the `System` class and the `Results` class has the attribute `tau_ref_epoch` which stores $t_{ref}$, so there should always be a convenient way to grab this number. By default, we use $t_{ref} = 58849$ MJD. \n",
+    "\n",
+    "One thing to note that is a given orbit has only a single valid $\\tau$, but that an orbit can be defined by many $t_p$, since the orbit is periodic. Thus, $t_p + P$ is another valid time of periastron. \n",
+    "\n",
+    "We also provide some helper functions to covert between $t_p$ and $\\tau$"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "60649.50097715886\n0.2000000000000002\n6634.471662393138\n"
+     ]
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "import orbitize.basis\n",
+    "\n",
+    "# How to get orbital period in the orbitize! standard basis\n",
+    "sma = 9 # au, semi-major axis\n",
+    "mtot = 1.2 # Solar masses, total mass\n",
+    "period = np.sqrt(sma**3/mtot) # years, period\n",
+    "\n",
+    "tau = 0.2\n",
+    "tau_ref_epoch = 58849\n",
+    "\n",
+    "# convert tau to tp\n",
+    "tp = orbitize.basis.tau_to_tp(tau, tau_ref_epoch, period)\n",
+    "\n",
+    "print(tp)\n",
+    "\n",
+    "# convert tp back to tau\n",
+    "tau2 = orbitize.basis.tp_to_tau(tp, tau_ref_epoch, period)\n",
+    "\n",
+    "print(tau2)\n",
+    "\n",
+    "# convert tau to tp, but pick the first tp after MJD = 0\n",
+    "tp_new = orbitize.basis.tau_to_tp(tau, tau_ref_epoch, period, after_date=0)\n",
+    "\n",
+    "print(tp_new)"
+   ]
+  },
+  {
+   "source": [
+    "## Relation to Mean Anomaly\n",
+    "\n",
+    "The mean anomaly (M) of an orbit describes the current orbital phase of a planet. M goes from 0 to 2$\\pi$, and M = 0 means the planet is at periastron. Unlike $t_p$ and $\\tau$ which describe the epoch of periastron, M describes the current position of the planet in its orbit. \n",
+    "\n",
+    "To compute M of a planet at some time t, we have provided the following helper function:"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "5.829874251150844\n1.3951473992034527e-15\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Use the orbit defined in the previous example\n",
+    "\n",
+    "t = 60000 # time in MJD when we want to know the M of the particle\n",
+    "\n",
+    "M = orbitize.basis.tau_to_manom(t, sma, mtot, tau, tau_ref_epoch)\n",
+    "\n",
+    "print(M)\n",
+    "\n",
+    "# now compute M for periastron\n",
+    "M_peri = orbitize.basis.tau_to_manom(tp, sma, mtot, tau, tau_ref_epoch)\n",
+    "\n",
+    "print(M_peri)"
+   ]
+  }
+ ]
+}