User guide

Defining the orbit: Orbit objects

The core of poliastro are the Orbit objects inside the poliastro.twobody module. They store all the required information to define an orbit:

  • The body acting as the central body of the orbit, for example the Earth.
  • The position and velocity vectors or the orbital elements.
  • The time at which the orbit is defined.

First of all, we have to import the relevant modules and classes:

import numpy as np
from astropy import units as u

from poliastro.bodies import Earth, Sun
from poliastro.twobody import Orbit

From position and velocity

There are several methods available to create Orbit objects. For example, if we have the position and velocity vectors we can use from_vectors():

# Data from Curtis, example 4.3
r = [-6045, -3490, 2500] *
v = [-3.457, 6.618, 2.533] * / u.s

ss = Orbit.from_vectors(Earth, r, v)

And that’s it! Notice a couple of things:

  • Defining vectorial physical quantities using Astropy units is very easy. The list is automatically converted to a Quantity, which is actually a subclass of NumPy arrays.

  • If no time is specified, then a default value is assigned:

    >>> ss.epoch
    <Time object: scale='utc' format='jyear_str' value=J2000.000>
    >>> ss.epoch.iso
    '2000-01-01 12:00:00.000'
Plot of the orbit

If we’re working on interactive mode (for example, using the wonderful IPython notebook) we can immediately plot the current state:

from poliastro.plotting import plot

This plot is made in the so called perifocal frame, which means:

  • we’re visualizing the plane of the orbit itself,
  • the \(x\) axis points to the pericenter, and
  • the \(y\) axis is turned \(90 \mathrm{^\circ}\) in the direction of the orbit.

The dotted line represents the osculating orbit: the instantaneous Keplerian orbit at that point. This is relevant in the context of perturbations, when the object shall deviate from its Keplerian orbit.


Be aware that, outside the Jupyter notebook (i.e. a normal Python interpreter or program) you might need to call after the plotting commands or plt.ion() before them or they won’t show. Check out the Matplotlib FAQ for more information.

From classical orbital elements

We can also define a Orbit using a set of six parameters called orbital elements. Although there are several of these element sets, each one with its advantages and drawbacks, right now poliastro supports the classical orbital elements:

  • Semimajor axis \(a\).
  • Eccentricity \(e\).
  • Inclination \(i\).
  • Right ascension of the ascending node \(\Omega\).
  • Argument of pericenter \(\omega\).
  • True anomaly \(\nu\).

In this case, we’d use the method from_classical():

# Data for Mars at J2000 from JPL HORIZONS
a = 1.523679 * u.AU
ecc = 0.093315 *
inc = 1.85 * u.deg
raan = 49.562 * u.deg
argp = 286.537 * u.deg
nu = 23.33 * u.deg

ss = Orbit.from_classical(Sun, a, ecc, inc, raan, argp, nu)

Notice that whether we create a Orbit from \(r\) and \(v\) or from elements we can access many mathematical properties individually using the state property of Orbit objects:

<Quantity 686.9713888628166 d>
>>> ss.state.v
<Quantity [  1.16420211, 26.29603612,  0.52229379] km / s>

To see a complete list of properties, check out the poliastro.twobody.orbit.Orbit class on the API reference.

Changing the orbit: Maneuver objects

poliastro helps us define several in-plane and general out-of-plane maneuvers with the Maneuver class inside the poliastro.maneuver module.

Each Maneuver consists on a list of impulses \(\Delta v_i\) (changes in velocity) each one applied at a certain instant \(t_i\). The simplest maneuver is a single change of velocity without delay: you can recreate it either using the impulse() method or instantiating it directly.

dv = [5, 0, 0] * u.m / u.s

man = Maneuver.impulse(dv)
man = Maneuver((0 * u.s, dv))  # Equivalent

There are other useful methods you can use to compute common in-plane maneuvers, notably hohmann() and bielliptic() for Hohmann and bielliptic transfers respectively. Both return the corresponding Maneuver object, which in turn you can use to calculate the total cost in terms of velocity change (\(\sum |\Delta v_i|\)) and the transfer time:

