PlanetOrbits.jl

Tools for calculating orbits of hierarchical systems of bodies, in the context of direct imaging, astrometry, and radial velocity.

The package is built around one idea:

A propagator produces per-body barycentric Cartesian states at requested epochs, and every observable is a function of a pair of references — weighted combinations of body states — plus system-level frame information.

Everything else follows from it. Observables are pairwise queries between any bodies, barycentres or photocentres; propagators are swappable behind a single output format; and the whole construct → solve → query path is allocation-free, so it can sit inside an MCMC hot loop. Automatic differentiation with ForwardDiff flows through construction, both propagators, and the observables.

To fit orbits to observations, see Octofitter.jl.

Installation

These docs describe PlanetOrbits v1. If you are coming from the old 0.11 line, see the migration guide. Install into a fresh project environment:

using Pkg
Pkg.activate("my-orbits")     # a fresh, dedicated environment
Pkg.add("PlanetOrbits")

To fit orbits to observations, install Octofitter.jl v9, which is built on PlanetOrbits v1 and installs it automatically.

Quick start

using PlanetOrbits
import PlanetOrbits as PO       # System, Body and Orbit are not exported

A = PO.Body(mass=1.1, name=:A)             # [M⊙]
b = PO.Body(mass=5mjup, name=:b)

sys = PO.System((A, b), (
    PO.Orbit(b, about=A; a=8.0, e=0.1, i=0.5, ω=1.1, Ω=2.2, tp=58849.0),
); plx=24.5)

traj = orbitsolve(sys, [58900.0, 59000.0, 59100.0])   # sorted epochs [MJD]

raoff(traj[1], b, A)                    # separation of b from A [mas]
radvel(traj[1], A, barycentre(sys))     # stellar reflex velocity [m/s]

Every orbit names its reference explicitly with about=. That is what lets one API describe a lone planet, a moon, a circumbinary planet or a 2+2 quadruple — see Hierarchical systems.

What is supported

• Bound circular and elliptical orbits, and unbound hyperbolic orbits (e > 1), including velocities.
• Hierarchical systems of any shape: Jacobi chains, astrocentric sets, moons, circumbinary planets, 2+2 quadruples, and mixtures of conventions.
• Two propagators — KeplerianApprox (each hierarchy row on an independent Keplerian orbit) and AHL21 (full symplectic N-body) — behind one interface, so switching costs one keyword.
• Arbitrary precision, by building the system from BigFloat values and choosing a solver with a user-specified tolerance.
• Plotting through a Makie extension: orbit tracks, calendar-date epoch axes, and shared axis-label metadata.

Where to go next

If you are new to orbital elements and the two-body problem, the free online text Orbital Mechanics & Astrodynamics by Bryan Weber is an excellent companion; the tutorials below link into the relevant sections as they come up.

Tutorials

• Introduction
• • Bodies
  • Orbits
  • Systems
  • Solving
  • Observables
  • • Over a whole trajectory
  • Barycentres and photocentres
  • Orbit properties
  • Allocation-free use
• Hierarchical systems
• • The reference grammar
  • Jacobi vs. astrocentric
  • Convention constructors
  • Moons
  • Circumbinary planets
  • Set exteriors: 2+2 quadruples
  • Blended sources & photocentres
  • • The worked example: two sources in a 2+2 quadruple
    • Membership that changes per draw or per epoch
  • Mixed conventions
  • Validation
  • Zero-mass bodies
  • How it works
• Parametrizations
• • Size: a or P
  • Shape
  • Phase
  • Cartesian initial conditions
  • Hyperbolic orbits
  • Thiele-Innes constants
  • Radial-velocity-only fits
  • The M= compatibility override
• N-body integration
• • The timestep
  • The osculating epoch t0
  • Convention independence
  • What is exact
  • Differentiability
  • Citing
• Plotting
• • Quick looks
  • Orbit tracks
  • The house theme
  • Time axes
  • Choosing epochs
  • Labels and units
  • Many orbits at once
  • Animation
  • The logo

Documentation

• API Documentation
• • Constructing systems
  • • When construction fails
    • Convention constructors
    • Alternative parametrizations
    • Two-body conveniences
  • References
  • Solving
  • • Propagators
  • Observables
  • • Physical units
    • Angular units
    • Frame quantities
  • Kepler solvers
  • System properties
  • Epochs and time
  • Constants
  • Plotting utilities
  • Index
• Conventions
• • Units
  • • The epoch timescale
  • The geometric convention
  • Elements
  • Reference epochs are three distinct things
  • The frame describes the barycentre
  • Topology is static
  • What is deliberately absent
• Precision opt-outs
• • observing_geometry
  • barycentric_lighttime
  • • The two settings are two conventions, and your data picks one
  • Rules of thumb
  • The Einstein term in radvel (modelled, always)
  • Observer-aware observables (opt-in, per read)
  • • Which reference for which data
  • What is not modelled at all
  • • Observer-side geometry
    • Relativistic terms
  • Cost
  • Checking the difference
• Kepler solvers
• • The SIMD batch path
  • The hyperbolic solver
  • High precision
  • Comparison
• Migrating from v0.11
• • The one idea that changed
  • Constructors
  • Masses
  • Solving
  • Observables
  • Angles and epochs
  • Plotting moved to Makie
  • Numerical differences
  • What v1 can do that v0.11 could not

Attribution

If you find this package useful in your research, please cite the following paper (open-access link).

The N-body propagator is the symplectic map of Agol, Hernandez & Langford (2021), MNRAS 507, 1582 (arXiv:2106.02188), whose kernels are merged into this package with the authors' agreement from NbodyGradient.jl (MIT, © Eric Agol). Please cite that paper when publishing results computed with AHL21. The hierarchy-matrix formalism follows Hamers & Portegies Zwart (2016).

This software package contains calculations that are adapted from various open source packages, including:

• NASA/JPL SPICE (public domain)
• keplerorbit.py by Spencer Wallace (MIT license)
• PoliaAstro (MIT license)
• Orbitize by Blunt et al. (BSD 3-Clause License)
• RadVel by Fulton et al. (MIT license)

These codes were useful references in the development of this package but are not redistributed.