OrbitTrajectory

Frame-aware orbital trajectory with automatic coordinate transformations.

OrbitTrajectory

OrbitTrajectory()

Orbital trajectory with frame and representation awareness.

Stores a sequence of orbital states at specific epochs with support for interpolation, frame conversions, and representation transformations.

Initialize instance.

__doc__ class-attribute

__doc__ = 'Orbital trajectory with frame and representation awareness.\n\nStores a sequence of orbital states at specific epochs with support for\ninterpolation, frame conversions, and representation transformations.'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'brahe._brahe'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

angle_format property

angle_format: AngleFormat

Get trajectory angle format for Keplerian states.

Returns:

Type	Description
AngleFormat	AngleFormat or None: Angle format for Keplerian representation, None for Cartesian

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
print(f"Angle format: {traj.angle_format}")

frame property

frame: OrbitFrame

Get trajectory reference frame.

Returns:

Name	Type	Description
OrbitFrame	OrbitFrame	Reference frame of the trajectory

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
print(f"Frame: {traj.frame}")

length property

length: int

Get the number of states in the trajectory.

Returns:

Name	Type	Description
int	int	Number of states in the trajectory

Example

import brahe as bh
import numpy as np

traj = bh.DTrajectory(6)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
print(f"Trajectory length: {traj.length}")

representation property

representation: OrbitRepresentation

Get trajectory state representation.

Returns:

Name	Type	Description
OrbitRepresentation	OrbitRepresentation	State representation format of the trajectory

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
print(f"Representation: {traj.representation}")

__getitem__ method descriptor

__getitem__(key: str) -> Any

Return self[key].

__iter__ method descriptor

__iter__() -> Any

Implement iter(self).

__len__ method descriptor

__len__() -> int

Return len(self).

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__() -> str

Return repr(self).

__str__ method descriptor

__str__() -> str

Return str(self).

add method descriptor

add(epoch: Epoch, state: ndarray) -> Any

Add a state to the trajectory.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Time of the state	required
state	ndarray	6-element state vector	required

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)

clear method descriptor

clear() -> Any

Clear all states from the trajectory.

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj.clear()

default builtin

default() -> OrbitTrajectory

Create a default empty orbital trajectory (ECI Cartesian).

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	New trajectory with ECI frame and Cartesian representation

dimension method descriptor

dimension() -> int

Get trajectory dimension (always 6 for orbital trajectories).

Returns:

Name	Type	Description
int	int	Dimension of the trajectory (always 6)

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
print(f"Dimension: {traj.dimension()}")

end_epoch method descriptor

end_epoch() -> Epoch

Get end epoch of trajectory.

Returns:

Type	Description
Epoch	Epoch or None: Last epoch if trajectory is not empty, None otherwise

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
print(f"End epoch: {traj.end_epoch()}")

epoch_at_idx method descriptor

epoch_at_idx(index: int) -> Epoch

Get the epoch at a specific index.

Parameters:

Name	Type	Description	Default
index	int	Index of the epoch to retrieve	required

Returns:

Name	Type	Description
Epoch	Epoch	Epoch at the specified index

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
state = np.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
traj.add(epc, state)

# Get epoch at index
epoch_0 = traj.epoch_at_idx(0)

epochs method descriptor

epochs() -> ndarray

Get all epochs as a numpy array.

Returns:

Type	Description
ndarray	numpy.ndarray: 1D array of Julian dates for all epochs

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj.add(epc + 60.0, state)
epochs_array = traj.epochs()

first method descriptor

first() -> Tuple

Get the first (epoch, state) tuple in the trajectory, if any exists.

Returns:

Type	Description
Tuple	tuple or None: Tuple of (Epoch, numpy.ndarray) for first state, or None if empty

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
first_epc, first_state = traj.first()

from_orbital_data builtin

