API Documentation

AbsoluteVisual{OrbitType}(..., ref_epoch=, ra=, dec=, plx=, rv=, pmra=, pmdec=)

This wraps another orbit object to add parallax, proper motion, and RV fields, at a given reference epoch.

Like a Visual{OrbitType} this allows for calculating projected quantities, eg. separation in milliarcseconds.

What this type additionally does is correct for the star's 3D motion through space (RV and proper motion) and differential light travel-time compared to a reference epoch when calculating various quantities. This becomes necessary when computing eg. RVs over a long time period.

ra : degrees dec : degrees parallax : mas pmra : mas/yr pmdec : mas/yr rv : m/s ref_epoch : years

TODO: account for viewing angle differences and differential light travel time between a planet and its host.

AbsoluteVisual{OrbitType}(..., ref_epoch=, ra=, dec=, plx=, rv=, pmra=, pmdec=)

This wraps another orbit object to add parallax, proper motion, and RV fields, at a given reference epoch.

Like a Visual{OrbitType} this allows for calculating projected quantities, eg. separation in milliarcseconds.

What this type additionally does is correct for the star's 3D motion through space (RV and proper motion) and differential light travel-time compared to a reference epoch when calculating various quantities. This becomes necessary when computing eg. RVs over a long time period.

ra : degrees dec : degrees plx : mas pmra : mas/yr pmdec : mas/yr rv : m/s ref_epoch : days

TODO: account for viewing angle differences and differential light travel time between a planet and its host.

AbstractOrbit

Represents a orbit. Contains all the information to calculate the location of a planet at a given time, true anomaly, eccentric anomaly, or mean anomaly. Different concrete implementations of AbstractOrbit contain varying amounts of information.

Basic information about the orbit can be queried using functions like period(orbit).

Orbits can be solved using functions like orbitsolve(orb).

See: RadialVelocityOrbit, KepOrbit, VisualOrbit

AbstractOrbitSolution

Represents the solution of an orbit. Contains all the information of an AbstractOrbit, plus information necessary to uniquely locate a planet.

The solution can be queried using a variety of functions such as radvel(solution).

The API for creating orbit solutions it not considered public as the fields may change between minor versions. Instead, create solutions only through the public orbitsolve and orbitsolve_... functions.

PlanetOrbits.Auto()

Automatic choice of Kepler solver algorithm. Currently defaults to PlanetOrbits.Markley()

This constructor assumes that 1 year, 1 AU, and 1 solar mass are compatible. According to IAU definitions, they are not. Use with care where high precision is needed.

Convert an existing orbit object to a CartesianOrbit.

PlanetOrbits.Goat()

Kepler solver implementation from https://arxiv.org/abs/2103.15829 and https://github.com/oliverphilcox/Keplers-Goat-Herd

It is here for comparison purposes only. In general, Markley() is more performant and accurate.

KepOrbit(
    a, # semi-major axis [AU]
    e, # eccentricity
    i, # inclination [rad]
    ω, # argument of periapsis [rad]
    Ω, # longitude of ascending node [rad]
    tp, # epoch of periastron passage at MJD=0
    M, # mass of primary [M⊙]
)

Represents the Keplerian elements of a secondary body orbiting a primary. Use the traditional Campbell parameterization. Values can be specified by keyword argument or named tuple for convenience.

PlanetOrbits.Markley()

Kepler solver implementation from AstroLib, based on Markley (1995) Celestial Mechanics and Dynamical Astronomy, 63, 101 (DOI:10.1007/BF00691917).

Represents a CartesianOrbit evaluated to some position.

Represents a KepOrbit evaluated to some position.

Represents a RadialVelocityOrbit evaluated to some position.

Represents a ThieleInnesOrbit evaluated to some position.

RadialVelocityOrbit(a, e, ω, tp, M)

Represents an orbit of a planet with only the information retrievable from radial velocity measurements. That is, without inclination, longitude of ascending node, or distance to the system.

