satnogs-predict 0.2__py3-none-any.whl

satnogs_predict/domain/window.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from satnogs_predict.domain.constraints import ConstraintAppliedResult
+
+from .geometry import GeometrySample
+from .time import TimeRange
+from .validation import ensure_required_fields_not_none
+
+
+class RangeToPassError(Exception):
+    pass
+
+
+@dataclass(slots=True)
+class ObservationWindow:
+    """
+    A schedulable observation window.
+    """
+
+    sat_identifier: str
+    observer_identifier: str
+
+    start_sample: GeometrySample
+    end_sample: GeometrySample
+    max_altitude_sample: GeometrySample
+
+    # The altitude does has multiple peaks during the window (None means unknown)
+    has_multiple_peaks: bool | None = None
+
+    constraint_applied_result: ConstraintAppliedResult | None = None
+    rejection_reason: str | None = None
+
+    overlapped: bool = False
+    overlap_ratio: float = 0.0
+
+    @property
+    def time_range(self):
+        return TimeRange(start=self.start_sample.instant, end=self.end_sample.instant)
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+
+        if int(self.start_sample.instant) >= int(self.end_sample.instant):
+            raise ValueError("ObservationWindow must be non-empty")
+
+    def __str__(self):
+        t_start = self.start_sample.instant
+        t_end = self.end_sample.instant
+        rise_azimuth = self.start_sample.azimuth_deg
+        max_altitude = self.max_altitude_sample.altitude_deg if self.max_altitude_sample else None
+        max_alt_str = f"{max_altitude:.1f}°" if max_altitude is not None else "Unknown"
+        set_azimuth = self.end_sample.azimuth_deg
+
+        representation = (
+            f"Window {{{t_start} -> {t_end}}} ({self.time_range.duration}) - "
+            f"{{Rise az: {rise_azimuth:.1f}°, Max alt: {max_alt_str}°, Set az: {set_azimuth:.1f}°}}"
+        )
+
+        if self.constraint_applied_result == ConstraintAppliedResult.REJECTED:
+            representation += f" | Rejected: {self.rejection_reason}"
+
+        return representation
+
+    def __repr__(self):
+        return str(self)

satnogs_predict/planning/planner.py

