keplemon 3.1.1__cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

keplemon/estimation.pyi

@@ -0,0 +1,200 @@
+# flake8: noqa
+from typing import Optional
+
+from keplemon.elements import TopocentricElements, CartesianVector
+from keplemon.time import Epoch
+from keplemon.bodies import Satellite, Sensor, Constellation
+from keplemon.enums import KeplerianType, AssociationConfidence
+
+class Covariance:
+    sigmas: list[float]
+    """"""
+
+class ObservationAssociation:
+    observation_id: str
+    satellite_id: str
+    residual: "ObservationResidual"
+    confidence: "AssociationConfidence"
+
+class Observation:
+    """
+    Args:
+        sensor: Sensor that made the observation
+        epoch: Time of the observation
+        observed_teme_topocentric: Topocentric elements of the satellite at the time of observation
+        observer_teme_position: Position of the observer in TEME coordinates
+    """
+
+    id: str
+    """Unique identifier for the observation"""
+
+    sensor: Sensor
+    """Sensor which produced the observation"""
+
+    epoch: Epoch
+    """Time the measurement was observed"""
+
+    range: Optional[float]
+    """Observed range from the sensor to the satellite in **_kilometers_**"""
+
+    range_rate: Optional[float]
+    """Observed range rate from the sensor to the satellite in **_kilometers per second_**"""
+
+    right_ascension: float
+    """Observed TEME right ascension in **_degrees_**"""
+
+    declination: float
+    """Observed TEME declination in **_degrees_**"""
+
+    right_ascension_rate: Optional[float]
+    """Observed right ascension rate in **_degrees per second_**"""
+
+    declination_rate: Optional[float]
+    """Observed declination rate in **_degrees per second_**"""
+
+    observed_satellite_id: Optional[str]
+    """Tagged satellite ID of the observation"""
+
+    def __init__(
+        self,
+        sensor: Sensor,
+        epoch: Epoch,
+        observed_teme_topocentric: TopocentricElements,
+        observer_teme_position: CartesianVector,
+    ) -> None: ...
+    @staticmethod
+    def from_saal_files(sensor_file: str, observation_file: str) -> list["Observation"]: ...
+    def get_residual(self, sat: Satellite) -> Optional[ObservationResidual]:
+        """
+        Calculate the residual of the observation with respect to a given satellite state.
+
+        !!! note
+            If an error occurs during propagation of the satellite state, this method will return None.
+
+        Args:
+            sat: Expected satellite state
+
+        Returns:
+            Calculated residual
+        """
+        ...
+
+    def get_associations(self, sats: Constellation) -> list[ObservationAssociation]:
+        """
+        Calculate the associations of the observation with respect to a given constellation of satellites.
+
+        Args:
+            sats: Constellation of satellites to compare against
+
+        Returns:
+            List of possible observation associations
+        """
+        ...
+
+class ObservationResidual:
+    range: float
+    """Euclidean distance between the observed and expected state in **_kilometers_**"""
+
+    radial: float
+    """Radial distance between the observed and expected state in **_kilometers_**"""
+
+    in_track: float
+    """In-track distance between the observed and expected state in **_kilometers_**"""
+
+    cross_track: float
+    """Cross-track distance between the observed and expected state in **_kilometers_**"""
+
+    velocity: float
+    """Velocity magnitude difference between the observed and expected state in **_kilometers per second_**"""
+
+    radial_velocity: float
+    """Radial velocity difference between the observed and expected state in **_kilometers per second_**"""
+
+    in_track_velocity: float
+    """In-track velocity difference between the observed and expected state in **_kilometers per second_**"""
+
+    cross_track_velocity: float
+    """Cross-track velocity difference between the observed and expected state in **_kilometers per second_**"""
+
+    time: float
+    """Time difference between the observed and expected state in **_seconds_**"""
+
+    beta: float
+    """Out-of-plane difference between the observed and expected state in **_degrees_**"""
+
+    height: float
+    """Height difference between the observed and expected state in **_kilometers_**"""
+
+class BatchLeastSquares:
+    """
+    Args:
+        obs: List of observations to be used in the estimation
+        a_priori: A priori satellite state
+    """
+
+    converged: bool
+    """Indicates if the solution meets the tolerance criteria"""
+
+    max_iterations: int
+    """Maximum number of iterations to perform when solving if the tolerance is not met"""
+
+    iteration_count: int
+    """Number of iterations performed to reach the solution"""
+
+    current_estimate: Satellite
+    """Current estimate of the satellite state after iterating or solving"""
+
+    rms: Optional[float]
+    """Root mean square of the residuals in **_kilometers_**"""
+
+    weighted_rms: Optional[float]
+    """Unitless weighted root mean square of the residuals"""
+
+    estimate_srp: bool
+    """Flag to indicate if solar radiation pressure should be estimated
+    
+    !!! warning
+        This currently has unexpected behavior if solving for output_types other than XP
+    """
+
+    estimate_drag: bool
+    """Flag to indicate if atmospheric drag should be estimated
+    
+    !!! warning
+        This currently has unexpected behavior if solving for output_types other than XP
+    """
+
+    a_priori: Satellite
+    """A priori satellite state used to initialize the estimation"""
+
+    observations: list[Observation]
+    """List of observations used in the estimation"""
+
+    residuals: list[tuple[Epoch, ObservationResidual]]
+    """List of residuals for each observation compared to the current estimate"""
+
+    covariance: Optional[Covariance]
+    """UVW covariance matrix of the current estimate in **_kilometers_** and **_kilometers per second_**"""
+
+    output_type: KeplerianType
+    """Type of Keplerian elements to be used in the output state"""
+
+    eccentricity_constraint_weight: Optional[float]
+    """Tikhonov weight that keeps equinoctial a_f/a_g (eccentricity) near the a priori state"""
+
+    def __init__(
+        self,
+        obs: list[Observation],
+        a_priori: Satellite,
+    ) -> None: ...
+    def solve(self) -> None:
+        """Iterate until the solution converges or the maximum number of iterations is reached."""
+        ...
+
+    def iterate(self) -> None:
+        """Perform a single iteration of the estimation process."""
+        ...
+
+    def reset(self) -> None:
+        """Reset the estimation process to the initial state."""
+        ...

