python-sgp4 compatability layer (#70)

* python-sgp4 compatability layer

* doc update

Author: ATTron

.github/workflows/ci.yaml

@@ -111,5 +111,48 @@ jobs:
           print(f'Batch: {positions.shape}')
           "
 
+      - name: Test python-sgp4 compatible API
+        run: |
+          pip install sgp4
+          python -c "
+          from astroz.api import Satrec, SatrecArray, jday, WGS72
+          from sgp4.api import Satrec as Sgp4Satrec, jday as sgp4_jday, WGS72 as SGP4_WGS72
+          import numpy as np
+
+          line1 = '1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995'
+          line2 = '2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123'
+
+          # Test Satrec
+          sat = Satrec.twoline2rv(line1, line2, WGS72)
+          print(f'Satrec: satnum={sat.satnum}, error={sat.error}')
+
+          # Test jday
+          jd, fr = jday(2024, 5, 6, 12, 0, 0.0)
+          print(f'jday: {jd} + {fr}')
+
+          # Test sgp4
+          e, r, v = sat.sgp4(jd, fr)
+          print(f'sgp4: error={e}, pos=({r[0]:.1f}, {r[1]:.1f}, {r[2]:.1f})')
+
+          # Test sgp4_array
+          jd_arr = np.full(100, jd)
+          fr_arr = fr + np.arange(100) / 1440.0
+          e, r, v = sat.sgp4_array(jd_arr, fr_arr)
+          print(f'sgp4_array: shape={r.shape}')
+
+          # Test SatrecArray
+          arr = SatrecArray([sat])
+          e, r, v = arr.sgp4(jd_arr, fr_arr)
+          print(f'SatrecArray: shape={r.shape}')
+
+          # Accuracy test vs python-sgp4
+          sgp4_sat = Sgp4Satrec.twoline2rv(line1, line2, SGP4_WGS72)
+          az_e, az_r, az_v = sat.sgp4(jd, fr)
+          sg_e, sg_r, sg_v = sgp4_sat.sgp4(jd, fr)
+          pos_diff = np.linalg.norm(np.array(az_r) - np.array(sg_r))
+          assert pos_diff < 0.001, f'Position error {pos_diff*1000:.1f}m exceeds 1mm'
+          print(f'Accuracy: {pos_diff*1000:.3f}mm (< 1mm OK)')
+          "
+
       - name: Run Python example
         run: python examples/python_sgp4.py

.github/workflows/python.yaml

@@ -119,6 +119,19 @@ jobs:
           pos = propagate(tle_text, [30.0])
           print(f'Position: {pos[0, 0]}')
           "
+          python -c "
+          from astroz.api import Satrec, SatrecArray, jday, WGS72
+          import numpy as np
+          line1 = '1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995'
+          line2 = '2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123'
+          sat = Satrec.twoline2rv(line1, line2, WGS72)
+          jd, fr = jday(2024, 5, 6, 12, 0, 0.0)
+          e, r, v = sat.sgp4(jd, fr)
+          print(f'astroz.api: pos=({r[0]:.1f}, {r[1]:.1f}, {r[2]:.1f})')
+          arr = SatrecArray([sat])
+          e, r, v = arr.sgp4(np.array([jd]), np.array([fr]))
+          print(f'SatrecArray: shape={r.shape}')
+          "
 
       - name: Upload wheels
         uses: actions/upload-artifact@v4

README.md

@@ -53,6 +53,54 @@ The [Cesium visualization example](examples/README.md) propagates the entire act
 pip install astroz
 ```
 
+#### python-sgp4 Compatible API (Recommended)
+
+Drop-in replacement for [python-sgp4](https://github.com/brandon-rhodes/python-sgp4). Just change the import for instant speedup:
+
+```python
+# Before                                    # After
+from sgp4.api import Satrec, jday      →    from astroz.api import Satrec, jday
+```
+
+| Your Code | python-sgp4 | astroz | Speedup |
+|-----------|-------------|--------|---------|
+| `sat.sgp4()` loop | 1.3M/s | 2.5M/s | **2x** |
+| `sat.sgp4_array()` | 2.7M/s | 15M/s | **5x** |
+| `SatrecArray.sgp4()` | 3M/s | 290M/s | **100x** |
+
+See [migration guide](bindings/python/README.md#migrating-from-python-sgp4) for optimization tips.
+
+```python
+from astroz.api import Satrec, SatrecArray, jday, WGS72
+import numpy as np
+
+# Single satellite (same syntax as python-sgp4)
+line1 = "1 25544U 98067A   24127.82853009  .00015698  00000+0  27310-3 0  9995"
+line2 = "2 25544  51.6393 160.4574 0003580 140.6673 205.7250 15.50957674452123"
+sat = Satrec.twoline2rv(line1, line2, WGS72)
+
+jd, fr = jday(2024, 5, 6, 12, 0, 0.0)
+error, position, velocity = sat.sgp4(jd, fr)
+
+# Batch propagation (270-330M props/sec with SIMD)
+sat_array = SatrecArray([sat1, sat2, ...])  # List of Satrec objects
+
+# Single time point (scalars)
+e, r, v = sat_array.sgp4(2460000.5, 0.5)
+
+# Multiple time points (arrays)
+jd = np.full(1440, 2460000.5)
+fr = np.linspace(0, 1, 1440)
+e, r, v = sat_array.sgp4(jd, fr)  # (n_sats, n_times, 3)
+
+# Skip velocities for 30% faster propagation
+e, r, _ = sat_array.sgp4(jd, fr, velocities=False)
+```
+
+#### High-Level API
+
+Convenience functions for common workflows:
+
 ```python
 from astroz import propagate, Constellation
 import numpy as np