PlanetOrbits.RootsMethod(method::Roots.PlanetOrbits.Roots.AbstractUnivariateZeroMethod, kwargs...)

Wraps a root finding method from Roots.jl. Requires Roots to be loaded first. You can also pass keyword arguments that will be forwarded to Roots to control the tolerance.

Examples:

method = PlanetOrbits.RootsMethod(Roots.Newton())
method = PlanetOrbits.RootsMethod(Roots.Thukral5B())
method = PlanetOrbits.RootsMethod(Roots.Bisection())
method = PlanetOrbits.RootsMethod(Roots.A42())
method = PlanetOrbits.RootsMethod(Roots.Newton(), rtol=1e-3, atol=1e-3)

ThieleInnesOrbit(e, tp, M, plx, A, B, F, G)

Represents a visual orbit of a planet using Thiele-Innes orbital elements. Convertable to and from a VisualOrbit. This parameterization does not have the issue that traditional angular parameters have where the argument of periapsis and longitude of ascending node become undefined for circular and face on orbits respectively.

Visual{OrbitType}(..., plx=...)

This wraps another orbit to add the parallax distance field plx, thus allowing projected quantities to be calculated. It forwards everything else to the parent orbit.

For example, the KepOrbit type supports calculating x and y positions in AU. A Visual{KepOrbit} additionally supports calculating projected right ascension and declination offsets.

Visual{OrbitType}(..., plx=...)

This wraps another orbit to add the parallax distance field plx, thus allowing projected quantities to be calculated. It forwards everything else to the parent orbit.

For example, the KepOrbit type supports calculating x and y positions in AU. A Visual{KepOrbit} additionally supports calculating projected right ascension and declination offsets.

Note: the ThieleInnesOrbit type does not need to be wrapped in Visual as it the Thiele-Innes constants are already expressed in milliarcseconds and thus it always requires a plx value.

accdec(orbit, t)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the secondary at the time t [days].

accdec(o)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the secondary from an instance of AbstractOrbitSolution.

accdec(elem, t, M_planet)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the primary in at the time t [days]. The units of M_planet and elem.M must match.

accdec(o)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the primary from an instance of AbstractOrbitSolution. The units of M_planet and elem.M must match.

accra(orbit, t)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the secondary at the time t [days].

accra(o)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the secondary from an instance of AbstractOrbitSolution.

accra(elem, t, M_planet)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the primary in at the time t [days]. The units of M_planet and elem.M must match.

accra(o)

Get the instantaneous acceleration [mas/julian year^2] in the right-ascension direction of the primary from an instance of AbstractOrbitSolution. The units of M_planet and elem.M must match.

apoapsis(orbit)

Return the apoapsis of an orbit in AU.

Keywords: apoastron, apohelion, apogee

astuple(elements)

Return the parameters of a KepOrbit value as a tuple.

This function calculates how to account for stellar 3D motion when comparing measurements across epochs (epoch1 vs epoch2).

Typically epoch1 is your reference epoch, epoch2 is your measurement epoch, and the remaining parameters are parameters you are hoping to fit. You use this function to calculate their compensated values, and compare these to data at epoch2.

Will also calculates light travel time, returning updated epochs (epoch2a) due to change in distance between epoch1 and epoch2. epoch2 will be when the light was detected, epoch2a will be the "emitted" time accounting for the different positions between epoch1 and epoch 2.

Original Author: Eric Nielsen

PlanetOrbits.dec(orbit, t)

Get the instantaneous position of a companion in degrees of RA and Dec. For the relative position, see decoff.

decoff(orbit, t)

Get the offset [mas] from the primary body in Declination at the time t [days].

decoff(orbit, t)

Get the offset [mas] from the primary body in Declination from an instance of AbstractOrbitSolution.

distance(orbit)

Distance to the system [pc].

eccanom(orbit, t)

Get the eccentric anomaly [radians] of the secondary at the time t [days].

eccanom(o)

