Mean Elements¶

Functions for converting between mean and osculating Keplerian orbital elements, using either first-order Brouwer-Lyddane theory or numerical windowed averaging.

Note

For conceptual explanations and usage examples, see Mean Elements in the User Guide.

Single-State Conversions¶

state_koe_osc_to_mean `builtin` ¶

state_koe_osc_to_mean(osc: ndarray, method: MeanElementMethod, angle_format: AngleFormat) -> ndarray

Convert osculating Keplerian elements to mean Keplerian elements.

Applies the selected mean-element method to convert osculating (instantaneous) orbital elements to mean (orbit-averaged) elements. MeanElementMethod.numerical() is batch-only and raises for single-state calls; use MeanElementMethod.BROUWER_LYDDANE for the first-order analytical J2 mapping.

Parameters:

Name	Type	Description	Default
`osc`	`ndarray`	Osculating Keplerian elements as a 6-element array: [a, e, i, Ω, ω, M] where: - a: Semi-major axis (meters) - e: Eccentricity (dimensionless) - i: Inclination (radians or degrees, per angle_format) - Ω: Right ascension of ascending node (radians or degrees, per angle_format) - ω: Argument of perigee (radians or degrees, per angle_format) - M: Mean anomaly (radians or degrees, per angle_format)	required
`method`	`MeanElementMethod`	Algorithm used to compute mean elements.	required
`angle_format`	`AngleFormat`	Format of angular elements (Radians or Degrees)	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Mean Keplerian elements in the same format as input.

Raises:

Type	Description
`BraheError`	If `method` is `MeanElementMethod.numerical()`.

Note

The forward and inverse transformations are not perfectly inverse due to first-order truncation of the infinite series. Small errors of order J2² are expected.

Example

import brahe as bh
import numpy as np

# Define osculating elements for a LEO satellite (angles in degrees)
osc = np.array([
    bh.R_EARTH + 500e3,  # a = 6878 km
    0.001,               # e = 0.001 (near-circular)
    45.0,                # i = 45 degrees
    0.0,                 # Ω = 0
    0.0,                 # ω = 0
    0.0,                 # M = 0
])

mean = bh.state_koe_osc_to_mean(osc, bh.MeanElementMethod.BROUWER_LYDDANE, bh.AngleFormat.DEGREES)

state_koe_mean_to_osc `builtin` ¶

state_koe_mean_to_osc(mean: ndarray, method: MeanElementMethod, angle_format: AngleFormat) -> ndarray

Convert mean Keplerian elements to osculating Keplerian elements.

Applies the selected mean-element method to convert mean (orbit-averaged) orbital elements to osculating (instantaneous) elements. MeanElementMethod.numerical() is batch-only and raises for single-state calls; use MeanElementMethod.BROUWER_LYDDANE for the first-order analytical J2 mapping.

Parameters:

Name	Type	Description	Default
`mean`	`ndarray`	Mean Keplerian elements as a 6-element array: [a, e, i, Ω, ω, M] where: - a: Semi-major axis (meters) - e: Eccentricity (dimensionless) - i: Inclination (radians or degrees, per angle_format) - Ω: Right ascension of ascending node (radians or degrees, per angle_format) - ω: Argument of perigee (radians or degrees, per angle_format) - M: Mean anomaly (radians or degrees, per angle_format)	required
`method`	`MeanElementMethod`	Algorithm used to compute osculating elements.	required
`angle_format`	`AngleFormat`	Format of angular elements (Radians or Degrees)	required

Returns:

Type	Description
`ndarray`	numpy.ndarray: Osculating Keplerian elements in the same format as input.

Raises:

Type	Description
`BraheError`	If `method` is `MeanElementMethod.numerical()`.

Note

The forward and inverse transformations are not perfectly inverse due to first-order truncation of the infinite series. Small errors of order J2² are expected.

Example

import brahe as bh
import numpy as np

# Define mean elements for a LEO satellite (angles in degrees)
mean = np.array([
    bh.R_EARTH + 500e3,  # a = 6878 km
    0.001,               # e = 0.001 (near-circular)
    45.0,                # i = 45 degrees
    0.0,                 # Ω = 0
    0.0,                 # ω = 0
    0.0,                 # M = 0
])

osc = bh.state_koe_mean_to_osc(mean, bh.MeanElementMethod.BROUWER_LYDDANE, bh.AngleFormat.DEGREES)

Batch Conversions¶

states_koe_osc_to_mean `builtin` ¶