from_orbital_data(epochs: list[Epoch], states: ndarray, frame: OrbitFrame, representation: OrbitRepresentation, angle_format: AngleFormat or None = None) -> OrbitTrajectory

Create orbital trajectory from existing data.

Parameters:

Name	Type	Description	Default
epochs	list[Epoch]	List of time epochs for each state	required
states	ndarray	Flattened 1D array of 6-element state vectors with total length N*6 where N is the number of epochs	required
frame	OrbitFrame	Reference frame for the states	required
representation	OrbitRepresentation	State representation format	required
angle_format	AngleFormat or None	Angle format for Keplerian states, must be None for Cartesian representation	None

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	New trajectory instance populated with data

get method descriptor

get(index: int) -> Tuple

Get both epoch and state at a specific index.

Parameters:

Name	Type	Description	Default
index	int	Index to retrieve	required

Returns:

Name	Type	Description
tuple	Tuple	Tuple of (Epoch, numpy.ndarray) for epoch and state at the index

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
ret_epc, ret_state = traj.get(0)

get_eviction_policy method descriptor

get_eviction_policy() -> str

Get current eviction policy.

Returns:

Name	Type	Description
str	str	String representation of eviction policy

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
policy = traj.get_eviction_policy()

get_interpolation_method method descriptor

get_interpolation_method() -> InterpolationMethod

Get the current interpolation method.

Returns:

Name	Type	Description
InterpolationMethod	InterpolationMethod	Current interpolation method

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
method = traj.get_interpolation_method()

index_after_epoch method descriptor

index_after_epoch(epoch: Epoch) -> int

Get the index of the state at or after the given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Name	Type	Description
int	int	Index of the state at or after the target epoch

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 11, 59, 0.0, 0.0, bh.TimeSystem.UTC)
index = traj.index_after_epoch(epc2)

index_before_epoch method descriptor

index_before_epoch(epoch: Epoch) -> int

Get the index of the state at or before the given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Name	Type	Description
int	int	Index of the state at or before the target epoch

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 12, 1, 0.0, 0.0, bh.TimeSystem.UTC)
index = traj.index_before_epoch(epc2)

interpolate method descriptor

interpolate(epoch: Epoch) -> ndarray

Interpolate state at a given epoch using the configured interpolation method.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Type	Description
ndarray	numpy.ndarray: Interpolated state vector

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state1 = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state1)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 12, 2, 0.0, 0.0, bh.TimeSystem.UTC)
state2 = np.array([bh.R_EARTH + 510e3, 0.0, 0.0, 0.0, 7650.0, 0.0])
traj.add(epc2, state2)
epc_mid = bh.Epoch.from_datetime(2024, 1, 1, 12, 1, 0.0, 0.0, bh.TimeSystem.UTC)
state_interp = traj.interpolate(epc_mid)

interpolate_linear method descriptor

interpolate_linear(epoch: Epoch) -> ndarray

Interpolate state at a given epoch using linear interpolation.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Type	Description
ndarray	numpy.ndarray: Linearly interpolated state vector

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state1 = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state1)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 12, 2, 0.0, 0.0, bh.TimeSystem.UTC)
state2 = np.array([bh.R_EARTH + 510e3, 0.0, 0.0, 0.0, 7650.0, 0.0])
traj.add(epc2, state2)
epc_mid = bh.Epoch.from_datetime(2024, 1, 1, 12, 1, 0.0, 0.0, bh.TimeSystem.UTC)
state_interp = traj.interpolate_linear(epc_mid)

is_empty method descriptor

is_empty() -> bool

Check if trajectory is empty.

Returns:

Name	Type	Description
bool	bool	True if trajectory contains no states, False otherwise

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
print(f"Is empty: {traj.is_empty()}")

last method descriptor

last() -> Tuple

Get the last (epoch, state) tuple in the trajectory, if any exists.

Returns:

Type	Description
Tuple	tuple or None: Tuple of (Epoch, numpy.ndarray) for last state, or None if empty

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
last_epc, last_state = traj.last()

