ssapy_toolkit.orbital_mechanics.transfer_optimal_function

Optimal transfer search between two orbits for SSAPy.

Where transfer_ssapy() solves a fixed boundary-value problem (two states, one time of flight -> the unique connecting two-burn transfer), transfer_optimal() searches over the free variables of an orbit-to-orbit transfer – departure time along orbit 1, time of flight, arrival phase along orbit 2 (insertion mode), and motion sense – to find the transfer that minimizes total delta-v (default) or, given a delta-v budget, the fastest transfer that fits it.

The search uses a coarse porkchop grid of fast impulsive Lambert solves (Keplerian boundary ephemerides), filters out infeasible candidates (no zero-revolution solution, or a transfer conic whose perigee dips below the Earth plus a safety margin), optionally polishes the winner with a Nelder-Mead local search, and finally plans/propagates the chosen transfer with transfer_ssapy() under the full force model – including single-burn intercept geometries via arrival_burn=False.

Set visualize=True for mission-designer curves (porkchop contour and delta-v vs time-of-flight Pareto front) saved via ssapy_toolkit.plots.yufig.

Functions

transfer_optimal(orbit1, orbit2[, ...])

Find the optimal two-burn (or intercept) transfer between orbits.

Classes

OptimalTransferResult(**kw)

Output of transfer_optimal().

class ssapy_toolkit.orbital_mechanics.transfer_optimal_function.OptimalTransferResult(**kw)[source]

Bases: object

Output of transfer_optimal().

transfer

The fully propagated/refined plan from transfer_ssapy() for the chosen geometry (burn NTW components, trajectory, etc.).

Type:: TransferResult

t_depart, t_arrive, tof

Chosen epochs [GPS s] and time of flight [s].

Type:: float

dv_total

Objective delta-v of the chosen transfer [m/s] (first burn only when arrival_burn=False).

Type:: float

prograde

Motion sense of the chosen Lambert geometry.

Type:: bool

arrival_phase

Insertion mode only: chosen arrival point, as time-since-epoch along orbit 2 [s].

Type:: float or None

objective, rendezvous, arrival_burn: The search configuration.

perigee_altitude

Transfer-conic perigee altitude above the Earth’s surface [m].

Type:: float

grid

The porkchop search grid: t_dep and tof axes [s], the cost array [m/s] (minimized over phase/sense; NaN where infeasible), and the feasible fraction.

Type:: dict

pareto

{'tof', 'dv'}: best feasible delta-v per time of flight.

Type:: dict

summary()[source]

ssapy_toolkit.orbital_mechanics.transfer_optimal_function.transfer_optimal(orbit1, orbit2, objective='min_dv', rendezvous=True, arrival_burn=True, t_window=None, tof_range=None, n_grid=(32, 32), n_phase=24, dv_budget=None, perigee_margin=100000.0, polish=True, visualize=False, fig_prefix='demo_gallery/figures/transfer_optimal', accel=None, propagator=None, burn_duration=10.0, burn_accel=None, thrust=None, mass=None, isp=None, **transfer_kwargs)[source]

Find the optimal two-burn (or intercept) transfer between orbits.

Parameters:

orbit1 (ssapy.orbit.Orbit or (r, v, t) tuple) – Departure and target orbits. Epochs may be GPS seconds or astropy.time.Time.
orbit2 (ssapy.orbit.Orbit or (r, v, t) tuple) – Departure and target orbits. Epochs may be GPS seconds or astropy.time.Time.
objective ({"min_dv", "min_time"}) – min_dv (default) minimizes the objective delta-v within the allowed windows. min_time minimizes time of flight among candidates whose delta-v fits dv_budget (required).
rendezvous (bool) – If True (default), the arrival state is wherever the object on orbit 2 is at t_depart + tof (its phase is set by its epoch). If False (insertion), the arrival point anywhere along orbit 2 is a free search variable – generally cheaper.
arrival_burn (bool) – If True (default), the second burn matching the arrival velocity is performed and counted. If False, optimize the first burn only (intercept/flyby): the spacecraft coasts through the target point without matching its velocity.
t_window ((float, float), optional) – Allowed departure epoch span [GPS s]. Default: one revolution of orbit 1 from its epoch.
tof_range ((float, float), optional) – Allowed time-of-flight span [s]. Default: 2% to 150% of the larger orbital period.
n_grid ((int, int)) – Porkchop grid resolution (departure x time-of-flight).
n_phase (int) – Arrival-phase samples along orbit 2 (insertion mode only).
dv_budget (float, optional) – Delta-v constraint [m/s]; required for objective='min_time', recorded/warned for min_dv (via transfer_ssapy).
perigee_margin (float) – Candidates whose transfer conic dips below EARTH_RADIUS + perigee_margin are rejected [m].
polish (bool) – Refine the best grid cell with a Nelder-Mead local search over the continuous variables.
visualize (bool) – Save mission-designer curves (porkchop + delta-v/TOF Pareto front) via ssapy_toolkit.plots.yufig under fig_prefix.
fig_prefix (str) – yufig path prefix for the visualization.
burn_accel (float, optional) – Burn acceleration magnitude [m/s^2]: the simple alternative to thrust/mass (mutually exclusive with them) when the thrust-to-mass analysis was done elsewhere. Sizes burns and drives the same feasibility filtering; no propellant estimates.
thrust (float, optional) – Engine model, passed through to transfer_ssapy() (thrust [N] and mass [kg] together size each burn’s duration; isp [s] adds propellant estimates). When given, the porkchop search also rejects candidates whose hardware-sized burns would not fit inside the time of flight – so min_time answers are engine-honest, not just budget-honest.
mass (float, optional) – Engine model, passed through to transfer_ssapy() (thrust [N] and mass [kg] together size each burn’s duration; isp [s] adds propellant estimates). When given, the porkchop search also rejects candidates whose hardware-sized burns would not fit inside the time of flight – so min_time answers are engine-honest, not just budget-honest.
isp (float, optional) – Engine model, passed through to transfer_ssapy() (thrust [N] and mass [kg] together size each burn’s duration; isp [s] adds propellant estimates). When given, the porkchop search also rejects candidates whose hardware-sized burns would not fit inside the time of flight – so min_time answers are engine-honest, not just budget-honest.
accel – Passed through to transfer_ssapy() for the final propagated plan (the search itself uses impulsive Keplerian Lambert costs; the finishing differential correction absorbs finite-burn and force-model differences).
propagator – Passed through to transfer_ssapy() for the final propagated plan (the search itself uses impulsive Keplerian Lambert costs; the finishing differential correction absorbs finite-burn and force-model differences).
burn_duration – Passed through to transfer_ssapy() for the final propagated plan (the search itself uses impulsive Keplerian Lambert costs; the finishing differential correction absorbs finite-burn and force-model differences).
**transfer_kwargs – Passed through to transfer_ssapy() for the final propagated plan (the search itself uses impulsive Keplerian Lambert costs; the finishing differential correction absorbs finite-burn and force-model differences).

Return type:

OptimalTransferResult

Notes

The search is zero-revolution Lambert per leg; long windows still explore multi-revolution phasing implicitly through the departure-time axis, but each transfer arc itself spans < 1 rev.
Boundary ephemerides during the search are Keplerian even when a perturbed accel is supplied; over windows of a few days the resulting epoch error is absorbed by the final refinement, but for strongly perturbed, multi-week windows treat the porkchop as approximate.
Both motion senses are searched automatically when the two orbits counter-rotate; co-rotating geometries search prograde only.