states_koe_osc_to_mean(epochs: list[Epoch], states: ndarray, method: MeanElementMethod, angle_format: AngleFormat) -> Tuple

Convert a batch of osculating Keplerian states to mean Keplerian states.

Applies the selected mean-element method across an epoch/state series. MeanElementMethod.BROUWER_LYDDANE maps each (epoch, state) pair independently, so the output has the same length as the input. MeanElementMethod.numerical() instead averages the osculating states over a moving window (see MeanElementNumericalMethodConfig); the output may be shorter than the input when edge is WindowEdgeHandling.TRUNCATE and some output epochs' windows are not fully supported by the input trajectory.

Parameters:

Name	Type	Description	Default
`epochs`	`list[Epoch]`	Epochs of the input osculating states, one per `states` row.	required
`states`	`ndarray`	Osculating Keplerian elements, shape (M, 6). Each row is [a, e, i, Ω, ω, M] where: - a: Semi-major axis (meters) - e: Eccentricity (dimensionless) - i: Inclination (radians or degrees, per angle_format) - Ω: Right ascension of ascending node (radians or degrees, per angle_format) - ω: Argument of perigee (radians or degrees, per angle_format) - M: Mean anomaly (radians or degrees, per angle_format)	required
`method`	`MeanElementMethod`	Algorithm used to compute mean elements.	required
`angle_format`	`AngleFormat`	Format of angular elements (Radians or Degrees).	required

Returns:

Name	Type	Description
`tuple`	`Tuple`	(list[Epoch], numpy.ndarray) of output epochs and mean Keplerian elements, shape (N, 6). N equals M for `BROUWER_LYDDANE`; for `numerical()` N may be less than M when `edge` is `WindowEdgeHandling.TRUNCATE`.

Raises:

Type	Description
`BraheError`	If `epochs` and `states` have different lengths, or if `method` is `MeanElementMethod.numerical()` and `window_seconds` is not positive.

Example

import brahe as bh
import numpy as np

e0 = bh.Epoch.from_gps_seconds(0.0)
epochs = [e0, e0 + 60.0, e0 + 120.0]
s = np.array([bh.R_EARTH + 500e3, 0.01, 45.0, 30.0, 60.0, 90.0])
states = np.vstack([s, s, s])

out_epochs, out_states = bh.states_koe_osc_to_mean(
    epochs, states, bh.MeanElementMethod.BROUWER_LYDDANE, bh.AngleFormat.DEGREES
)

states_koe_mean_to_osc `builtin` ¶

states_koe_mean_to_osc(epochs: list[Epoch], states: ndarray, method: MeanElementMethod, angle_format: AngleFormat) -> Tuple

Convert a batch of mean Keplerian states to osculating Keplerian states.

Applies the selected mean-element method across an epoch/state series. MeanElementMethod.BROUWER_LYDDANE maps each (epoch, state) pair independently, so the output has the same length as the input. MeanElementMethod.numerical() instead inverts the windowed averaging via iterative differential correction (see MeanElementNumericalMethodConfig and MeanElementInverseConfig); the output has the same length and epochs as the input.

Parameters:

Name	Type	Description	Default
`epochs`	`list[Epoch]`	Epochs of the input mean states, one per `states` row.	required
`states`	`ndarray`	Mean Keplerian elements, shape (M, 6). Each row is [a, e, i, Ω, ω, M] where: - a: Semi-major axis (meters) - e: Eccentricity (dimensionless) - i: Inclination (radians or degrees, per angle_format) - Ω: Right ascension of ascending node (radians or degrees, per angle_format) - ω: Argument of perigee (radians or degrees, per angle_format) - M: Mean anomaly (radians or degrees, per angle_format)	required
`method`	`MeanElementMethod`	Algorithm used to compute osculating elements.	required
`angle_format`	`AngleFormat`	Format of angular elements (Radians or Degrees).	required

Returns:

Name	Type	Description
`tuple`	`Tuple`	(list[Epoch], numpy.ndarray) of output epochs and osculating Keplerian elements, shape (M, 6).

Raises:

Type	Description
`BraheError`	If `epochs` and `states` have different lengths; if `method` is `MeanElementMethod.numerical()` and `inverse` was not configured on the `MeanElementNumericalMethodConfig`; or if the differential correction fails to converge within `inverse.max_iterations` for any state.

Example

import brahe as bh
import numpy as np

