ssapy_toolkit.orbital_mechanics.transfer_ssapy_function

Two-point orbital transfer planning and propagation for SSAPy.

Given two boundary states (departure and arrival), this module solves Lambert’s problem for the connecting transfer orbit, expresses the two required burns as delta-v vectors in the NTW frame (SSAPy convention: N = in-plane normal to velocity, T = along velocity, W = along orbital angular momentum), and optionally propagates the maneuver using SSAPy’s AccelConstNTW finite-burn accelerations on top of any force model.

The force model defaults to two-body Keplerian gravity (AccelKepler) but any SSAPy Accel (or list of them, e.g. harmonics + drag + SRP) may be supplied, in which case the burns are computed against the Keplerian Lambert solution and the trajectory is propagated under the full force model.

Example

>>> import numpy as np
>>> from ssapy.orbit import Orbit
>>> from ssapy.constants import RGEO, EARTH_MU
>>> r1 = np.array([7000e3, 0, 0])
>>> v1 = np.array([0, np.sqrt(EARTH_MU / 7000e3), 0])
>>> dep = Orbit(r1, v1, t=0.0)
>>> # ... build an arrival Orbit `arr` at a later time ...
>>> result = transfer_ssapy(dep, arr)
>>> print(result.summary())

Functions

`solve_lambert`(r1, r2, tof[, mu, prograde, ...])	Solve Lambert's problem with universal variables.
`transfer_ssapy`(departure, arrival[, accel, ...])	Plan and propagate a two-burn transfer between two orbital states.

Classes

`Burn`(t_start, t_end, dv, dv_ntw)	A single finite (or effectively impulsive) maneuver.
`TransferResult`(burns, dv_budget, transfer_orbit)	Output of `transfer_ssapy()`.

class ssapy_toolkit.orbital_mechanics.transfer_ssapy_function.Burn(t_start, t_end, dv, dv_ntw)[source]

Bases: object

A single finite (or effectively impulsive) maneuver.

t_start, t_end

Burn on/off times, GPS seconds.

Type:: float

dv

Delta-v vector in the inertial frame [m/s].

Type:: ndarray (3,)

dv_ntw

Delta-v resolved on the NTW frame of the pre-burn state [m/s], ordered (N, T, W) per SSAPy convention.

Type:: ndarray (3,)

dv_mag

Delta-v magnitude [m/s].

Type:: float

direction_ntw

Unit thrust direction in NTW.

Type:: ndarray (3,)

accel

Ready-to-use SSAPy acceleration implementing this burn.

Type:: ssapy.accel.AccelConstNTW

class ssapy_toolkit.orbital_mechanics.transfer_ssapy_function.TransferResult(burns, dv_budget, transfer_orbit)[source]

Bases: object

Output of transfer_ssapy().

burns

Departure and arrival burns.

Type:: list of Burn

dv_total

Sum of burn magnitudes [m/s].

Type:: float

dv_budget

The budget supplied by the caller, if any.

Type:: float or None

within_budget

Whether dv_total <= dv_budget (None if no budget given).

Type:: bool or None

transfer_orbit

Keplerian transfer conic immediately after the departure burn.

Type:: ssapy.orbit.Orbit

trajectory

If propagated: {'t', 'r', 'v'} arrays sampled along the transfer under the full force model, including the finite burns.

Type:: dict or None

arrival_error

If propagated: distance [m] between the propagated final position and the requested arrival position.

Type:: float or None

propagator

The propagator (force model + burns) used, reusable for further calls to ssapy.compute.rv.

Type:: ssapy.propagator.RK78Propagator or None

summary()[source]

ssapy_toolkit.orbital_mechanics.transfer_ssapy_function.solve_lambert(r1, r2, tof, mu=398600441800000.0, prograde=True, max_iter=200, tol=1e-09)[source]

Solve Lambert’s problem with universal variables.

Find the velocities of the (zero-revolution) conic connecting position r1 to position r2 in time-of-flight tof.

Parameters:

r1 (array_like, shape (3,)) – Initial and final position vectors [m] in an inertial frame.
r2 (array_like, shape (3,)) – Initial and final position vectors [m] in an inertial frame.
tof (float) – Time of flight [s]; must be > 0.
mu (float) – Gravitational parameter [m^3/s^2]. Default is Earth’s.
prograde (bool) – If True, choose the short-way/prograde geometry (transfer angular momentum has +z component); otherwise retrograde.
max_iter (int) – Maximum bisection/Newton iterations on the universal variable.
tol (float) – Relative tolerance on time of flight.

Returns:

v1, v2 – Required velocity [m/s] at r1 (departure) and r2 (arrival) on the transfer conic.

Return type:

ndarray, shape (3,)

Raises:

RuntimeError – If the iteration fails to converge (e.g. near-180-degree transfer geometry, which is singular for single-plane Lambert solutions).

ssapy_toolkit.orbital_mechanics.transfer_ssapy_function.transfer_ssapy(departure, arrival, accel=None, dv_budget=None, burn_duration=10.0, burn_accel=None, thrust=None, mass=None, isp=None, prograde=True, arrival_burn=True, propagate=True, propagator=None, refine=True, refine_tol=(10.0, 0.01), max_refine_iter=8, n_samples=200, rk_step=10.0, raise_on_budget=False)[source]

