two_body_dynamics

Functions for (semi-)analytical calculations in a simple two-body point-mass system.

This module provides functions and classes for analytical solutions to two-body orbital mechanics problems, including:

  • Kepler orbit propagation

  • Escape and capture delta-v calculations

  • Lambert problem solvers (orbit determination between two positions)

  • Gravity assist calculations

Classes

LambertTargeter

Base class for Lambert targeting algorithms.

LambertTargeterGooding

LambertTargeterIzzo

Lambert targeter using Izzo's algorithm.

ZeroRevolutionLambertTargeterIzzo

Zero-revolution Lambert targeter using Izzo's algorithm.

MultiRevolutionLambertTargeterIzzo

Multi-revolution Lambert targeter using Izzo's algorithm.

PericenterFindingFunctions

EccentricityFindingFunctions

Class containing functions for finding the eccentricity during a gravity assist.

Functions

propagate_kepler_orbit(...[, root_finder])

Function to propagate Keplerian elements to a later epoch, assuming an unperturbed system.

compute_escape_or_capture_delta_v(...)

Compute the escape or capture delta-v budget for a spacecraft.

Lambert Problem Solvers

class LambertTargeter

Bases: pybind11_object

Base class for Lambert targeting algorithms.

This abstract base class defines the interface for Lambert problem solvers. The Lambert problem consists of finding the orbit that connects two position vectors in a specified time of flight. Derived classes implement specific solution algorithms (e.g., Gooding, Izzo).

__init__(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeter, departure_position: numpy.ndarray[numpy.float64[3, 1]], arrival_position: numpy.ndarray[numpy.float64[3, 1]], time_of_flight: float | SupportsIndex, gravitational_parameter: float | SupportsIndex) → None

Constructor for LambertTargeter.

Parameters:

  • departure_position (numpy.ndarray) – Cartesian position vector at departure [m].

  • arrival_position (numpy.ndarray) – Cartesian position vector at arrival [m].

  • time_of_flight (float) – Time of flight between departure and arrival [s].

  • gravitational_parameter (float) – Gravitational parameter of the central body [m^3/s^2].

get_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeter) → numpy.ndarray[numpy.float64[3, 1]]

Get the inertial velocity at arrival.

Returns:

Cartesian velocity vector at arrival [m/s].

Return type:

numpy.ndarray

get_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeter) → numpy.ndarray[numpy.float64[3, 1]]

Get the inertial velocity at departure.

Returns:

Cartesian velocity vector at departure [m/s].

Return type:

numpy.ndarray

get_velocity_vectors(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeter) → tuple[numpy.ndarray[numpy.float64[3, 1]], numpy.ndarray[numpy.float64[3, 1]]]

Get both velocity vectors as a pair.

Returns:

Tuple containing the departure and arrival velocity vectors [m/s].

Return type:

tuple[numpy.ndarray, numpy.ndarray]

class LambertTargeterGooding

Bases: LambertTargeter

__init__(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding, departure_position: numpy.ndarray[numpy.float64[3, 1]], arrival_position: numpy.ndarray[numpy.float64[3, 1]], time_of_flight: float | SupportsIndex, gravitational_parameter: float | SupportsIndex, root_finder: tudatpy.kernel.math.root_finders.RootFinderCore = None) → None

Constructor for LambertTargeterGooding.

Parameters:

  • departure_position (numpy.ndarray) – Cartesian position vector at departure [m].

  • arrival_position (numpy.ndarray) – Cartesian position vector at arrival [m].

  • time_of_flight (float) – Time of flight between departure and arrival [s].

  • gravitational_parameter (float) – Gravitational parameter of the central body [m^3/s^2].

  • root_finder (RootFinder, default=None) – Root finder to use for solving the Lambert equation. If None, a default Newton-Raphson solver with 1000 iterations and 1e-12 relative tolerance is used.

get_radial_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding) → float

Get the radial velocity component at arrival.

Returns:

Radial velocity at arrival [m/s].

Return type:

float

get_radial_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding) → float

Get the radial velocity component at departure.

Returns:

Radial velocity at departure [m/s].

Return type:

float

get_semi_major_axis(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding) → float

Get the semi-major axis of the transfer orbit.

Returns:

Semi-major axis of the conic section connecting departure and arrival [m].

Return type:

float

get_transverse_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding) → float

Get the transverse velocity component at arrival.

Returns:

Transverse velocity at arrival [m/s].

Return type:

float