keplemon/events.py

@@ -0,0 +1,17 @@
+from keplemon._keplemon.events import (  # type: ignore
+    CloseApproach,
+    CloseApproachReport,
+    HorizonAccess,
+    HorizonAccessReport,
+    FieldOfViewCandidate,
+    FieldOfViewReport,
+)
+
+__all__ = [
+    "CloseApproach",
+    "CloseApproachReport",
+    "HorizonAccess",
+    "HorizonAccessReport",
+    "FieldOfViewCandidate",
+    "FieldOfViewReport",
+]

keplemon/events.pyi

@@ -0,0 +1,103 @@
+# flake8: noqa
+from keplemon.time import Epoch, TimeSpan
+from keplemon.elements import HorizonState, CartesianVector, TopocentricElements
+from keplemon.enums import ReferenceFrame
+
+class FieldOfViewCandidate:
+    satellite_id: str
+    """ID of the candidate satellite"""
+
+    direction: TopocentricElements
+    """Measured direction to the candidate satellite in the sensor's topocentric frame"""
+
+class FieldOfViewReport:
+    epoch: Epoch
+    """UTC epoch of the field of view report"""
+
+    sensor_position: CartesianVector
+    """TEME position of the sensor in the observatory's topocentric frame in **_kilometers_**"""
+
+    sensor_direction: TopocentricElements
+    """Direction of the sensor in the observatory's topocentric frame"""
+
+    fov_angle: float
+    """Field of view angle of the sensor in **_degrees_**"""
+
+    candidates: list[FieldOfViewCandidate]
+    """List of candidate satellites within the field of view"""
+
+    reference_frame: ReferenceFrame
+    """Reference frame of the output direction elements"""
+
+class CloseApproach:
+    epoch: Epoch
+    """UTC epoch of the close approach"""
+
+    primary_id: str
+    """Satellite ID of the primary body in the close approach"""
+
+    secondary_id: str
+    """Satellite ID of the secondary body in the close approach"""
+
+    distance: float
+    """Distance between the two bodies in **_kilometers_**"""
+
+class CloseApproachReport:
+    """
+    Args:
+        start: CA screening start time
+        end: CA screening end time
+        distance_threshold: Distance threshold for CA screening in **_kilometers_**
+    """
+
+    close_approaches: list[CloseApproach]
+    """List of close approaches found during the screening"""
+
+    distance_threshold: float
+    def __init__(self, start: Epoch, end: Epoch, distance_threshold: float) -> None: ...
+
+class HorizonAccess:
+
+    satellite_id: str
+    """ID of the satellite for which the access is calculated"""
+
+    observatory_id: str
+    """ID of the observatory for which the access is calculated"""
+
+    start: HorizonState
+    """State of the satellite at the start of the access period"""
+
+    end: HorizonState
+    """State of the satellite at the end of the access period"""
+
+class HorizonAccessReport:
+    """
+    Args:
+        start: UTC epoch of the start of the access report
+        end: UTC epoch of the end of the access report
+        min_elevation: Minimum elevation angle for access in **_degrees_**
+        min_duration: Minimum duration of access
+    """
+
+    accesses: list[HorizonAccess]
+    """List of horizon accesses found during the screening"""
+
+    elevation_threshold: float
+    """Minimum elevation angle for access in **_degrees_**"""
+
+    start: Epoch
+    """UTC epoch of the start of the access report"""
+
+    end: Epoch
+    """UTC epoch of the end of the access report"""
+
+    duration_threshold: TimeSpan
+    """Minimum duration of a valid access"""
+
+    def __init__(
+        self,
+        start: Epoch,
+        end: Epoch,
+        min_elevation: float,
+        min_duration: TimeSpan,
+    ) -> None: ...

