satnogs-predict 0.2__py3-none-any.whl

satnogs_predict/__init__.py

@@ -0,0 +1,9 @@
+from . import constraints, domain
+from .constraints import *  # noqa: F401,F403
+from .core.engine import find_observation_windows, get_and_validate_pass_from_range
+from .domain import *  # noqa: F401,F403
+from .planning.planner import check_observation_density_limit_respected, has_range_list_overlap
+
+__all__ = list(domain.__all__) + list(constraints.__all__)
+__all__ += ["check_observation_density_limit_respected", "has_range_list_overlap"]
+__all__ += ["find_observation_windows", "get_and_validate_pass_from_range"]

satnogs_predict/constraints/__init__.py

@@ -0,0 +1,3 @@
+from .constraints import MaxDurationConstraint, MinCulminationConstraint, MinDurationConstraint
+
+__all__ = ["MinCulminationConstraint", "MinDurationConstraint", "MaxDurationConstraint"]

satnogs_predict/constraints/constraints.py

@@ -0,0 +1,111 @@
+from typing import Protocol
+
+from satnogs_predict.domain.constraints import ConstraintAppliedResult, ConstraintCheckFailedError
+from satnogs_predict.domain.time import Duration
+from satnogs_predict.domain.window import ObservationWindow
+
+
+class Constraint(Protocol):
+    """
+    Abstract Constraint parent class.
+    """
+
+    name: str
+
+    def apply(self, candidate: ObservationWindow) -> ObservationWindow:
+        """
+        Applies the constraint to a candidate observation window.
+        Returns the candidate with the constraint_applied_result field set.
+
+        The candidate may or may not be altered by the constraint.
+        """
+        ...  # pragma: no cover
+
+    def check(self, candidate: ObservationWindow):
+        """
+        Checks if the candidate respects the constraint.
+        Does not alter the candidate.
+        Raises a ConstraintCheckFailedError error if the check fails.
+        """
+        ...  # pragma: no cover
+
+    def _get_check_failed_message(self, reason: str):
+        return f"{self.name} - constraint check failed: {reason}"
+
+
+class MinCulminationConstraint(Constraint):
+    """
+    Ensures the observation window contains a minumum altitude for the pass.
+    """
+
+    name: str = "min-culmination"
+
+    def __init__(self, min_culmination_deg: float):
+        self.min_culmination_deg = min_culmination_deg
+
+    def check(self, candidate: ObservationWindow):
+        if candidate.max_altitude_sample.altitude_deg < self.min_culmination_deg:
+            raise ConstraintCheckFailedError(
+                self._get_check_failed_message("Max altitude less than min culmination")
+            )
+
+    def apply(self, candidate: ObservationWindow) -> ObservationWindow:
+        if candidate.max_altitude_sample.altitude_deg < self.min_culmination_deg:
+            candidate.constraint_applied_result = ConstraintAppliedResult.REJECTED
+            candidate.rejection_reason = "Max altitude less than min culmination"
+        else:
+            candidate.constraint_applied_result = ConstraintAppliedResult.UNCHANGED
+
+        return candidate
+
+
+class MinDurationConstraint(Constraint):
+    """
+    Ensures the observation window contains a minumum altitude for the pass.
+    """
+
+    name: str = "min-duration"
+
+    def __init__(self, min_duration: Duration):
+        self.min_duration = min_duration
+
+    def check(self, candidate: ObservationWindow):
+        if candidate.time_range.duration < self.min_duration:
+            raise ConstraintCheckFailedError(
+                self._get_check_failed_message("Duration less than min duration")
+            )
+
+    def apply(self, candidate: ObservationWindow) -> ObservationWindow:
+        if candidate.time_range.duration < self.min_duration:
+            candidate.rejection_reason = "Duration less than min duration"
+            candidate.constraint_applied_result = ConstraintAppliedResult.REJECTED
+        else:
+            candidate.constraint_applied_result = ConstraintAppliedResult.UNCHANGED
+
+        return candidate
+
+
+class MaxDurationConstraint(Constraint):
+    """
+    Ensures the observation window does not exceed a maximum duration.
+    """
+
+    name: str = "max-duration"
+
+    def __init__(self, max_duration: Duration):
+        self.max_duration = max_duration
+
+    def check(self, candidate: ObservationWindow):
+        if candidate.time_range.duration > self.max_duration:
+            raise ConstraintCheckFailedError(
+                self._get_check_failed_message("Duration more than max duration")
+            )
+
+    def apply(self, candidate: ObservationWindow) -> ObservationWindow:
+        if candidate.time_range.duration > self.max_duration:
+            candidate.rejection_reason = "Duration more than max duration"
+            candidate.constraint_applied_result = ConstraintAppliedResult.REJECTED
+        else:
+            candidate.constraint_applied_result = ConstraintAppliedResult.UNCHANGED
+
+        return candidate