@@ -0,0 +1,211 @@
+from typing import Sequence
+
+from satnogs_predict.domain.observer import Observer
+from satnogs_predict.domain.orbit import Satellite
+from satnogs_predict.domain.planner import OverlapHandling, PlanningConfig
+from satnogs_predict.domain.time import Duration, Instant, TimeRange
+from satnogs_predict.domain.window import ObservationWindow
+from satnogs_predict.propagation.propagator import obs_window_from_range
+
+
+def plan_observation_windows(
+    satellite: Satellite,
+    observer: Observer,
+    thepass: ObservationWindow,
+    config: PlanningConfig,
+    ordered_scheduled: list[TimeRange],
+) -> list[ObservationWindow]:
+    """
+    Handles pass overlapping with scheduled ranges,
+    as well as splitting long windows
+    """
+    overlap_idx = _idx_of_overlap(thepass, ordered_scheduled, config)
+
+    if overlap_idx is None:
+        obs_ranges = [thepass.time_range]
+    else:
+        thepass.overlapped = True
+        thepass.overlap_ratio = _overlap_ratio(thepass, ordered_scheduled)
+        match config.overlap_handling:
+            case OverlapHandling.DROP:
+                return []
+
+            case OverlapHandling.FULL:
+                obs_ranges = [thepass.time_range]
+
+            case OverlapHandling.TRUNCATE:
+                obs_ranges = _resolve_overlaps(
+                    thepass.time_range, ordered_scheduled[overlap_idx:], config
+                )
+
+            case _:
+                raise ValueError("Unhandled overlap handling mode")
+
+    if config.split_long_windows:
+        split_ranges: list[TimeRange] = []
+        for rg in obs_ranges:
+            split_ranges.extend(_split_long_range(rg, config))
+        obs_ranges = split_ranges
+
+    obs_windows = [
+        obs_window_from_range(satellite, observer, therange, thepass) for therange in obs_ranges
+    ]
+    return obs_windows
+
+
+def has_range_list_overlap(
+    ordered_ranges: Sequence[TimeRange], padding: Duration = Duration(0)
+) -> bool:
+    """
+    Return `True` if any adjacent ranges overlap after applying symmetric padding.
+
+    `ordered_ranges` is assumed to be sorted by `start` in ascending order.
+    Two touching ranges are treated as overlapping (`next_start <= current_end`).
+    """
+    for idx in range(len(ordered_ranges) - 1):
+        current = ordered_ranges[idx]
+        next_range = ordered_ranges[idx + 1]
+
+        current_end = current.end + padding
+        next_start = next_range.start - padding
+
+        if next_start <= current_end:
+            return True
+
+    return False
+
+
+def _idx_of_overlap(
+    thepass: ObservationWindow, ordered_scheduled: Sequence[TimeRange], config: PlanningConfig
+) -> int | None:
+    """
+    Returns the index of the first range in ordered_scheduled that overlaps
+    with the time range of thepass, after applying padding.
+
+    ordered_scheduled must be a sequence ordered by time_range.start
+
+    returns the index if there is an overlap, None otherwise.
+    """
+
+    if config.overlap_padding is None:
+        disallowed_ranges = ordered_scheduled
+    else:
+        disallowed_ranges = [
+            obs.pad_duration(left=config.overlap_padding, right=config.overlap_padding)
+            for obs in ordered_scheduled
+        ]
+
+    for idx, obs in enumerate(disallowed_ranges):
+        if thepass.time_range.intersects(obs):
+            return idx
+    return None
+
+
+def _overlap_ratio(thepass: ObservationWindow, ordered_scheduled: Sequence[TimeRange]) -> float:
+    """
+    Returns the percentage (in decimal e.g. 0.1 = 10%) that unpadded scheduled ranges overlap with the pass.
+    """
+
+    return sum(
+        thepass.time_range.overlap_ratio(scheduled_range) for scheduled_range in ordered_scheduled
+    )
+
+
+def _split_long_range(window: TimeRange, config: PlanningConfig) -> list[TimeRange]:
+    """
+    Split a long TimeRange into multiple windows of `config.max_window_duration`,
+    separated by `config.break_duration`.
+
+    If the remainder is < `config.remainder_cutoff_duration`, it is dropped.
+    """
+
+    windows: list[TimeRange] = []
+
+    if config.max_window_duration is None:
+        raise ValueError("PlanningConfig missing max_window_duration value")
+
+    if config.break_duration is None:
+        raise ValueError("PlanningConfig missing break_duration value")
+
+    if config.remainder_cutoff_duration is None:
+        raise ValueError("PlanningConfig missing remainder_cutoff_duration value")
+
+    cycle = config.max_window_duration + config.break_duration
+    total_duration = window.duration
+
+    split_count = (total_duration.micros // cycle.micros) + 1
+    remainder = Duration(total_duration.micros % cycle.micros)
+
+    if remainder < config.remainder_cutoff_duration:
+        split_count -= 1
+
+    for i in range(split_count):
+        start_offset = cycle * i
+        window_start = Instant(int(window.start) + start_offset.micros)
+
+        # If the last split will have window.end as end value
+        window_end = min(window.end, Instant(int(window_start) + config.max_window_duration.micros))
+
+        windows.append(TimeRange(window_start, window_end))
+
+    return windows
+
+
+def _resolve_overlaps(
+    candidate: TimeRange, sorted_scheduled: Sequence[TimeRange], config: PlanningConfig
+) -> list[TimeRange]:
+    """
+    Return parts of the candiate that don't overlap with the `sorted_scheduled` ranges,
+    after padding has been aplied to each of them.
+    """
+
+    if config.overlap_padding is None:
+        raise ValueError("PlanningConfig missing overlap_padding value")
+
+    disallowed_ranges = [
+        obs.pad_duration(left=config.overlap_padding, right=config.overlap_padding)
+        for obs in sorted_scheduled
+    ]
+    window_ranges = [candidate]
+
+    for obs in disallowed_ranges:
+        new_windows: list[TimeRange] = []
+        for w in window_ranges:
+            new_windows.extend(w.subtract(obs))
+        window_ranges = new_windows
+
+    return window_ranges
+
+
+def check_observation_density_limit_respected(
+    ordered_observation_starts: Sequence[Instant],
+    obs_density_limit: int,
+    evaluation_duration: Duration,
+) -> bool:
+    """
+    Check that any `evaluation_duration` window doesn't contain more than
+    `obs_density_limit` observation starts.
+
+    This enforces a specific density of observations.
+
+    `ordered_observation_starts` is assumed to be sorted ascending.
+    Starts exactly at `inst + evaluation_duration` are included in the same
+    evaluation window.
+    """
+
+    if len(ordered_observation_starts) <= obs_density_limit:
+        return True
+
+    for idx, inst in enumerate(ordered_observation_starts):
+        eval_window_end = inst + evaluation_duration
+        number_of_obs_in_eval_window = 0
+        for start_instant in ordered_observation_starts[idx:]:
+            if start_instant > eval_window_end:
+                break
+            number_of_obs_in_eval_window += 1
+            if number_of_obs_in_eval_window > obs_density_limit:
+                return False
+        if eval_window_end > ordered_observation_starts[-1]:
+            break
+
+    return True

satnogs_predict/propagation/propagator.py

@@ -0,0 +1,375 @@
+from dataclasses import dataclass
+
+from skyfield.api import Angle, EarthSatellite, Time, Topos, load  # type: ignore[import-untyped]
+from skyfield.searchlib import find_maxima  # type: ignore[import-untyped]
+
+from satnogs_predict.domain.geometry import GeometrySample
+from satnogs_predict.domain.observer import Observer
+from satnogs_predict.domain.orbit import TLE, OrbitRepresentation, Satellite
+from satnogs_predict.domain.time import (
+    Instant,
+    TimeRange,
+)
+from satnogs_predict.domain.window import ObservationWindow
+
+ts = load.timescale()
+
+
+@dataclass(frozen=True, slots=True)
+class SkyfieldSample:
+    t: Time
+    alt: Angle
+    az: Angle
+
+
+@dataclass(frozen=True, slots=True)
+class SkyfieldPass:
+    start_sample: SkyfieldSample
+    peak_sample: SkyfieldSample
+    end_sample: SkyfieldSample
+    has_multiple_peaks: bool
+
+
+def _get_sample_at_time(sat: EarthSatellite, observer: Topos, t: Time) -> SkyfieldSample:
+    alt, az, _ = (sat - observer).at(t).altaz()
+    return SkyfieldSample(t=t, alt=alt, az=az)
+
+
+def _skyfield_time_from_instant(instant: Instant) -> Time:
+    return ts.from_datetime(instant.to_datetime())
+
+
+def _skyfield_times_from_range(time_range: TimeRange) -> tuple[Time, Time]:
+    return (
+        _skyfield_time_from_instant(time_range.start),
+        _skyfield_time_from_instant(time_range.end),
+    )
+
+
+def _instant_from_skyfield_time(t: Time):
+    return Instant.from_datetime(t.utc_datetime())
+
+
+_last_sat: EarthSatellite | None = None
+_last_sat_identifier: str | None = None
+
+
+def _skyfield_sat_from_satellite(satellite: Satellite) -> EarthSatellite:
+    global _last_sat, _last_sat_identifier
+
+    if _last_sat_identifier == satellite.identifier and _last_sat is not None:
+        return _last_sat
+
+    match satellite.orbit.representation:
+        case OrbitRepresentation.TLE:
+            tle: TLE = satellite.orbit.data
+            skyfield_sat = EarthSatellite(
+                tle.line1,
+                tle.line2,
+                satellite.identifier,
+                ts,
+            )
+        case _:
+            raise ValueError("Unknown orbit representation")
+
+    _last_sat_identifier = satellite.identifier
+    _last_sat = skyfield_sat
+    return skyfield_sat
+
+
+_last_topos: Topos | None = None
+_last_identifier: str | None = None
+
+
+def _skyfield_topos_from_observer(observer: Observer) -> Topos:
+    global _last_topos, _last_identifier
+
+    if _last_identifier == observer.identifier and _last_topos is not None:
+        return _last_topos
+
+    _last_topos = Topos(
+        latitude_degrees=observer.lat_deg,
+        longitude_degrees=observer.lon_deg,
+        elevation_m=observer.elevation_meters,
+    )
+    _last_identifier = observer.identifier
+    return _last_topos
+
+
+def _get_sample_from_skyfield_sample(skyfield_sample: SkyfieldSample) -> GeometrySample:
+    instant = _instant_from_skyfield_time(skyfield_sample.t)
+    azimuth_deg = float(skyfield_sample.az.degrees)
+    altitude_deg = float(skyfield_sample.alt.degrees)
+    return GeometrySample(instant=instant, azimuth_deg=azimuth_deg, altitude_deg=altitude_deg)
+
+
+def _skyfield_pass_to_obs_window(
+    thepass: SkyfieldPass, sat_identifier: str, obs_identifier: str
+) -> ObservationWindow:
+    start_sample = _get_sample_from_skyfield_sample(thepass.start_sample)
+    max_altitude_sample = _get_sample_from_skyfield_sample(thepass.peak_sample)
+    end_sample = _get_sample_from_skyfield_sample(thepass.end_sample)
+    return ObservationWindow(
+        start_sample=start_sample,
+        max_altitude_sample=max_altitude_sample,
+        end_sample=end_sample,
+        sat_identifier=sat_identifier,
+        observer_identifier=obs_identifier,
+        has_multiple_peaks=thepass.has_multiple_peaks,
+    )
+
+
+def _find_visibility_intervals(
+    satellite: EarthSatellite,
+    station: Topos,
+    t_start: Time,
+    t_end: Time,
+    horizon_deg: float,
+) -> list[SkyfieldPass]:
+    """
+    Find exact visibility intervals where the satellite is above
+    a constant horizon.
+
+    Handles:
+    - passes already above the horizon at t_start
+    - geosynchronous / geostatic satellites
+
+    Returns: list of (t_start, t_peak, peak_altevation_deg, t_end)
+    """
+
+    start_sample = _get_sample_at_time(satellite, station, t_start)
+    visible_at_start = start_sample.alt.degrees > horizon_deg  # Satellite is overhead
+
+    times, events = satellite.find_events(
+        station,
+        t_start,
+        t_end,
+        altitude_degrees=horizon_deg,
+    )
+
+    passes: list[SkyfieldPass] = []
+
+    # If the sat is currently overhead, start the pass at t_start
+    current_start_sample: SkyfieldSample | None = start_sample if visible_at_start else None
+    current_peak_sample: SkyfieldSample | None = None
+
+    has_multiple_peaks = False
+    last_event: int | None = 0 if visible_at_start else None
+
+    for t, event in zip(times, events):
+        if event == 0:
+            # Rise
+            current_start_sample = _get_sample_at_time(satellite, station, t)
+            current_peak_sample = None
+            last_event = 0
+        elif event == 1:
+            # Culmination
+
+            if not current_start_sample:
+                # This case can happen if the satellite culminates while under the horizon
+                continue
+
+            # In some cases (old TLE or non-leo orbit) there can be multiple culmination events in a row.
+            # The satellite descends after one culmination, but not below horizon. Then rises again.
+            # In these cases, we keep the overall highest altitude.
+            candidate_peak_sample = _get_sample_at_time(satellite, station, t)
+            if (
+                last_event != 1
+                or not current_peak_sample
+                or candidate_peak_sample.alt.degrees > current_peak_sample.alt.degrees
+            ):
+                current_peak_sample = candidate_peak_sample
+            if last_event == 1:
+                has_multiple_peaks = True
+            last_event = 1
+        elif event == 2:
+            # Set
+            assert current_start_sample is not None, "Set event without active pass"
+
+            if not current_peak_sample:
+                # If there is no peak, the altitude function is monotonic in the time range
+                # If we have set event without culmination -> start is after culmination
+                # Therefore the pass has max altitude at start
+                current_peak_sample = current_start_sample
+            passes.append(
+                SkyfieldPass(
+                    start_sample=current_start_sample,
+                    peak_sample=current_peak_sample,
+                    end_sample=_get_sample_at_time(satellite, station, t),
+                    has_multiple_peaks=has_multiple_peaks,
+                )
+            )
+            current_start_sample = None
+            current_peak_sample = None
+            last_event = 2
+            has_multiple_peaks = False
+
+    # If we have an open-ended pass at t_end, make the pass end then
+    if current_start_sample is not None:
+        current_end_sample = _get_sample_at_time(satellite, station, t_end)
+        if not current_peak_sample:
+            # If there is no peak, the altitude function is monotonic in the time range.
+            # Either start is after culmination or end is before culmination because no culmination event
+            if current_start_sample.alt.degrees > current_end_sample.alt.degrees:
+                # start is after culmination because alt is decreasing
+                current_peak_sample = current_start_sample
+            else:
+                # end is before culmination because alt is increasing
+                current_peak_sample = current_end_sample
+
+        passes.append(
+            SkyfieldPass(
+                start_sample=current_start_sample,
+                peak_sample=current_peak_sample,
+                end_sample=current_end_sample,
+                has_multiple_peaks=has_multiple_peaks,
+            )
+        )
+
+    return passes
+
+
+def find_passes(
+    satellite: Satellite, observer: Observer, time_range: TimeRange
+) -> list[ObservationWindow]:
+    """
+    Finds a list of AOS -> LOS for a satellite over an observer.
+    """
+    skyfield_sat = _skyfield_sat_from_satellite(satellite)
+    skyfield_observer = _skyfield_topos_from_observer(observer)
+    t_start, t_end = _skyfield_times_from_range(time_range)
+
+    passes = [
+        _skyfield_pass_to_obs_window(skyfield_pass, satellite.identifier, observer.identifier)
+        for skyfield_pass in _find_visibility_intervals(
+            skyfield_sat, skyfield_observer, t_start, t_end, observer.horizon_deg
+        )
+    ]
+
+    return passes
+
+
+def obs_window_from_range(
+    satellite: Satellite,
+    observer: Observer,
+    time_range: TimeRange,
+    origin_pass: ObservationWindow | None,
+) -> ObservationWindow:
+    """
+    Calculates the start and end sample for a time range, converting it into an ObservationWindow.
+    Does not compute the max_altitude_sample.
+    """
+    t_start, t_end = _skyfield_times_from_range(time_range)
+    skyfield_satellite = _skyfield_sat_from_satellite(satellite)
+    skyfield_observer = _skyfield_topos_from_observer(observer)
+
+    skyfield_start_sample = _get_sample_at_time(skyfield_satellite, skyfield_observer, t_start)
+    start_sample = _get_sample_from_skyfield_sample(skyfield_start_sample)
+
+    skyfield_end_sample = _get_sample_at_time(skyfield_satellite, skyfield_observer, t_end)
+    end_sample = _get_sample_from_skyfield_sample(skyfield_end_sample)
+
+    if origin_pass and not origin_pass.has_multiple_peaks:
+        t_closest_approach = origin_pass.max_altitude_sample.instant
+        if t_closest_approach > time_range.end:
+            max_altitude_sample = end_sample
+        elif t_closest_approach < time_range.start:
+            max_altitude_sample = start_sample
+        else:
+            max_altitude_sample = origin_pass.max_altitude_sample
+        has_multiple_peaks = False
+
+    else:
+        max_altitude__skyfield_sample = _calculate_max_alt_skyfield_sample(
+            skyfield_start_sample, skyfield_end_sample, skyfield_satellite, skyfield_observer
+        )
+        max_altitude_sample = _get_sample_from_skyfield_sample(max_altitude__skyfield_sample)
+        has_multiple_peaks = None  # Unknown
+
+    return ObservationWindow(
+        start_sample=start_sample,
+        end_sample=end_sample,
+        max_altitude_sample=max_altitude_sample,
+        sat_identifier=satellite.identifier,
+        observer_identifier=observer.identifier,
+        has_multiple_peaks=has_multiple_peaks,
+    )
+
+
+def _calculate_max_alt_skyfield_sample(
+    start_sample: SkyfieldSample,
+    end_sample: SkyfieldSample,
+    skyfield_sat: EarthSatellite,
+    topos: Topos,
+    step_seconds: float = 5.0,
+) -> SkyfieldSample:
+    if end_sample.t.tt <= start_sample.t.tt:
+        raise ValueError("Invalid window: end <= start")
+
+    def altitude_degrees(t: Time):  # pragma: no cover
+        alt, _, _ = (skyfield_sat - topos).at(t).altaz()
+        return alt.degrees
+
+    # Control coarse search resolution
+    altitude_degrees.step_days = step_seconds / 86400.0  # type: ignore[attr-defined]
+
+    t_peaks, peak_values = find_maxima(start_sample.t, end_sample.t, altitude_degrees)
+
+    # Include endpoints
+    alt_start = start_sample.alt.degrees
+    alt_end = end_sample.alt.degrees
+
+    max_alt = alt_start
+    max_time = start_sample.t
+
+    if alt_end > max_alt:
+        max_alt = alt_end
+        max_time = end_sample.t
+
+    # Compare interior maxima
+    for t_peak, alt_peak in zip(t_peaks, peak_values):
+        if alt_peak > max_alt:
+            max_alt = alt_peak
+            max_time = t_peak
+
+    return _get_sample_at_time(skyfield_sat, topos, max_time)
+
+
+def _calculate_min_alt_skyfield_sample(
+    start_sample: SkyfieldSample,
+    end_sample: SkyfieldSample,
+    skyfield_sat: EarthSatellite,
+    topos: Topos,
+    step_seconds: float = 5.0,
+) -> SkyfieldSample:
+    if end_sample.t.tt <= start_sample.t.tt:
+        raise ValueError("Invalid window: end <= start")
+
+    def neg_altitude_degrees(t: Time) -> float:  # pragma: no cover
+        alt, _, _ = (skyfield_sat - topos).at(t).altaz()
+        return -float(alt.degrees)
+
+    # Control coarse search resolution
+    neg_altitude_degrees.step_days = step_seconds / 86400.0  # type: ignore[attr-defined]
+
+    t_mins, neg_values = find_maxima(start_sample.t, end_sample.t, neg_altitude_degrees)
+
+    # Include endpoints
+    alt_start = float(start_sample.alt.degrees)
+    alt_end = float(end_sample.alt.degrees)
+
+    min_alt = alt_start
+    min_time = start_sample.t
+
+    if alt_end < min_alt:
+        min_alt = alt_end
+        min_time = end_sample.t
+
+    # Compare interior minima: neg_values are maxima of (-alt) => minima of alt
+    for t_min, neg_val in zip(t_mins, neg_values):
+        alt_val = -float(neg_val)
+        if alt_val < min_alt:
+            min_alt = alt_val
+            min_time = t_min
+
+    return _get_sample_at_time(skyfield_sat, topos, min_time)