diff --git a/docs/index.rst b/docs/index.rst index 354cf734..d37d4510 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,6 +50,7 @@ User Guide: faq contributing api + manual Changelog: ++++++++++ @@ -58,6 +59,7 @@ Changelog: - discuss MCMC autocorrelation in MCMC tutorial (@michaelkmpoon) - add time warning if OFTI doesn't accept an orbit in first 60 s (@michaelkmpoon) +- add first parts of orbitize! manual (@sofiacovarrubias/@sblunt) - bugfix for rebound MCMC fits (issue #357; @sblunt) - implementation of Hipparcos-Gaia catalog of accelerations fitting! (@semaphoreP) - implementation of residual plotting method for orbit plots (@Saanikachoudhary and @semaphoreP) diff --git a/docs/manual.rst b/docs/manual.rst new file mode 100644 index 00000000..7b1c1ef4 --- /dev/null +++ b/docs/manual.rst @@ -0,0 +1,128 @@ +.. _manual: + +orbitize! Manual +============== + +Intro to ``orbitize!`` ++++++++++++++++++ + +``orbitize!`` hinges on the two-body problem, which describes the paths of two +bodies gravitationally bound to each other as a function of time, +given parameters determining the position and velocity of both objects at a particular epoch. +There are many basis sets (orbital bases) that can be used to describe an orbit, +which can then be solved using Kepler’s equation, but first it is important to be explicit about coordinate systems. + +.. Note:: + For an interactive visualization to define and help users understand our coordinate system, + you can check out `this GitHub tutorial `_. + + There is also a `YouTube video `_ + with use and explanation of the coordinate system by Sarah Blunt. + +In its “standard” mode, ``orbitize!`` assumes that the user only has relative astrometric data to fit. +In the ``orbitize!`` coordinate system, relative R.A. and declination can be expressed as the following functions +of orbital parameters + +.. math:: + \Delta R.A. = \pi a(1-ecosE)[cos^2{i\over 2}sin(f+\omega_p+\Omega)-sin^2{i\over 2}sin(f+\omega_p-\Omega)] + + \Delta decl. = \pi a(1-ecosE)[cos^2{i\over 2}cos(f+\omega_p+\Omega)+sin^2{i\over 2}cos(f+\omega_p-\Omega)] + +where 𝑎, 𝑒, :math:`\omega_p`, Ω, and 𝑖 are orbital parameters, and 𝜋 is the system parallax. f is +the true anomaly, and E is the eccentric anomaly, which are related to elapsed time +through Kepler’s equation and Kepler’s third law + +.. math:: + M = 2\pi ({t\over P}-(\tau -\tau_{ref})) + + +.. math:: + ({P\over yr})^2 =({a\over au})^3({M_\odot \over M_{tot}}) + + M =E-esinE + + f = 2tan^{-1}[\sqrt{{1+e\over 1-e}}tan{E\over 2}] + +``orbitize!`` employs two Kepler solvers to convert between mean +and eccentric anomaly: one that is efficient for the highest eccentricities, and Newton’s method, which in other cases is more efficient for solving for the average +orbit. See `Blunt et al. (2020) `_ for more detail. + + +From scrutinizing the above sets of equations, one may observe +a few important degeneracies: + +1. Individual component masses do not show up anywhere in this equation set. + +2. The degeneracy between semimajor axis 𝑎, total mass :math:`𝑀_{tot}`, and +parallax 𝜋. If we just had relative astrometric measurements and no external knowledge of the system parallax, +we would not be able to distinguish between a system +that has larger distance and larger semimajor axis (and therefore larger total mass, +assuming a fixed period) from a system that has smaller distance, smaller semimajor +axis, and smaller total mass. + +3. The argument of periastron :math:`\omega_p` and the position angle of nodes Ω. +The above defined R.A. and decl. functions are invariant to the transformation: + +.. math:: + \omega_p' = \omega_p + \pi + + \Omega' = \Omega - \pi + +which creates a 180◦ degeneracy between particular values of :math:`\omega_p` and Ω, and +a characteristic “double-peaked” structure in marginalized 1D posteriors of these +parameters. + +Solutions to breaking degeneracies 1 and 3 can be found in the next section. + + +Using Radial Velocities ++++++++++++++++++ +In the ``orbitize!`` coordinate system, and relative to the system barycenter, the +radial velocity of the planet due to the gravitational influence of the star is: + +.. math:: + rv_p(f) = \sqrt{{G\over (1-e^2)}}M_* sini(M_{tot})^{-1/2}a^{-1/2}(cos(\omega_p+f)+ecos\omega_p) + + rv_*(f) = \sqrt{{G\over (1-e^2)}}M_p sini(M_{tot})^{-1/2}a^{-1/2}(cos(\omega_*+f)+ecos\omega_*) + +where 𝜔∗ is the argument of periastron of the star’s orbit, which is equal to 𝜔𝑝 + +180◦. + +In these equations, the individual component masses m𝑝 and m∗ enter. This means +radial velocity measurements break the total mass degeneracy and enable measurements of individual component masses +(“dynamical” masses). However it is crucial to keep in mind that radial velocities of a planet do not enable +dynamical mass measurements of the planet itself, but of the star. +Radial velocity measurements also break the Ω/𝜔 degeneracy discussed in the +previous section, uniquely orienting the orbit in 3D space. + +``orbitize!`` can perform joint fits of RV and astrometric data in two different +ways, which have complementary applications. + +The first method is automatically triggered when an ``orbitize!`` user inputs radial velocity data. +``orbitize!`` automatically parses the data, sets up an appropriate model, +then runs the user’s Bayesian computation +algorithm of choice to jointly constrain all free parameters in the fit. +``orbitize!`` can handle both primary and secondary RVs, and fits for the appropriate dynamical +masses when RVs are present; when primary RVs are included, ``orbitize!`` fits for +the dynamical masses of secondary objects, and vice versa. +Instrumental nuisance parameters (RV zeropoint offset, 𝛾, and white noise jitter, 𝜎) for each RV instrument +are also included as additional free parameters in the fit if the user specifies different +instrument names in the data file. + +The second method of jointly fitting RV and astrometric data in ``orbitize!`` separates out the fitting of +radial velocities and astrometry, enabling a user to fit “one at a +time,” and combine the results in a Bayesian framework. First, a user performs a +fit to just the radial velocity data using, for example, radvel (but can be any radial +velocity orbit-fitting code). The user then feeds the numerical posterior samples +into ``orbitize!`` through the ``orbitize.priors.KDEPrior`` object. This prior +creates a representation of the prior using kernel density estimation +(`kernel density estimation `_), +which can then be used to generate random prior samples or compute the prior +probability of a sample orbit. Importantly, this prior preserves covariances between +input parameters, allowing ``orbitize!`` to use an accurate representation of the RV +posterior to constrain the fit. This method can be referred to as the “posteriors as priors” +method, since posteriors output from a RV fitting code are, through KDE sampling, +being applied as priors in ``orbitize!`` . + + +More coming soon! \ No newline at end of file