satnogs_predict/core/engine.py

@@ -0,0 +1,105 @@
+from typing import Sequence
+
+from satnogs_predict.constraints.constraints import Constraint
+from satnogs_predict.domain.constraints import ConstraintAppliedResult
+from satnogs_predict.domain.observer import Observer
+from satnogs_predict.domain.orbit import Satellite
+from satnogs_predict.domain.planner import PlanningConfig
+from satnogs_predict.domain.time import TimeRange
+from satnogs_predict.domain.window import ObservationWindow, RangeToPassError
+from satnogs_predict.planning.planner import plan_observation_windows
+from satnogs_predict.propagation.propagator import find_passes
+
+
+def _validate_windows(
+    candidate_windows: Sequence[ObservationWindow], constraints: Sequence[Constraint]
+) -> tuple[list[ObservationWindow], list[ObservationWindow]]:
+    """
+    Applies the constraints and returns the valid and rejected windows.
+    Valid windows may or may not be modified.
+    """
+    valid: list[ObservationWindow] = []
+    rejected: list[ObservationWindow] = []
+    for window in candidate_windows:
+        constrained_pass = window
+        for constr in constraints:
+            constrained_pass = constr.apply(constrained_pass)
+            if constrained_pass.constraint_applied_result == ConstraintAppliedResult.REJECTED:
+                rejected.append(constrained_pass)
+                break
+        else:
+            valid.append(constrained_pass)
+
+    return valid, rejected
+
+
+def _ensure_window_respects_constraints(
+    window: ObservationWindow, constraints: Sequence[Constraint]
+) -> None:
+    """
+    Makes sure that the provided windows already respect the constraints
+    """
+
+    for constr in constraints:
+        constr.check(window)
+
+
+def find_observation_windows(
+    satellite: Satellite,
+    observer: Observer,
+    time_range: TimeRange,
+    planning_config: PlanningConfig,
+    pre_plan_constraints: Sequence[Constraint] = [],
+    post_plan_constraints: Sequence[Constraint] = [],
+    scheduled_intervals: Sequence[TimeRange] = [],
+) -> tuple[list[ObservationWindow], list[ObservationWindow]]:
+    # Find passes
+    candidate_passes = find_passes(satellite, observer, time_range)
+    # Validate passes (prunning)
+    valid_passes, rejected_passes = _validate_windows(candidate_passes, pre_plan_constraints)
+
+    valid_windows: list[ObservationWindow] = []
+    rejected_windows: list[ObservationWindow] = rejected_passes
+    for thepass in valid_passes:
+        # Find available windows given already scheduled time ranges of the observer
+        ordered_scheduled_intervals = list(scheduled_intervals)
+        ordered_scheduled_intervals.sort(key=lambda o: o.start)
+        candidate_windows = plan_observation_windows(
+            satellite, observer, thepass, planning_config, ordered_scheduled_intervals
+        )
+        # Validate those windows
+        current_valid_windows, current_rejected_windows = _validate_windows(
+            candidate_windows, post_plan_constraints
+        )
+        valid_windows.extend(current_valid_windows)
+        rejected_windows.extend(current_rejected_windows)
+
+    return valid_windows, rejected_windows
+
+
+def get_and_validate_pass_from_range(
+    satellite: Satellite,
+    observer: Observer,
+    time_range: TimeRange,
+    constraints: Sequence[Constraint] = [],
+) -> ObservationWindow:
+    """
+    Return the single pass corresponding to `time_range` after validating constraints.
+
+    The function first finds passes in `time_range` and requires exactly one result.
+    It then validates that pass with each constraint via `constraint.check`.
+
+    Raises:
+        RangeToPassError: if no pass or multiple passes are found in `time_range`.
+        ConstraintCheckFailedError: if any provided constraint check fails.
+    """
+
+    thepass = find_passes(satellite, observer, time_range)
+    if not len(thepass):
+        raise RangeToPassError("No pass found in the provided time range")
+    if len(thepass) > 1:
+        raise RangeToPassError("Multiple passes found in the provided time range")
+
+    _ensure_window_respects_constraints(thepass[0], constraints)
+
+    return thepass[0]

