astroz 0.4.1__cp312-cp312-manylinux_2_38_x86_64.whl

astroz/__init__.py

@@ -0,0 +1,22 @@
+"""astroz - High-performance astrodynamics library."""
+
+import atexit
+from .__version__ import __version__
+from ._lib import _lib
+from .tle import Tle
+from .sgp4 import Sgp4
+from . import orbital
+from . import coords
+
+# initialize on import
+_lib.astroz_init()
+atexit.register(_lib.astroz_deinit)
+
+
+def version() -> str:
+    """Return astroz version string."""
+    v = _lib.astroz_version()
+    return f"{(v >> 16) & 0xFF}.{(v >> 8) & 0xFF}.{v & 0xFF}"
+
+
+__all__ = ["__version__", "version", "Tle", "Sgp4", "orbital", "coords"]

astroz/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.1"

astroz/_lib.py

@@ -0,0 +1,111 @@
+"""Load the astroz shared library."""
+
+import ctypes
+import os
+import platform
+
+
+_LIB_NAMES = {
+    "Linux": "libastroz_c.so",
+    "Darwin": "libastroz_c.dylib",
+    "Windows": "astroz_c.dll",
+}
+
+
+def _find_library():
+    """Find libastroz_c shared library.
+
+    Search order:
+    1. ASTROZ_LIB env var (explicit override)
+    2. Next to this package (installed via pip)
+    3. zig-out/lib/ (development)
+    """
+    system = platform.system()
+    name = _LIB_NAMES.get(system)
+    if name is None:
+        raise OSError(f"Unsupported platform: {system}")
+
+    # Explicit override
+    env_path = os.environ.get("ASTROZ_LIB")
+    if env_path:
+        if os.path.exists(env_path):
+            return env_path
+        raise OSError(f"ASTROZ_LIB set but file not found: {env_path}")
+
+    # Standard search paths
+    pkg_dir = os.path.dirname(__file__)
+    search_paths = [
+        os.path.join(pkg_dir, "lib", name),  # installed package (wheel)
+        os.path.join(pkg_dir, name),  # legacy location
+        os.path.join(pkg_dir, "..", "..", "zig-out", "lib", name),  # dev
+    ]
+
+    for path in search_paths:
+        if os.path.exists(path):
+            return path
+
+    raise OSError(
+        f"Cannot find {name}. Either:\n"
+        f"  - Run 'zig build c-api' for development\n"
+        f"  - Set ASTROZ_LIB=/path/to/{name}"
+    )
+
+
+_lib = ctypes.CDLL(_find_library())
+
+# aliases
+_ptr = ctypes.c_void_p
+_i32 = ctypes.c_int32
+_u32 = ctypes.c_uint32
+_f32 = ctypes.c_float
+_f64 = ctypes.c_double
+_str = ctypes.c_char_p
+_out_ptr = ctypes.POINTER(ctypes.c_void_p)
+_out_vec3 = ctypes.POINTER(ctypes.c_double * 3)
+
+
+def _sig(func, args, ret=_i32):
+    """Set function signature: argtypes and restype."""
+    func.argtypes = args
+    func.restype = ret
+
+
+_sig(_lib.astroz_init, [], None)
+_sig(_lib.astroz_deinit, [], None)
+_sig(_lib.astroz_version, [], _u32)
+
+_sig(_lib.tle_parse, [_str, _out_ptr])
+_sig(_lib.tle_free, [_ptr], None)
+_sig(_lib.tle_get_satellite_number, [_ptr], _u32)
+_sig(_lib.tle_get_epoch, [_ptr], _f64)
+_sig(_lib.tle_get_inclination, [_ptr], _f64)
+_sig(_lib.tle_get_eccentricity, [_ptr], _f64)
+_sig(_lib.tle_get_mean_motion, [_ptr], _f64)
+
+_sig(_lib.sgp4_init, [_ptr, _i32, _out_ptr])
+_sig(_lib.sgp4_free, [_ptr], None)
+_sig(_lib.sgp4_propagate, [_ptr, _f64, _out_vec3, _out_vec3])
+_sig(
+    _lib.sgp4_propagate_batch, [_ptr, ctypes.POINTER(_f64), ctypes.POINTER(_f64), _u32]
+)
+
+
+class HohmannResult(ctypes.Structure):
+    _fields_ = [
+        ("semi_major_axis", _f64),
+        ("delta_v1", _f64),
+        ("delta_v2", _f64),
+        ("total_delta_v", _f64),
+        ("transfer_time", _f64),
+        ("transfer_time_days", _f64),
+    ]
+
+
+_sig(_lib.orbital_hohmann, [_f64, _f64, _f64, ctypes.POINTER(HohmannResult)])
+_sig(_lib.orbital_velocity, [_f64, _f64, _f64], _f64)
+_sig(_lib.orbital_period, [_f64, _f64], _f64)
+_sig(_lib.orbital_escape_velocity, [_f64, _f64], _f64)
+
+_sig(_lib.coords_eci_to_ecef, [_out_vec3, _f64, _out_vec3], None)
+_sig(_lib.coords_ecef_to_geodetic, [_out_vec3, _out_vec3], None)
+_sig(_lib.coords_julian_to_gmst, [_f64], _f64)

