5. Trajectory#

class Trajectory(name: str, position=None, velocity=None, epoch: EpochArray = None, ref_frame=None, origin=None, body=None, degree_poly=3, parameters=None, state_definition=None, sequence_definition=None, offset=None, STMs=None, propagator_settings_dict=None, state_array=None, sequence_propagated=None)#

Bases: object

Represents a spacecraft or celestial object’s trajectory in a defined reference frame and origin.

This class encapsulates trajectory data, including position, velocity, estimated parameters, and state transition matrices (STMs). It supports both single-phase trajectories and multi-leg mission sequences.

The trajectory can be initialized using:

  • Explicit position, velocity, and epoch inputs.

  • A StateArray directly from a propagator.

Parameters:

  • name (str) – The name of the trajectory.

  • position (ArrayWUnits, optional) – The position vector history of the object in the specified reference frame. Defaults to None.

  • velocity (ArrayWUnits, optional) – The velocity vector history of the object in the specified reference frame. Defaults to None.

  • epoch (EpochArray, optional) – The array of epochs associated with the trajectory data. Defaults to None.

  • ref_frame (str, optional) – The reference frame in which the trajectory is defined (e.g., "J2000"). Defaults to None.

  • origin (str, optional) – The origin of the trajectory (e.g., "SUN"). Defaults to None.

  • body (CelestialBody, optional) – The celestial body or spacecraft associated with this trajectory. Defaults to None.

  • degree_poly (int, optional) – The degree of the polynomial used for SPICE interpolation. Defaults to 3.

  • parameters (list of ArrayWUnits, optional) – Additional estimated parameters related to the trajectory (e.g., range biases, solar radiation pressure coefficients). Defaults to None.

  • state_definition (list, optional) – A list defining the state vector components (e.g., position, velocity, station biases). Used when a single model describes the entire trajectory. Defaults to None.

  • sequence_definition (MissionSequence, optional) – Defines a sequence of trajectory legs with different state models. Used for complex mission phases involving maneuvers or multiple estimation regimes. Defaults to None.

  • offset (ArrayWUnits, optional) – A fixed position offset for coordinate transformations. Defaults to None.

  • STMs (list, optional) – The state transition matrices (STMs) associated with the trajectory. Defaults to None.

  • propagator_settings_dict (dict, optional) – A dictionary of propagator settings for numerical integration. Defaults to None.

  • state_array (StateArray, optional) – If provided, initializes the trajectory from a propagated StateArray, extracting position, velocity, epoch, reference frame, and parameters. Defaults to None.

Raises:

  • ValueError –

    • If both state_definition and sequence_definition are provided simultaneously.

    • If both standard trajectory inputs and a StateArray are provided.

    • If StateArray is missing position or velocity components.

  • Exception – If the trajectory contains fewer than two data points.

Notes

  • If state_definition is provided, the trajectory follows a single continuous model.

  • If sequence_definition is used, the trajectory consists of multiple segments (e.g., before and after a maneuver).

  • The trajectory is stored in a SPICE kernel format for interpolation and retrieval.

Examples

Standard Initialization:

import scarabaeus as scb

# Define epochs
epoch_start = scb.SpiceManager.jd2et(2461809.72995654)
epoch_end = scb.SpiceManager.jd2et(2461809.72995654 + 1)
epochs = scb.EpochArray(np.linspace(epoch_start, epoch_end, 100), time_frame="TDB")

# Define position and velocity
position = scb.ArrayWUnits(np.random.rand(100, 3), "km")
velocity = scb.ArrayWUnits(np.random.rand(100, 3), "km/s")

# Initialize trajectory
traj = scb.Trajectory(
    name="Test_Trajectory",
    position=position,
    velocity=velocity,
    epoch=epochs,
    ref_frame="J2000",
    origin="SUN",
    body=scb.CelestialBody.from_constants("EARTH")
)

# Retrieve state at a given epoch
state = traj.get_state(epochs[0])

>>> print("Position:", state["position"])
'Position: [0.123, 0.456, 0.789] [km]'

Alternative Initialization from a Propagator:

# Initialize trajectory using propagated StateArray
traj = scb.Trajectory("Orbiter_trajectory", state_array=propagated_state_array)

Attributes

STMs

The state transition matrices (STMs) associated with the trajectory.

body

The celestial body or spacecraft associated with the trajectory.

end_epoch

The end epoch of the trajectory.

epoch

The epochs associated with the trajectory.

name

The name of the trajectory.

offset

A fixed position offset for coordinate transformations.

origin

The origin of the trajectory.

parameters

Additional estimated parameters associated with the trajectory.

poly_deg

The degree of the polynomial used for interpolation.

position

The position history of the trajectory in the specified reference frame.

propagator_settings_dict

The dictionary of propagator settings for numerical integration.

ref_frame

The reference frame of the trajectory.

sequence_definition

The mission sequence definition governing the trajectory's structure.

start_epoch

The start epoch of the trajectory.

state_definition

The definition of the trajectory's state vector.

velocity

The velocity history of the trajectory in the specified reference frame.

Methods

add_STMs(STMs)

Associates state transition matrices (STMs) with the trajectory.

get_STM(epoch_input[, origin_input, ...])

Retrieves the state transition matrix (STM) at a specified epoch.

get_offset_position(epoch_input[, ...])

Computes the trajectory position with an applied constant offset.

get_state(epoch_input[, origin_input, ...])

Retrieves the trajectory state at a specified epoch.