e0 = bh.Epoch.from_gps_seconds(0.0)
epochs = [e0, e0 + 60.0, e0 + 120.0]
s = np.array([bh.R_EARTH + 500e3, 0.01, 45.0, 30.0, 60.0, 90.0])
states = np.vstack([s, s, s])

out_epochs, out_states = bh.states_koe_mean_to_osc(
    epochs, states, bh.MeanElementMethod.BROUWER_LYDDANE, bh.AngleFormat.DEGREES
)

Methods and Configuration¶

MeanElementMethod ¶

MeanElementMethod()

Algorithm used to map between mean and osculating Keplerian elements.

Note

This class is created via a class attribute and a class method: - MeanElementMethod.BROUWER_LYDDANE - First-order analytical J2 mapping - MeanElementMethod.numerical(config) - Numerical windowed averaging (batch-only)

Example

import brahe as bh

# Analytical Brouwer-Lyddane method (single-state and batch)
method = bh.MeanElementMethod.BROUWER_LYDDANE

# Numerical windowed-averaging method (batch-only)
cfg = bh.MeanElementNumericalMethodConfig(5400.0, bh.WindowAlignment.CENTERED, bh.WindowEdgeHandling.TRUNCATE)
method = bh.MeanElementMethod.numerical(cfg)

Initialize instance.

BROUWER_LYDDANE `class-attribute` ¶

BROUWER_LYDDANE: Any = MeanElementMethod.BROUWER_LYDDANE

Algorithm used to map between mean and osculating Keplerian elements.

Note

This class is created via a class attribute and a class method: - MeanElementMethod.BROUWER_LYDDANE - First-order analytical J2 mapping - MeanElementMethod.numerical(config) - Numerical windowed averaging (batch-only)

Example

import brahe as bh

# Analytical Brouwer-Lyddane method (single-state and batch)
method = bh.MeanElementMethod.BROUWER_LYDDANE

# Numerical windowed-averaging method (batch-only)
cfg = bh.MeanElementNumericalMethodConfig(5400.0, bh.WindowAlignment.CENTERED, bh.WindowEdgeHandling.TRUNCATE)
method = bh.MeanElementMethod.numerical(cfg)

numerical `builtin` ¶

numerical(config: MeanElementNumericalMethodConfig) -> MeanElementMethod

Create a numerical windowed-averaging method selector (batch-only).

Parameters:

Name	Type	Description	Default
`config`	`MeanElementNumericalMethodConfig`	Numerical averaging window configuration.	required

Returns:

Name	Type	Description
`MeanElementMethod`	`MeanElementMethod`	A numerical method selector.

WindowAlignment ¶

WindowAlignment()

Placement of the numerical averaging window relative to the output epoch.

Example

import brahe as bh

alignment = bh.WindowAlignment.CENTERED

Initialize instance.

CENTERED `class-attribute` ¶

CENTERED: Any = WindowAlignment.Centered

Placement of the numerical averaging window relative to the output epoch.

Example

import brahe as bh

alignment = bh.WindowAlignment.CENTERED

LEADING `class-attribute` ¶

LEADING: Any = WindowAlignment.Leading

Placement of the numerical averaging window relative to the output epoch.

Example

import brahe as bh

alignment = bh.WindowAlignment.CENTERED

TRAILING `class-attribute` ¶

TRAILING: Any = WindowAlignment.Trailing

Placement of the numerical averaging window relative to the output epoch.

Example

import brahe as bh

alignment = bh.WindowAlignment.CENTERED

WindowEdgeHandling ¶

WindowEdgeHandling()

Handling of output epochs whose averaging window runs past the data bounds.

Example

import brahe as bh

edge = bh.WindowEdgeHandling.TRUNCATE

Initialize instance.

PRESERVE_WINDOW `class-attribute` ¶

PRESERVE_WINDOW: Any = WindowEdgeHandling.PreserveWindow

Handling of output epochs whose averaging window runs past the data bounds.

Example

import brahe as bh

edge = bh.WindowEdgeHandling.TRUNCATE

TRUNCATE `class-attribute` ¶

TRUNCATE: Any = WindowEdgeHandling.Truncate

Handling of output epochs whose averaging window runs past the data bounds.

Example

import brahe as bh

edge = bh.WindowEdgeHandling.TRUNCATE

MeanElementNumericalMethodConfig ¶

MeanElementNumericalMethodConfig(window_seconds: float, alignment: WindowAlignment, edge: WindowEdgeHandling, inverse: MeanElementInverseConfig = None)