astroz/coords.py

@@ -0,0 +1,30 @@
+"""Coordinate transformations."""
+
+from ctypes import byref, c_double
+from ._lib import _lib
+
+
+def eci_to_ecef(eci: tuple, gmst: float) -> tuple:
+    """ECI to ECEF. Returns (x, y, z) in km."""
+    eci_arr = (c_double * 3)(*eci)
+    ecef_arr = (c_double * 3)()
+    _lib.coords_eci_to_ecef(byref(eci_arr), gmst, byref(ecef_arr))
+    return (ecef_arr[0], ecef_arr[1], ecef_arr[2])
+
+
+def ecef_to_geodetic(ecef: tuple) -> tuple:
+    """ECEF to geodetic (WGS84). Returns (lat_deg, lon_deg, alt_km)."""
+    ecef_arr = (c_double * 3)(*ecef)
+    lla_arr = (c_double * 3)()
+    _lib.coords_ecef_to_geodetic(byref(ecef_arr), byref(lla_arr))
+    return (lla_arr[0], lla_arr[1], lla_arr[2])
+
+
+def eci_to_geodetic(eci: tuple, gmst: float) -> tuple:
+    """ECI to geodetic (WGS84). Returns (lat_deg, lon_deg, alt_km)."""
+    return ecef_to_geodetic(eci_to_ecef(eci, gmst))
+
+
+def julian_to_gmst(jd: float) -> float:
+    """Julian date to GMST (radians)."""
+    return _lib.coords_julian_to_gmst(jd)

astroz/exceptions.py

@@ -0,0 +1,40 @@
+"""Exception handling for astroz errors."""
+
+
+class AstrozError(Exception):
+    """Base exception for astroz errors."""
+
+
+class TleParseError(AstrozError):
+    """TLE parsing failed."""
+
+
+class Sgp4Error(AstrozError):
+    """SGP4 propagation error."""
+
+
+class OrbitalError(AstrozError):
+    """Orbital mechanics calculation error."""
+
+
+_ERROR_MAP = {
+    -1: (TleParseError, "Bad TLE length"),
+    -2: (TleParseError, "Bad checksum"),
+    -10: (Sgp4Error, "Deep space not supported"),
+    -11: (Sgp4Error, "Invalid eccentricity"),
+    -12: (Sgp4Error, "Satellite decayed"),
+    -20: (OrbitalError, "Invalid orbital parameters"),
+    -100: (AstrozError, "Allocation failed"),
+    -101: (AstrozError, "Null pointer"),
+    -102: (AstrozError, "Not initialized"),
+}
+
+
+def check(code: int) -> None:
+    """Raise exception if error code is non-zero."""
+    if code == 0:
+        return
+    err = _ERROR_MAP.get(code)
+    if err:
+        raise err[0](err[1])
+    raise AstrozError(f"Unknown error: {code}")

