Orbit utilities

Collection of utilities to compute and convert orbital elements

Conventions

M

mean - mean anomaly (normalized to 2 pi for one period)

f

anomaly - true anomaly (angle from perapis relative to focal point)

E

eccentric - eccentric anomaly - angle from periapsis realtive to centre of ellipse to projection of position on circle though centre of ellipsis

p

phase - mean / (2 pi)

t

tau - time relative to periapsis

a

semimahor axis

b

semiminor axis (90 deg in direction of rotation

e

Runge-Lenz vector

W

Longitude of ascending node

w

argument of periapsis

i

inclination

EE

specific energy

euler = (W, i, w)

Euler angles

(use positive x-axis as refernece direction, observer in z direction)

r

radius vecor of orbit, r2 - r1

v

velocity vector of orbit, v2 - v1

mt

total mass (cgs)

mti

1 / mt

m1

mass of object 1

m2

mass of object 2

Gmi

1 / (G mt)

xn

norm of vector x

xe

unit vector of vector x

h

specific angular momentum of orbit

q

\(h \times e\)

ln

(\(\ell\)) norm of semi-latus rectum (scalar)

rp

periastron distance (scalar)

ra

apoastron distance (scalar)

See https://www.bogan.ca/orbits/kepler/orbteqtn.html

Special conversion functions

*1: e < 1
*2: e > 1
*3: e == 1

Implementation

multistar.orbit.mean2eccentric(M, en=0): compute eccentric anomaly as a function of the mean anomaly relative to periapsis.

multistar.orbit.phase2eccentric(phase, en=0): compute elliptical orbit ellipse angle (eccentric anomaly) as function of phase ([0, 1], mean anomaly / (2*pi)) relative to periapsis

multistar.orbit.ae2rp(an, en): convert semimajor axis (scalar) and eccentrity to periapsis distance (rp)

multistar.orbit.ae2ra(an, en)

convert semimajor axis (scalar) and eccentrity to apoapsis distance (ra)

yields:

nan for parabolic orbits
inf for hyperbolic orbits

multistar.orbit.rpe2a(rp, en): convert periapsis distance (rp) and eccentrity to semimajor axis (scalar)

multistar.orbit.rpe2l(rp, en): convert periapsis distance (rp) and eccentrity to semi-latus rectum (l)

multistar.orbit.ler2anomaly(ln, en, rn): compute true anomaly from semi-latus rectum, eccentrity, and distance

multistar.orbit.rper2anomaly(rp, en, rn): compute true anomaly from periapsis distance (rp), eccentrity, and distance

multistar.orbit.rper2tau(rp, en, rn, **kwargs)

compute time since periastron from periapsis distance (rp), eccentrity, and distance

kwargs need to contain mass (m1 + m2 | mt | mti) or wn

multistar.orbit.rper2mean(rp, en, rn): compute mean anomaly from periapsis distance (rp), eccentrity, and distance

multistar.orbit.rper2phase(rp, en, rn): compute phase from periapsis distance (rp), eccentrity, and distance

multistar.orbit.le2a(ln, en): convert semi-latus rectum (l) and eccentrity to semimajor axis (scalar)

multistar.orbit.rpl2e(rp, ln): convert periapsis distance (rp) and semi-latus rectum (l) to eccentrity (en)

multistar.orbit.ae2l(an, en): convert semimajor axis (scalar) and eccentrity (en) to semi-latus rectum (l)

multistar.orbit.ae2EE(an, en, mt): return specific energy of orbit (EE) for given semi-major axis (an), eccentricity (en), and total mass (mt)

multistar.orbit.EE2a(EE, mt)

return semi-major axis of the orbit (an) for given specific energy (EE) and total mass (mt)

For EE = 0, NaN is returned

multistar.orbit.rpEE2ae(rp, EE, mt): return semi-major axis and eccentricity for given periapsis distance (rp) and specific energy (EE) and total mass (mt)

multistar.orbit.eEE2rp(en, EE, mt): return periapsis distnace (cm) for given eccenricity (en), specific energy (EE, erg), and total mass (mt, g)

multistar.orbit.ae2vperi(an, en, mt): return velocity at periapsis

multistar.orbit.ae2vapo(an, en, mt): return velocity at apoapsis or infinity

multistar.orbit.rv2vapo(*args, **kwargs): return velocity at apoapsis or infinity for given r, v, m (see orbit_rv2abe)

multistar.orbit.rv2vperi(*args, **kwargs): return velocity at periapsis for given r, v, m (see orbit_rv2abe)

multistar.orbit.rv2n(*args, **kwargs): return mean motion for given r, v, m (see orbit_rv2abe)

multistar.orbit.rpa2e(rp, an, ellipse=True, elim=None): convert periapsis distance (rp) and semimajor axis (scalar) to eccentrity

multistar.orbit.amt2w(an, mt): get angular velocity form semimajor axis and total mass

multistar.orbit.amt2P(an, mt): get period form semimajor axis and total mass

multistar.orbit.Pmt2a(P, mt): get semimajor axis form period and total mass

multistar.orbit.rpemt2P(rp, e, mt): get period form periapsis distance (rp) and eccentricity

multistar.orbit.rv2rp(*args, **kwargs): return rp for given r, v, mt

multistar.orbit.rv2rpf(*args, **kwargs): return rp and f for given r, v, mt

multistar.orbit.rv2f(*args, **kwargs): return f for given r, v, mt

multistar.orbit.rv2M(*args, **kwargs): return M for given r, v, mt

multistar.orbit.rv2E(*args, **kwargs): return E for given r, v, mt

multistar.orbit.rv2en(*args, **kwargs): return en for given r, v, mt

multistar.orbit.rpemt2vp(rp, en, mt): return vp for given rp, en, mt

multistar.orbit.rv2vp(r, v, mt, elim=None): return vp for given r, v, mt

multistar.orbit.tau2mean(t, en=0, wn=None, an=None, rp=None, mt=None, mti=None, m1=None, m2=None): convert time since periapsis to mean anomaly

multistar.orbit.mean2tau(M, en=0, wn=None, an=None, rp=None, mt=None, mti=None, m1=None, m2=None): convert mean anomaly to time since periapsis

multistar.orbit.phase2tau(p, *args, **kwargs): convert phase (mean anomaly / (2 * PI)) to time since periapsis

multistar.orbit.tau2phase(*args, **kwargs): convert time since periapsis to phase (mean anomaly / (2 * PI))

multistar.orbit.tau2eccentric(tau, en, **kwargs): convert time since periapsis to eccentric anomaly

multistar.orbit.tau2anomaly(t, en, **kwargs): convert time since periapsis to true anomaly

multistar.orbit.anomaly2tau(f, en, **kwargs): convert true anomaly to time since periapsis

multistar.orbit.eccentric2tau(f, en, **kwargs): convert eccentric anomaly to time since periapsis

multistar.orbit.eccentric2mean(E, en=0)

Return mean anomaly (phase * (2*pi) for a given elliptical angle relative to periapsis.

For a periodic orbit this is an angle staring at periapsis.

multistar.orbit.eccentric2phase(E, en=0)

Return phase (mean anomaly / (2*pi) for a given elliptical angle relative to periapsis.

For a periodic orbit the phase is the fraction of the period staring at periapsis.

multistar.orbit.eccentric2anomaly(E, en=0): return true anomaly from eccentric anomaly

multistar.orbit.anomaly2eccentric(f, en=0): compute eccentric anomaly from true anomaly

multistar.orbit.maxanomaly(en): return maximum allowed true anomaly magnitude for (hyperbolic) orbits

multistar.orbit.anomaly2phase(f, en=0): compute phase from true anomaly

multistar.orbit.anomaly2mean(f, en=0): compute mean anomaly from true anomaly

multistar.orbit.mean2anomaly(M, en=0): compute true anomaly from mean anomaly

multistar.orbit.phase2anomaly(phase, en=0): compute true anomaly from phase

multistar.orbit.phase2mean(phase, en=0): compute mean anomaly from phase

multistar.orbit.mean2phase(M, en=0): compute phase from mean anomaly

multistar.orbit.convert2(q, en=None, phase=None, E=None, f=None, t=None, M=None, wn=None, an=None, rp=None, mti=None, mt=None, m1=None, m2=None, elim=None)

obtain desired orbital position parameter from other and required inputs (en; an, mt, wn, rp as needed)

E - eccentric anomaly M - mean anomaly t - tau - time since periapsis p - phase (internal; mean anomaly / 2 pi for elliptical orbits) f - true anomaly

multistar.orbit.rrpen2tau(rn, rp, en, elim=None, **kwargs)

convert rn to tau for given rp, en, and mass

mass is mt, mti, or (m1, m2)

multistar.orbit.orbit_rv2abe(r, v, mti=None, mt=None, m1=None, m2=None, m=None, return_phase=False, return_angle=False, return_tau=False, return_omega=False, return_mt=False, elim=None)

Return orbital elements for a given r, v, and total mass

Requires one if the following:: m1, m2 - masses of the two bodies mt - total mass of the two bodies mti - inverse of the sum of the masses of the two bodies (default, preferred) m - array for masses

if mti > 1. assume it is actually mt

multistar.orbit.orbit_rv2aeiwWf(r, v, mti=None, mt=None, m1=None, m2=None, elim=None)

Return orbital elements a, e, i, omega, Omega, and f for a given r, v, and total mass

Requires one if the following:: m1, m2 - masses of the two bodies mt - total mass of the two bodies mti - inverse of the sum of the masses of the two bodies (default, preferred)

if mti > 1. assume it is actually mt

ez is used as direction of observer ex is used as origin of longitude

multistar.orbit.orbit_aeiwWf2rv(an, en, i, w, W, f, mti=None, mt=None, m1=None, m2=None, elim=None): get back physical r,v from observed orbital parameters

multistar.orbit.orbit_aeiwWf2abe(an, en, i, w, W, f, elim=None): get back vectorial a, b, en, phase from observed orbital parameters

multistar.orbit.orbit_abe2aeiwWf(a, b, en, phase): get back observed orbital parameters from vectorial a, b, en, phase

multistar.orbit.orbit_abe2rv(a, b, en, phase=None, E=None, f=None, t=None, M=None, mti=None, mt=None, m1=None, m2=None)

return radius and velocity

velocity just scales as sqrt(Gm = GRAV * mt)

multistar.orbit.evinf2rp(en, vinf, mti=None, mt=None, m1=None, m2=None)

rp from eccentricity and velocity at infinity for hyperbolic orbit

returns NaN for en < 1 and inf for en == 1

multistar.orbit.bvinf2rpen(b, vinf, mti=None, mt=None, m1=None, m2=None): eccentricity and rp from impact parameter and v_inf for hyperbola

multistar.orbit.hvinf2b(hn, vinf)

impact parameter from specific moment of inertia and velocity at infinity for hyperbolic orbits

return np.inf for parabolic orbits (vinf == 0)

return np.nan for hn < 0 or elliptic orbits

multistar.orbit.hEE2b(hn, EE)

impact parameter from specific moment of inertia and energy at infinity for hyperbolic orbits

return np.inf for parabolic orbits (EE == 0)

return np.nan for hn < 0 or elliptic orbits

multistar.orbit.hEE2rpen(hn, EE, mti=None, mt=None, m1=None, m2=None, elim=None): eccentricity and rp from specific angular momentum and specific energy for hyperbola

multistar.orbit.bEE2rpen(b, vinf, mti=None, mt=None, m1=None, m2=None): eccentricity and rp from impact parameter and specific energy for hyperbola

multistar.orbit.rpe2b(rp, en)

impact parameter b from periapsis distance and eccentricity

returns NaN for en < 1 and inf for en == 1

multistar.orbit.ae2va(an, en, mti=None, mt=None, m1=None, m2=None)

apoapsis velocity from semimajor axis and eccentricity

for e >= 1 return velocity at infinity (0 for e == 1)

multistar.orbit.ae2vp(an, en, mti=None, mt=None, m1=None, m2=None): periapsis velocity from semimajor axis and eccentricity

multistar.orbit.rpra2en(ra, rp)

return eccentricty based on ra and rp.

switch of the two parameters is allowed

class multistar.orbit.Orbit(a, b, en, star=True, color=None)

Bases: object

container class for orbit