satnogs_predict/domain/__init__.py

@@ -0,0 +1,29 @@
+from .constraints import ConstraintAppliedResult, ConstraintCheckFailedError
+from .geometry import GeometrySample
+from .observer import Observer
+from .orbit import TLE, Orbit, OrbitRepresentation, Satellite
+from .planner import OverlapHandling, PlanningConfig
+from .time import (
+    Duration,
+    Instant,
+    TimeRange,
+)
+from .window import ObservationWindow, RangeToPassError
+
+__all__ = [
+    "ConstraintAppliedResult",
+    "ConstraintCheckFailedError",
+    "GeometrySample",
+    "Observer",
+    "TLE",
+    "OrbitRepresentation",
+    "Orbit",
+    "Satellite",
+    "Instant",
+    "Duration",
+    "TimeRange",
+    "ObservationWindow",
+    "RangeToPassError",
+    "PlanningConfig",
+    "OverlapHandling",
+]

satnogs_predict/domain/constraints.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ConstraintAppliedResult(IntEnum):
+    REJECTED = 0
+    UNCHANGED = 1
+    MODIFIED = 2
+
+
+class ConstraintCheckFailedError(Exception):
+    pass

satnogs_predict/domain/geometry.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .time import Instant
+from .validation import ensure_required_fields_not_none
+
+
+@dataclass(frozen=True, slots=True)
+class GeometrySample:
+    """Geometry at an instant, relative to an observer."""
+
+    instant: Instant
+    azimuth_deg: float
+    altitude_deg: float
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)

satnogs_predict/domain/observer.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .validation import ensure_required_fields_not_none
+
+
+@dataclass(frozen=True, slots=True)
+class Observer:
+    """Observer to calculate passes over e.g. a ground station"""
+
+    lat_deg: float
+    lon_deg: float
+    elevation_meters: int
+    horizon_deg: float
+    identifier: str
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)

satnogs_predict/domain/orbit.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+from .validation import ensure_required_fields_not_none
+
+
+@dataclass(frozen=True, slots=True)
+class TLE:
+    line0: str
+    line1: str
+    line2: str
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+
+
+class OrbitRepresentation(IntEnum):
+    TLE = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Orbit:
+    representation: OrbitRepresentation
+    data: TLE
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+
+
+@dataclass(frozen=True, slots=True)
+class Satellite:
+    orbit: Orbit
+    identifier: str
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+
+    @classmethod
+    def from_tle(cls, line0: str, line1: str, line2: str, identifier: str = ""):
+        tle = TLE(line0, line1, line2)
+        orbit = Orbit(representation=OrbitRepresentation.TLE, data=tle)
+        if not identifier:
+            identifier = line0
+        sat = cls(orbit=orbit, identifier=identifier)
+        return sat