keplemon/exceptions.py

@@ -0,0 +1,5 @@
+from keplemon._keplemon.exceptions import (  # type: ignore
+    SAALError,
+)
+
+__all__ = ["SAALError"]

keplemon/propagation.py

@@ -0,0 +1,15 @@
+from keplemon._keplemon.propagation import (  # type: ignore
+    ForceProperties,
+    InertialPropagator,
+    SGP4Output,
+    b_star_to_drag_coefficient,
+    drag_coefficient_to_b_star,
+)
+
+__all__ = [
+    "ForceProperties",
+    "InertialPropagator",
+    "SGP4Output",
+    "b_star_to_drag_coefficient",
+    "drag_coefficient_to_b_star",
+]

keplemon/propagation.pyi

@@ -0,0 +1,50 @@
+# flake8: noqa
+from __future__ import annotations
+
+from typing import Optional
+
+from keplemon.elements import CartesianState, GeodeticPosition, KeplerianElements, KeplerianState, TLE
+from keplemon.time import Epoch
+
+class ForceProperties:
+    srp_coefficient: float
+    drag_coefficient: float
+    mass: float
+    srp_area: float
+    drag_area: float
+    mean_motion_dot: float
+    mean_motion_dot_dot: float
+    def __init__(
+        self,
+        srp_coefficient: float,
+        srp_area: float,
+        drag_coefficient: float,
+        drag_area: float,
+        mass: float,
+        mean_motion_dot: float,
+        mean_motion_dot_dot: float,
+    ) -> None: ...
+
+class InertialPropagator:
+    @staticmethod
+    def from_tle(tle: TLE) -> InertialPropagator: ...
+
+    def get_cartesian_state_at_epoch(self, epoch: Epoch) -> Optional[CartesianState]: ...
+    def get_keplerian_state_at_epoch(self, epoch: Epoch) -> Optional[KeplerianState]: ...
+
+    keplerian_state: KeplerianState
+    force_properties: ForceProperties
+
+class SGP4Output:
+    cartesian_state: CartesianState
+    mean_elements: KeplerianElements
+    osculating_elements: KeplerianElements
+    geodetic_position: GeodeticPosition
+
+def b_star_to_drag_coefficient(b_star: float) -> float:
+    """Convert B* to drag coefficient."""
+    ...
+
+def drag_coefficient_to_b_star(drag_coefficient: float) -> float:
+    """Convert drag coefficient to B*."""
+    ...