get_transverse_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterGooding) → float

Get the transverse velocity component at departure.

Returns:

Transverse velocity at departure [m/s].

Return type:

float

class LambertTargeterIzzo

Bases: LambertTargeter

Lambert targeter using Izzo’s algorithm.

Implementation of Izzo’s Lambert targeting algorithm. This method is particularly robust for near-pi transfers and does not suffer from singularities that affect other methods. It supports both prograde and retrograde orbits.

References

Izzo, D., “Revisiting Lambert’s problem”, Celestial Mechanics and Dynamical Astronomy, Vol. 121, 2015.

__init__(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo, departure_position: numpy.ndarray[numpy.float64[3, 1]], arrival_position: numpy.ndarray[numpy.float64[3, 1]], time_of_flight: float | SupportsIndex, gravitational_parameter: float | SupportsIndex, is_retrograde: bool = False, tolerance: float | SupportsIndex = 1e-09, max_iter: int | SupportsIndex = 50) → None

Constructor for LambertTargeterIzzo.

Parameters:

  • departure_position (numpy.ndarray) – Cartesian position vector at departure [m].

  • arrival_position (numpy.ndarray) – Cartesian position vector at arrival [m].

  • time_of_flight (float) – Time of flight between departure and arrival [s].

  • gravitational_parameter (float) – Gravitational parameter of the central body [m^3/s^2].

  • is_retrograde (bool, default=False) – If True, computes retrograde orbit; if False, computes prograde orbit.

  • tolerance (float, default=1e-9) – Convergence tolerance for the iterative solution.

  • max_iter (int, default=50) – Maximum number of iterations for the solution procedure.

get_radial_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo) → float

Get the radial velocity component at arrival.

Returns:

Radial velocity at arrival [m/s].

Return type:

float

get_radial_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo) → float

Get the radial velocity component at departure.

Returns:

Radial velocity at departure [m/s].

Return type:

float

get_semi_major_axis(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo) → float

Get the semi-major axis of the transfer orbit.

Returns:

Semi-major axis of the conic section connecting departure and arrival [m].

Return type:

float

get_transverse_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo) → float

Get the transverse velocity component at arrival.

Returns:

Transverse velocity at arrival [m/s].

Return type:

float

get_transverse_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.LambertTargeterIzzo) → float

Get the transverse velocity component at departure.

Returns:

Transverse velocity at departure [m/s].

Return type:

float

class ZeroRevolutionLambertTargeterIzzo

Bases: LambertTargeter

Zero-revolution Lambert targeter using Izzo’s algorithm.

Specialized implementation of Izzo’s algorithm for zero-revolution transfers (direct transfers without completing full orbits). This is a more focused version that handles the most common case efficiently.

__init__(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo, departure_position: numpy.ndarray[numpy.float64[3, 1]], arrival_position: numpy.ndarray[numpy.float64[3, 1]], time_of_flight: float | SupportsIndex, gravitational_parameter: float | SupportsIndex, is_retrograde: bool = False, tolerance: float | SupportsIndex = 1e-09, max_iter: int | SupportsIndex = 50) → None

Constructor for ZeroRevolutionLambertTargeterIzzo.

Parameters:

  • departure_position (numpy.ndarray) – Cartesian position vector at departure [m].

  • arrival_position (numpy.ndarray) – Cartesian position vector at arrival [m].

  • time_of_flight (float) – Time of flight between departure and arrival [s].

  • gravitational_parameter (float) – Gravitational parameter of the central body [m^3/s^2].

  • is_retrograde (bool, default=False) – If True, computes retrograde orbit; if False, computes prograde orbit.

  • tolerance (float, default=1e-9) – Convergence tolerance for the iterative solution.

  • max_iter (int, default=50) – Maximum number of iterations for the solution procedure.

get_radial_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo) → float

Get the radial velocity component at arrival.

Returns:

Radial velocity at arrival [m/s].

Return type:

float

get_radial_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo) → float

Get the radial velocity component at departure.

Returns:

Radial velocity at departure [m/s].

Return type:

float

get_semi_major_axis(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo) → float

Get the semi-major axis of the transfer orbit.

Returns:

Semi-major axis of the conic section connecting departure and arrival [m].

Return type:

float

get_transverse_arrival_velocity(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo) → float

Get the transverse velocity component at arrival.

Returns:

Transverse velocity at arrival [m/s].

Return type:

float