set_name(name)

Updates the trajectory's name.

set_offset(offset)

Sets the constant position offset for the trajectory.
add_STMs(STMs: list)#

Associates state transition matrices (STMs) with the trajectory.

Parameters:

STMs (list or ArrayWFrame) – A list of state transition matrices or a single ArrayWFrame object.

get_STM(epoch_input, origin_input=None, ref_frame_input=None, idx_leg_input=None) → dict#

Retrieves the state transition matrix (STM) at a specified epoch.

Queries SPICE to obtain the STM corresponding to a given epoch, considering optional reference frame and origin transformations.

Parameters:

  • epoch_input (EpochArray) – The epoch at which to retrieve the STM.

  • origin_input (str, optional) – Custom origin for the STM retrieval. Defaults to the trajectory’s origin.

  • ref_frame_input (str, optional) – Custom reference frame for the STM retrieval. Default is the trajectory’s reference frame.

  • idx_leg_input (int, optional) – The index of the trajectory leg to retrieve if the trajectory is sequence-based. Defaults to None.

Returns:

stm – The queried STM, containing:

  • "STM" : numpy.ndarray = The state transition matrix.

  • "epoch" : EpochArray = The requested epoch.

  • "state_definition" : dict = The state definition used.

  • "propagator_settings" : dict = The settings used for propagation, if available.

Return type:

dict

get_offset_position(epoch_input, origin_input=None, ref_frame_input=None) → ArrayWUnits#

Computes the trajectory position with an applied constant offset.

If a reference frame transformation is required, the offset is rotated accordingly. The method also accounts for origin shifts when necessary.

Parameters:

  • epoch_input (EpochArray) – The epoch at which to compute the offset position.

  • origin_input (str, optional) – Custom origin for position computation. Defaults to the trajectory’s origin.

  • ref_frame_input (str, optional) – Custom reference frame for position computation. Defaults to the trajectory’s reference frame.

Returns:

offset_pos – The computed position including the constant offset. Expressed in units of kilometers.

Return type:

ArrayWUnits

get_state(epoch_input: EpochArray, origin_input=None, ref_frame_input=None, idx_leg_input=None)#

Retrieves the trajectory state at a specified epoch.

Queries SPICE to obtain position, velocity, and any associated parameters for a given epoch, considering optional reference frame and origin transformations.

Parameters:

  • epoch_input (EpochArray) – The epoch at which to compute the state.

  • origin_input (str, optional) – Custom origin for the state computation. Defaults to the trajectory’s origin.

  • ref_frame_input (str, optional) – Custom reference frame for the state computation. Defaults to the trajectory’s reference frame.

  • idx_leg_input (int, optional) – The index of the trajectory leg to retrieve if the trajectory is sequence-based. Defaults to None.

Returns:

state – The queried state, containing:

  • "position" : ArrayWUnits = The position vector. Expressed in units of kilometers.

  • "velocity" : ArrayWUnits = The velocity vector. Expressed in units of \(\frac{km}{s}\)

  • "epoch" : EpochArray = The requested epoch.

  • "parameters" = Any estimated parameters, if available.

  • "state_definition" : dict = The state definition used.

  • "propagator_settings" : dict = The settings used for propagation, if available.

Return type:

dict

set_name(name)#

Updates the trajectory’s name.

Parameters:

name (str) – The new name of the trajectory.

set_offset(offset: ArrayWUnits) → None#

Sets the constant position offset for the trajectory.

Parameters:

offset (ArrayWUnits) – The constant offset in position. Expressed in units of kilometers.

Return type:

None

property STMs: list | None#

The state transition matrices (STMs) associated with the trajectory.

property body: Body#

The celestial body or spacecraft associated with the trajectory.

property end_epoch: EpochArray#

The end epoch of the trajectory.

property epoch: EpochArray#

The epochs associated with the trajectory.

property name: str#

The name of the trajectory.

property offset: ArrayWUnits#

A fixed position offset for coordinate transformations.

property origin: str#

The origin of the trajectory.

property parameters: list#

Additional estimated parameters associated with the trajectory. These parameters include mission-specific estimated values, such as:

  • Ground station range biases (e.g., clock offsets, tropospheric delays).

  • Additional environmental parameters (e.g., solar radiation pressure coefficients).

  • Model calibration parameters (e.g., empirical accelerations).

If no additional parameters exist, returns None.

property poly_deg: int#

The degree of the polynomial used for interpolation.

property position: ArrayWUnits#

The position history of the trajectory in the specified reference frame.

property propagator_settings_dict: dict | None#

The dictionary of propagator settings for numerical integration.

property ref_frame: Frame#

The reference frame of the trajectory.

property sequence_definition: MissionSequence#

The mission sequence definition governing the trajectory’s structure. This property is used when the trajectory consists of multiple segments (legs), where different state definitions or models are required for each segment. It is typically used for:

  • Handling maneuvers (e.g., impulsive burns).

  • Multi-phase missions with different dynamical regimes.

  • Modeling spacecraft transitions between different reference frames.

property start_epoch: EpochArray#

The start epoch of the trajectory.

property state_definition: dict#

The definition of the trajectory’s state vector. This describes the structure of the estimated state, specifying:

  • Which variables are included in the state (e.g., position, velocity, parameters).

  • Whether they are dynamic or static.

  • Their associated reference objects (e.g., spacecraft, ground stations).

property velocity: ArrayWUnits#

The velocity history of the trajectory in the specified reference frame.