keplemon/time.py

@@ -0,0 +1,96 @@
+from keplemon._keplemon.time import (  # type: ignore
+    TimeSpan,
+    TimeComponents,
+    Epoch,
+)
+import requests  # type: ignore
+from datetime import datetime
+from keplemon._keplemon.enums import TimeSystem  # type: ignore
+
+__all__ = [
+    "TimeSpan",
+    "TimeComponents",
+    "Epoch",
+    "request_time_constants_update",
+]
+
+
+def request_time_constants_update(output_path: str) -> None:
+    finals = requests.get("https://maia.usno.navy.mil/ser7/finals.all").text.splitlines()
+
+    leap_seconds = requests.get("https://maia.usno.navy.mil/ser7/tai-utc.dat").text.splitlines()
+
+    month_map = {
+        "JAN": 1,
+        "FEB": 2,
+        "MAR": 3,
+        "APR": 4,
+        "MAY": 5,
+        "JUN": 6,
+        "JUL": 7,
+        "AUG": 8,
+        "SEP": 9,
+        "OCT": 10,
+        "NOV": 11,
+        "DEC": 12,
+    }
+    leap_second_map = {}
+    for line in leap_seconds:
+        yy = int(line[3:5].strip())
+        mm = month_map[line[6:9]]
+        dd = int(line[10:12].strip())
+        time_comps = TimeComponents(yy, mm, dd, 0, 0, 0)
+        current_epoch = Epoch.from_time_components(time_comps, TimeSystem.UTC)
+        ds50 = int(current_epoch.days_since_1950)
+        leap = float(line[38:48].strip())
+        leap_second_map[ds50] = leap
+
+    time_constant_lines: list[str] = []
+    sorted_leap_seconds = sorted(leap_second_map, reverse=True)
+    ut1 = 0.0
+    prev_ut1_utc = 0.0
+    prev_time = 0
+    prev_leap = 0.0
+    for line in finals:
+
+        if len(line.strip()) < 68:
+            break
+
+        yy = int(line[0:2].strip())
+        mm = int(line[2:4].strip())
+        dd = int(line[4:6].strip())
+        if yy < 50:
+            yyyy = 2000 + yy
+        else:
+            yyyy = 1900 + yy
+        ymd = datetime(yyyy, mm, dd).strftime("%d-%b-%y")
+
+        time_comps = TimeComponents(yy, mm, dd, 0, 0, 0)
+        current_epoch = Epoch.from_time_components(time_comps, TimeSystem.UTC)
+        ds50 = int(current_epoch.days_since_1950)
+        leap = 0.0
+        for leap_ds50 in sorted_leap_seconds:
+            if ds50 >= leap_ds50:
+                leap = leap_second_map[leap_ds50]
+                break
+
+        ut1 = float(line[58:68].strip())
+        if prev_time == 0:
+            ut1_r = 0.0
+        else:
+            ut1_r = (ut1 - prev_ut1_utc) / (ds50 - prev_time)
+            ut1_r = (ut1_r - (leap - prev_leap)) * 1e3
+
+        p_x = float(line[18:27].strip())
+        p_y = float(line[37:46].strip())
+
+        doy = current_epoch.day_of_year
+        time_constant_lines.append(
+            f" {yy:02d}  {doy:03.0f}   {ymd} {leap:3.0f}  {ut1:8.5f}  {ut1_r:6.3f}   {p_x:7.4f}   {p_y:7.4f}\n"
+        )
+        prev_time = ds50
+        prev_ut1_utc = ut1
+        prev_leap = leap
+
+    with open(output_path, "w") as f:
+        f.writelines(time_constant_lines)