# API reference¶

This page holds poliastro’s API documentation, which might be helpful for final users or developers to create their own poliastro-based utilities. Among the different sub-packages and modules, we might differentiate two big categories: core utilities and high-level ones.

## High level API¶

The high level API of poliastro allows you to do most common tasks (propagate an osculating orbit, sampling an ephemerides, compute maneuvers) in a straightforward way. All the methods expect Astropy units.

The most important high level objects and methods are poliastro.twobody.Orbit, , and . Here is a summarized reference of commonly used methods:

class poliastro.twobody.Orbit(state, epoch)

Position and velocity of a body with respect to an attractor at a given time (epoch).

Regardless of how the Orbit is created, the implicit reference system is an inertial one. For the specific case of the Solar System, this can be assumed to be the International Celestial Reference System or ICRS.

classmethod from_classical(cls, attractor, a, ecc, inc, raan, argp, nu, epoch=J2000, plane=Planes.EARTH_EQUATOR)

Return Orbit from classical orbital elements.

Parameters
• attractor () – Main attractor.

• a () – Semi-major axis.

• ecc () – Eccentricity.

• inc () – Inclination

• raan () – Right ascension of the ascending node.

• argp () – Argument of the pericenter.

• nu () – True anomaly.

• epoch (, optional) – Epoch, default to J2000.

• plane (Planes) – Fundamental plane of the frame.

classmethod from_sbdb(cls, name, **kwargs)

Return osculating Orbit by using SBDB from Astroquery.

Parameters

name (str) – Name of the body to make the request.

Returns

ss – Orbit corresponding to body_name

Return type

Examples

>>> from poliastro.twobody.orbit import Orbit
>>> apophis_orbit = Orbit.from_sbdb('apophis')

classmethod from_vectors(cls, attractor, r, v, epoch=J2000, plane=Planes.EARTH_EQUATOR)

Return Orbit from position and velocity vectors.

Parameters
• attractor () – Main attractor.

• r () – Position vector wrt attractor center.

• v () – Velocity vector.

• epoch (, optional) – Epoch, default to J2000.

• plane (Planes) – Fundamental plane of the frame.

propagate(self, value, method=farnocchia, rtol=1e-10, **kwargs)

Propagates an orbit a specified time.

If value is true anomaly, propagate orbit to this anomaly and return the result. Otherwise, if time is provided, propagate this Orbit some time and return the result.

Parameters
• value (, , ) – Scalar time to propagate.

• rtol (float, optional) – Relative tolerance for the propagation algorithm, default to 1e-10.

• method (function, optional) – Method used for propagation

• **kwargs – parameters used in perturbation models

Returns

New orbit after propagation.

Return type

sample(self, values=100, *, min_anomaly=None, max_anomaly=None)

Samples an orbit to some specified time values.

New in version 0.8.0.

Parameters
• values (int) – Number of interval points (default to 100).

• min_anomaly (, optional) – Anomaly limits to sample the orbit. For elliptic orbits the default will be $$E \in \left[0, 2 \pi \right]$$, and for hyperbolic orbits it will be $$\nu \in \left[-\nu_c, \nu_c \right]$$, where $$\nu_c$$ is either the current true anomaly or a value that corresponds to $$r = 3p$$.

• max_anomaly (, optional) – Anomaly limits to sample the orbit. For elliptic orbits the default will be $$E \in \left[0, 2 \pi \right]$$, and for hyperbolic orbits it will be $$\nu \in \left[-\nu_c, \nu_c \right]$$, where $$\nu_c$$ is either the current true anomaly or a value that corresponds to $$r = 3p$$.

Returns

positions – Array of x, y, z positions.

Return type

Notes

When specifying a number of points, the initial and final position is present twice inside the result (first and last row). This is more useful for plotting.

Examples

>>> from astropy import units as u
>>> from poliastro.examples import iss
>>> iss.sample()
<CartesianRepresentation (x, y, z) in km ...
>>> iss.sample(10)
<CartesianRepresentation (x, y, z) in km ...