satnogs_predict/domain/planner.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+from enum import IntEnum
+
+from .time import Duration
+from .validation import ensure_required_fields_not_none
+
+
+class OverlapHandling(IntEnum):
+    """
+    0 -> reject overlaps entirely
+    1 -> return truncated/split windows where possible
+    2 -> return full pass even if overlapped (and annotate overlap ratio)
+    """
+
+    DROP = 0
+    TRUNCATE = 1
+    FULL = 2
+
+
+@dataclass(frozen=True, slots=True)
+class PlanningConfig:
+    """
+    The planner's configuration for splitting and handling window overlaps
+    """
+
+    overlap_handling: OverlapHandling
+    split_long_windows: bool
+
+    # When truncating around overlaps, apply padding.
+    overlap_padding: Duration | None = None
+
+    # If a usable window is longer than max_window_duration, split into chunks separated by break_duration.
+    max_window_duration: Duration | None = None
+
+    # Time to wait between splits
+    break_duration: Duration | None = None
+
+    # If after splitting, what remains is less than remainder_cutoff_duration, drop it.
+    remainder_cutoff_duration: Duration | None = None
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+
+        if self.overlap_handling == OverlapHandling.TRUNCATE and not self.overlap_padding:
+            raise ValueError(
+                "PlanningConfig error: overlap_padding is required when overlap_handling=OverlapHandling.TRUNCATE"
+            )
+
+        if self.split_long_windows and not all(
+            (self.max_window_duration, self.break_duration, self.remainder_cutoff_duration)
+        ):
+            raise ValueError(
+                "PlanningConfig error: max_window_duration, break_duration, remainder_cutoff_duration are required when split_long_windows=True"
+            )

