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: ndarray, gm: float) -> float

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

ECI state vector [x, y, z, vx, vy, vz] in meters and meters/second.

 required
gm float

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

 required

Returns:

Name Type Description
float float

Orbital period in seconds.
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: float = None, *, r_body: float) -> float

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

Parameters:

Name Type Description Default
a_or_oe float or array

Either the semi-major axis in meters, or a 6-element Keplerian elements array [a, e, i, Ω, ω, ν] from which a and e will be extracted.

 required
e float

The eccentricity. Required if a_or_oe is a scalar, ignored if vector.

 None
r_body float

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

 required

Returns:

Name Type Description
float float

The altitude above the body's surface at periapsis in meters.
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, bh.R_EARTH)
print(f"Periapsis altitude: {alt_peri/1000:.2f} km")

# Using Keplerian elements vector
oe = [bh.R_EARTH + 500e3, 0.01, np.radians(45), 0, 0, 0]
alt_peri = bh.periapsis_altitude(oe, r_body=bh.R_EARTH)
print(f"Periapsis altitude: {alt_peri/1000:.2f} km")

apoapsis_altitude builtin 

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

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

Parameters:

Name Type Description Default
a_or_oe float or array

Either the semi-major axis in meters, or a 6-element Keplerian elements array [a, e, i, Ω, ω, ν] from which a and e will be extracted.

 required
e float

The eccentricity. Required if a_or_oe is a scalar, ignored if vector.

 None
r_body float

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

 required

Returns:

Name Type Description
float float

The altitude above the body's surface at apoapsis in meters.
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, bh.R_MOON)
print(f"Apoapsis altitude: {alt_apo/1000:.2f} km")

# Using Keplerian elements vector
oe = [bh.R_MOON + 100e3, 0.05, np.radians(30), 0, 0, 0]
alt_apo = bh.apoapsis_altitude(oe, r_body=bh.R_MOON)
print(f"Apoapsis altitude: {alt_apo/1000:.2f} km")

Perigee and Apogee (Earth-Specific)

perigee_altitude builtin 

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

Calculate the altitude above Earth's surface at perigee.

Parameters:

Name Type Description Default
a_or_oe float or array

Either the semi-major axis in meters, or a 6-element Keplerian elements array [a, e, i, Ω, ω, ν] from which a and e will be extracted.

 required
e float

The eccentricity. Required if a_or_oe is a scalar, ignored if vector.

 None

Returns:

Name Type Description
float float

The altitude above Earth's surface at perigee in meters.
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 Keplerian elements vector
oe = [bh.R_EARTH + 420e3, 0.0005, np.radians(51.6), 0, 0, 0]
alt = bh.perigee_altitude(oe)
print(f"Perigee altitude: {alt/1000:.2f} km")

apogee_altitude builtin 

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

Calculate the altitude above Earth's surface at apogee.

Parameters:

Name Type Description Default
a_or_oe float or array

Either the semi-major axis in meters, or a 6-element Keplerian elements array [a, e, i, Ω, ω, ν] from which a and e will be extracted.

 required
e float

The eccentricity. Required if a_or_oe is a scalar, ignored if vector.

 None

Returns:

Name Type Description
float float

The altitude above Earth's surface at apogee in meters.
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 Keplerian elements vector
oe = [26554000.0, 0.7, np.radians(63.4), 0, 0, 0]
alt = bh.apogee_altitude(oe)
print(f"Apogee altitude: {alt/1000:.2f} km")