astroz/orbital.py

@@ -0,0 +1,38 @@
+"""Orbital mechanics functions."""
+
+from ctypes import byref
+from ._lib import _lib, HohmannResult
+from .exceptions import check
+
+
+def hohmann(mu: float, r1: float, r2: float) -> dict:
+    """Hohmann transfer between two circular orbits.
+
+    Returns dict with: semi_major_axis, delta_v1, delta_v2,
+    total_delta_v, transfer_time, transfer_time_days
+    """
+    result = HohmannResult()
+    check(_lib.orbital_hohmann(mu, r1, r2, byref(result)))
+    return {
+        "semi_major_axis": result.semi_major_axis,
+        "delta_v1": result.delta_v1,
+        "delta_v2": result.delta_v2,
+        "total_delta_v": result.total_delta_v,
+        "transfer_time": result.transfer_time,
+        "transfer_time_days": result.transfer_time_days,
+    }
+
+
+def velocity(mu: float, radius: float, sma: float = 0) -> float:
+    """Orbital velocity (km/s). Use sma=0 for circular orbit."""
+    return _lib.orbital_velocity(mu, radius, sma)
+
+
+def period(mu: float, sma: float) -> float:
+    """Orbital period (seconds)."""
+    return _lib.orbital_period(mu, sma)
+
+
+def escape_velocity(mu: float, radius: float) -> float:
+    """Escape velocity (km/s)."""
+    return _lib.orbital_escape_velocity(mu, radius)

astroz/sgp4.py

@@ -0,0 +1,86 @@
+"""SGP4 orbit propagator wrapper."""
+
+import ctypes
+from ._lib import _lib
+from .exceptions import check
+from .tle import Tle
+
+
+class Sgp4:
+    """SGP4 orbit propagator."""
+
+    WGS84 = 0
+    WGS72 = 1
+
+    def __init__(self, tle: Tle, gravity_model: int = WGS84):
+        """Initialize SGP4 propagator from TLE."""
+        self._handle = ctypes.c_void_p()
+        check(_lib.sgp4_init(tle._handle, gravity_model, ctypes.byref(self._handle)))
+
+    def __del__(self):
+        if hasattr(self, "_handle") and self._handle:
+            _lib.sgp4_free(self._handle)
+
+    def propagate(self, tsince: float) -> tuple:
+        """Propagate to time since TLE epoch.
+
+        Args:
+            tsince: Minutes since TLE epoch
+
+        Returns:
+            (position, velocity) tuples in km and km/s (TEME frame)
+        """
+        pos = (ctypes.c_double * 3)()
+        vel = (ctypes.c_double * 3)()
+        check(
+            _lib.sgp4_propagate(
+                self._handle, tsince, ctypes.byref(pos), ctypes.byref(vel)
+            )
+        )
+        return (pos[0], pos[1], pos[2]), (vel[0], vel[1], vel[2])
+
+    def propagate_batch(self, times: list) -> list:
+        """Batch propagation - much faster for multiple time steps.
+
+        Args:
+            times: List of minutes since TLE epoch
+
+        Returns:
+            List of (position, velocity) tuples
+        """
+        n = len(times)
+        times_arr = (ctypes.c_double * n)(*times)
+        results_arr = (ctypes.c_double * (n * 6))()
+        check(_lib.sgp4_propagate_batch(self._handle, times_arr, results_arr, n))
+        out = []
+        for i in range(n):
+            base = i * 6
+            pos = (results_arr[base], results_arr[base + 1], results_arr[base + 2])
+            vel = (results_arr[base + 3], results_arr[base + 4], results_arr[base + 5])
+            out.append((pos, vel))
+        return out
+
+    def propagate_batch_np(self, times):
+        """Batch propagation returning numpy arrays (fastest).
+
+        Args:
+            times: Array-like of minutes since TLE epoch
+
+        Returns:
+            (positions, velocities) as numpy arrays of shape (n, 3)
+        """
+        import numpy as np
+
+        times = np.asarray(times, dtype=np.float64)
+        n = len(times)
+        results = np.empty(n * 6, dtype=np.float64)
+        check(
+            _lib.sgp4_propagate_batch(
+                self._handle,
+                times.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                results.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                n,
+            )
+        )
+        results = results.reshape(n, 6)
+        return results[:, :3], results[:, 3:]

