Events & Visibility

Represents a detected event (zero-crossing of a function).

Events are detected when a monitored function crosses zero. The crossing direction indicates "up" (negative to positive) or "down" (positive to negative).

Methods:

• crossing –

  Return the crossing direction ("up" or "down").

• time –

  Return the time of this event.

crossing() -> str

time() -> Time

Represents a time interval between two times.

Intervals represent periods when certain conditions are met, such as visibility intervals between a ground station and spacecraft.

Methods:

• contains –

  Return whether this interval fully contains another interval.

• contains_time –

  Return whether this interval contains the given time.

• duration –

  Return the duration of this interval.

• end –

  Return the end time of this interval.

• intersect –

  Return the intersection of this interval with another.

• is_empty –

  Return whether this interval is empty (start >= end).

• linspace –

  Return a list of n evenly-spaced times within this interval.

• overlaps –

  Return whether this interval overlaps with another.

• start –

  Return the start time of this interval.

• step_by –

  Return a list of times spaced by the given step within this interval.

contains(other: Interval) -> bool

contains_time(time: Time) -> bool

duration() -> TimeDelta

end() -> Time

intersect(other: Interval) -> Interval

is_empty() -> bool

linspace(n: int) -> list[Time]

overlaps(other: Interval) -> bool

start() -> Time

step_by(step: TimeDelta) -> list[Time]

A named ground station for visibility analysis.

Wraps a ground location with an identifier, an optional operational minimum-elevation floor, and an optional measured horizon mask. Visibility tests elevation against the maximum of both.

Parameters:

• id

  –

  Unique identifier for this ground station.

• location

  –

  Ground station location.

• min_elevation

  –

  Optional minimum-elevation floor (unconstrained when omitted).

• horizon_mask

  –

  Optional measured horizon profile (flat 0° horizon when omitted).

• tx_terminals

  –

  Optional dict of named transmit terminals (TxChain or EirpModel).

• rx_terminals

  –

  Optional dict of named receive terminals (RxChain or GtModel).

Examples:

>>> gs = lox.GroundStation("ESOC", ground_location, min_elevation=5 * lox.deg)

Methods:

• horizon_mask –

  Return the horizon mask, if set.

• id –

  Return the asset identifier.

• location –

  Return the ground location.

• min_elevation –

  Return the minimum-elevation floor, if set.

• network_id –

  Return the network identifier, if assigned.

• rx_terminals –

  Return the named receive terminals as a dict.

• threshold_at –

  Return the effective elevation threshold at the given azimuth.

• tx_terminals –

  Return the named transmit terminals as a dict.

horizon_mask() -> HorizonMask | None

id() -> str

location() -> EllipsoidLocation

min_elevation() -> Angle | None

network_id() -> str | None

rx_terminals() -> dict[str, RxTerminal]

threshold_at(azimuth: Angle) -> Angle

tx_terminals() -> dict[str, TxTerminal]

A named spacecraft for visibility analysis.

Wraps an orbit source (propagator or pre-computed trajectory) with an identifier.

Parameters:

• id

  –

  Unique identifier for this spacecraft.

• orbit

  –

  Orbit source — an SGP4, Vallado, J2, J4, Numerical propagator, or a pre-computed Trajectory.

• max_slew_rate

  –

  Optional maximum slew rate.

• tx_terminals

  –

  Optional dict of named transmit terminals (TxChain or EirpModel).

• rx_terminals

  –

  Optional dict of named receive terminals (RxChain or GtModel).

Examples:

>>> sc = lox.Spacecraft("ISS", lox.SGP4(tle))
>>> sc = lox.Spacecraft("SAT", trajectory)

Methods:

• constellation_id –

  Return the constellation identifier, if assigned.

• id –

  Return the asset identifier.

• max_slew_rate –

  Return the maximum slew rate, if set.

• optical_payload –

  Return the optical payload, if set.

• rx_terminals –

  Return the named receive terminals as a dict.

• sar_payload –

  Return the SAR payload, if set.

• tx_terminals –

  Return the named transmit terminals as a dict.

constellation_id() -> str | None

id() -> str

max_slew_rate() -> AngularRate | None

optical_payload() -> OpticalPayload | None

rx_terminals() -> dict[str, RxTerminal]

sar_payload() -> SarPayload | None

tx_terminals() -> dict[str, TxTerminal]

A scenario grouping spacecraft, ground stations, and a time interval.

Parameters:

• start

  –

  Start time of the scenario.

• end

  –

  End time of the scenario.

• spacecraft

  –

  List of Spacecraft objects.

• ground_stations

  –

  List of GroundStation objects.

Examples:

>>> scenario = lox.Scenario(t0, t1, spacecraft=[sc], ground_stations=[gs])

Methods:

• end –

  Return the end time.

• propagate –

  Propagate all spacecraft, returning an Ensemble.

• start –

  Return the start time.

• with_constellation –

  Add a constellation to the scenario.

end() -> Time

propagate() -> Ensemble

start() -> Time

with_constellation(constellation: Constellation) -> Scenario

A collection of propagated trajectories keyed by spacecraft id.

Examples:

>>> ensemble = scenario.propagate()
>>> traj = ensemble.get("ISS")

