Skip to content

Trajectory

Dynamic-dimension trajectory container for N-dimensional state data.

Trajectory 

Trajectory(dimension: int = 6)

Dynamic-dimension trajectory container.

Stores a sequence of N-dimensional states at specific epochs with support for interpolation and automatic state eviction policies. Dimension is determined at runtime.

Parameters:

Name Type Description Default
dimension int

Trajectory dimension (default 6, must be greater than 0)

 6

Attributes:

Name Type Description
dimension int

State vector dimension
interpolation_method InterpolationMethod

Current interpolation method
Example 
1
2
3
4
import brahe as bh

traj = bh.Trajectory(6)  # 6D trajectory
traj = bh.Trajectory(3)  # 3D trajectory

Initialize instance.

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 
1
2
3
4
5
6
7
8
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}")

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

N-element state vector where N is the trajectory dimension

 required
Example 
1
2
3
4
5
6
7
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)

add_with_covariance method descriptor 

add_with_covariance(epoch: Epoch, state: ndarray, covariance: ndarray) -> Any

Add a state with its corresponding covariance matrix.

This automatically enables covariance storage if not already enabled.

Parameters:

Name Type Description Default
epoch Epoch

Time epoch

 required
state ndarray

State vector (must match trajectory dimension)

 required
covariance ndarray

Covariance matrix (must be square, dimension x dimension)

 required
Example 
1
2
3
4
5
6
7
8
import brahe as bh
import numpy as np

traj = bh.DTrajectory(6)
epc = bh.Epoch.from_datetime(2024, 1, 1, 0, 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])
cov = np.eye(6) * 100.0  # 100 m²/m²/s² diagonal covariance
traj.add_with_covariance(epc, state, cov)

clear method descriptor 

clear() -> Any

Clear all states from the trajectory.

covariance_at method descriptor 

covariance_at(epoch: Epoch) -> ndarray

Get covariance matrix at a specific epoch (with interpolation).

Returns None if covariance storage is not enabled or epoch is out of range.

Parameters:

Name Type Description Default
epoch Epoch

Time epoch to query

 required

Returns:

Type Description
ndarray

numpy.ndarray or None: Covariance matrix at the requested epoch (interpolated if necessary)
Example 
1
2
3
4
5
6
7
import brahe as bh

# ... create trajectory with covariances ...
epc = bh.Epoch.from_datetime(2024, 1, 1, 0, 5, 0.0, 0.0, bh.TimeSystem.UTC)
cov = traj.covariance_at(epc)
if cov is not None:
    print(f"Position variance: {cov[0,0]} m²")

dimension method descriptor 

dimension() -> int

Get the trajectory dimension (method form).

Returns:

Name Type Description
int int

Dimension of the trajectory
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
print(f"Dimension: {traj.dimension()}")

enable_covariance_storage method descriptor 

enable_covariance_storage() -> Any

Enable covariance storage for this trajectory.

Initializes the covariance vector with zero matrices for all existing states. After calling this, covariances can be added using add_with_covariance() or set_covariance_at().

Example 
1
2
3
import brahe as bh
traj = bh.DTrajectory(6)
traj.enable_covariance_storage()

end_epoch method descriptor 

end_epoch() -> Any

Get end epoch of trajectory

epoch_at_idx method descriptor 

epoch_at_idx(index: int) -> Epoch

Get epoch at a specific index

Parameters:

Name Type Description Default
index int

Index of the epoch

 required

Returns:

Name Type Description
Epoch Epoch

Epoch at index
Example 
1
2
3
4
5
6
7
8
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)
retrieved_epc = traj.epoch_at_idx(0)

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 
1
2
3
4
5
6
7
8
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_data builtin 

from_data(epochs: list[Epoch], states: ndarray, interpolation_method: InterpolationMethod = None) -> Trajectory

Create a trajectory from existing data.

Parameters:

Name Type Description Default
epochs list[Epoch]

List of time epochs

 required
states ndarray

2D array of states with shape (num_epochs, dimension) where each row is a state vector

 required
interpolation_method InterpolationMethod

Interpolation method (default Linear)

 None

Returns:

Name Type Description
DTrajectory Trajectory

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 
1
2
3
4
5
6
7
8
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_covariance_interpolation_method method descriptor 

get_covariance_interpolation_method() -> CovarianceInterpolationMethod

Get current covariance interpolation method.

Returns:

Name Type Description
CovarianceInterpolationMethod CovarianceInterpolationMethod

Current covariance interpolation method
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
method = traj.get_covariance_interpolation_method()

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 
1
2
3
4
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 interpolation method.

Returns:

Name Type Description
InterpolationMethod InterpolationMethod