get_transverse_departure_velocity(self: tudatpy.kernel.astro.two_body_dynamics.ZeroRevolutionLambertTargeterIzzo) → float

Get the transverse velocity component at departure.

Returns:

Transverse velocity at departure [m/s].

Return type:

float

class MultiRevolutionLambertTargeterIzzo

Bases: ZeroRevolutionLambertTargeterIzzo

Multi-revolution Lambert targeter using Izzo’s algorithm.

Extension of Izzo’s algorithm to handle multi-revolution transfers. Supports computing solutions for transfers that complete one or more full orbits before arrival, with both left-branch and right-branch solutions available.

__init__(self: tudatpy.kernel.astro.two_body_dynamics.MultiRevolutionLambertTargeterIzzo, departure_position: numpy.ndarray[numpy.float64[3, 1]], arrival_position: numpy.ndarray[numpy.float64[3, 1]], time_of_flight: float | SupportsIndex, gravitational_parameter: float | SupportsIndex, n_revolutions: int | SupportsIndex = 0, is_right_branch: bool = False, is_retrograde: bool = False, tolerance: float | SupportsIndex = 1e-09, max_iter: int | SupportsIndex = 50) → None

Constructor for MultiRevolutionLambertTargeterIzzo.

Parameters:

  • departure_position (numpy.ndarray) – Cartesian position vector at departure [m].

  • arrival_position (numpy.ndarray) – Cartesian position vector at arrival [m].

  • time_of_flight (float) – Time of flight between departure and arrival [s].

  • gravitational_parameter (float) – Gravitational parameter of the central body [m^3/s^2].

  • n_revolutions (int, default=0) – Number of complete revolutions before arrival.

  • is_right_branch (bool, default=False) – If True, uses right branch solution; if False, uses left branch solution.

  • is_retrograde (bool, default=False) – If True, computes retrograde orbit; if False, computes prograde orbit.

  • tolerance (float, default=1e-9) – Convergence tolerance for the iterative solution.

  • max_iter (int, default=50) – Maximum number of iterations for the solution procedure.

compute_for_revolutions_and_branch(self: tudatpy.kernel.astro.two_body_dynamics.MultiRevolutionLambertTargeterIzzo, n_revolutions: int | SupportsIndex, is_right_branch: bool) → None

Compute the Lambert solution for specified revolutions and branch.

Parameters:

  • n_revolutions (int) – Number of complete revolutions.

  • is_right_branch (bool) – If True, uses right branch solution; if False, uses left branch solution.

get_maximum_number_of_revolutions(self: tudatpy.kernel.astro.two_body_dynamics.MultiRevolutionLambertTargeterIzzo) → int

Get the maximum number of revolutions for which a solution exists.

Returns:

Maximum number of revolutions possible for the given geometry and time of flight.

Return type:

int

Gravity Assist Utilities

class PericenterFindingFunctions

Bases: pybind11_object

__init__(self: tudatpy.kernel.astro.two_body_dynamics.PericenterFindingFunctions, absolute_incoming_semi_major_axis: float | SupportsIndex, absolute_outgoing_semi_major_axis: float | SupportsIndex, bending_angle: float | SupportsIndex) → None
compute_derivative_pericenter_radius_fn(self: tudatpy.kernel.astro.two_body_dynamics.PericenterFindingFunctions, arg0: float | SupportsIndex) → float
compute_pericenter_radius_fn(self: tudatpy.kernel.astro.two_body_dynamics.PericenterFindingFunctions, arg0: float | SupportsIndex) → float
class EccentricityFindingFunctions

Bases: pybind11_object

Class containing functions for finding the eccentricity during a gravity assist.

This class provides the objective function and its derivative for solving the incoming eccentricity in a gravity assist maneuver, given the incoming and outgoing hyperbolic semi-major axes and the bending angle. Used as input for root-finding algorithms.

__init__(self: tudatpy.kernel.astro.two_body_dynamics.EccentricityFindingFunctions, absolute_incoming_semi_major_axis: float | SupportsIndex, absolute_outgoing_semi_major_axis: float | SupportsIndex, bending_angle: float | SupportsIndex) → None

Constructor for EccentricityFindingFunctions.

Parameters:

  • absolute_incoming_semi_major_axis (float) – Absolute value of the semi-major axis of the incoming hyperbolic trajectory [m].

  • absolute_outgoing_semi_major_axis (float) – Absolute value of the semi-major axis of the outgoing hyperbolic trajectory [m].

  • absolute_bending_angle (float) – Bending angle of the gravity assist [rad].