class poliastro.ephem.Ephem(coordinates, epochs, plane)

Time history of position and velocity of some object at particular epochs.

Instead of creating Ephem objects directly, use the available classmethods.

Parameters
classmethod from_body(cls, body, epochs, *, attractor=None, plane=Planes.EARTH_EQUATOR)

Return Ephem for a SolarSystemPlanet at certain epochs.

Parameters
• body () – Body.

• epochs () – Epochs to sample the body positions.

• attractor (, optional) – Body to use as central location, if not given the Solar System Barycenter will be used.

• plane (Planes, optional) – Fundamental plane of the frame, default to Earth Equator.

classmethod from_horizons(cls, name, epochs, *, attractor=None, plane=Planes.EARTH_EQUATOR, id_type=None)

Return Ephem for an object using JPLHorizons module of Astroquery.

Parameters
• name (str) – Name of the body to query for.

• epochs () – Epochs to sample the body positions.

• attractor (, optional) – Body to use as central location, if not given the Solar System Barycenter will be used.

• plane (Planes, optional) – Fundamental plane of the frame, default to Earth Equator.

• id_type (NoneType or str, optional) – Use “smallbody” for Asteroids and Comets and None (default) to first search for Planets and Satellites.

classmethod from_orbit(cls, orbit, epochs, plane=Planes.EARTH_EQUATOR)

Return Ephem from an Orbit at certain epochs.

Parameters
• orbit () – Orbit.

• epochs () – Epochs to sample the orbit positions.

• plane (Planes, optional) – Fundamental plane of the frame, default to Earth Equator.

rv(self, epochs=None, **kwargs)

Position and velocity vectors at given epochs.

Parameters

epochs (, optional) – Epochs to sample the ephemerides, default to now.

sample(self, epochs=None, *, method=InterpolationMethods.SPLINES, **kwargs)

Returns coordinates at specified epochs.

Parameters
• epochs (, optional) – Epochs to sample the ephemerides, if not given the original one from the object will be used.

• method (, optional) – Interpolation method to use for epochs outside of the original ones, default to splines.

Returns

Sampled coordinates with velocities.

Return type

CartesianRepresentation

class poliastro.maneuver.Maneuver(*args)

Class to represent a Maneuver.

Each Maneuver consists on a list of impulses $$\Delta v_i$$ (changes in velocity) each one applied at a certain instant $$t_i$$. You can access them directly indexing the Maneuver object itself.

>>> man = Maneuver((0 * u.s, [1, 0, 0] * u.km / u.s),
... (10 * u.s, [1, 0, 0] * u.km / u.s))
>>> man[0]
(<Quantity 0. s>, <Quantity [1., 0., 0.] km / s>)
>>> man.impulses[1]
(<Quantity 10. s>, <Quantity [1., 0., 0.] km / s>)

classmethod bielliptic(cls, orbit_i, r_b, r_f)

Compute a bielliptic transfer between two circular orbits.

Parameters
• orbit_i () – Initial orbit

• r_b (astropy.unit.Quantity) – Altitude of the intermediate orbit

• r_f (astropy.unit.Quantity) – Final orbital radius

classmethod hohmann(cls, orbit_i, r_f)

Compute a Hohmann transfer between two circular orbits.

Parameters
classmethod impulse(cls, dv)

Single impulse at current time.

Parameters

dv (np.array) – Velocity components of the impulse.

classmethod lambert(cls, orbit_i, orbit_f, method=lambert_izzo, short=True, **kwargs)

Computes Lambert maneuver between two different points.

Parameters
• orbit_i (Orbit) – Initial orbit

• orbit_f (Orbit) – Final orbit

• method (function) – Method for solving Lambert’s problem

• short (keyword, boolean) – Selects between short and long solution

You can read the complete reference of the high level API here:

## Core API¶

The core API is a low level layer that contains simple functions. They are accelerated using Numba, a Just-in-Time compiler for Python, to achieve good performance. However, they take raw NumPy arrays and Python scalars, so they will not protect you from dimensional errors.