satnogs-predict 0.3__tar.gz → 0.5__tar.gz

{satnogs_predict-0.3 → satnogs_predict-0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: satnogs-predict
-Version: 0.3
+Version: 0.5
 Summary: A package for calculating passes and observation windows for satellites.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{satnogs_predict-0.3 → satnogs_predict-0.5}/docs/docs.md

@@ -21,7 +21,8 @@
   - [6.2 - Windows returned](#62---windows-returned)
   - [6.3 - Implementation Details](#63---implementation-details)
   - [6.4 - Full workflow for finding passes](#64---full-workflow-for-finding-passes)
-  - [6.5 - Full workflow for validating time ranges that belong to passes](#65---full-workflow-for-validating-time-ranges-that-belong-to-passes)
+  - [6.5 - Sampling point-in-time geometry](#65---sampling-point-in-time-geometry)
+  - [6.6 - Full workflow for validating time ranges that belong to passes](#66---full-workflow-for-validating-time-ranges-that-belong-to-passes)
 
 
 # 1. Installation
@@ -41,11 +42,15 @@ level:
 ``` python
 from satnogs_predict import (
     find_observation_windows,
+    get_altaz,
     get_and_validate_pass_from_range,
+    get_range,
     check_observation_density_limit_respected,
     has_range_list_overlap,
     generate_fake_tle,
 
+    AngularSeparationConstraint,
+    AzimuthWindowConstraint,
     MaxDurationConstraint,
     MinCulminationConstraint,
     MinDurationConstraint,
@@ -53,6 +58,7 @@ from satnogs_predict import (
     ConstraintAppliedResult,
     ConstraintCheckFailedError,
     GeometrySample,
+    RangeSample,
     Observer,
     TLE,
     OrbitRepresentation,
@@ -78,15 +84,26 @@ The top-level exports define the supported API contract.
 
 ## 3.1 - Satellite
 
-Represents orbital information, currently derived from TLE data.
-(In the future, more ways may be added.)
+Represents orbital information derived from TLE or OMM data.
 
 ```python
 satellite = Satellite.from_tle(
-    line0=tle['tle0'], line1=tle['tle1'], line2=tle['tle2'], identifier="XSKZ-5603-1870-9019-3066"
+    line0=tle['tle0'], line1=tle['tle1'], line2=tle['tle2']
 )
 ```
 
+You can also create a satellite from an OMM element dictionary. The field names and
+values are passed through to Skyfield's `EarthSatellite.from_omm` support:
+
+```python
+satellite = Satellite.from_omm(
+    fields=omm_fields,
+)
+```
+
+The `identifier` is optional and defaults to a random UUID. Provide an explicit
+identifier when you need a stable public value or cache key.
+
 For testing or development, you can also generate a synthetic TLE:
 
 ```python
@@ -111,11 +128,13 @@ station = Observer(
     lat_deg=37.983810,
     lon_deg=23.727539,
     elevation_meters=100,
-    horizon_deg=10.0,
-    identifier="360"
+    horizon_deg=10.0
 )
 ```
 
+The `identifier` is optional here as well and defaults to a random UUID. Provide one
+when you need a stable public value or cache key.
+
 
 ## 3.3 - Time Modeling
 
@@ -138,14 +157,47 @@ now_instant = Instant.from_datetime(now)
 five_mins_dur = Duration.from_timedelta(delta)
 five_mins_dur_2 = Duration.from_seconds(5 * 60)
 
+later_instant = now_instant + five_mins_dur
+earlier_instant = later_instant - five_mins_dur
+
 time_range = TimeRange.from_datetimes(now, future)
+range_duration = time_range.duration
+shifted_range = time_range.shift(Duration.from_seconds(30))
+padded_range = time_range.pad_duration(
+    left=Duration.from_seconds(10),
+    right=Duration.from_seconds(20),
+)
+
+assert now_instant < later_instant
+assert time_range.contains(now_instant)
+assert time_range.intersects(shifted_range)
 ```
 
+Supported operations include:
+
+- `Instant.from_datetime(dt)` and `instant.to_datetime()`
+- `Instant + Duration -> Instant`
+- `Instant - Duration -> Instant`
+- ordering/comparisons between `Instant` values
+- `Duration.from_timedelta(td)`, `Duration.from_seconds(seconds)`, `duration.to_timedelta()`, `duration.to_seconds()`
+- `Duration + Duration -> Duration`
+- `TimeRange.from_datetimes(start, end)` creates a range from two timezone-aware datetimes
+- `TimeRange.duration` returns the range length as a `Duration`
+- `TimeRange.contains(instant)` checks whether an instant lies inside the range
+- `TimeRange.intersects(other)` checks whether two ranges overlap
+- `TimeRange.intersection(other)` returns the overlapping part of two ranges, or `None`
+- `TimeRange.subtract(other)` removes the overlapping part and returns the remaining pieces
+- `TimeRange.shift(duration)` moves the whole range by a duration
+- `TimeRange.pad_secs(left, right)` extends the range by raw second values on each side
+- `TimeRange.pad_duration(left, right)` extends the range by `Duration` values on each side
+
 # 4. Observation Windows & samples
 
 ## 4.1 - Samples
 
-A sample represents information of a satellite's orbit relative to the observer at a specific instant:
+A sample represents information of a satellite's orbit relative to the observer at a specific instant.
+
+`GeometrySample` stores angular geometry:
 
 ```python
 class GeometrySample:
@@ -157,7 +209,35 @@ class GeometrySample:
 
 ```
 
-## 4.2 - Observation Windows
+`RangeSample` stores distance information:
+
+```python
+class RangeSample:
+    """Range and range velocity at an instant, relative to an observer."""
+
+    instant: Instant
+    range_m: float
+    range_rate: float
+```
+
+`range_m` is the observer-to-satellite distance in meters, and `range_rate` is the
+rate of change of that distance in meters per second.
+
+## 4.2 - Doppler correction
+
+Use `get_doppler_adjusted_frequency` to apply the Doppler correction to a
+base frequency:
+
+```python
+from satnogs_predict.core import get_doppler_adjusted_frequency
+
+adjusted_frequency_hz = get_doppler_adjusted_frequency(
+    range_rate_m_per_s=range_sample.range_rate,
+    frequency_hz=145_000_000.0,
+)
+```
+
+## 4.3 - Observation Windows
 
 An observation window represents a pass or a subset of a pass.
 
@@ -199,14 +279,48 @@ If due to the constraints, a window is rejected, the reason is set in `rejection
 
 If the window has an overlap with the provided already scheduled ranges, `overlapped` will be set to `True` and the ratio will be the percentage (as a decimal) that is overlapped.
 
-## 4.3 - Constraints
+Note: if a later constraint modifies the window length, `overlap_ratio` is currently not recalculated. It remains the value computed earlier during planning.
+
+## 4.4 - Constraints
 
 When searching for observation windows (more on this below), certain constraints can be applied. Currently supported constraints are:
 
-- `MaxDurationConstraint` Rejects windows over a certain duration. Does not change the window.
+- `AngularSeparationConstraint` Trims a window to stay within a target angular separation from a fixed pointing direction, with optional fallback behavior controlled by `min_duration`.
+- `AzimuthWindowConstraint` Trims the start and end of a window so that both edge azimuths lie inside a clockwise azimuth interval.
+- `MaxDurationConstraint` Rejects windows over a certain duration. If `trim=True`, it trims them symmetrically instead.
 - `MinDurationConstraint` Rejects windows under a certain duration. Does not change the window.
 - `MinCulminationConstraint` Rejects windows whose max altitude is under a certain threshold. Does not change the window.
 
+For `AzimuthWindowConstraint`, the allowed region is defined by sweeping clockwise from `az_start` to `az_end`.
+
+Examples:
+
+- `AzimuthWindowConstraint(20.0, 100.0)` allows azimuths between `20°` and `100°`.
+- `AzimuthWindowConstraint(350.0, 20.0)` wraps around north and allows azimuths between `350°..360°` and `0°..20°`.
+
+If a window already satisfies the azimuth interval at both edges, it is left unchanged. Otherwise, the start is swept forward and the end is swept backward until both edge azimuths are inside the interval. If no valid sub-window remains, the window is rejected.
+
+`AngularSeparationConstraint` defines a fixed antenna pointing direction with:
+
+- `pointing_az_deg`
+- `pointing_el_deg`
+- `max_separation_deg`
+
+The pass is sampled over time, and the angular separation between the satellite direction and that fixed pointing direction is checked at each sample.
+
+If `min_duration` is `None`, the constraint trims the pass to the sampled interval that lies within `max_separation_deg`.
+
+If `min_duration` is provided:
+
+- if the within-separation interval is already at least `min_duration`, the pass is trimmed to that interval
+- if trimming to the within-separation interval would make the pass shorter than `min_duration`, a fallback window of exactly `min_duration` is selected around the closest sampled approach, while staying inside the original pass
+- if the original pass itself is shorter than `min_duration`, the constraint rejects it
+
+`MaxDurationConstraint` supports two modes:
+
+- by default, it rejects any window longer than `max_duration`
+- if `trim=True`, it trims the window symmetrically around its center down to `max_duration`
+
 Constraint behavior is:
 
 - `constraint.apply(window) -> ObservationWindow`: annotates the window with `constraint_applied_result` / `rejection_reason`.
@@ -295,6 +409,8 @@ Internally, satellite & observer are converted to Skyfield's types, which is com
 
 This way, repeated consecutive calls of `find_observation_windows` with the same satellite, or with the same `observer` reuse the objects under the hood.
 
+If you need to clear these caches explicitly, the public helpers `clear_satellite_cache()` and `clear_observer_cache()` are available.
+
 ## 6.4 - Full workflow for finding passes
 
 High-level process:
@@ -346,19 +462,50 @@ planning_config = PlanningConfig(
 
 min_duration_constraint = MinDurationConstraint(Duration.from_seconds(5))
 min_culmination_constraint = MinCulminationConstraint(55.0)
+azimuth_window_constraint = AzimuthWindowConstraint(220.0, 330.0)
 
 valid_windows, rejected_windows = find_observation_windows(
     sat,
     observer,
     time_range,
     planning_config,
-    pre_plan_constraints=[min_duration_constraint, min_culmination_constraint],
-    post_plan_constraints=[min_duration_constraint, min_culmination_constraint],
+    pre_plan_constraints=[
+        min_duration_constraint,
+        min_culmination_constraint,
+        azimuth_window_constraint,
+    ],
+    post_plan_constraints=[
+        min_duration_constraint,
+        min_culmination_constraint,
+        azimuth_window_constraint,
+    ],
     scheduled_intervals=scheduled_ranges,
 )
 ```
 
-## 6.5 - Full workflow for validating time ranges that belong to passes
+## 6.5 - Sampling point-in-time geometry
+
+For point-in-time queries, the public API also provides helpers for sampling a satellite relative to an observer at a single `Instant`.
+
+```python
+altaz_sample = get_altaz(
+    satellite,
+    observer,
+    instant,
+)
+
+range_sample = get_range(
+    satellite,
+    observer,
+    instant,
+)
+```
+
+- `get_altaz()` returns a `GeometrySample` with azimuth and altitude.
+- `get_range()` returns a `RangeSample` with range in meters and range rate in meters per second.
+
+
+## 6.6 - Full workflow for validating time ranges that belong to passes
 
 - Given a time range, we can validate whether it belongs to a single pass and whether it satisfies constraints.
 

{satnogs_predict-0.3 → satnogs_predict-0.5}/src/satnogs_predict/__init__.py

@@ -1,11 +1,24 @@
 from . import constraints, domain
 from .constraints import *  # noqa: F401,F403
-from .core.engine import find_observation_windows, get_and_validate_pass_from_range
+from .core.engine import (
+    find_observation_windows,
+    get_altaz,
+    get_and_validate_pass_from_range,
+    get_range,
+)
 from .domain import *  # noqa: F401,F403
 from .planning.planner import check_observation_density_limit_respected, has_range_list_overlap
+from .propagation import clear_observer_cache, clear_satellite_cache
 from .tle import generate_fake_tle
 
 __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"]
+__all__ += [
+    "clear_observer_cache",
+    "clear_satellite_cache",
+    "find_observation_windows",
+    "get_altaz",
+    "get_and_validate_pass_from_range",
+    "get_range",
+]
 __all__ += ["generate_fake_tle"]

satnogs_predict-0.5/src/satnogs_predict/constraints/__init__.py

@@ -0,0 +1,15 @@
+from .constraints import (
+    AngularSeparationConstraint,
+    AzimuthWindowConstraint,
+    MaxDurationConstraint,
+    MinCulminationConstraint,
+    MinDurationConstraint,
+)
+
+__all__ = [
+    "AngularSeparationConstraint",
+    "AzimuthWindowConstraint",
+    "MinCulminationConstraint",
+    "MinDurationConstraint",
+    "MaxDurationConstraint",
+]