Configuration for the numerical windowed-averaging mean-element method.

Parameters:

Name	Type	Description	Default
`window_seconds`	`float`	Averaging window length in seconds.	required
`alignment`	`WindowAlignment`	Placement of the averaging window relative to the output epoch.	required
`edge`	`WindowEdgeHandling`	Handling of output epochs whose window runs past the data bounds.	required
`inverse`	`MeanElementInverseConfig`	Dynamics for the iterative mean-to-osculating inverse. Required for numerical mean-to-osculating conversion; unused for osculating-to-mean.	`None`

Example

import brahe as bh

cfg = bh.MeanElementNumericalMethodConfig(5400.0, bh.WindowAlignment.CENTERED, bh.WindowEdgeHandling.TRUNCATE)

Initialize instance.

alignment `property` ¶

alignment: Any

Placement of the averaging window relative to the output epoch.

edge `property` ¶

edge: Any

Handling of output epochs whose window runs past the data bounds.

inverse `property` ¶

inverse: Any

Dynamics for the iterative mean-to-osculating inverse, if configured.

window_seconds `property` ¶

window_seconds: float

Averaging window length in seconds.

MeanElementInverseConfig ¶

MeanElementInverseConfig(force_model: ForceModelConfig, propagation: NumericalPropagationConfig, tolerance: float, max_iterations: int)

Iterative differential-correction dynamics for numerical mean-to-osculating conversion.

Parameters:

Name	Type	Description	Default
`force_model`	`ForceModelConfig`	Force model used to propagate the trial osculating state.	required
`propagation`	`NumericalPropagationConfig`	Integrator settings for the trial propagation.	required
`tolerance`	`float`	Convergence tolerance on the mean-element residual, compared against the mixed norm `\|Δa\| (m) + 1e6·\|Δe\| + 1e6·‖Δ(i, Ω, ω, M)‖ (rad)`. For example, `tolerance=1.0` demands roughly 1 m in a, 1e-6 in e, and 1e-6 rad (~0.2 arcsec) in the angles combined.	required
`max_iterations`	`int`	Maximum number of differential-correction iterations.	required

Example

import brahe as bh

cfg = bh.MeanElementInverseConfig(
    bh.ForceModelConfig.default(),
    bh.NumericalPropagationConfig.default(),
    1.0,
    50,
)

Initialize instance.

force_model `property` ¶

force_model: Any

Force model used to propagate the trial osculating state.

max_iterations `property` ¶

max_iterations: Any

Maximum number of differential-correction iterations.

propagation `property` ¶

propagation: Any

Integrator settings for the trial propagation.

tolerance `property` ¶

tolerance: Any

Convergence tolerance on the mean-element residual (mixed norm |Δa| (m) + 1e6·|Δe| + 1e6·‖Δ(i, Ω, ω, M)‖ (rad)).

Mean Elements¶

Single-State Conversions¶

state_koe_osc_to_mean builtin ¶

state_koe_mean_to_osc builtin ¶

Batch Conversions¶

states_koe_osc_to_mean builtin ¶

states_koe_mean_to_osc builtin ¶

Methods and Configuration¶

MeanElementMethod ¶

BROUWER_LYDDANE class-attribute ¶

numerical builtin ¶

WindowAlignment ¶

CENTERED class-attribute ¶

LEADING class-attribute ¶

TRAILING class-attribute ¶

WindowEdgeHandling ¶

PRESERVE_WINDOW class-attribute ¶

TRUNCATE class-attribute ¶

MeanElementNumericalMethodConfig ¶

alignment property ¶

edge property ¶

inverse property ¶

window_seconds property ¶

MeanElementInverseConfig ¶

force_model property ¶

max_iterations property ¶

propagation property ¶

tolerance property ¶

See Also¶

state_koe_osc_to_mean `builtin` ¶

state_koe_mean_to_osc `builtin` ¶

states_koe_osc_to_mean `builtin` ¶

states_koe_mean_to_osc `builtin` ¶

BROUWER_LYDDANE `class-attribute` ¶

numerical `builtin` ¶

CENTERED `class-attribute` ¶

LEADING `class-attribute` ¶

TRAILING `class-attribute` ¶

PRESERVE_WINDOW `class-attribute` ¶

TRUNCATE `class-attribute` ¶

alignment `property` ¶

edge `property` ¶

inverse `property` ¶

window_seconds `property` ¶

force_model `property` ¶

max_iterations `property` ¶

propagation `property` ¶

tolerance `property` ¶