astroz/tle.py

@@ -0,0 +1,43 @@
+"""TLE (Two-Line Element) wrapper."""
+
+import ctypes
+from ._lib import _lib
+from .exceptions import check
+
+
+class Tle:
+    """Two-Line Element set for satellite orbit data."""
+
+    def __init__(self, tle_string: str):
+        """Parse a TLE string (both lines)."""
+        self._handle = ctypes.c_void_p()
+        check(_lib.tle_parse(tle_string.encode(), ctypes.byref(self._handle)))
+
+    def __del__(self):
+        if hasattr(self, "_handle") and self._handle:
+            _lib.tle_free(self._handle)
+
+    @property
+    def satellite_number(self) -> int:
+        """NORAD catalog number."""
+        return _lib.tle_get_satellite_number(self._handle)
+
+    @property
+    def epoch(self) -> float:
+        """Epoch in J2000 seconds."""
+        return _lib.tle_get_epoch(self._handle)
+
+    @property
+    def inclination(self) -> float:
+        """Orbital inclination in degrees."""
+        return _lib.tle_get_inclination(self._handle)
+
+    @property
+    def eccentricity(self) -> float:
+        """Orbital eccentricity."""
+        return _lib.tle_get_eccentricity(self._handle)
+
+    @property
+    def mean_motion(self) -> float:
+        """Mean motion in revolutions per day."""
+        return _lib.tle_get_mean_motion(self._handle)