len method descriptor

len() -> int

Get the number of states in the trajectory (alias for length).

Returns:

Name	Type	Description
int	int	Number of states in the trajectory

Example

import brahe as bh
import numpy as np

traj = bh.DTrajectory(6)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
print(f"Number of states: {traj.len()}")

nearest_state method descriptor

nearest_state(epoch: Epoch) -> Tuple

Get the nearest state to a given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Name	Type	Description
tuple	Tuple	Tuple of (Epoch, numpy.ndarray) containing the nearest state

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 30.0, 0.0, bh.TimeSystem.UTC)
nearest_epc, nearest_state = traj.nearest_state(epc2)

remove method descriptor

remove(index: int) -> Tuple

Remove a state at a specific index.

Parameters:

Name	Type	Description	Default
index	int	Index of the state to remove	required

Returns:

Name	Type	Description
tuple	Tuple	Tuple of (Epoch, numpy.ndarray) for the removed epoch and state

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
removed_epc, removed_state = traj.remove(0)

remove_epoch method descriptor

remove_epoch(epoch: Epoch) -> ndarray

Remove a state at a specific epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Epoch of the state to remove	required

Returns:

Type	Description
ndarray	numpy.ndarray: The removed state vector

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
removed_state = traj.remove_epoch(epc)

set_eviction_policy_max_age method descriptor

set_eviction_policy_max_age(max_age: float) -> Any

Set eviction policy to keep states within maximum age.

Parameters:

Name	Type	Description	Default
max_age	float	Maximum age in seconds relative to most recent state	required

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj.set_eviction_policy_max_age(3600.0)

set_eviction_policy_max_size method descriptor

set_eviction_policy_max_size(max_size: int) -> Any

Set eviction policy to keep maximum number of states.

Parameters:

Name	Type	Description	Default
max_size	int	Maximum number of states to retain	required

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj.set_eviction_policy_max_size(1000)

set_interpolation_method method descriptor

set_interpolation_method(method: InterpolationMethod) -> Any

Set the interpolation method for the trajectory.

Parameters:

Name	Type	Description	Default
method	InterpolationMethod	New interpolation method	required

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj.set_interpolation_method(bh.InterpolationMethod.LINEAR)

start_epoch method descriptor

start_epoch() -> Epoch

Get start epoch of trajectory.

Returns:

Type	Description
Epoch	Epoch or None: First epoch if trajectory is not empty, None otherwise

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
print(f"Start epoch: {traj.start_epoch()}")

state method descriptor

state(epoch: Epoch) -> ndarray

Get state at specified epoch (in native frame/representation).

Parameters:

Name	Type	Description	Default
epoch	Epoch	Time for state query	required

Returns:

Type	Description
ndarray	numpy.ndarray: State vector in trajectory's native frame and representation

Example

import brahe as bh
import numpy as np

# Create ECI Cartesian trajectory
traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
state1 = np.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
traj.add(epc1, state1)

# Query state at epoch
state = traj.state(epc1)

state_after_epoch method descriptor

state_after_epoch(epoch: Epoch) -> Tuple

Get the state at or after the given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Name	Type	Description
tuple	Tuple	Tuple of (Epoch, numpy.ndarray) containing state at or after the target epoch

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 11, 59, 0.0, 0.0, bh.TimeSystem.UTC)
ret_epc, ret_state = traj.state_after_epoch(epc2)

state_as_osculating_elements method descriptor

state_as_osculating_elements(epoch: Epoch, angle_format: AngleFormat) -> ndarray

Get state as osculating Keplerian elements at specified epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Time for state query	required
angle_format	AngleFormat	Desired angle format for output	required

Returns:

Type	Description
ndarray	numpy.ndarray: Osculating Keplerian elements [a, e, i, raan, argp, M]

Example

import brahe as bh
import numpy as np