>>> ss_i = Orbit.circular(Earth, alt=700 *
>>> hoh = Maneuver.hohmann(ss_i, 36000 *
>>> hoh.get_total_cost()
<Quantity 3.6173981270031357 km / s>
>>> hoh.get_total_time()
<Quantity 15729.741535747102 s>

You can also retrieve the individual vectorial impulses:

>>> hoh.impulses[0]
(<Quantity 0 s>, <Quantity [ 0.        , 2.19739818, 0.        ] km / s>)
>>> hoh[0]  # Equivalent
(<Quantity 0 s>, <Quantity [ 0.        , 2.19739818, 0.        ] km / s>)
>>> tuple(_.decompose([, u.s]) for _ in hoh[1])
(<Quantity 15729.741535747102 s>, <Quantity [ 0.        , 1.41999995, 0.        ] km / s>)

To actually retrieve the resulting Orbit after performing a maneuver, use the method apply_maneuver():

>>> ss_f = ss_i.apply_maneuver(hoh)
>>> ss_f.rv()
(<Quantity [ -3.60000000e+04, -7.05890200e-11, -0.00000000e+00] km>, <Quantity [ -8.97717523e-16, -3.32749489e+00, -0.00000000e+00] km / s>)

More advanced plotting: OrbitPlotter objects

We previously saw the poliastro.plotting.plot() function to easily plot orbits. Now we’d like to plot several orbits in one graph (for example, the maneuver we computed in the previous section). For this purpose, we have OrbitPlotter objects in the plotting module.

These objects hold the perifocal plane of the first Orbit we plot in them, projecting any further trajectories on this plane. This allows to easily visualize in two dimensions:

from poliastro.plotting import OrbitPlotter

op = OrbitPlotter()
ss_a, ss_f = ss_i.apply_maneuver(hoh, intermediate=True)
op.plot(ss_i, label="Initial orbit")
op.plot(ss_a, label="Transfer orbit")
op.plot(ss_f, label="Final orbit")

Which produces this beautiful plot:

Hohmann transfer

Plot of a Hohmann transfer.

Where are the planets? Computing ephemerides

New in version 0.3.0.

Thanks to Astropy and jplephem, poliastro can now read Satellite Planet Kernel (SPK) files, part of NASA’s SPICE toolkit. This means that we can query the position and velocity of the planets of the Solar System.

The function poliastro.ephem.get_body_ephem() will return position and velocity vectors using low precision ephemerides available in Astropy and an astropy.time.Time:

>>> from astropy import time
>>> epoch = time.Time("2015-05-09 10:43")
>>> from poliastro import ephem
>>> r, v = ephem.get_body_ephem("earth", epoch)
>>> r
<Quantity [ -9.99804957e+07, -1.03444423e+08, -4.48688994e+07] km>
>>> v
<Quantity [ 1879036.90811082,-1579527.58964453, -684736.68156739] km / d>

This does not require any external download. If on the other hand we want to use higher precision ephemerides, we can tell Astropy to do so:

>>> from astropy.coordinates import solar_system_ephemeris
>>> solar_system_ephemeris.set("jpl")
|==========>-------------------------------|  23M/119M (19.54%) ETA    59s22ss23

This in turn will download the ephemerides files from NASA and use them for future computations. For more information, check out Astropy documentation on ephemerides.


The position and velocity vectors are given with respect to the Solar System Barycenter in the International Celestial Reference Frame (ICRF), which means approximately equatorial coordinates.

Traveling through space: solving the Lambert problem

The determination of an orbit given two position vectors and the time of flight is known in celestial mechanics as Lambert’s problem, also known as two point boundary value problem. This contrasts with Kepler’s problem or propagation, which is rather an initial value problem.

The package poliastro.iod allows as to solve Lambert’s problem, provided the main attractor’s gravitational constant, the two position vectors and the time of flight. As you can imagine, being able to compute the positions of the planets as we saw in the previous section is the perfect complement to this feature!

For instance, this is a simplified version of the example Going to Mars with Python using poliastro, where the orbit of the Mars Science Laboratory mission (rover Curiosity) is determined:

>>> from astropy import time
>>> date_launch = time.Time('2011-11-26 15:02', scale='utc')
>>> date_arrival = time.Time('2012-08-06 05:17', scale='utc')
>>> tof = date_arrival - date_launch
>>> from poliastro import ephem
>>> r0, _ = ephem.planet_ephem(ephem.EARTH, date_launch)
>>> r, _ = ephem.planet_ephem(ephem.MARS, date_arrival)
>>> from poliastro import iod
>>> from poliastro.bodies import Sun
>>> (v0, v), = iod.lambert(Sun.k, r0, r, tof)
>>> v0
<Quantity [-29.29150998, 14.53326521,  5.41691336] km / s>
>>> v
<Quantity [ 17.6154992 ,-10.99830723, -4.20796062] km / s>
MSL orbit

Mars Science Laboratory orbit.

Per Python ad astra ;)