Skip to content

Altitude and Period Functions

Functions for computing orbital altitudes and periods from orbital elements or state vectors.

Orbital Period from State

orbital_period_from_state builtin 

orbital_period_from_state(state_eci: Union[ndarray, Sequence], gm: float, axis: int = -1) -> Union[float, ndarray]

Computes orbital period from an ECI state vector using the vis-viva equation.

This function uses the vis-viva equation to compute the semi-major axis from the position and velocity, then calculates the orbital period.

Parameters:

Name Type Description Default
state_eci ndarray or list

ECI state vector [x, y, z, vx, vy, vz] in meters and meters/second. Also accepts a batch of states with the 6 components along axis (for example shape (n, 6)).

 required
gm float

Gravitational parameter in m³/s². Use GM_EARTH for Earth orbits.

 required
axis int

The axis of state_eci along which the 6 state components of a single vector lie; the remaining axes enumerate the batch. For a batch of shape (n, 6) the components lie along the last axis, so the default -1 applies; a (6, n) column layout uses axis=0.

 -1

Returns:

Type Description
Union[float, ndarray]

float or numpy.ndarray: Orbital period in seconds. An array of the batch dimensions is returned for batched input.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import brahe as bh
import numpy as np

# Create a circular orbit state at 500 km altitude
r = bh.R_EARTH + 500e3
v = np.sqrt(bh.GM_EARTH / r)
state_eci = np.array([r, 0, 0, 0, v, 0])

# Compute orbital period from state
period = bh.orbital_period_from_state(state_eci, bh.GM_EARTH)
print(f"Period: {period/60:.2f} minutes")

Altitude Functions

Periapsis and Apoapsis (General)

periapsis_altitude builtin 

periapsis_altitude(a_or_oe: Union[float, array], e: Union[float, array] = None, *, r_body: float) -> Union[float, ndarray]

Calculate the altitude above a body's surface at periapsis.

Parameters:

Name Type Description Default
a_or_oe float or array

The semi-major axis in meters, as a scalar or an array evaluated element-wise (broadcast against e); or, when e is omitted, a 2-D array of shape (n, 6) of Keplerian element sets [a, e, i, Ω, ω, ν] from which a and e are taken row by row.

 required
e float or array

The eccentricity, broadcast against a_or_oe when either is an array. Required unless a_or_oe is a 2-D element-set batch, where it is ignored.

 None
r_body float

(keyword-only) The radius of the central body in meters.

 required

Returns:

Type Description
Union[float, ndarray]

float or numpy.ndarray: The altitude above the body's surface at periapsis in meters. An array is returned for array input: shape (n,) for n element sets, or the broadcast shape for element-wise input.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import brahe as bh
import numpy as np

# Using scalar parameters
a = bh.R_EARTH + 500e3  # 500 km mean altitude
e = 0.01  # slight eccentricity
alt_peri = bh.periapsis_altitude(a, e, r_body=bh.R_EARTH)
print(f"Periapsis altitude: {alt_peri/1000:.2f} km")

# Using a batch of Keplerian element sets, one result per row
oe = [bh.R_EARTH + 500e3, 0.01, np.radians(45), 0, 0, 0]
alt_peri_rows = bh.periapsis_altitude(np.array([oe, oe]), r_body=bh.R_EARTH)
print(f"Periapsis altitude: (first row) {alt_peri_rows[0]/1000:.2f} km")

apoapsis_altitude builtin 

apoapsis_altitude(a_or_oe: Union[float, array], e: Union[float, array] = None, *, r_body: float) -> Union[float, ndarray]

Calculate the altitude above a body's surface at apoapsis.

Parameters:

Name Type Description Default
a_or_oe float or array

The semi-major axis in meters, as a scalar or an array evaluated element-wise (broadcast against e); or, when e is omitted, a 2-D array of shape (n, 6) of Keplerian element sets [a, e, i, Ω, ω, ν] from which a and e are taken row by row.

 required
e float or array

The eccentricity, broadcast against a_or_oe when either is an array. Required unless a_or_oe is a 2-D element-set batch, where it is ignored.

 None