Plan and propagate a two-burn transfer between two orbital states.

Solves Lambert’s problem between the departure position at its epoch and the arrival position at its (later) epoch, computes the departure and arrival delta-v vectors and their NTW components, models each burn as a constant-acceleration AccelConstNTW of length burn_duration, and (optionally) propagates the maneuvering trajectory under the supplied force model with SSAPy’s RK78 integrator.

Parameters:

departure (ssapy.orbit.Orbit or tuple) – Pre-burn state: an SSAPy Orbit, or a (r, v, t) tuple with r and v in meters / meters-per-second (inertial frame) and t in GPS seconds or as an astropy.time.Time.
arrival (ssapy.orbit.Orbit or tuple) – Target state in the same formats. Its epoch must be later than the departure epoch; the difference sets the time of flight. The target velocity defines the second (circularization/matching) burn.
accel (ssapy.accel.Accel or list of Accel, optional) – Force model for propagation. Default AccelKepler() (two-body gravity). A list is summed. Note the burn solution itself is the Keplerian Lambert solution; with strong perturbations the propagated arrival error reported in the result quantifies the mismatch.
dv_budget (float, optional) – Total delta-v budget [m/s]. The result records whether the transfer fits; set raise_on_budget=True to raise instead.
burn_duration (float) – Length of each finite burn [s]. Short durations approximate impulsive burns. Ignored when thrust/mass are given. The burns must fit inside the time of flight.
burn_accel (float, optional) – Burn acceleration magnitude [m/s^2] – the simple hardware shortcut when the thrust-to-mass analysis was already done elsewhere. Equivalent to specifying thrust/mass with the same ratio (and mutually exclusive with them): burn durations are sized as |dv_i| / burn_accel with the same consistency iteration and fit checks. Propellant estimates are unavailable in this mode (those need mass and isp).
thrust (float, optional) – Engine thrust [N]. Requires mass. When given, each burn’s duration is sized from the hardware instead of burn_duration: duration_i = mass * |dv_i| / thrust (constant acceleration thrust/mass; durations are fixed from the impulsive Lambert delta-vs, which the refinement then perturbs by < ~1%). Raises ValueError when the engine is too weak for the burns to fit inside the time of flight.
mass (float, optional) – Spacecraft wet mass [kg], treated as constant: propellant depletion is NOT modeled, so the burn acceleration does not grow as propellant is spent (a few-percent-of-mass burn is well approximated; a 30%+ burn is not).
isp (float, optional) – Specific impulse [s]. Requires mass. Reporting only – the dynamics are unchanged: attaches a Tsiolkovsky propellant-mass estimate to each burn (sequentially debited between burns) and to the summary.
prograde (bool) – Sense of motion for the Lambert geometry.
arrival_burn (bool) – If True (default), perform and cost the second burn that matches the arrival velocity (rendezvous/insertion). If False, plan an intercept: only the departure burn is performed, the refinement targets the arrival position only, and the spacecraft coasts through the target point on the Lambert conic without matching its velocity (e.g. flyby or impactor geometries). The result then contains a single burn and the arrival velocity mismatch is expected.
propagate (bool) – If True, numerically propagate the burn-inclusive trajectory and report the achieved arrival error.
propagator (class or callable, optional) – How to build the propagator for each transfer segment. Default is RK78Propagator with step rk_step. Accepts either a propagator class with an (accel, h) constructor (e.g. RK4Propagator, RK8Propagator, LeapfrogPropagator) or a factory callable f(accel) -> propagator instance for full control, e.g. lambda a: SciPyPropagator(a, ode_kwargs=dict(rtol=1e-10)). A class/factory is required rather than an instance because each segment (burn 1 / coast / burn 2) is propagated under a different acceleration sum. The propagator must actually integrate the supplied accelerations: analytic/element propagators such as KeplerianPropagator, SGP4Propagator, or SeriesPropagator ignore them, so the burns would never fire (this is detected and raised during refinement).
refine (bool) – If True (default, requires propagate), apply a differential- correction (Newton shooting) step: the six NTW burn components are adjusted until the propagated finite-burn trajectory under the full force model meets the target position and velocity. This removes both the finite-burn/impulsive mismatch (the NTW frame rotates during a burn) and, when perturbing accelerations are supplied, the Keplerian-Lambert modeling error.
refine_tol (tuple of float) – Convergence tolerances (position [m], velocity [m/s]) for the refinement.
max_refine_iter (int) – Maximum Newton iterations for the refinement.
n_samples (int) – Number of trajectory sample times if propagating.
rk_step (float) – Initial RK78 step size [s].
raise_on_budget (bool) – If True and the budget is exceeded, raise ValueError.

Return type:

TransferResult

Notes

NTW components follow SSAPy’s convention (ssapy.utils.rv_to_ntw): T along velocity, W along the orbital angular momentum (r x v), and N = T x W completing the right-handed, in-plane axis (radially outward for a circular orbit).
Burn 1 fires over [t1, t1 + d1] and burn 2 over [t2 - d2, t2] where the d_i are burn_duration or the thrust-sized durations; the differential correction absorbs the finite-burn arc so the propagated trajectory still meets the target to refine_tol.