# Create Cartesian trajectory
traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
state_cart = np.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
traj.add(epc, state_cart)

# Get osculating elements in degrees
elements = traj.state_as_osculating_elements(epc, bh.AngleFormat.DEGREES)
print(f"Semi-major axis: {elements[0]/1000:.2f} km")
print(f"Inclination: {elements[2]:.2f} degrees")

state_at_idx method descriptor

state_at_idx(index: int) -> ndarray

Get the state vector at a specific index.

Parameters:

Name	Type	Description	Default
index	int	Index of the state to retrieve	required

Returns:

Type	Description
ndarray	numpy.ndarray: State vector at the specified index

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
state = np.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
traj.add(epc, state)

# Get state at index
state_0 = traj.state_at_idx(0)

state_before_epoch method descriptor

state_before_epoch(epoch: Epoch) -> Tuple

Get the state at or before the given epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Target epoch	required

Returns:

Name	Type	Description
tuple	Tuple	Tuple of (Epoch, numpy.ndarray) containing state at or before the target epoch

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc1 = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc1, state)
epc2 = bh.Epoch.from_datetime(2024, 1, 1, 12, 1, 0.0, 0.0, bh.TimeSystem.UTC)
ret_epc, ret_state = traj.state_before_epoch(epc2)

state_ecef method descriptor

state_ecef(epoch: Epoch) -> ndarray

Get state in ECEF Cartesian frame at specified epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Time for state query	required

Returns:

Type	Description
ndarray	numpy.ndarray: State vector in ECEF Cartesian [x, y, z, vx, vy, vz] (meters, m/s)

Example

import brahe as bh
import numpy as np

# Create ECI trajectory
traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
state_eci = np.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
traj.add(epc, state_eci)

# Get ECEF state (automatically converted from ECI)
state_ecef = traj.state_ecef(epc)

state_eci method descriptor

state_eci(epoch: Epoch) -> ndarray

Get state in ECI Cartesian frame at specified epoch.

Parameters:

Name	Type	Description	Default
epoch	Epoch	Time for state query	required

Returns:

Type	Description
ndarray	numpy.ndarray: State vector in ECI Cartesian [x, y, z, vx, vy, vz] (meters, m/s)

Example

import brahe as bh
import numpy as np

# Create trajectory in any frame/representation
traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.KEPLERIAN, bh.AngleFormat.DEGREES)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.UTC)
oe = np.array([bh.R_EARTH + 500e3, 0.001, 98.0, 15.0, 30.0, 45.0])
traj.add(epc, oe)

# Get ECI Cartesian state (automatically converted from Keplerian)
state_eci = traj.state_eci(epc)

states method descriptor

states() -> ndarray

Get all states as a numpy array.

Returns:

Type	Description
ndarray	numpy.ndarray: 2D array of states with shape (6, N) where N is the number of states

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj.add(epc + 60.0, state)
states_array = traj.states()

timespan method descriptor

timespan() -> float

Get time span of trajectory in seconds.

Returns:

Type	Description
float	float or None: Time span between first and last epochs, or None if less than 2 states

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj.add(epc + 3600.0, state)
print(f"Timespan: {traj.timespan()} seconds")

to_ecef method descriptor

to_ecef() -> OrbitTrajectory

Convert to ECEF (Earth-Centered Earth-Fixed) frame in Cartesian representation.

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Trajectory in ECEF Cartesian frame

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj_ecef = traj.to_ecef()

to_eci method descriptor

to_eci() -> OrbitTrajectory

Convert to ECI (Earth-Centered Inertial) frame in Cartesian representation.

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Trajectory in ECI Cartesian frame

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECEF, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 0.0, 0.0])
traj.add(epc, state)
traj_eci = traj.to_eci()

to_keplerian method descriptor

to_keplerian(angle_format: AngleFormat) -> OrbitTrajectory