r_body float

(keyword-only) The radius of the central body in meters.

 required

Returns:

Type Description
Union[float, ndarray]

float or numpy.ndarray: The altitude above the body's surface at apoapsis in meters. An array is returned for array input: shape (n,) for n element sets, or the broadcast shape for element-wise input.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import brahe as bh
import numpy as np

# Using scalar parameters
a = bh.R_MOON + 100e3  # 100 km mean altitude
e = 0.05  # moderate eccentricity
alt_apo = bh.apoapsis_altitude(a, e, r_body=bh.R_MOON)
print(f"Apoapsis altitude: {alt_apo/1000:.2f} km")

# Using a batch of Keplerian element sets, one result per row
oe = [bh.R_MOON + 100e3, 0.05, np.radians(30), 0, 0, 0]
alt_apo_rows = bh.apoapsis_altitude(np.array([oe, oe]), r_body=bh.R_MOON)
print(f"Apoapsis altitude: (first row) {alt_apo_rows[0]/1000:.2f} km")

Perigee and Apogee (Earth-Specific)

perigee_altitude builtin 

perigee_altitude(a_or_oe: Union[float, array], e: Union[float, array] = None) -> Union[float, ndarray]

Calculate the altitude above Earth's surface at perigee.

Parameters:

Name Type Description Default
a_or_oe float or array

The semi-major axis in meters, as a scalar or an array evaluated element-wise (broadcast against e); or, when e is omitted, a 2-D array of shape (n, 6) of Keplerian element sets [a, e, i, Ω, ω, ν] from which a and e are taken row by row.

 required
e float or array

The eccentricity, broadcast against a_or_oe when either is an array. Required unless a_or_oe is a 2-D element-set batch, where it is ignored.

 None

Returns:

Type Description
Union[float, ndarray]

float or numpy.ndarray: The altitude above Earth's surface at perigee in meters. An array is returned for array input: shape (n,) for n element sets, or the broadcast shape for element-wise input.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import brahe as bh
import numpy as np

# Using scalar parameters
a = bh.R_EARTH + 420e3  # 420 km mean altitude
e = 0.0005  # very nearly circular
alt = bh.perigee_altitude(a, e)
print(f"Perigee altitude: {alt/1000:.2f} km")

# Using a batch of Keplerian element sets, one result per row
oe = [bh.R_EARTH + 420e3, 0.0005, np.radians(51.6), 0, 0, 0]
alt_rows = bh.perigee_altitude(np.array([oe, oe]))
print(f"Perigee altitude: (first row) {alt_rows[0]/1000:.2f} km")

apogee_altitude builtin 

apogee_altitude(a_or_oe: Union[float, array], e: Union[float, array] = None) -> Union[float, ndarray]

Calculate the altitude above Earth's surface at apogee.

Parameters:

Name Type Description Default
a_or_oe float or array

The semi-major axis in meters, as a scalar or an array evaluated element-wise (broadcast against e); or, when e is omitted, a 2-D array of shape (n, 6) of Keplerian element sets [a, e, i, Ω, ω, ν] from which a and e are taken row by row.

 required
e float or array

The eccentricity, broadcast against a_or_oe when either is an array. Required unless a_or_oe is a 2-D element-set batch, where it is ignored.

 None

Returns:

Type Description
Union[float, ndarray]

float or numpy.ndarray: The altitude above Earth's surface at apogee in meters. An array is returned for array input: shape (n,) for n element sets, or the broadcast shape for element-wise input.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import brahe as bh
import numpy as np

# Using scalar parameters
a = 26554000.0  # ~26554 km semi-major axis
e = 0.7  # highly eccentric
alt = bh.apogee_altitude(a, e)
print(f"Apogee altitude: {alt/1000:.2f} km")

# Using a batch of Keplerian element sets, one result per row
oe = [26554000.0, 0.7, np.radians(63.4), 0, 0, 0]
alt_rows = bh.apogee_altitude(np.array([oe, oe]))
print(f"Apogee altitude: (first row) {alt_rows[0]/1000:.2f} km")