satnogs_predict/domain/time.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .validation import ensure_required_fields_not_none
+
+# Instant = NewType("Instant", int)  # microseconds since Unix epoch (UTC)
+
+
+class Instant(int):
+    """Microseconds since Unix epoch (UTC)."""
+
+    def to_iso_utc(self) -> str:
+        dt = datetime.fromtimestamp(int(self) / 1_000_000, tz=timezone.utc)
+        # Keep microseconds and use Z for UTC
+        return dt.isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+    @classmethod
+    def from_datetime(cls, dt: datetime) -> "Instant":
+        if dt.tzinfo is None:
+            raise ValueError("dt must be timezone-aware")
+        dt = dt.astimezone(timezone.utc)
+        epoch = datetime(1970, 1, 1, tzinfo=timezone.utc)
+        delta = dt - epoch
+        micros = delta.days * 86_400_000_000 + delta.seconds * 1_000_000 + delta.microseconds
+        return cls(micros)
+
+    def to_datetime(self) -> "datetime":
+        seconds, micros = divmod(int(self), 1_000_000)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc).replace(microsecond=micros)
+
+    def __add__(self, other: object) -> "Instant":
+        if not isinstance(other, Duration):
+            return NotImplemented
+        return Instant(int(self) + other.micros)
+
+    def __radd__(self, other: object) -> "Instant":
+        if not isinstance(other, Duration):
+            return NotImplemented
+        return self + other
+
+    def __sub__(self, other: object) -> "Instant | int":
+        if isinstance(other, Duration):
+            return Instant(int(self) - other.micros)
+        if isinstance(other, int):
+            return int(self) - other
+        return NotImplemented
+
+    def __str__(self) -> str:
+        return self.to_datetime().isoformat(timespec="seconds").replace("+00:00", "Z")
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Duration:
+    """A non-negative duration."""
+
+    micros: int
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+        if self.micros < 0:
+            raise ValueError("Duration must be non-negative")
+
+    def __mul__(self, n: int) -> Duration:
+        return Duration(self.micros * n)
+
+    def __add__(self, other: "Duration") -> "Duration":
+        if not isinstance(other, Duration):
+            return NotImplemented
+        return Duration(self.micros + other.micros)
+
+    def __sub__(self, other: "Duration") -> int:
+        if not isinstance(other, Duration):
+            return NotImplemented
+        return self.micros - other.micros
+
+    def __int__(self) -> int:
+        return self.micros
+
+    def __radd__(self, other: object) -> "Duration":
+        if other == 0:
+            return self
+        return NotImplemented
+
+    @classmethod
+    def from_timedelta(cls, td: timedelta) -> "Duration":
+        micros = int(td.total_seconds() * 1_000_000)
+        return cls(micros=micros)
+
+    @classmethod
+    def from_seconds(cls, seconds: int) -> "Duration":
+        return cls(micros=seconds * 1_000_000)
+
+    def to_timedelta(self) -> timedelta:
+        return timedelta(microseconds=self.micros)
+
+    def to_seconds(self) -> float:
+        return self.micros / 1_000_000
+
+    def __str__(self) -> str:
+        total_seconds = self.micros // 1_000_000
+        hours, remainder = divmod(total_seconds, 3600)
+        minutes, seconds = divmod(remainder, 60)
+
+        parts: list[str] = []
+        if hours:
+            parts.append(f"{hours} hr" + ("" if hours == 1 else "s"))
+        if minutes:
+            parts.append(f"{minutes} min" + ("" if minutes == 1 else "s"))
+        if seconds:
+            parts.append(f"{seconds} sec" + ("" if seconds == 1 else "s"))
+
+        if not parts:
+            return "0 secs"
+
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return str(self)
+
+
+@dataclass(frozen=True, slots=True)
+class TimeRange:
+    """Half-open interval [start, end)."""
+
+    start: Instant
+    end: Instant
+
+    def __post_init__(self) -> None:
+        ensure_required_fields_not_none(self)
+        if int(self.start) >= int(self.end):
+            raise ValueError("TimeRange requires start < end")
+
+    @classmethod
+    def from_datetimes(cls, start: datetime, end: datetime) -> "TimeRange":
+        return cls(
+            start=Instant.from_datetime(start),
+            end=Instant.from_datetime(end),
+        )
+
+    @property
+    def duration(self) -> Duration:
+        return Duration(micros=int(self.end) - int(self.start))
+
+    def contains(self, instant: Instant) -> bool:
+        return int(self.start) <= int(instant) < int(self.end)
+
+    def intersects(self, other: "TimeRange") -> bool:
+        return int(self.start) < int(other.end) and int(other.start) < int(self.end)
+
+    def intersection(self, other: "TimeRange") -> "TimeRange | None":
+        s = max(int(self.start), int(other.start))
+        e = min(int(self.end), int(other.end))
+        if s >= e:
+            return None
+        return TimeRange(start=Instant(s), end=Instant(e))
+
+    def subtract(self, other: TimeRange) -> tuple[TimeRange, ...]:
+        inter = self.intersection(other)
+        if inter is None:
+            return (self,)
+
+        pieces: list[TimeRange] = []
+
+        if int(self.start) < int(inter.start):
+            pieces.append(TimeRange(self.start, inter.start))
+
+        if int(inter.end) < int(self.end):
+            pieces.append(TimeRange(inter.end, self.end))
+
+        return tuple(pieces)
+
+    def overlap_ratio(self, other: TimeRange) -> float:
+        overlap = self.intersection(other)
+        if overlap is None:
+            return 0.0
+        return int(overlap.duration) / int(self.duration)
+
+    def shift(self, delta: Duration) -> "TimeRange":
+        return TimeRange(
+            start=self.start + delta,
+            end=self.end + delta,
+        )
+
+    def pad_secs(self, left: float = 0.0, right: float = 0.0) -> "TimeRange":
+        left_micros = int(left * 1_000_000)
+        right_micros = int(right * 1_000_000)
+        return TimeRange(
+            start=Instant(int(self.start) - left_micros),
+            end=Instant(int(self.end) + right_micros),
+        )
+
+    def pad_duration(self, left: Duration, right: Duration) -> "TimeRange":
+        left_micros = left.micros if left else 0
+        right_micros = right.micros if right else 0
+        return TimeRange(
+            start=Instant(int(self.start) - left_micros),
+            end=Instant(int(self.end) + right_micros),
+        )
+
+    def __str__(self) -> str:
+        return f"TimeRange: {str(self.start)} -> {self.end}"
+
+    def __repr__(self) -> str:
+        return str(self)

satnogs_predict/domain/validation.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import MISSING, fields
+from typing import Any
+
+
+def ensure_required_fields_not_none(instance: Any) -> None:
+    """Fail fast when required dataclass fields are passed as None."""
+    for field in fields(instance):
+        has_default = field.default is not MISSING or field.default_factory is not MISSING
+        if not has_default and getattr(instance, field.name) is None:
+            raise ValueError(f"{type(instance).__name__}.{field.name} cannot be None")