astroz-0.4.1.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: astroz
+Version: 0.4.1
+Summary: Python bindings for astroz - high-performance astrodynamics library
+License: MIT
+Project-URL: Repository, https://github.com/ATTron/astroz
+Keywords: astrodynamics,orbital-mechanics,sgp4,tle,satellite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# astroz Python bindings
+
+Python bindings for [astroz](https://github.com/ATTron/astroz), a high-performance astrodynamics library written in Zig.
+
+## Performance
+
+Using the batch numpy API, astroz significantly outperforms other Python SGP4 libraries:
+
+| Scenario | astroz | python-sgp4 | skyfield | vs sgp4 |
+|----------|--------|-------------|----------|---------|
+| 1 day (minute res) | 0.37 ms | 0.54 ms | 8 ms | **1.5x faster** |
+| 1 week (minute res) | 2.6 ms | 3.7 ms | 50 ms | **1.4x faster** |
+| 2 weeks (minute res) | 4.8 ms | 7.4 ms | 92 ms | **1.5x faster** |
+| 2 weeks (second res) | 280 ms | 460 ms | - | **1.6x faster** |
+| 1 month (minute res) | 9.8 ms | 17 ms | 187 ms | **1.7x faster** |
+
+The raw Zig implementation achieves ~5 million propagations/second, outperforming
+the Rust [sgp4 crate](https://github.com/neuromorphicsystems/sgp4) by 1.3-2.2x.
+
+## Installation
+
+```bash
+# Build the shared library first
+cd /path/to/astroz
+zig build c-api
+
+# Install Python package
+cd python
+pip install -e .
+```
+
+## Usage
+
+```python
+import astroz
+from astroz import Tle, Sgp4, orbital, coords
+
+# Parse TLE and propagate with SGP4
+tle = Tle("""1 25544U 98067A   24001.50000000  .00016717  00000-0  10270-3 0  9025
+2 25544  51.6400 208.9163 0006703  40.6542 114.5435 15.49910020999999""")
+
+sgp4 = Sgp4(tle)
+pos, vel = sgp4.propagate(30.0)  # 30 minutes after epoch
+print(f"Position: {pos} km")
+print(f"Velocity: {vel} km/s")
+
+# Convert to ground coordinates
+gmst = coords.julian_to_gmst(2460310.5)
+lat, lon, alt = coords.eci_to_geodetic(pos, gmst)
+print(f"Lat: {lat:.2f}, Lon: {lon:.2f}, Alt: {alt:.1f} km")
+
+# Orbital mechanics
+transfer = orbital.hohmann(398600.5, 6778, 42164)  # LEO to GEO
+print(f"Delta-V: {transfer['total_delta_v']:.2f} km/s")
+```
+
+## API
+
+### TLE Parsing
+- `Tle(tle_string)` - Parse two-line element set
+- Properties: `satellite_number`, `epoch`, `inclination`, `eccentricity`, `mean_motion`
+
+### SGP4 Propagation
+- `Sgp4(tle, gravity_model=WGS84)` - Initialize propagator
+- `propagate(tsince)` - Single propagation (returns tuple)
+- `propagate_batch(times)` - Batch propagation (returns list)
+- `propagate_batch_np(times)` - Batch with numpy (fastest, returns arrays)
+
+### Coordinates
+- `coords.eci_to_ecef(eci, gmst)` - ECI to ECEF
+- `coords.ecef_to_geodetic(ecef)` - ECEF to lat/lon/alt
+- `coords.eci_to_geodetic(eci, gmst)` - ECI to lat/lon/alt
+- `coords.julian_to_gmst(jd)` - Julian date to GMST
+
+### Orbital Mechanics
+- `orbital.hohmann(mu, r1, r2)` - Hohmann transfer calculation
+- `orbital.velocity(mu, radius, sma=0)` - Orbital velocity
+- `orbital.period(mu, sma)` - Orbital period
+- `orbital.escape_velocity(mu, radius)` - Escape velocity

astroz-0.4.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+astroz/__init__.py,sha256=bVQmXRjQQDIjBs8wW8iGwT9LTy7LPNUB8qNhfPnbY_I,527
+astroz/__version__.py,sha256=pMtTmSUht-XtbR_7Doz6bsQqopJJd8rZ8I8zy2HwwoA,22
+astroz/_lib.py,sha256=FGADZSXmW5fRIr53H3RDzSEz-rK5lR1j2BTAwALv5Rg,3065
+astroz/coords.py,sha256=fYODTZ0ZqZ9tf8NjRo-2Dr7H2FOol0frMD0t45DgIlc,984
+astroz/exceptions.py,sha256=7FdJk0FENI3DZ0UJxBeouwmQAWExcWHHPkZsncq05ts,1000
+astroz/orbital.py,sha256=xSfXJPc_vwhkSKCk4GOQ-0R5yDKFDbwNNiR6-Cw_wFg,1191
+astroz/sgp4.py,sha256=efsOBmtYLLS8Z1MdcjyXiMKcV5cwDC9tkQqIw-UYAfs,2658
+astroz/tle.py,sha256=6OLdcLG_wSNJ3u8SL9JSoEvRxOBizKqwZ3MAV-s2b-I,1232
+astroz/lib/libastroz_c.so,sha256=xV8K7x_Jt2l_0r-ejVGuZMtmEaURszrFwZ4Hr15oXU0,276368
+astroz-0.4.1.dist-info/METADATA,sha256=XLsAGlFkB42qIs0F3rVL8oD0WEVp2ODBOMxVC7fQ328,3252
+astroz-0.4.1.dist-info/WHEEL,sha256=w_6alU7T_sBwGm5Vyu6GD3AOYNoPHJEZwBbFBO_bp5Q,113
+astroz-0.4.1.dist-info/top_level.txt,sha256=X8LWxpbPipvBmFB0vnafmfaz1WmkzU2MOyoeJX30Yig,12
+astroz-0.4.1.dist-info/RECORD,,

astroz-0.4.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_38_x86_64
+

astroz-0.4.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+astroz
+dist