faster conjunction (#64)

* faster conjunction

* fix ci

Author: ATTron

.github/workflows/ci.yaml

@@ -94,26 +94,21 @@ jobs:
 
       - name: Test import and basic functionality
         run: |
-          python -c "from astroz import Tle, Sgp4, __version__; print(f'astroz {__version__}')"
+          python -c "from astroz import Tle, Constellation, propagate, __version__; print(f'astroz {__version__}')"
           python -c "
-          from astroz import Tle, Sgp4
+          from astroz import Tle, propagate
           import numpy as np
 
+          tle_text = '1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995\n2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123'
+
           # Test TLE parsing
-          tle = Tle('1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995\n2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123')
+          tle = Tle(tle_text)
           print(f'Satellite: {tle.satellite_number}')
 
-          # Test single propagation
-          sgp4 = Sgp4(tle)
-          pos, vel = sgp4.propagate(30.0)
-          print(f'Position: {pos}')
-
-          # Test batch propagation
+          # Test propagation
           times = np.arange(100, dtype=np.float64)
-          positions = np.empty((100, 3), dtype=np.float64)
-          velocities = np.empty((100, 3), dtype=np.float64)
-          sgp4.propagate_into(times, positions, velocities)
-          print(f'Batch: {len(positions)} points')
+          positions = propagate(tle_text, times)
+          print(f'Batch: {positions.shape}')
           "
 
       - name: Run Python example

.github/workflows/python.yaml

@@ -111,13 +111,13 @@ jobs:
       - name: Test wheel
         run: |
           pip install bindings/python/dist/*.whl
-          python -c "from astroz import Tle, Sgp4, __version__; print(f'astroz {__version__}')"
+          python -c "from astroz import Tle, Constellation, propagate, __version__; print(f'astroz {__version__}')"
           python -c "
-          from astroz import Tle, Sgp4
-          tle = Tle('1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995\n2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123')
-          sgp4 = Sgp4(tle)
-          pos, vel = sgp4.propagate(30.0)
-          print(f'Position: {pos}')
+          from astroz import Tle, propagate
+          tle_text = '1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995\n2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123'
+          tle = Tle(tle_text)
+          pos = propagate(tle_text, [30.0])
+          print(f'Position: {pos[0, 0]}')
           "
 
       - name: Upload wheels

README.md

@@ -54,31 +54,28 @@ pip install astroz
 ```
 
 ```python
-from astroz import Constellation
+from astroz import propagate, Constellation
 import numpy as np
 
 # Load and propagate - automatically optimized for maximum performance
-constellation = Constellation("starlink")
-positions = constellation.propagate(np.arange(1440))  # 1 day at 1-min intervals
+positions = propagate("starlink", np.arange(1440))  # 1 day at 1-min intervals
 # shape: (1440, num_satellites, 3) in km, ECEF coordinates
 
 # With options
 from datetime import datetime, timezone
-positions = constellation.propagate(
+positions = propagate(
+    "starlink",
     np.arange(1440),
     start_time=datetime(2024, 6, 15, tzinfo=timezone.utc),
     output="geodetic",  # "ecef" (default), "teme", or "geodetic"
 )
 
 # With velocities
-positions, velocities = constellation.propagate(np.arange(1440), velocities=True)
+positions, velocities = propagate("starlink", np.arange(1440), velocities=True)
 
-# Single satellite
-from astroz import Tle, Sgp4
-
-tle = Tle("1 25544U 98067A   24127.82853009 ...\n2 25544  51.6393 ...")
-sgp4 = Sgp4(tle)
-pos, vel = sgp4.propagate(30.0)  # 30 min after epoch
+# For repeated propagation, pre-parse to avoid overhead
+c = Constellation("starlink")
+positions = propagate(c, np.arange(1440))
 ```
 
 ### Usage

benchmarks/python_bench.py

@@ -4,14 +4,17 @@
 import time
 import numpy as np
 
+ISS_TLE = """ISS (ZARYA)
+1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995
+2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123"""
+
 ISS_TLE_LINE1 = "1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995"
 ISS_TLE_LINE2 = "2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123"
 
 SCENARIOS = [
     ("1 day (minute)", 1440, 1.0),
     ("1 week (minute)", 10080, 1.0),
     ("2 weeks (minute)", 20160, 1.0),
-    ("2 weeks (second)", 1209600, 1.0 / 60.0),
     ("1 month (minute)", 43200, 1.0),
 ]
 
@@ -20,27 +23,27 @@
 
 def bench_astroz():
     try:
-        from astroz import Tle, Sgp4
+        from astroz import Constellation, propagate
     except ImportError:
         print(
             "astroz not installed... run: zig build python-bindings && pip install -e bindings/python/"
         )
         return None
 
-    tle = Tle(f"{ISS_TLE_LINE1}\n{ISS_TLE_LINE2}")
-    sgp4 = Sgp4(tle)
-    for i in range(100):  # warmup
-        sgp4.propagate(float(i))
+    # Pre-parse constellation to avoid parsing overhead in benchmark
+    c = Constellation(ISS_TLE)
+
+    # Warmup
+    for _ in range(10):
+        propagate(c, np.arange(100, dtype=np.float64))
 
     results = {}
     for name, points, step in SCENARIOS:
         times = np.arange(points, dtype=np.float64) * step
-        positions = np.empty((points, 3), dtype=np.float64)
-        velocities = np.empty((points, 3), dtype=np.float64)
         total = 0
         for _ in range(ITERATIONS):
             start = time.perf_counter_ns()
-            sgp4.propagate_into(times, positions, velocities)
+            propagate(c, times)
             total += time.perf_counter_ns() - start
         results[name] = total / ITERATIONS / 1_000_000
     return results

bindings/python/README.md

@@ -7,125 +7,93 @@ High-performance SGP4 satellite propagation, powered by Zig with SIMD accelerati
 ## Quick Start
 
 ```python
-from astroz import Constellation
+from astroz import propagate
 import numpy as np
 
 # Load and propagate - automatically optimized for 300M+ props/sec
-constellation = Constellation("starlink")
-positions = constellation.propagate(np.arange(1440))  # 1 day at 1-min intervals
+positions = propagate("starlink", np.arange(1440))  # 1 day at 1-min intervals
 # positions: (1440, num_satellites, 3) in km, ECEF coordinates
 ```
 
-## Loading Constellations
+## Loading Sources
 
 ```python
-from astroz import Constellation
+from astroz import propagate, Constellation
 
 # CelesTrak groups
-constellation = Constellation("starlink")
-constellation = Constellation("iss")
-constellation = Constellation("gps")
-constellation = Constellation("all")  # ~13k active satellites
+positions = propagate("starlink", times)
+positions = propagate("iss", times)
+positions = propagate("gps", times)
+positions = propagate("all", times)  # ~13k active satellites
 
 # By NORAD ID
-constellation = Constellation(norad_id=25544)  # ISS
-constellation = Constellation(norad_id=[25544, 48274])  # Multiple
+positions = propagate(None, times, norad_id=25544)  # ISS
+positions = propagate(None, times, norad_id=[25544, 48274])  # Multiple
 
 # Local file or URL
-constellation = Constellation("satellites.tle")
-constellation = Constellation("https://example.com/tles.txt")
+positions = propagate("satellites.tle", times)
+positions = propagate("https://example.com/tles.txt", times)
 
-# With metadata (name, norad_id, inclination, period, etc.)
-constellation = Constellation("starlink", with_metadata=True)
-for sat in constellation.metadata:
-    print(f"{sat['name']}: {sat['inclination']:.1f}° inc, {sat['period']:.1f} min period")
+# For repeated propagation, pre-parse to avoid overhead
+c = Constellation("starlink")
+positions1 = propagate(c, times1)
+positions2 = propagate(c, times2)
 ```
 
 Groups: `all`, `starlink`, `oneweb`, `planet`, `spire`, `gps`, `glonass`, `galileo`, `beidou`, `stations`/`iss`, `weather`, `geo`
 
 ## Propagation
 
 ```python
-from astroz import Constellation
+from astroz import propagate, Constellation
 from datetime import datetime, timezone
 import numpy as np
 
-constellation = Constellation("starlink")
+times = np.arange(1440)  # 1 day at 1-min intervals
 
 # Simple (defaults: now UTC, ECEF output)
-positions = constellation.propagate(np.arange(1440))
+positions = propagate("starlink", times)
 
 # With options
-positions = constellation.propagate(
+positions = propagate(
+    "starlink",
     np.arange(14 * 1440),  # 2 weeks
     start_time=datetime(2024, 6, 1, tzinfo=timezone.utc),
     output="geodetic",  # "ecef" (default), "teme", or "geodetic"
 )
 
 # With velocities
-positions, velocities = constellation.propagate(np.arange(1440), velocities=True)
+positions, velocities = propagate("starlink", times, velocities=True)
 ```
 
-## Single Satellite
+## Conjunction Screening
 
 ```python
-from astroz import Tle, Sgp4
+from astroz import screen
 import numpy as np
 
-tle = Tle("""1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995
-2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123""")
+times = np.arange(1440)
 
-sgp4 = Sgp4(tle)
-pos, vel = sgp4.propagate(30.0)  # 30 min after epoch
-positions, velocities = sgp4.propagate_batch(np.arange(1440))
-```
-
-## Collision Screening
-
-```python
-from astroz import Constellation, coarse_screen, min_distances
-import numpy as np
-
-constellation = Constellation("starlink")
-positions = constellation.propagate(np.arange(1440), output="teme")
+# Single target (fastest - uses fused propagate+screen, no full position array)
+min_dists, min_t_indices = screen("starlink", times, threshold=50.0, target=0)
+# Returns per-satellite minimum distance to target and time index
 
-# Find pairs within 10km
-pairs, t_indices = coarse_screen(positions, threshold=10.0)
-
-# Get exact minimum distances
-pairs_array = np.array(pairs, dtype=np.uint32)
-min_dists, min_times = min_distances(positions, pairs_array)
+# All-vs-all screening
+pairs, t_indices = screen("starlink", times, threshold=10.0)
+# Returns all conjunction events within threshold
 ```
 
 ## Performance
 
-| Constellation (13,478 sats × 1,440 steps) | Throughput |
+| Constellation (13,478 sats x 1,440 steps) | Throughput |
 |--------------------------------------------|------------|
 | 1 thread | 37.7M props/sec |
 | 16 threads | 303M props/sec |
 
-*Benchmarked on AMD Ryzen 7 7840U with AVX512. The `Constellation` class automatically handles buffer reuse and warmup for optimal performance.*
+*Benchmarked on AMD Ryzen 7 7840U with AVX512.*
 
 Set `ASTROZ_THREADS` to control thread count (defaults to all cores).
 
-## Advanced: Pre-allocated Buffers
-
-For maximum performance with repeated propagations, pre-allocate output buffers:
-
-```python
-from astroz import Constellation
-import numpy as np
-
-constellation = Constellation("starlink")
-times = np.arange(1440, dtype=np.float64)
-
-# Pre-allocate buffer
-out = np.empty((len(times), constellation.num_satellites, 3), dtype=np.float64)
-positions = constellation.propagate(times, out=out)
-```
-
-Note: The `Constellation` class automatically reuses buffers internally when the output shape matches previous calls.
-
 ## Building
 
 Requires [Zig](https://ziglang.org/) and Python 3.10+.