Geopack-2008 2.2.1__py3-none-win_arm64.whl

geopack/__init__.py

@@ -0,0 +1,322 @@
+"""Geopack-2008 for Python.
+
+A Pythonic wrapper around the NativeAOT-built ``geopack`` shared library
+(magnetic field of the Earth, solar-terrestrial coordinate transforms). No .NET
+runtime is required at runtime.
+
+Typical usage::
+
+    import geopack
+
+    ctx = geopack.recalc(1997, 12, 16, 21, 0, 0, vx=-304, vy=13.78, vz=4)
+    b = ctx.igrf_gsw(1, 1, 1)          # (bx, by, bz) nT, GSW
+    r = ctx.gsw_to_geo(1, 1, 1)        # (x, y, z) Earth radii, GEO
+    ctx.close()
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import NamedTuple, Optional, Sequence, Union
+
+from . import _native
+from ._enums import CoordinateSystem, MagnetopausePosition
+from ._native import GeopackError
+
+__all__ = [
+    "GeopackError",
+    "CoordinateSystem",
+    "MagnetopausePosition",
+    "Vector3",
+    "Sun",
+    "MagnetopauseResult",
+    "Context",
+    "DEFAULT_SOLAR_WIND",
+    "recalc",
+    "sun",
+    "shu_mgnp",
+    "t96_mgnp",
+    "t89",
+    "__version__",
+]
+
+__version__ = "2.2.1"
+
+#: Default solar wind velocity (GSE, km/s) used when the caller does not provide one.
+DEFAULT_SOLAR_WIND = (-400.0, 0.0, 0.0)
+
+
+class Vector3(NamedTuple):
+    """A Cartesian vector in Earth radii (positions) or nT (fields).
+    
+    Attributes:
+        x: X component.
+        y: Y component.
+        z: Z component.
+    """
+
+    x: float
+    y: float
+    z: float
+
+
+class Sun(NamedTuple):
+    """Position of the Sun for a given UTC date/time.
+    
+    Attributes:
+        gst: Greenwich mean sidereal time in radians.
+        slong: Ecliptic longitude of the Sun in radians.
+        srasn: Right ascension of the Sun in radians.
+        sdec: Declination of the Sun in radians.
+    """
+
+    gst: float
+    slong: float
+    srasn: float
+    sdec: float
+
+
+class MagnetopauseResult(NamedTuple):
+    """Result of a magnetopause model evaluation.
+    
+    Attributes:
+        boundary: Nearest boundary point in GSW (Earth radii).
+        dist: Distance from the input point to the boundary (Earth radii).
+        position: Relative position of the point (Inside, Outside, NotDefined).
+    """
+
+    boundary: Vector3
+    dist: float
+    position: MagnetopausePosition
+
+
+class Context:
+    """A frozen computation context for a single UTC date/time.
+
+    Created by :func:`recalc`. All field and transform methods take coordinates
+    in the documented system and return plain ``(x, y, z)`` tuples. The context
+    is immutable on the native side and safe to share between threads.
+    """
+
+    __slots__ = ("_handle", "_closed")
+
+    def __init__(self, handle: int):
+        self._handle = handle
+        self._closed = False
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        """Release the native computation context. Idempotent."""
+        if not self._closed:
+            _native.context_release(self._handle)
+            self._closed = True
+
+    def __del__(self) -> None:  # pragma: no cover - interpreter shutdown
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __enter__(self) -> "Context":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("Geopack context has been closed")
+
+    # -- field models -------------------------------------------------------
+
+    def igrf_gsw(self, x: float, y: float, z: float) -> Vector3:
+        """IGRF magnetic field at ``(x, y, z)`` in GSW, returned in nT."""
+        self._check_open()
+        return Vector3(*_native.igrf_gsw(self._handle, x, y, z))
+
+    def dip(self, x: float, y: float, z: float) -> Vector3:
+        """Dipole magnetic field at ``(x, y, z)`` in GSW, returned in nT."""
+        self._check_open()
+        return Vector3(*_native.dip(self._handle, x, y, z))
+
+    def igrf_geo(self, r: float, theta: float, phi: float) -> Vector3:
+        """IGRF field in GEO spherical coordinates at radius ``r`` (Re),
+        colatitude ``theta`` and longitude ``phi`` (radians).
+
+        Returns the spherical components ``(Br, Btheta, Bphi)`` in nT.
+        """
+        self._check_open()
+        return Vector3(*_native.igrf_geo(self._handle, r, theta, phi))
+
+    # -- external field models ----------------------------------------------
+
+    @property
+    def psi(self) -> float:
+        """Dipole tilt angle (radians) for this context's date/time, as computed by Recalc."""
+        self._check_open()
+        return _native.context_psi(self._handle)
+
+    def t89(self, iopt: int, x: float, y: float, z: float, psi: Optional[float] = None) -> Vector3:
+        """Tsyganenko (1989) external field at ``(x, y, z)`` in GSW.
+
+        ``iopt`` is the disturbance-level index (1..7, maps to Kp intervals).
+        ``psi`` is the dipole tilt in radians and defaults to this context's tilt.
+        Returns the field vector in GSM (nT). Calls are serialized natively
+        because the model keeps static state (not thread-safe).
+        """
+        self._check_open()
+        if psi is None:
+            psi = self.psi
+        return Vector3(*_native.t89(iopt, psi, x, y, z))
+
+    # -- coordinate transforms (in -> out, Earth radii) ---------------------
+
+    def gsw_to_gse(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GSW to GSE."""
+        return self._transform(_native.gsw_to_gse, x, y, z)
+
+    def gse_to_gsw(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GSE to GSW."""
+        return self._transform(_native.gse_to_gsw, x, y, z)
+
+    def geo_to_mag(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GEO to MAG."""
+        return self._transform(_native.geo_to_mag, x, y, z)
+
+    def mag_to_geo(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from MAG to GEO."""
+        return self._transform(_native.mag_to_geo, x, y, z)
+
+    def gei_to_geo(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GEI to GEO."""
+        return self._transform(_native.gei_to_geo, x, y, z)
+
+    def geo_to_gei(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GEO to GEI."""
+        return self._transform(_native.geo_to_gei, x, y, z)
+
+    def mag_to_sm(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from MAG to SM."""
+        return self._transform(_native.mag_to_sm, x, y, z)
+
+    def sm_to_mag(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from SM to MAG."""
+        return self._transform(_native.sm_to_mag, x, y, z)
+
+    def sm_to_gsw(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from SM to GSW."""
+        return self._transform(_native.sm_to_gsw, x, y, z)
+
+    def gsw_to_sm(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GSW to SM."""
+        return self._transform(_native.gsw_to_sm, x, y, z)
+
+    def geo_to_gsw(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GEO to GSW."""
+        return self._transform(_native.geo_to_gsw, x, y, z)
+
+    def gsw_to_geo(self, x: float, y: float, z: float) -> Vector3:
+        """Transform Cartesian (x, y, z) from GSW to GEO."""
+        return self._transform(_native.gsw_to_geo, x, y, z)
+
+    def _transform(self, fn, x: float, y: float, z: float) -> Vector3:
+        self._check_open()
+        return Vector3(*fn(self._handle, x, y, z))
+
+
+def recalc(
+    date_or_year: Union[datetime, int],
+    month: Optional[int] = None,
+    day: Optional[int] = None,
+    hour: int = 0,
+    minute: int = 0,
+    second: int = 0,
+    vx: float = DEFAULT_SOLAR_WIND[0],
+    vy: float = DEFAULT_SOLAR_WIND[1],
+    vz: float = DEFAULT_SOLAR_WIND[2],
+) -> Context:
+    """Create a :class:`Context` for a UTC date/time and solar wind velocity.
+
+    ``date_or_year`` is either a ``datetime.datetime`` (then ``month``/``day``
+    must be omitted) or a bare year. The solar wind velocity defaults to
+    ``(-400, 0, 0)`` km/s (GSE) as in the original GEOPACK-2008.
+    """
+    if isinstance(date_or_year, datetime):
+        if month is not None or day is not None:
+            raise ValueError("pass either a datetime or (year, month, day), not both")
+        dt = date_or_year
+        year, month, day = dt.year, dt.month, dt.day
+        hour, minute, second = dt.hour, dt.minute, dt.second
+    else:
+        if month is None or day is None:
+            raise ValueError("month and day are required when a year is given")
+        year = date_or_year
+
+    handle = _native.context_create(
+        year, month, day, hour, minute, second, vx, vy, vz
+    )
+    return Context(handle)
+
+
+def sun(date_or_year: Union[datetime, int], month: Optional[int] = None, day: Optional[int] = None,
+        hour: int = 0, minute: int = 0, second: int = 0) -> Sun:
+    """Position of the Sun for a UTC date/time (see :func:`recalc`)."""
+    if isinstance(date_or_year, datetime):
+        if month is not None or day is not None:
+            raise ValueError("pass either a datetime or (year, month, day), not both")
+        dt = date_or_year
+        year, month, day = dt.year, dt.month, dt.day
+        hour, minute, second = dt.hour, dt.minute, dt.second
+    else:
+        if month is None or day is None:
+            raise ValueError("month and day are required when a year is given")
+        year = date_or_year
+
+    return Sun(*_native.sun(year, month, day, hour, minute, second))
+
+
+def shu_mgnp(
+    xn_pd: float, vel: float, bz_imf: float, x: float, y: float, z: float,
+) -> MagnetopauseResult:
+    """Shue et al. (1998) magnetopause model. Input in GSW (Re).
+
+    ``xn_pd`` is either the solar wind proton number density (per cm3) if
+    ``vel > 0``, or the solar wind ram pressure in nPa if ``vel < 0``.
+    ``vel`` is the velocity in km/s (a negative value signals that ``xn_pd``
+    is a pressure, not a density). ``bz_imf`` is the IMF Bz in nT.
+    ``(x, y, z)`` is the probe point in GSW.
+    """
+    mx, my, mz, dist, position = _native.shu_mgnp(xn_pd, vel, bz_imf, x, y, z)
+    return MagnetopauseResult(Vector3(mx, my, mz), dist, MagnetopausePosition(position))
+
+
+def t96_mgnp(xn_pd: float, vel: float, x: float, y: float, z: float) -> MagnetopauseResult:
+    """Tsyganenko 1996 magnetopause model. Input in GSW (Re).
+
+    ``xn_pd`` is either the solar wind proton number density (per cm3) if
+    ``vel > 0``, or the solar wind ram pressure in nPa if ``vel < 0``.
+    ``vel`` is the velocity in km/s (a negative value signals that ``xn_pd``
+    is a pressure, not a density). ``(x, y, z)`` is the probe point in GSW.
+    """
+    mx, my, mz, dist, position = _native.t96_mgnp(xn_pd, vel, x, y, z)
+    return MagnetopauseResult(Vector3(mx, my, mz), dist, MagnetopausePosition(position))
+
+
+def t89(
+    iopt: int,
+    psi: float,
+    x: float,
+    y: float,
+    z: float,
+    parmod: Optional[Sequence[float]] = None,
+) -> Vector3:
+    """Tsyganenko (1989) external field model. Input in GSW (Re).
+
+    ``iopt`` is the disturbance-level index (1..7, maps to Kp intervals).
+    ``psi`` is the dipole tilt angle in radians.
+    ``parmod`` is a dummy parameter array accepted for parity with the .NET
+    ``IT89.Calculate`` contract; it is not used by T89 and defaults to ``None``.
+    ``(x, y, z)`` is the probe point in GSW. Returns the field vector in GSM (nT).
+    """
+    return Vector3(*_native.t89(iopt, psi, x, y, z))

geopack/_enums.py

@@ -0,0 +1,30 @@
+"""Enumerations shared with the native Geopack ABI.
+
+The numeric values mirror the C# ``CoordinateSystem`` and
+``MagnetopausePosition`` enums so the integer codes crossing the C ABI stay
+unambiguous.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class CoordinateSystem(IntEnum):
+    """Geographic coordinate system codes (GEO = 0, GSW = 1, ...)."""
+
+    GEO = 0
+    GSW = 1
+    GSE = 2
+    MAG = 3
+    SM = 4
+    GEI = 5
+    GSM = 6
+
+
+class MagnetopausePosition(IntEnum):
+    """Position of a point relative to the magnetopause boundary."""
+
+    NotDefined = 0
+    Inside = 1
+    Outside = 2

geopack/_native.py

@@ -0,0 +1,322 @@
+"""Thin ctypes layer over the NativeAOT-built geopack shared library.
+
+The library exposes a flat C ABI (see src/Geopack.Native/GeopackNative.cs):
+
+  * every function returns an ``int`` error code (0 = success, non-zero = error);
+  * results are written into caller-provided out-pointers;
+  * a ``ComputationContext`` lives behind an opaque ``long`` handle created by
+    ``gp_context_create`` and released by ``gp_context_release``;
+  * the thread-local error message (UTF-8) is fetched with ``gp_last_error``.
+
+This module only knows how to cross the FFI boundary. The object-oriented,
+user-facing API lives in :mod:`geopack`.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import sys
+from typing import NamedTuple, Optional, Tuple
+
+#: Filenames to try, in order, per platform. The native build produces
+#: ``geopack.dylib`` on macOS, ``geopack.so`` on Linux and ``geopack.dll`` on
+#: Windows (no ``lib`` prefix). A GEOPACK_LIBRARY env var overrides all of them.
+_LIBRARY_NAMES = {
+    "darwin": ("geopack.dylib", "libgeopack.dylib"),
+    "linux": ("geopack.so", "libgeopack.so"),
+    "win32": ("geopack.dll",),
+}
+_FALLBACK_NAMES = ("geopack.dylib", "libgeopack.dylib", "geopack.so", "libgeopack.so", "geopack.dll")
+
+
+class GeopackError(Exception):
+    """Raised when the native library reports a non-zero error code."""
+
+
+def _find_library_path() -> str:
+    """Locate the native library, preferring the package directory."""
+    package_dir = os.path.dirname(os.path.abspath(__file__))
+    override = os.environ.get("GEOPACK_LIBRARY")
+    candidates = [override] if override else []
+    candidates += list(_LIBRARY_NAMES.get(sys.platform, ())) + list(_FALLBACK_NAMES)
+
+    for name in candidates:
+        if not name:
+            continue
+        path = os.path.join(package_dir, name)
+        if os.path.exists(path):
+            return path
+        if os.path.isabs(name) and os.path.exists(name):
+            return name
+
+    raise ImportError(
+        "Native geopack library not found. Build it with python/build_native.sh "
+        f"and place it next to this module. Tried: {', '.join(candidates)}"
+    )
+
+
+_lib = ctypes.CDLL(_find_library_path())
+
+# ---------------------------------------------------------------------------
+# Prototypes
+# ---------------------------------------------------------------------------
+
+_c_handle = ctypes.c_int64
+_c_double = ctypes.c_double
+_c_int = ctypes.c_int
+_p_handle = ctypes.POINTER(ctypes.c_int64)
+_p_double = ctypes.POINTER(ctypes.c_double)
+_p_byte = ctypes.POINTER(ctypes.c_byte)
+
+_lib.gp_context_create.argtypes = [
+    _c_int, _c_int, _c_int, _c_int, _c_int, _c_int,  # y mo d h mi s
+    _c_double, _c_double, _c_double,                  # vx vy vz
+    _p_handle,                                        # out handle
+]
+_lib.gp_context_create.restype = _c_int
+
+_lib.gp_context_release.argtypes = [_c_handle]
+_lib.gp_context_release.restype = None
+
+_lib.gp_last_error.argtypes = [_p_byte, _c_int]
+_lib.gp_last_error.restype = _c_int
+
+# Field models + transforms: (i64 ctx, double x, y, z, double* o1, o2, o3)
+_TRANSFORM_ARGTYPES = [
+    _c_handle,
+    _c_double, _c_double, _c_double,
+    _p_double, _p_double, _p_double,
+]
+
+_lib.gp_igrf_gsw.argtypes = _TRANSFORM_ARGTYPES
+_lib.gp_igrf_gsw.restype = _c_int
+_lib.gp_dip.argtypes = _TRANSFORM_ARGTYPES
+_lib.gp_dip.restype = _c_int
+
+_lib.gp_igrf_geo.argtypes = [
+    _c_handle,
+    _c_double, _c_double, _c_double,  # r theta phi
+    _p_double, _p_double, _p_double,  # out br bt bp
+]
+_lib.gp_igrf_geo.restype = _c_int
+
+_lib.gp_sun.argtypes = [
+    _c_int, _c_int, _c_int, _c_int, _c_int, _c_int,  # y mo d h mi s
+    _p_double, _p_double, _p_double, _p_double,      # out gst slong srasn sdec
+]
+_lib.gp_sun.restype = _c_int
+
+for _name in (
+    "gp_gsw_to_gse",
+    "gp_gse_to_gsw",
+    "gp_geo_to_mag",
+    "gp_mag_to_geo",
+    "gp_gei_to_geo",
+    "gp_geo_to_gei",
+    "gp_mag_to_sm",
+    "gp_sm_to_mag",
+    "gp_sm_to_gsw",
+    "gp_gsw_to_sm",
+    "gp_geo_to_gsw",
+    "gp_gsw_to_geo",
+):
+    getattr(_lib, _name).argtypes = _TRANSFORM_ARGTYPES
+    getattr(_lib, _name).restype = _c_int
+
+_lib.gp_shu_mgnp.argtypes = [
+    _c_double, _c_double, _c_double,  # xnPd vel bzImf
+    _c_double, _c_double, _c_double,  # x y z
+    _p_double, _p_double, _p_double,  # out mx my mz
+    _p_double,                        # out dist
+    _p_int := ctypes.POINTER(ctypes.c_int),
+]
+_lib.gp_shu_mgnp.restype = _c_int
+
+_lib.gp_t96_mgnp.argtypes = [
+    _c_double, _c_double,             # xnPd vel
+    _c_double, _c_double, _c_double,  # x y z
+    _p_double, _p_double, _p_double,  # out mx my mz
+    _p_double,                        # out dist
+    ctypes.POINTER(ctypes.c_int),
+]
+_lib.gp_t96_mgnp.restype = _c_int
+
+# External field models (context-free, input GSW, output GSM)
+_lib.gp_t89.argtypes = [
+    _c_int, _c_double, _c_double, _c_double, _c_double,  # iopt psi x y z
+    _p_double, _p_double, _p_double,                     # out bx by bz
+]
+_lib.gp_t89.restype = _c_int
+
+# Context dipole tilt (radians), computed by Recalc
+_lib.gp_context_psi.argtypes = [_c_handle, _p_double]
+_lib.gp_context_psi.restype = _c_int
+
+del _name  # loop variable cleanup
+
+# ---------------------------------------------------------------------------
+# Error plumbing
+# ---------------------------------------------------------------------------
+
+
+def _last_error() -> Optional[str]:
+    """Read and clear the thread-local error message set by the native side."""
+    # Probe: null buffer + zero capacity returns the UTF-8 byte length without
+    # clearing the stored message.
+    size = _lib.gp_last_error(None, 0)
+    if size <= 0:
+        return None
+    buf = ctypes.create_string_buffer(size + 1)
+    _lib.gp_last_error(ctypes.cast(buf, _p_byte), size + 1)
+    return buf.value.decode("utf-8", errors="replace")
+
+
+def _check(rc: int) -> None:
+    if rc != 0:
+        raise GeopackError(_last_error() or f"native geopack error (code {rc})")
+
+
+# ---------------------------------------------------------------------------
+# Raw wrappers
+# ---------------------------------------------------------------------------
+
+
+def context_create(
+    year: int, month: int, day: int, hour: int, minute: int, second: int,
+    vx: float, vy: float, vz: float,
+) -> int:
+    handle = ctypes.c_int64()
+    rc = _lib.gp_context_create(
+        year, month, day, hour, minute, second, vx, vy, vz, ctypes.byref(handle)
+    )
+    _check(rc)
+    return handle.value
+
+
+def context_release(handle: int) -> None:
+    _lib.gp_context_release(handle)
+
+
+def igrf_gsw(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_igrf_gsw, handle, x, y, z)
+
+
+def dip(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_dip, handle, x, y, z)
+
+
+def igrf_geo(handle: int, r: float, theta: float, phi: float) -> Tuple[float, float, float]:
+    bx, bt, bp = ctypes.c_double(), ctypes.c_double(), ctypes.c_double()
+    rc = _lib.gp_igrf_geo(
+        handle, r, theta, phi, ctypes.byref(bx), ctypes.byref(bt), ctypes.byref(bp)
+    )
+    _check(rc)
+    return bx.value, bt.value, bp.value
+
+
+def sun(
+    year: int, month: int, day: int, hour: int, minute: int, second: int,
+) -> Tuple[float, float, float, float]:
+    gst, slong, srasn, sdec = (ctypes.c_double() for _ in range(4))
+    rc = _lib.gp_sun(
+        year, month, day, hour, minute, second,
+        ctypes.byref(gst), ctypes.byref(slong), ctypes.byref(srasn), ctypes.byref(sdec),
+    )
+    _check(rc)
+    return gst.value, slong.value, srasn.value, sdec.value
+
+
+def _call_vector(fn, handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    ox, oy, oz = ctypes.c_double(), ctypes.c_double(), ctypes.c_double()
+    rc = fn(handle, x, y, z, ctypes.byref(ox), ctypes.byref(oy), ctypes.byref(oz))
+    _check(rc)
+    return ox.value, oy.value, oz.value
+
+
+# Coordinate transforms: (long ctx, double x, y, z) -> (ox, oy, oz)
+def gsw_to_gse(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_gsw_to_gse, handle, x, y, z)
+
+
+def gse_to_gsw(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_gse_to_gsw, handle, x, y, z)
+
+
+def geo_to_mag(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_geo_to_mag, handle, x, y, z)
+
+
+def mag_to_geo(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_mag_to_geo, handle, x, y, z)
+
+
+def gei_to_geo(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_gei_to_geo, handle, x, y, z)
+
+
+def geo_to_gei(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_geo_to_gei, handle, x, y, z)
+
+
+def mag_to_sm(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_mag_to_sm, handle, x, y, z)
+
+
+def sm_to_mag(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_sm_to_mag, handle, x, y, z)
+
+
+def sm_to_gsw(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_sm_to_gsw, handle, x, y, z)
+
+
+def gsw_to_sm(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_gsw_to_sm, handle, x, y, z)
+
+
+def geo_to_gsw(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_geo_to_gsw, handle, x, y, z)
+
+
+def gsw_to_geo(handle: int, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    return _call_vector(_lib.gp_gsw_to_geo, handle, x, y, z)
+
+
+def shu_mgnp(
+    xn_pd: float, vel: float, bz_imf: float, x: float, y: float, z: float,
+) -> Tuple[float, float, float, float, int]:
+    return _call_mgnp(_lib.gp_shu_mgnp, xn_pd, vel, bz_imf, x, y, z)
+
+
+def t96_mgnp(xn_pd: float, vel: float, x: float, y: float, z: float) -> Tuple[float, float, float, float, int]:
+    return _call_mgnp(_lib.gp_t96_mgnp, xn_pd, vel, x, y, z)
+
+
+def _call_mgnp(fn, *args: float) -> Tuple[float, float, float, float, int]:
+    mx, my, mz, dist = (ctypes.c_double() for _ in range(4))
+    position = ctypes.c_int()
+    rc = fn(
+        *args,
+        ctypes.byref(mx), ctypes.byref(my), ctypes.byref(mz),
+        ctypes.byref(dist), ctypes.byref(position),
+    )
+    _check(rc)
+    return mx.value, my.value, mz.value, dist.value, position.value
+
+
+def t89(iopt: int, psi: float, x: float, y: float, z: float) -> Tuple[float, float, float]:
+    """Tsyganenko (1989) external field at (x, y, z) in GSW, GSM components in nT."""
+    bx, by, bz = ctypes.c_double(), ctypes.c_double(), ctypes.c_double()
+    rc = _lib.gp_t89(iopt, psi, x, y, z, ctypes.byref(bx), ctypes.byref(by), ctypes.byref(bz))
+    _check(rc)
+    return bx.value, by.value, bz.value
+
+
+def context_psi(handle: int) -> float:
+    """Dipole tilt (radians) for the given context, as computed by Recalc."""
+    psi = ctypes.c_double()
+    rc = _lib.gp_context_psi(handle, ctypes.byref(psi))
+    _check(rc)
+    return psi.value

geopack_2008-2.2.1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: Geopack-2008
+Version: 2.2.1
+Summary: Geopack-2008 magnetospheric field model and solar-terrestrial coordinate transforms (NativeAOT bindings)
+Author: Aurora Science Hub
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Aurora-Science-Hub/Geopack
+Project-URL: Repository, https://github.com/Aurora-Science-Hub/Geopack
+Project-URL: Issues, https://github.com/Aurora-Science-Hub/Geopack/issues
+Project-URL: Changelog, https://github.com/Aurora-Science-Hub/Geopack/blob/main/CHANGELOG.md
+Keywords: geopack,space physics,geophysics,magnetosphere,magnetic field,igrf,tsyganenko,t89,magnetopause,solar wind,coordinate-transforms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Geopack-2008 — GEOPACK-2008 geomagnetic field model for Python
+
+[![Python](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python&label=Python)](https://www.python.org/)
+[![Python Package](https://github.com/Aurora-Science-Hub/Geopack/actions/workflows/python-package.yml/badge.svg)](https://github.com/Aurora-Science-Hub/Geopack/actions/workflows/python-package.yml)
+[![License: GPL v3+](https://img.shields.io/badge/License-GPLv3+-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![GitHub Stars](https://img.shields.io/github/stars/Aurora-Science-Hub/Geopack?style=social)](https://github.com/Aurora-Science-Hub/Geopack)
+
+**Geopack-2008** (imported as `geopack`) is a self-contained, zero-dependency Python package for the
+**GEOPACK-2008** geomagnetic field model: the **International Geomagnetic
+Reference Field (IGRF)**, the **dipole field**, the **Tsyganenko (1989)
+external field model (T89)**, the **Shue et al. (1998) and Tsyganenko (1996)
+magnetopause models**, the **Sun position** computation, and the standard
+**solar-terrestrial coordinate transforms** (GEO, GSW, GSE, SM, MAG, GEI, GSM).
+
+It is a Python binding over a [C# port of GEOPACK-2008](https://github.com/Aurora-Science-Hub/Geopack)
+compiled ahead-of-time with NativeAOT into a shared library (`geopack.dylib` /
+`geopack.so` / `geopack.dll`), loaded through `ctypes` from the Python standard
+library. No .NET runtime is required at runtime, and there are no Python
+dependencies (no NumPy/SciPy).
+
+- **Double precision**: accuracy matches the original Fortran code to 12–13 decimal digits
+- **Standard library only** — no third-party runtime dependencies
+- **Thread-safe** immutable computation contexts
+- **Platform wheels** for Linux (x64/arm64), Windows (x64/arm64) and macOS (arm64)
+
+## Install
+
+Build the wheel for your platform (requires .NET SDK 10 + a C toolchain) and
+`pip install` it. On macOS/Linux:
+
+```bash
+./python/build_wheel.sh
+pip install python/dist/geopack_2008-*.whl
+```
+
+On Windows (cmd):
+
+```bat
+.\python\build_wheel.bat
+pip install python\dist\geopack_2008-*.whl
+```
+
+The scripts build the native library for the host platform only; for another
+OS/arch, build the wheel on that machine (NativeAOT does not cross-compile).
+
+## Usage
+
+```python
+import geopack
+
+ctx = geopack.recalc(1997, 12, 16, 21, 0, 0, vx=-304, vy=13.78, vz=4)
+b = ctx.igrf_gsw(1, 1, 1)     # (bx, by, bz) nT in GSW
+r = ctx.gsw_to_geo(1, 1, 1)   # (x, y, z) Earth radii in GEO
+ctx.close()
+
+# A datetime works too, and contexts are context managers:
+with geopack.recalc(datetime(1997, 12, 16, 21, 0), vx=-304, vy=13.78, vz=4) as ctx:
+    b = ctx.igrf_gsw(1, 1, 1)
+
+s = geopack.sun(1997, 12, 16, 21, 0, 0)   # (gst, slong, srasn, sdec), radians
+
+mp = geopack.shu_mgnp(xn_pd=2.0, vel=400.0, bz_imf=0.0, x=10, y=0, z=0)
+print(mp.boundary, mp.dist, mp.position)  # Vector3, float, MagnetopausePosition
+
+# Tsyganenko (1989) external field — input GSW, output GSM (nT):
+b = geopack.t89(iopt=3, psi=ctx.psi, x=-6.6, y=0, z=0)
+b = ctx.t89(iopt=3, x=-6.6, y=0, z=0)     # psi defaults to ctx.psi
+```
+
+A runnable example with all of the above (sun position, IGRF/dipole fields,
+coordinate transforms, magnetopause models) is in
+[`python/example.py`](example.py):
+
+```bash
+python3 python/example.py
+```
+
+## Implemented models and coordinate systems
+
+| Category | Model | Python API |
+| --- | --- | --- |
+| Internal field | IGRF (geomagnetic main field) | `Context.igrf_gsw`, `Context.igrf_geo` |
+| Internal field | Dipole | `Context.dip` |
+| External field | Tsyganenko (1989) — T89 | `Context.t89`, `geopack.t89` |
+| Magnetopause | Shue et al. (1998) | `geopack.shu_mgnp` |
+| Magnetopause | Tsyganenko (1996) | `geopack.t96_mgnp` |
+| Sun position | Greenwich sidereal time, solar ephemeris | `geopack.sun` |
+
+Supported coordinate systems (see `CoordinateSystem`): **GEO** (geographic),
+**GSW** (geocentric solar wind), **GSE** (geocentric solar ecliptic),
+**SM** (solar magnetic), **MAG** (geomagnetic), **GEI** (geocentric solar
+equatorial inertial) and **GSM** (geocentric solar magnetospheric).
+
+## API
+
+All coordinates are in Earth radii; magnetic fields are in nT; angles are in
+radians; solar wind velocity is in km/s.
+
+* `recalc(date_or_year, month=None, day=None, hour=0, minute=0, second=0, vx=-400, vy=0, vz=0) -> Context`
+* `Context` methods:
+  * fields: `igrf_gsw(x,y,z)`, `dip(x,y,z)`, `igrf_geo(r,theta,phi)`,
+    `t89(iopt,x,y,z, psi=None)`, property `psi` (dipole tilt, radians)
+  * transforms: `gsw_to_gse`, `gse_to_gsw`, `geo_to_mag`, `mag_to_geo`,
+    `gei_to_geo`, `geo_to_gei`, `mag_to_sm`, `sm_to_mag`, `sm_to_gsw`,
+    `gsw_to_sm`, `geo_to_gsw`, `gsw_to_geo` — each `(x,y,z) -> (x,y,z)`
+  * lifecycle: `close()`, context manager
+* `sun(...) -> Sun(gst, slong, srasn, sdec)` — no context needed
+* `shu_mgnp(xn_pd, vel, bz_imf, x, y, z)` and `t96_mgnp(xn_pd, vel, x, y, z)`
+  return `MagnetopauseResult(boundary, dist, position)` — no context needed
+* `t89(iopt, psi, x, y, z, parmod=None) -> Vector3` — Tsyganenko (1989) external
+  field, input GSW, output GSM (nT); `parmod` is a dummy accepted for parity with
+  the .NET `IT89.Calculate` contract (unused) — no context needed
+
+`GEOPACK_LIBRARY` environment variable points the loader at a specific library
+path if the packaged one is not present.
+
+## How to Cite
+
+If you use this software in your research, please cite it — see the
+[`How to Cite`](https://github.com/Aurora-Science-Hub/Geopack#how-to-cite)
+section of the main repository README (APA and BibTeX entries with a Zenodo DOI).
+
+## References
+
+The implementation is based on the GEOPACK-2008 library and the following
+scientific works:
+
+1. **Tsyganenko, N. A.** (1989). *A magnetospheric magnetic field model with a warped tail current sheet*. Planetary and Space Science, 37(1), 5–20. https://doi.org/10.1016/0032-0633(89)90066-4
+
+2. **Tsyganenko, N. A.** (1996). *Effects of the solar wind conditions on the global magnetospheric configuration as deduced from data-based field models*. ESA SP-389, 181–185.
+
+3. **Shue, J.-H., et al.** (1998). *Magnetopause location under extreme solar wind conditions*. Journal of Geophysical Research, 103(A8), 17691–17700. https://doi.org/10.1029/98JA01103
+
+4. **Hapgood, M. A.** (1992). *Space physics coordinate transformations: A user guide*. Planetary and Space Science, 40(5), 711–717. https://doi.org/10.1016/0032-0633(92)90012-D
+
+5. **Tsyganenko, N. A.** (2002). *A model of the near magnetosphere with a dawn-dusk asymmetry 1. Mathematical structure*. Journal of Geophysical Research, 107(A8). https://doi.org/10.1029/2001JA000219
+
+6. **Tsyganenko, N. A., & Sitnov, M. I.** (2005). *Modeling the dynamics of the inner magnetosphere during strong geomagnetic storms*. Journal of Geophysical Research: Space Physics, 110(A3), A03208. https://doi.org/10.1029/2004JA010798

geopack_2008-2.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+geopack/__init__.py,sha256=1hLWM4nJnaWuQKcM7045kjHCOpbziYHlfmNyZ5vePiM,11921
+geopack/_enums.py,sha256=o2bZ15IU2J_HMg5hipvFo7HESw8UoHCCBnBdabGE4UE,644
+geopack/_native.py,sha256=IoKTS0-oPK-eaAGIL_mBgUQCM197NKbmRv9ftjtxM2Y,11537
+geopack/geopack.dll,sha256=fBtBC3fma0adAqR4jxedft2opvzugGlbanBT6JZ7O1c,1486336
+geopack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+geopack_2008-2.2.1.dist-info/METADATA,sha256=oU2_f9zj05h_bYo2sAA1gItTtTsFRjgvg8JoBztCrbA,8472
+geopack_2008-2.2.1.dist-info/WHEEL,sha256=QE-niYB-ZRQVWczDB301OM3v6K9Rt_4BEsv6l0aMysk,98
+geopack_2008-2.2.1.dist-info/top_level.txt,sha256=5wOBhK4wkKyuE1EMPgWf9CTiOAWArRHC3Mk3e0nEbfk,8
+geopack_2008-2.2.1.dist-info/RECORD,,

geopack_2008-2.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_arm64
+

geopack_2008-2.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+geopack