Methods:

• get –

  Return the trajectory for a given spacecraft id.

get(id: str) -> Trajectory | None

Computes ground-station-to-spacecraft and inter-satellite visibility.

Ground-to-space pairs are always computed when ground assets are present. Inter-satellite pairs are additionally computed when inter_satellite is set to True.

Parameters:

• scenario

  –

  Scenario containing spacecraft, ground stations, and time interval.

• ensemble

  –

  Optional pre-computed Ensemble. If not provided, the scenario is propagated automatically.

• occulting_bodies

  –

  Optional list of additional occulting bodies for line-of-sight checking. For inter-satellite visibility, the scenario's central body is always checked automatically.

• step

  –

  Optional time step for event detection (default: 60s).

• min_pass_duration

  –

  Optional minimum pass duration. Passes shorter than this value may be missed. Enables two-level stepping for faster detection.

• inter_satellite

  –

  If True, also compute inter-satellite visibility for all unique spacecraft pairs (default: False).

• ground_space_filter

  –

  Optional callable (GroundStation, Spacecraft) -> bool that receives a ground station and a spacecraft and returns whether the pair should be evaluated. Called once per candidate pair before the parallel phase.

• inter_satellite_filter

  –

  Optional callable (Spacecraft, Spacecraft) -> bool that receives two spacecraft and returns whether the pair should be evaluated. Called once per candidate pair before the parallel phase. When provided, inter-satellite visibility is automatically enabled.

• min_range

  –

  Optional minimum range constraint for inter-satellite pairs.

• max_range

  –

  Optional maximum range constraint for inter-satellite pairs.

Examples:

>>> scenario = lox.Scenario(t0, t1, spacecraft=[sc], ground_stations=[gs])
>>> analysis = lox.VisibilityAnalysis(scenario, step=lox.TimeDelta(60))
>>> results = analysis.compute(spk)

Methods:

• compute –

  Compute visibility intervals for all pairs.

compute(ephemeris: SPK) -> VisibilityResults

Results of a visibility analysis.

Provides access to visibility intervals and passes. Intervals (time windows) are computed eagerly; observables-rich Pass objects are computed on demand.

Methods:

• all_intervals –

  Return all intervals for all pairs.

• all_passes –

  Compute passes for all ground-to-space pairs.

• ground_space_intervals –

  Return intervals for ground-to-space pairs only.

• ground_space_pair_ids –

  Return pair identifiers for ground-to-space pairs only.

• inter_satellite_intervals –

  Return intervals for inter-satellite pairs only.

• inter_satellite_pair_ids –

  Return pair identifiers for inter-satellite pairs only.

• intervals –

  Return visibility intervals for a specific pair.

• num_pairs –

  Return the total number of pairs.

• pair_ids –

  Return all pair identifiers.

• passes –

  Compute passes with observables for a specific ground-to-space pair.

• total_intervals –

  Return the total number of visibility intervals across all pairs.

all_intervals() -> dict[tuple[str, str], list[Interval]]

all_passes() -> dict[tuple[str, str], list[Pass]]

ground_space_intervals() -> dict[tuple[str, str], list[Interval]]

ground_space_pair_ids() -> list[tuple[str, str]]

inter_satellite_intervals() -> dict[tuple[str, str], list[Interval]]

inter_satellite_pair_ids() -> list[tuple[str, str]]

intervals(id1: str, id2: str) -> list[Interval]

num_pairs() -> int

pair_ids() -> list[tuple[str, str]]

passes(ground_id: str, space_id: str) -> list[Pass]

total_intervals() -> int

Power budget analysis for spacecraft in a scenario.

Computes eclipse intervals, sun beta angle, and solar flux for each spacecraft. The shadow model is cylindrical (umbra only) — penumbra is not modelled.

Parameters:

• scenario

  –

  Scenario containing spacecraft and time interval.

• ensemble

  –

  Optional pre-computed Ensemble.

• step

  –

  Optional time step for sampling / event detection (default: 60s).

• spacecraft_ids

  –

  Optional list of spacecraft ids to restrict the analysis.

Examples:

>>> analysis = lox.PowerBudgetAnalysis(scenario)
>>> results = analysis.compute()          # analytical Sun
>>> results = analysis.compute(ephemeris)  # SPK Sun

Methods:

• compute –

  Compute the power budget analysis.

compute(ephemeris: SPK | None = None) -> PowerBudgetResults

Results of a power budget analysis.

Provides access to eclipse intervals, eclipse/sunlit fractions, beta-angle time series, and solar-flux time series for each spacecraft.

Methods:

• beta_angles –

  Return beta-angle time series (radians).

• eclipse_fraction –

  Return eclipse fraction (0 = fully sunlit, 1 = always eclipsed).

• eclipse_intervals –

  Return eclipse intervals for a specific spacecraft.

• solar_flux –

  Return solar-flux time series (W/m²).

• sunlit_fraction –

  Return sunlit fraction (1 - eclipse_fraction).

beta_angles(id: str) -> TimeSeries | None

eclipse_fraction(id: str) -> float | None

eclipse_intervals(id: str) -> list[Interval]

solar_flux(id: str) -> TimeSeries | None

sunlit_fraction(id: str) -> float | None