Current interpolation method
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
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 
1
2
3
4
5
6
7
8
9
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 
1
2
3
4
5
6
7
8
9
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 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
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 
1
2
3
4
5
6
7
8
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 
1
2
3
4
5
6
7
8
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 
1
2
3
4
5
6
7
8
9
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 
1
2
3
4
5
6
7
8
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 
1
2
3
4
5
6
7
8
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_covariance_at method descriptor 

set_covariance_at(index: int, covariance: ndarray) -> Any

Set covariance matrix at a specific index.

Enables covariance storage if not already enabled.

Parameters:

Name Type Description Default
index int

Index in the trajectory

 required
covariance ndarray

Covariance matrix (must be square, dimension x dimension)

 required
Example 
1
2
3
4
5
6
7
import brahe as bh
import numpy as np

traj = bh.DTrajectory(6)
# ... add states ...
cov = np.eye(6) * 100.0
traj.set_covariance_at(0, cov)

set_covariance_interpolation_method method descriptor 

set_covariance_interpolation_method(method: CovarianceInterpolationMethod) -> Any

Set covariance interpolation method.

Covariance matrices require special interpolation methods to preserve positive semi-definiteness.

Parameters:

Name Type Description Default
method CovarianceInterpolationMethod

Covariance interpolation method to use

 required
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
traj.set_covariance_interpolation_method(bh.CovarianceInterpolationMethod.MATRIX_SQUARE_ROOT)

set_eviction_policy_max_age method descriptor 

set_eviction_policy_max_age(max_age: float) -> Any

Set maximum age for trajectory states.

Parameters:

Name Type Description Default
max_age float

Maximum age in seconds relative to most recent state

 required

set_eviction_policy_max_size method descriptor 

set_eviction_policy_max_size(max_size: int) -> Any

Set maximum trajectory size.

Parameters:

Name Type Description Default
max_size int

Maximum number of states to retain

 required

set_interpolation_method method descriptor 

set_interpolation_method(method: InterpolationMethod) -> Any

Set interpolation method.

Parameters:

Name Type Description Default
method InterpolationMethod

New interpolation method

 required
Example 
1
2
3
4
5
import brahe as bh

traj = bh.DTrajectory(6)
method = bh.InterpolationMethod.LINEAR
traj.set_interpolation_method(method)

start_epoch method descriptor 

start_epoch() -> Any

Get start epoch of trajectory

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 
1
2
3
4
5
6
7
8
9
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_at_idx method descriptor 

state_at_idx(index: int) -> ndarray

Get state at a specific index

Parameters:

Name Type Description Default
index int

Index of the state

 required

Returns:

Type Description
ndarray

numpy.ndarray: State vector at index
Example 
1
2
3
4
5
6
7
8
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)
retrieved_state = 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 
1
2
3
4
5
6
7
8
9
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)

timespan method descriptor 

timespan() -> Any

Get time span of trajectory in seconds

to_matrix method descriptor 

to_matrix() -> ndarray

Get all states as a numpy array

with_covariance_interpolation_method method descriptor 

with_covariance_interpolation_method(method: CovarianceInterpolationMethod) -> DTrajectory

Set covariance interpolation method using builder pattern.

Covariance matrices require special interpolation methods to preserve positive semi-definiteness. This method allows setting the interpolation method used when calling covariance_at().

Parameters:

Name Type Description Default
method CovarianceInterpolationMethod

Covariance interpolation method to use

 required

Returns:

Name Type Description
DTrajectory DTrajectory

Self with updated covariance interpolation method
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
traj = traj.with_covariance_interpolation_method(bh.CovarianceInterpolationMethod.TWO_WASSERSTEIN)

with_eviction_policy_max_age method descriptor 

with_eviction_policy_max_age(max_age: float) -> DTrajectory

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
DTrajectory DTrajectory

Self with updated eviction policy
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
traj = traj.with_eviction_policy_max_age(3600.0)

with_eviction_policy_max_size method descriptor 

with_eviction_policy_max_size(max_size: int) -> DTrajectory

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
DTrajectory DTrajectory

Self with updated eviction policy
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
traj = traj.with_eviction_policy_max_size(1000)

with_interpolation_method method descriptor 

with_interpolation_method(interpolation_method: InterpolationMethod) -> DTrajectory

Set interpolation method using builder pattern

Parameters:

Name Type Description Default
interpolation_method InterpolationMethod

Interpolation method to use

 required

Returns:

Name Type Description
DTrajectory DTrajectory

Self with updated interpolation method
Example 
1
2
3
4
import brahe as bh

traj = bh.DTrajectory(6)
traj = traj.with_interpolation_method(bh.InterpolationMethod.LINEAR)

See Also