Skip to content

Commit

Permalink
Merge pull request #367 from sblunt/v3
Browse files Browse the repository at this point in the history
V3!!!!!!!!!!!
  • Loading branch information
sblunt committed Apr 11, 2024
2 parents d59a1e4 + 5afbc1a commit 1b8c99b
Show file tree
Hide file tree
Showing 50 changed files with 9,847 additions and 2,820 deletions.
8 changes: 6 additions & 2 deletions .github/workflows/python-package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.8", "3.9", "3.10"]
python-version: ["3.10", "3.11", "3.12"]

steps:
- uses: actions/checkout@v3
Expand All @@ -40,5 +40,9 @@ jobs:
run: |
pytest --cov
- name: Coveralls GitHub Action
if: ${{ matrix.python-version }} == '3.12'
uses: coverallsapp/github-action@v2

with:
parallel: true
flag-name: run-$

36 changes: 36 additions & 0 deletions .github/workflows/run-notebooks.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: Test jupyter notebook tutorials

on:
push:
branches:
- main # only rerun tutorials when making PRs or changing main
- v3
pull_request:
branches:
- '*'

jobs:
build:

runs-on: macos-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.12"]

steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install jupyter setuptools wheel nbmake
python -m pip install -r requirements.txt
python -m pip install . --no-build-isolation
- name: Run tutorial notebooks
run: |
py.test --nbmake --nbmake-timeout=3000 docs/tutorials/*.ipynb
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,14 @@ orbitize/example_data/rebound*.csv
orbitize/example_data/*test.hdf5
.vscode/launch.json
.vscode/settings.json
*.DS_Store

# images & storage files generated by tutorials
*.hdf5
!orbitize/example_data/v1_posterior.hdf5
*.fits
*.png
!docs/tutorials/eift_hd206893.png
tests/test_results.h5
tests/multiplanet*test.csv

Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@
# Disable notebook timeout
nbsphinx_timeout = -1

# Always re-run notebooks when building docss
nbsphinx_execute = "always"
# Only re-run notebooks that have no outputs
nbsphinx_execute = "auto"

# Allow notebook errors
nbsphinx_allow_errors = False
Expand Down
14 changes: 14 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,24 @@ User Guide:
faq
contributing
api
manual

Changelog:
++++++++++

**3.0.0 (2024-4-11)**

- implementation of Hipparcos-Gaia catalog of accelerations fitting! (@semaphoreP)
- fit arbitrary absolute astrometry (@sblunt)
- implement O'Neil observation-based priors (@sblunt/@clarissardoo)
- 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 residual plotting method for orbit plots (@Saanikachoudhary and @semaphoreP)
- plot companion RVs (@chihchunhsu)
- add documentation about referencing issues when modifying priors to tutorial (@wcroberson)

**2.2.2 (2023-06-30)**

- tests now overwrite any generated text files (@sblunt)
Expand Down
128 changes: 128 additions & 0 deletions docs/manual.rst
Original file line number Diff line number Diff line change
@@ -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 <https://github.com/sblunt/orbitize/blob/main/docs/tutorials/show-me-the-orbit.ipynb>`_.

There is also a `YouTube video <https://www.youtube.com/watch?v=0e24VUhQmbM>`_
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) <https://iopscience.iop.org/article/10.3847/1538-3881/ab6663>`_ 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 <https://mathisonian.github.io/kde/>`_),
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!
2 changes: 2 additions & 0 deletions docs/tutorials.rst
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ us if you are still confused).
tutorials/Using_nonOrbitize_Posteriors_as_Priors.ipynb
tutorials/Changing_bases_tutorial.ipynb
tutorials/Hipparcos_IAD.ipynb
tutorials/HGCA_tutorial.ipynb
tutorials/abs_astrometry.ipynb



0 comments on commit 1b8c99b

Please sign in to comment.