astro.Orbit#

class hohmannpy.astro.Orbit(position, velocity, grav_param=398600441800000.0, track_equinoctial=False, *, _default=True)#

Class which contains all the information needed to define an orbit. This includes a variety of orbit determination schemes (from state, from orbital elements, Gibb’s method, etc;) as well as functions to compute all the parameters which define an orbit.

The basic __init__() creates an object from the Cartesian state. As an alternative to this, a variety of different instantiations decorated using @classmethod are available for alternative forms of orbit determination. Internally, these all use the input parameters to generate the Cartesian state which is then used to call the base __init__().

Caution

The Cartesian state, as well as orbital elements (including the classical and equinoctial ones), are all stored as attributes of this class. The Cartesian state acts as the source of truth for the orbit and is always kept up to date. The other attributes are not updated automatically from said state when they are accessed (such as by using the @property decorator). The rationale for this is that when determining an orbit from say classical elements, if these elements were then passed into a Keplerian solver it would be expected that they would not change. However, if the elements were constantly recomputed from the Cartesian state it would introduce floating-point errors that could accumulate over time. Instead, manual update methods of the form update_element() must be called to force a recomputation. These should be used with caution, and ideally only update_classical() and update_equinoctial() should be called externally.

Parameters:

  • position (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position, units of \(m\).

  • velocity (np.ndarray) – A (3, ) vector of the satellite’s planet-centered velocity, units of \(m\).

  • grav_param (float) – Constant related to the gravitational field strength of the central body, units of \(m^3/s^2\). Defaults to that of the Earth.

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

Variables:

  • position (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position.

  • velocity (np.ndarray) – A (3, ) vector of the satellite’s planet-centered velocity.

  • spf_angular_momentum (np.ndarray) – A (3, ) vector of the satellite’s specific angular momentum.

  • eccentricity_vec (np.ndarray) – A (3, ) vector whose magnitude is the eccentricity of the orbit and that points towards the orbit’s periapsis.

  • nodal_vec (np.ndarray) – A (3, ) vector which points along the line of intersection between the orbital and ecliptic (PCI 1-2) planes towards the right ascending node.

  • time (float) – Current simulation time. This starts at 0 when propagation begins and is not equivalent to the actual time in for example UT1 and Gregorian date.

  • grav_param (float) – Constant related to the gravitational field strength of the central body. Defaults to that of the Earth.

  • sm_axis (float) – \(1/2\) the length of the orbit’s major axis.

  • sl_rectum (float) – \(1/2\) the length of the orbit’s latus rectum (line perpendicular to the major axis whose midpoint is the primary foci of the orbit.

  • eccentricity (float) – How elliptical the orbit is (<1 = ellipse, >1 = hyperbola).

  • raan (float) – (Longitude of the right ascending node) Angle between the PCI 1-axis (approximately the Vernal equinox) and the nodal vector.

  • argp (float) – (Argument of periapsis) Angle between nodal and eccentricity vectors in the orbital plane.

  • inclination (float) – Angle between the orbital and ecliptic (PCI 1-2) planes. Equivalently the angle between the eccentricity and specific angular momentum vectors.

  • true_anomaly (float) – Angle between the eccentricity and position vector, “fast variable” used to track the satellite’s current location.

  • longp (float) – (Longitude of periapsis) Sum of the RAAN and argument of periapsis, only well-defined when the inclination is zero.

  • argl (float) – (Argument of latitude) Sum of the argument of periapsis and true anomaly, only well-defined when the orbit is circular and used in place of the true anomaly to track the satellite.

  • true_latitude (float) – Sum of the RAAN, argument of periapsis, and true anomaly, only well-defined when the inclination is zero and the orbit is circular and used in place of the true anomaly to track the satellite.

  • e_component1 (float) – 1-component of the project of the eccentricity vector into the equinoctial plane.

  • e_component2 (float) – 2-component of the project of the eccentricity vector into the equinoctial plane.

  • n_component1 (float) – 1-component of the project of the nodal vector into the equinoctial plane.

  • n_component2 (float) – 2-component of the project of the eccentricity vector into the equinoctial plane.

  • eccentric_anomaly (float) – Eccentric anomaly of the orbit. Not used by default unless orbit is propagated using KeplerPropagator.

  • stumpff_param (float) – Stumpff parameter of the orbit. Not used by default unless orbit is propagated using UniversalVariablePropagator.

  • universal_variable (float) – Universal variable of the orbit. Not used by default unless orbit is propagated using UniversalVariablePropagator.

  • inverse_sm_axis (float) – Inverse of the semi-major axis of the orbit. Used by UniversalVariablePropagator so that it can handle parabolic orbits.

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

Notes

All vector quantities are given in planet-centered inertial (PCI) coordinates.

classmethod from_classical_elements(sm_axis, eccentricity, raan, inclination, argp, true_anomaly, grav_param=398600441800000.0, track_equinoctial=False)#

Alternative constructor which performs orbit determination using the classical orbital elements.

It takes in the classical orbital elements and calls elements_2_state() to convert the Cartesian position and velocity and from there generate the orbit.

Parameters:

  • sm_axis (float) – Semi-major axis.

  • eccentricity (float) – Eccentricity.

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

  • argp (float) – Argument of periapsis.

  • inclination (float) – Inclination.

  • true_anomaly (float) – True anomaly.

  • grav_param (float) – Gravitational parameter of the central body (defaults to that of the Earth in \(\text{m}^3/\text{s}^2\)).

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

Returns:

orbit (Orbit) – Call to the base initialization function for this class.

classmethod from_classical_elements_p(sl_rectum, eccentricity, raan, inclination, argp, true_anomaly, grav_param=398600441800000.0, track_equinoctial=False)#

Same as from_classical_elements() but explicitly for parabolic orbits where semi-major axis is not defined and the semi-latus rectum is used instead.

Parameters:

  • sl_rectum (float) – Semi-major axis.

  • eccentricity (float) – Eccentricity.

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

  • argp (float) – Argument of periapsis.

  • inclination (float) – Inclination.

  • true_anomaly (float) – True anomaly.

  • grav_param (float) – Gravitational parameter of the central body (defaults to that of the Earth in \(\text{m}^3/\text{s}^2\)).

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

Returns:

orbit (Orbit) – Call to the base initialization function for this class.

classmethod from_equinoctial_elements(sl_rectum, e_component1, e_component2, n_component1, n_component2, true_latitude, grav_param=398600441800000.0, track_equinoctial=True)#

Similar to from_classical_elements() but using the modified equinoctial elements instead of the classical ones.

Parameters:

  • sl_rectum (float) – Semi-major axis.

  • e_component1 (float) – 1-component of the project of the eccentricity vector into the equinoctial plane.

  • e_component2 (float) – 2-component of the project of the eccentricity vector into the equinoctial plane.

  • n_component1 (float) – 1-component of the project of the nodal vector into the equinoctial plane.

  • n_component2 (float) – 2-component of the project of the eccentricity vector into the equinoctial plane.

  • true_latitude (float) – Sum of the RAAN, argument of periapsis, and true anomaly, only well-defined when the inclination is zero and the orbit is circular and used in place of the true anomaly to track the satellite.

  • grav_param (float) – Gravitational parameter of the central body (defaults to that of the Earth in \(\text{m}^3/\text{s}^2\)).

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

Returns:

orbit (Orbit) – Call to the base initialization function for this class.

classmethod from_gibbs(position1, position2, position3, current_position_index=2, grav_param=398600441800000.0, track_equinoctial=False)#

Alternative constructor which returns the position and velocity given three co-planar position vectors. The process of determining the conic whose origin lies at the center of three co-planar vectors is known as Gibbs’ method.

Parameters:

  • position1 (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position at the earliest time sighting.

  • position2 (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position at the middle time sighting.

  • position3 (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position at the latest time sighting.

  • current_position_index (int) – Which position vector the satellite currently is located at.

  • grav_param (float) – Constant related to the gravitational field strength of the central body. Defaults to that of the Earth.

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

classmethod from_lambert(position1, position2, tof, grav_param=398600441800000.0, track_equinoctial=False, current_position_index=1, short_transfer=True, prograde=True, fg_constraint=True, solver_tol=1e-08, stumpff_tol=1e-08, stumpff_series_length=10)#

A universal variable implementation of Gauss’ method to solving Lambert’s problem.

Lambert’s problem involves finding the orbit which corresponds to two position vectors and the time-of-flight between them (whether that involves traveling the long or short route between them must be specified by the user).

Parameters:

  • position1 (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position at one of the two sightings.

  • position2 (np.ndarray) – A (3, ) vector of the satellite’s planet-centered inertial position at one of the two sightings.

  • tof (float) – Time-of-flight between the two positions.

  • current_position_index (int) – Which position vector the satellite currently is located at. Should be either 1 or 2.

  • short_transfer (bool) – Flag which indicates the satellite took the long or short arc between the two positions. Set to true for a short transfer arc and false for a long arc transfer.

  • prograde (bool) – Flag which indicates whether satellite is in a prograde orbit, determines the sign on Lambert’s constant. True for prograde orbits and false for retrograde ones.

  • fg_constraint (bool) – Flag indicating whether to compute the gdot-series independently (increasing computation time) or to instead use the series constraint.

  • solver_tol (float) – Tolerance to use when solving Kepler’s equation.

  • stumpff_tol (float) – Minimum absolute value of the Stumpff parameter before switching to the infinite series definition of the Stumpff series.

  • stumpff_series_length – How many terms to evaluate in the Stumpff series when using their infinite series definitions.

  • grav_param (float) – Constant related to the gravitational field strength of the central body. Defaults to that of the Earth.

  • track_equinoctial (bool) – Flag which indicates whether to track the equinoctial elements. By default, only the Cartesian state and the classical orbital elements (as well as their degenerate cases) are tracked.

classmethod from_state(position, velocity, grav_param=398600441800000.0, track_equinoctial=False)#

Identical to __init__(). Returns an Orbit based on the Cartesian position and velocity.

update_classical()#

Master function which updates all the classical orbital elements (as well as intermediate values needed to compute them and the additional parameters used in degenerate cases) based on the PCI position and velocity.

update_equinoctial()#

Master function which updates all the modified equinoctial orbital parameters based on the given position and velocity. Note that this does not update the semi-latus rectum and true latitude as those are already handled in update_classical().