API: astrodyn_core.orekit_env

astrodyn_core.orekit_env

Shared Orekit environment configuration and resolver helpers.

This package centralizes the environment settings used across subsystems:

• universe configuration loading/validation
• IERS/ITRF frame resolution
• Earth shape and gravitational parameter resolution

Most users import these helpers indirectly through higher-level APIs, but the functions here are stable and useful for advanced workflows and tests.

coerce_bool(value)

Coerce bool-like YAML values into bool.

Recognized string values (case-insensitive):

• truthy: 1, true, yes, on
• falsy: 0, false, no, off

Unrecognized values fall back to Python's bool(value) semantics.

Parameters:

Name	Type	Description	Default
value	Any	Arbitrary value parsed from config/YAML input.	required

Returns:

Type	Description
bool	The coerced boolean value.

get_earth_shape(universe=None)

Build the configured Orekit OneAxisEllipsoid Earth model.

The ellipsoid uses the ITRF frame resolved from the same universe configuration. The shape can be one of the predefined model names (for example WGS84 or GRS80) or a custom mapping with:

• equatorial_radius (meters)
• flattening (dimensionless)

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping. If omitted, the active global universe configuration is used.	None

Returns:

Type	Description
Any	An Orekit OneAxisEllipsoid configured from the resolved Earth shape
Any	and ITRF frame.

Raises:

Type	Description
ModuleNotFoundError	If Orekit is not installed in the active Python environment.

get_iers_conventions(universe=None)

Resolve the configured Orekit IERSConventions enum value.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping. If omitted, the active global universe configuration is used.	None

Returns:

Type	Description
Any	The Orekit IERSConventions enum member selected by the configuration.

Raises:

Type	Description
ModuleNotFoundError	If Orekit is not installed in the active Python environment.
RuntimeError	If the JVM/Orekit bridge is not initialized and the local Orekit installation requires explicit initialization before import.

get_itrf_frame(universe=None)

Build the configured Orekit ITRF terrestrial reference frame.

The frame is resolved from:

• ITRF version (for example ITRF_2020)
• IERS conventions (for example IERS_2010)
• use_simple_eop Earth-orientation-parameter handling flag

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping. If omitted, the active global universe configuration is used.	None

Returns:

Type	Description
Any	The Orekit frame instance returned by FramesFactory.getITRF(...).

Raises:

Type	Description
ModuleNotFoundError	If Orekit is not installed in the active Python environment.

get_itrf_version(universe=None)

Resolve the configured Orekit ITRFVersion enum value.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping. If omitted, the active global universe configuration is used.	None

Returns:

Type	Description
Any	The Orekit ITRFVersion enum member selected by the configuration.

Raises:

Type	Description
ModuleNotFoundError	If Orekit is not installed in the active Python environment.

get_mu(universe=None)

Resolve the configured Earth gravitational parameter mu.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional universe configuration mapping. If omitted, the active global universe configuration is used.	None

Returns:

Type	Description
float	Earth's gravitational parameter in m^3 / s^2.

Raises:

Type	Description
ModuleNotFoundError	If Orekit is not installed in the active Python environment and a predefined MU constant must be resolved.

get_universe_config()

Return the active universe configuration, loading defaults on demand.

If no configuration has been explicitly loaded yet, this function first uses the built-in defaults and then, when present, loads the repository default YAML file.

Returns:

Type	Description
dict[str, Any]	A copy of the active normalized universe configuration.

load_default_universe_config()

Load and cache the repository default universe configuration.

Returns:

Type	Description
dict[str, Any]	A normalized copy of the default universe configuration.

load_universe_config(path)

Load, validate, and cache a universe configuration from YAML.

The YAML payload may either contain universe keys at the root level or under a top-level universe mapping. Values are normalized and validated using :func:load_universe_from_dict.

This function updates the module-global active configuration cache used by :func:get_universe_config.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to a YAML file containing universe settings.	required

Returns:

Type	Description
dict[str, Any]	A normalized copy of the loaded universe configuration.

Raises:

Type	Description
FileNotFoundError	If path does not exist.
TypeError	If the YAML payload or universe section is not a mapping.
ValueError	If a configured option is unsupported or invalid.
KeyError	If a custom Earth shape mapping is missing required keys.
YAMLError	If the YAML file cannot be parsed.

load_universe_from_dict(data)

Validate and normalize a parsed universe configuration mapping.

The input may be either:

• a mapping containing universe keys directly, or
• a mapping with a top-level universe section

The returned configuration is normalized to canonical strings/booleans and validated against the supported IERS/ITRF/Earth-shape/MU options.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Parsed configuration mapping.	required

Returns:

Type	Description
dict[str, Any]	A normalized universe configuration mapping. The input mapping is not
dict[str, Any]	modified.

Raises:

Type	Description
TypeError	If data or the nested universe section is not a mapping, or if configured values have the wrong type.
ValueError	If a configured option is unsupported or malformed.
KeyError	If a custom earth_shape_model mapping is missing required keys.

resolve_universe_config(universe=None)

Resolve explicit or globally configured universe settings.

Parameters:

Name	Type	Description	Default
universe	Mapping[str, Any] | None	Optional explicit universe mapping. If provided, it is validated and normalized. If omitted, the current active config is returned (loading defaults if necessary).	None

Returns:

Type	Description
dict[str, Any]	A normalized universe configuration mapping.

Raises:

Type	Description
TypeError	If universe is provided but is not a valid mapping.
ValueError	If universe contains unsupported values.
KeyError	If a custom Earth shape mapping is missing required keys.