Get the eccentric anomaly [radians] of the secondary from an instance of AbstractOrbitSolution.

Note that for hyperbolic orbits, eccentric anomaly is not defined and the hyperbolic anomaly is returned instead.

eccentricity(orbit)

Eccentricity of an orbit, between 0 and 1.

inclination(orbit)

Inclination of an orbit, if available [rad].

meananom(orbit, t)

Get the mean anomaly [radians] of the secondary at the time t [days].

meananom(o)

Get the mean anomaly [radians] of the secondary from an instance of AbstractOrbitSolution.

meanmotion(orbit)

Mean motion [rad/julian year].

Note: a 1 AU (IAU) orbit around a 1Msun (IAU) star has a period just over 1 julian year.

mjd("2020-01-01")

Get the modfied julian day of a date, or in general a UTC timestamp.

mjd(Date("2020-01-01"))

Get the modfied julian day of a Date or DateTime object.

mjd()

Get the current modified julian day of right now.

mjd2date(modified_julian)

Get a Date value from a modfied julian day, rounded to closest day

Examples

julia> mjd2date(59160.8)
2020-11-08

orbit(...)

Construct an orbit from the provided keyword arguments. Will automatically select a subclass of AbstractOrbit based on the information provided. This is a convenience function that is not type stable and should not be used in performance sensitive contexts. Instead, call one of the concrete constructors KepOrbit, VisualOrbit, or RadialVelocityOrbit directly. This function logs the kind of elements created so that it's easy to select the correct constructor.

Required arguments:

• a: semi-major axis [AU]
• M: gravitational parameter [M⊙]

Optional arguments:

• tp: epoch of periastron passage, default=0
• e: eccentricity, default=0
• ω: argument of periapsis [rad], default=0
• i: inclination [rad]
• Ω: longitude of ascending node [rad]
• plx: parallax [mas]; defines the distance to the primary

orbitsolve(orbit, t, method=Auto())

Given an orbit object and a time t in days, get the position and velocity of the secondary body (e.g. planet around a star).

This will output a struct that is a subtype of AbstractOrbitSolution which we can then query with raoff, decoff, radvel, etc.

You can also calculate those quanitities individually (see their docstrings) but if you need more than one, it is most efficient to save the orbit solution once.

Note: these calculations use the small angle approximation, so are only accurate when the star is much further way from the observer than the secondary is from the primary.

See also: orbitsolve_ν, orbitsolve_meananom, orbitsolve_eccanom, projectedseparation, raoff, decoff, radvel, propmotionanom.

orbitsolve_eccanom(elements, EA)

Same as orbitsolve, but solves orbit for a given eccentric anomaly instead of time.

orbitsolve_meananom(elements, MA)

Same as orbitsolve, but solves orbit for a given mean anomaly instead of time.

orbitsolve_ν(elem, ν)

Solve a keplerian orbit from a given true anomaly [rad]. See orbitsolve for the same function accepting a given time.

orbitsolve_ν(elem, ν, EA)

Solve an orbit from a given true anomaly [rad]. See orbitsolve for the same function accepting a given time. Can optionally pass eccentric anomaly (EA) if already computed.

periapsis(orbit)

Return the periapsis of an orbit in AU.

Keywords: periastron, perihelion, perigee

periastron(elements)

Compute the MJD of periastron passage most recently after the reference epoch tref specified in the orbit. N.B. mjd of 58849 = 2020-01-01

period(orbit)

Period of an orbit [days].

Note: a 1 AU (IAU) orbit around a 1Msun (IAU) star has a period just over 1 julian year.

pmdec(orbit, t)

Get the instantaneous proper motion anomaly [mas/julian year] in declination of the secondary at the time t [days].

pmdec(o)

Get the instantaneous proper motion anomaly [mas/julian year] in declination of the secondary from an instance of AbstractOrbitSolution.

pmdec(elem, t, M_planet)

Get the instantaneous proper motion anomaly [mas/julian year] in declination of the primary in at the time t [days]. The units of M_planet and elem.M must match.