compute_derivative_incoming_eccentricity_fn(self: tudatpy.kernel.astro.two_body_dynamics.EccentricityFindingFunctions, incoming_eccentricity: float | SupportsIndex) → float

Compute the first derivative of the incoming eccentricity function.

Parameters:

incoming_eccentricity (float) – Incoming eccentricity for which to evaluate the derivative [-].

Returns:

First derivative of the function.

Return type:

float

compute_incoming_eccentricity_fn(self: tudatpy.kernel.astro.two_body_dynamics.EccentricityFindingFunctions, incoming_eccentricity: float | SupportsIndex) → float

Compute the incoming eccentricity function value.

Parameters:

incoming_eccentricity (float) – Incoming eccentricity for which to evaluate the function [-].

Returns:

Function value.

Return type:

float

Orbital Propagation Functions

propagate_kepler_orbit(initial_kepler_elements: numpy.ndarray[numpy.float64[6, 1]], propagation_time: float | SupportsIndex, gravitational_parameter: float | SupportsIndex, root_finder: tudatpy.kernel.math.root_finders.RootFinderCore = None) → numpy.ndarray[numpy.float64[6, 1]]

Function to propagate Keplerian elements to a later epoch, assuming an unperturbed system.

Function to propagate Keplerian elements to a later epoch, assuming an unperturbed system. This function will take the initial Keplerian elements, and propagate the true anomaly in time as per the requested input. This is done by converting true anomaly to mean anomaly, apply the constant rate in mean motion for the requested time, and converting the result back to true anomaly. Currently both elliptic and hyperbolic orbits are supported. Parabolic orbits are not supported and will result in an error message.

Parameters:

  • initial_kepler_elements (numpy.ndarray) – Keplerian elements that are to be propagated (see element_conversion for order)

  • propagation_time (astro.time_representation.Time) – Time object for which the elements are to be propagated w.r.t. the initial elements

  • gravitational_parameter (float) – Gravitational parameter of central body used for propagation

  • root_finder (RootFinder, default = None) – Root finder used to solve Kepler’s equation when converting mean to eccentric anomaly. When no root finder is specified, the default option of the mean to eccentric anomaly function is used (see mean_to_eccentric_anomaly()).

Returns:

Keplerian elements, propagated in time from initial elements assuming unperturbed dynamics. Note that the true anomaly is returned within the -PI to PI spectrum. If the user desires a different spectrum (possibly including the number of revolutions), these should be added by the user a posteriori.

Return type:

numpy.ndarray

compute_escape_or_capture_delta_v(gravitational_param: float | SupportsIndex, semi_major_axis: float | SupportsIndex, eccentricity: float | SupportsIndex, excess_velocity: float | SupportsIndex) → float

Compute the escape or capture delta-v budget for a spacecraft.

This function calculates the required change in velocity (delta-v) for a spacecraft to escape from or be captured by the gravitational influence of a central body. The calculation is based on the pericenter of the orbit, the orbital parameters, and the excess velocity of the spacecraft. It is commonly used in mission design for estimating propulsion requirements in orbital transfers or interplanetary trajectories.

Parameters:

  • gravitational_parameter (float) – Gravitational parameter of the central body, defined as the product of the gravitational constant (G) and the mass of the body (M).

  • semi_major_axis (float) – Semi-major axis of the spacecraft’s orbit, representing the average distance from the central body.

  • eccentricity (float) – Eccentricity of the spacecraft’s orbit, which defines its shape. Must be valid for elliptical or hyperbolic orbits (e.g., 0 <= eccentricity < 1 for elliptical orbits).

  • excess_velocity (float) – Excess velocity of the spacecraft, representing its velocity relative to the central body at infinity.

Returns:

deltaV – The delta-v required for the escape or capture maneuver. This is the difference between the velocity needed to achieve the specified excess velocity at infinity and the current orbital velocity at the pericenter.

Return type:

float

Notes

Lambert’s Problem:

Lambert’s problem is the determination of an orbit connecting two position vectors in a specified time of flight. This is a fundamental problem in:

  • Preliminary mission design

  • Interplanetary trajectory optimization

  • Rendezvous and intercept calculations

Multi-Revolution Transfers:

For long time-of-flight scenarios, multiple solutions may exist corresponding to different numbers of complete revolutions around the central body. The MultiRevolutionLambertTargeterIzzo class can compute these solutions.

Solver Selection:

References