Convert to Keplerian representation in ECI frame.

Parameters:

Name	Type	Description	Default
angle_format	AngleFormat	Angle format for the result (Radians or Degrees)	required

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Trajectory in ECI Keplerian representation

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
traj_kep = traj.to_keplerian(bh.AngleFormat.RADIANS)

to_matrix method descriptor

to_matrix() -> ndarray

Convert trajectory to matrix representation.

Returns:

Type	Description
ndarray	numpy.ndarray: 2D array with shape (6, N) where N is number of states

Example

import brahe as bh
import numpy as np

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
state = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])
traj.add(epc, state)
matrix = traj.to_matrix()

with_eviction_policy_max_age method descriptor

with_eviction_policy_max_age(max_age: float) -> OrbitTrajectory

Set eviction policy to keep states within maximum age using builder pattern.

Parameters:

Name	Type	Description	Default
max_age	float	Maximum age of states in seconds	required

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Self with updated eviction policy

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj = traj.with_eviction_policy_max_age(3600.0)

with_eviction_policy_max_size method descriptor

with_eviction_policy_max_size(max_size: int) -> OrbitTrajectory

Set eviction policy to keep maximum number of states using builder pattern.

Parameters:

Name	Type	Description	Default
max_size	int	Maximum number of states to retain	required

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Self with updated eviction policy

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj = traj.with_eviction_policy_max_size(1000)

with_interpolation_method method descriptor

with_interpolation_method(interpolation_method: InterpolationMethod) -> OrbitTrajectory

Set interpolation method using builder pattern.

Parameters:

Name	Type	Description	Default
interpolation_method	InterpolationMethod	Interpolation method to use	required

Returns:

Name	Type	Description
OrbitTrajectory	OrbitTrajectory	Self with updated interpolation method

Example

import brahe as bh

traj = bh.OrbitTrajectory(bh.OrbitFrame.ECI, bh.OrbitRepresentation.CARTESIAN, None)
traj = traj.with_interpolation_method(bh.InterpolationMethod.LINEAR)

Overview

OrbitTrajectory is a specialized trajectory container for orbital mechanics that stores states in a specific reference frame (ECI or ECEF) and can automatically transform between frames when querying.

Module: brahe.trajectories

Key Features: - Frame-aware storage (ECI or ECEF) - Automatic frame transformations on query - Built on STrajectory6 (6D states only) - Same performance as STrajectory6

Creating with Frame

import brahe as bh

# ECI frame trajectory
traj_eci = bh.OrbitTrajectory(frame=bh.OrbitFrame.ECI)

# ECEF frame trajectory
traj_ecef = bh.OrbitTrajectory(frame=bh.OrbitFrame.ECEF)

Example Usage

import brahe as bh
import numpy as np

# Create ECI trajectory
traj = bh.OrbitTrajectory(frame=bh.OrbitFrame.ECI)

# Propagate and store states in ECI
epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
elements = np.array([7000e3, 0.001, 98*bh.DEG2RAD, 0, 0, 0])
prop = bh.KeplerianPropagator(
    epoch=epoch,
    elements=elements,
    frame=bh.OrbitFrame.ECI
)

# Add states
for i in range(100):
    t = epoch + i * 60.0
    state_eci = prop.propagate(t)
    traj.add(t, state_eci)

# States are stored and retrieved in ECI
query_epoch = epoch + 1800.0
state = traj.interpolate(query_epoch)  # ECI frame

Frame Information

# Get trajectory frame
frame = traj.frame()  # Returns OrbitFrame.ECI or OrbitFrame.ECEF

API

OrbitTrajectory has the same API as STrajectory6 and DTrajectory, plus frame awareness.

See STrajectory6 or DTrajectory for full API documentation.

See Also

• STrajectory6 - Non-frame-aware 6D trajectory
• DTrajectory - Dynamic-dimension trajectory
• OrbitFrame - Frame specifications