pmdec(o, M_planet)

Same as above, but from an orbit solution.

pmra(orbit, t)

Get the instantaneous proper motion anomaly [mas/julian year] in right-ascension of the secondary at the time t [days].

pmra(o)

Get the instantaneous proper motion anomaly [mas/julian year] in right-ascension of the secondary from an instance of AbstractOrbitSolution.

pmra(elem, t, M_planet)

Get the instantaneous proper motion anomaly [mas/julian year] in right-ascension of the primary in at the time t [days]. The units of M_planet and elem.M must match.

pmra(o, M_planet)

Same as above, but from an orbit solution.

posangle(orbit, t)

Calculate the position angle [rad] of the secondary about its primary from our perspective at the time t [days].

posangle(o)

Calculate the position angle [rad] of the secondary about its primary from our perspective from an instance of AbstractOrbitSolution.

posangle(elem, t, M_planet)

Calculate the position angle [rad] of the secondary about its primary from our perspective at the time t [days]. In this case only, the value of M_planet can be arbitrary.

posangle(o, M_planet)

Calculate the position angle [rad] of the primary from our perspective from an instance of AbstractOrbitSolution. In this case only, the value of M_planet can be arbitrary.

posx(orbit, t)

Get the offset [AU] from the primary body at the time t [days].

posx(orbit, t)

Same as above, but from an instance of AbstractOrbitSolution.

Get the position in the x direction in astronomical units.

posy(orbit, t)

Get the offset [AU] from the primary body at the time t [days].

posy(o)

Same as above, but from an instance of AbstractOrbitSolution.

Get the position in the y direction in astronomical units.

posz(orbit, t)

Get the offset [AU] from the primary body at the time t [days].

posz(o)

Same as above, but from an instance of AbstractOrbitSolution.

Get the position in the z direction in astronomical units.

projectedseparation(orbit, t)

Calculate the projected separation [mas] of the secondary from its primary at the time t [days].

projectedseparation(o)

Calculate the projected separation [mas] of the secondary from its primary from an instance of AbstractOrbitSolution.

PlanetOrbits.ra(orbit, t)

Get the instantaneous position of a companion in degrees of RA and Dec. For the relative position, see raoff.

radvel(orbit, t)

Get the relative radial velocity [m/s] of the secondary vs the primary along the line of sight (positive meaning moving away) at the time t [days].

radvel(o)

Get the relative radial velocity [m/s] of the secondary vs the primary along the line of sight (positive meaning moving away) from an instance of AbstractOrbitSolution.

radvel(elem, t, M_planet)

Get the absolute radial velocity [m/s] of the primary long the line of sight (positive meaning moving away) at the time t [days]. The units of M_planet and elem.M must match.

radvel(o, M_planet)

Get the absolute radial velocity [m/s] of the primary along the line of sight (positive meaning moving away) from an AbstractOrbitSolution. The units of M_planet and elem.M must match.

raoff(orbit, t)

Get the offset [mas] from the primary body in Right Ascension at the time t [days].

raoff(o)

Get the offset [mas] from the primary body in Right Ascension from an instance of AbstractOrbitSolution.

semiamplitude(orbit)

Radial velocity semiamplitude [m/s].

semimajoraxis(orbit)

Semi-major axis of an orbit, if available [au].

semiminoraxis(orbit)

Return the semi-minor axis of an orbit in AU.

totalmass(orbit)

Total mass of the system in solar masses

trueanom(orbit, t)

Get the true anomaly [radians] of the secondary at the time t [days].

trueanom(o)

Get the true anomaly [radians] of the secondary from an instance of AbstractOrbitSolution.

Get the velocity in the x direction in astronomical units / julian year.

Get the velocity in the y direction in astronomical units / julian year.

Get the velocity in the z direction in astronomical units / julian year.

years2mjd()

Convert from decimal years (e.g. 1995.25) into modified julian date, rounded to closest second