sidereon 2.0.0__tar.gz → 2.1.0__tar.gz

{sidereon-2.0.0 → sidereon-2.1.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the Sidereon Python interface are documented here.
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-05
+
+### Added
+
+- Configurable SP3 coverage-gap interpolation policy (`gap_threshold_factor`, default 1.5):
+  - `load_sp3(..., gap_threshold_factor=None)` loads SP3 products with an explicit gap threshold factor.
+  - `Sp3.gap_threshold_factor` reads the active factor; `Sp3.with_interpolation_options(factor)` returns a copy with the updated policy.
+  - `Sp3.check_continuity(..., gap_threshold_factor=None)` and `Sp3.continuity_verdict(..., gap_threshold_factor=None)` accept an optional gap threshold factor override.
+  - `PreciseEphemerisSamples.from_samples(..., gap_threshold_factor=None)` preserves or overrides the factor; `PreciseEphemerisSamples.gap_threshold_factor` and `with_interpolation_options(factor)` inspect and update it.
+  - `PreciseEphemerisInterpolant.from_sp3(..., gap_threshold_factor=None)`, `from_samples(..., gap_threshold_factor=None)`, and `from_precise_ephemeris_samples(..., gap_threshold_factor=None)` accept an optional factor; `PreciseEphemerisInterpolant.gap_threshold_factor` and `with_interpolation_options(factor)` inspect and update it.
+  - `Sp3.precise_interpolant_artifact_bytes(gap_threshold_factor=None)`, `build_precise_interpolant_artifact_bytes(sp3, gap_threshold_factor=None)`, and `PreciseInterpolantArtifact.gap_threshold_factor` serialize, build, and inspect precomputed artifacts with the interpolation policy.
+
+### Changed
+
+- Engine update: sidereon 2.1.0 / sidereon-core 2.1.0. Additive upstream release: the SP3 coverage-gap threshold is now a validated, product-carried policy (`Sp3InterpolationOptions`, default 1.5 and bit-identical to before), the SP3 window-scoped continuity reach is derived from the interpolator's actual selectable node spans, and RINEX 4 CNAV week/TOW round trips are stable at the week boundary.
+
 ## [2.0.0] - 2026-09-03
 
 ### Changed

{sidereon-2.0.0 → sidereon-2.1.0}/Cargo.lock

@@ -588,9 +588,9 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "sidereon"
-version = "2.0.0"
+version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7aaadf9ee0b3917f63996d4183cafe03937c352c715a9135681dae1aa3e81325"
+checksum = "34f5f297673a6c59dd5f22fa93124f8502a1ffa39b4c5c3c2f75d764a2ead2d0"
 dependencies = [
  "crc32fast",
  "flate2",
@@ -599,9 +599,9 @@ dependencies = [
 
 [[package]]
 name = "sidereon-core"
-version = "2.0.0"
+version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b3fe43597d67daf76b3e030cee2de20cea5b94e8044189e97b49f0cdf14ba03"
+checksum = "f6dea92a59883415b579bded7065f8f233c4d069a1677c629685eef7b6620d17"
 dependencies = [
  "approx",
  "cc",
@@ -622,7 +622,7 @@ dependencies = [
 
 [[package]]
 name = "sidereon-py"
-version = "2.0.0"
+version = "2.1.0"
 dependencies = [
  "nalgebra",
  "numpy",

{sidereon-2.0.0 → sidereon-2.1.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sidereon-py"
-version = "2.0.0"
+version = "2.1.0"
 authors = []
 edition = "2021"
 description = "Python (PyO3) bindings over the sidereon ergonomic API: SP3 loading and SPP/RTK/PPP positioning solves"
@@ -21,8 +21,8 @@ exact-cache-test-failpoints = ["sidereon-core/exact-cache-test-failpoints"]
 # The thin ergonomic engine surface this binding marshals to. No modeling logic
 # lives here: every solve delegates to a `sidereon` entry point, which in turn
 # delegates to `sidereon-core`.
-sidereon = "2.0.0"
-sidereon-core = { version = "2.0.0", features = ["mmap"] }
+sidereon = "2.1.0"
+sidereon-core = { version = "2.1.0", features = ["mmap"] }
 # The standalone general-purpose trust-region least-squares solver: a data-driven
 # `least_squares` whose residual and Jacobian are evaluated entirely in Rust, so
 # no per-iteration Python callback is paid.

{sidereon-2.0.0 → sidereon-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sidereon
-Version: 2.0.0
+Version: 2.1.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
@@ -157,9 +157,12 @@ The Python package mirrors the full breadth of the engine.
   decode and SSR store helpers, and NTRIP client stream handling.
 - **Ephemeris and time:** broadcast ephemeris and precise SP3 products, JPL SPK
   (DAF/.bsp) kernels, uniform satellite-state sampling across broadcast and
-  precise sources with batched multi-satellite interpolation, scale-aware time
-  (UTC/TAI/TT/TDB/UT1 and the GNSS system times) with leap-second handling,
-  and Earth orientation parameters (EOP).
+  precise sources with batched multi-satellite interpolation, configurable
+  SP3 coverage-gap interpolation policy (`gap_threshold_factor`, default 1.5)
+  and window-scoped continuity verification options (`check_continuity` and
+  `continuity_verdict`), scale-aware time (UTC/TAI/TT/TDB/UT1 and the GNSS
+  system times) with leap-second handling, and Earth orientation parameters
+  (EOP).
 - **Timing and clocks:** Allan-family stability analysis (ADEV/MDEV/HDEV/TDEV)
   and power-law clock-noise identification with a five-coefficient fit
   (IEEE 1139).

{sidereon-2.0.0 → sidereon-2.1.0}/README.md

@@ -138,9 +138,12 @@ The Python package mirrors the full breadth of the engine.
   decode and SSR store helpers, and NTRIP client stream handling.
 - **Ephemeris and time:** broadcast ephemeris and precise SP3 products, JPL SPK
   (DAF/.bsp) kernels, uniform satellite-state sampling across broadcast and
-  precise sources with batched multi-satellite interpolation, scale-aware time
-  (UTC/TAI/TT/TDB/UT1 and the GNSS system times) with leap-second handling,
-  and Earth orientation parameters (EOP).
+  precise sources with batched multi-satellite interpolation, configurable
+  SP3 coverage-gap interpolation policy (`gap_threshold_factor`, default 1.5)
+  and window-scoped continuity verification options (`check_continuity` and
+  `continuity_verdict`), scale-aware time (UTC/TAI/TT/TDB/UT1 and the GNSS
+  system times) with leap-second handling, and Earth orientation parameters
+  (EOP).
 - **Timing and clocks:** Allan-family stability analysis (ADEV/MDEV/HDEV/TDEV)
   and power-law clock-noise identification with a five-coefficient fit
   (IEEE 1139).

{sidereon-2.0.0 → sidereon-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sidereon"
-version = "2.0.0"
+version = "2.1.0"
 description = "Python (PyO3) bindings over the sidereon engine: SP3 loading and SPP/RTK/PPP positioning solves"
 readme = "README.md"
 license = { text = "MIT" }

{sidereon-2.0.0 → sidereon-2.1.0}/python/sidereon/__init__.pyi

@@ -110,6 +110,24 @@ class Sp3:
     @property
     def satellites(self) -> list[str]: ...
     @property
+    def gap_threshold_factor(self) -> float: ...
+    def with_interpolation_options(self, gap_threshold_factor: float) -> Sp3: ...
+    def check_continuity(
+        self,
+        orbit_class: str | None = ...,
+        residual_tolerance_m: float | None = ...,
+        gap_threshold_factor: float | None = ...,
+    ) -> dict[str, Any]: ...
+    def stencil_extent(self) -> tuple[float, float]: ...
+    def continuity_verdict(
+        self,
+        from_j2000_s: float,
+        through_j2000_s: float,
+        orbit_class: str | None = ...,
+        residual_tolerance_m: float | None = ...,
+        gap_threshold_factor: float | None = ...,
+    ) -> dict[str, Any]: ...
+    @property
     def epochs_j2000_seconds(self) -> npt.NDArray[np.float64]: ...
     def interpolate(
         self, satellite: str, j2000_seconds: npt.NDArray[np.float64]
@@ -118,7 +136,9 @@ class Sp3:
     def prediction_summary(self) -> Sp3PredictionSummary: ...
     def to_sp3_string(self) -> str: ...
     def precise_ephemeris_samples(self) -> list[PreciseEphemerisSample]: ...
-    def precise_interpolant_artifact_bytes(self) -> bytes: ...
+    def precise_interpolant_artifact_bytes(
+        self, gap_threshold_factor: float | None = ...
+    ) -> bytes: ...
     def __repr__(self) -> str: ...
 
 class ExactSp3ValidationError(ValueError): ...
@@ -248,6 +268,12 @@ class PreciseEphemerisSamples:
     @staticmethod
     def from_samples(
         samples: Sequence[PreciseEphemerisSample],
+        gap_threshold_factor: float | None = ...,
+    ) -> PreciseEphemerisSamples: ...
+    @property
+    def gap_threshold_factor(self) -> float: ...
+    def with_interpolation_options(
+        self, gap_threshold_factor: float
     ) -> PreciseEphemerisSamples: ...
     @property
     def time_scale(self) -> TimeScale: ...
@@ -523,14 +549,24 @@ class PreciseEphemerisInterpolant:
     """Reusable precise-ephemeris interpolant with cached per-satellite nodes."""
 
     @staticmethod
-    def from_sp3(source: Sp3) -> PreciseEphemerisInterpolant: ...
+    def from_sp3(
+        source: Sp3,
+        gap_threshold_factor: float | None = ...,
+    ) -> PreciseEphemerisInterpolant: ...
     @staticmethod
     def from_samples(
         samples: Sequence[PreciseEphemerisSample],
+        gap_threshold_factor: float | None = ...,
     ) -> PreciseEphemerisInterpolant: ...
     @staticmethod
     def from_precise_ephemeris_samples(
         source: PreciseEphemerisSamples,
+        gap_threshold_factor: float | None = ...,
+    ) -> PreciseEphemerisInterpolant: ...
+    @property
+    def gap_threshold_factor(self) -> float: ...
+    def with_interpolation_options(
+        self, gap_threshold_factor: float
     ) -> PreciseEphemerisInterpolant: ...
     @property
     def time_scale(self) -> TimeScale: ...
@@ -568,6 +604,8 @@ class PreciseInterpolantArtifact:
     def digest_provenance(self) -> Literal["verified", "attested"]: ...
     def verify(self) -> None: ...
     @property
+    def gap_threshold_factor(self) -> float: ...
+    @property
     def time_scale(self) -> TimeScale: ...
     @property
     def satellites(self) -> list[str]: ...
@@ -4955,13 +4993,19 @@ def leap_second_table_info() -> LeapSecondTable: ...
 def ut1_coverage_info() -> Ut1Coverage: ...
 def timescale_offset(from_: TimeScale, to: TimeScale) -> float: ...
 def timescale_offset_at(from_: TimeScale, to: TimeScale, utc_jd: float) -> float: ...
-def load_sp3(source: bytes | bytearray | str | os.PathLike[str]) -> Sp3: ...
+def load_sp3(
+    source: bytes | bytearray | str | os.PathLike[str],
+    gap_threshold_factor: float | None = ...,
+) -> Sp3: ...
 def parse_exact_sp3(
     source: bytes | bytearray | str | os.PathLike[str],
     request: ExactSp3Request,
 ) -> tuple[Sp3, ExactSp3Coverage]: ...
 def validate_exact_sp3(sp3: Sp3, request: ExactSp3Request) -> ExactSp3Coverage: ...
-def build_precise_interpolant_artifact_bytes(sp3: Sp3) -> bytes: ...
+def build_precise_interpolant_artifact_bytes(
+    sp3: Sp3,
+    gap_threshold_factor: float | None = ...,
+) -> bytes: ...
 def observable_states_at_j2000_s(
     source: (
         Sp3 | PreciseEphemerisSamples | PreciseEphemerisInterpolant | BroadcastEphemeris

{sidereon-2.0.0 → sidereon-2.1.0}/src/ephemeris.rs

@@ -34,7 +34,8 @@ use sidereon_core::ephemeris::{
 };
 use sidereon_core::ephemeris::{
     check_continuity, ContinuityDefect, ContinuityOptions, EpochWindow, MergeContinuityViolation,
-    OrbitClass, SpeedBound, StencilExtent, WindowContinuityDecision, WindowContinuityVerdict,
+    OrbitClass, Sp3InterpolationOptions, SpeedBound, StencilExtent, WindowContinuityDecision,
+    WindowContinuityVerdict,
 };
 use sidereon_core::DigestProvenance;
 use sidereon_core::Error as CoreError;
@@ -137,6 +138,7 @@ fn parse_sat(token: &str) -> PyResult<GnssSatelliteId> {
 fn continuity_options(
     orbit_class: Option<&str>,
     residual_tolerance_m: Option<f64>,
+    gap_threshold_factor: Option<f64>,
 ) -> PyResult<ContinuityOptions> {
     let speed_bound = match orbit_class {
         None => None,
@@ -152,6 +154,11 @@ fn continuity_options(
     let mut options = ContinuityOptions::new(speed_bound, residual_tolerance_m);
     options.speed_bound = speed_bound;
     options.residual_tolerance_m = residual_tolerance_m;
+    if let Some(factor) = gap_threshold_factor {
+        let interpolation = Sp3InterpolationOptions::new(factor)
+            .map_err(|error| PyValueError::new_err(error.to_string()))?;
+        options = options.with_interpolation_options(interpolation);
+    }
     Ok(options)
 }
 
@@ -307,6 +314,21 @@ impl PySp3 {
             .collect()
     }
 
+    /// SP3 interpolation gap threshold factor carried by this product.
+    #[getter]
+    fn gap_threshold_factor(&self) -> f64 {
+        self.inner.interpolation_options().gap_threshold_factor()
+    }
+
+    /// Return a copy of this product with an explicit gap threshold factor.
+    fn with_interpolation_options(&self, gap_threshold_factor: f64) -> PyResult<Self> {
+        let options = Sp3InterpolationOptions::new(gap_threshold_factor)
+            .map_err(|error| PyValueError::new_err(error.to_string()))?;
+        Ok(Self {
+            inner: self.inner.clone().with_interpolation_options(options),
+        })
+    }
+
     /// The product's parsed epochs as seconds since J2000, in the file's own time
     /// scale, ascending, as a numpy `(n,)` `float64` array.
     ///
@@ -330,21 +352,28 @@ impl PySp3 {
     /// `orbit_class` is one of `"meo_gnss"` (default), `"geosynchronous"`,
     /// `"leo"`, or `None` to disable the speed gate.
     /// `residual_tolerance_m` enables the residual check; `None` disables it.
+    /// `gap_threshold_factor` configures the hold-out interpolation policy;
+    /// `None` leaves the core default (1.5).
     ///
     /// Returns a dict with `defects`, `attested`, and the counts of what was
     /// examined, so "checked and clean" stays distinguishable from "not
     /// checked". This reports rather than refuses: whether a product with
     /// defects is acceptable is the caller's decision.
-    #[pyo3(signature = (orbit_class = "meo_gnss", residual_tolerance_m = Some(1.0)))]
+    #[pyo3(signature = (
+        orbit_class = "meo_gnss",
+        residual_tolerance_m = Some(1.0),
+        gap_threshold_factor = None,
+    ))]
     fn check_continuity(
         &self,
         py: Python<'_>,
         orbit_class: Option<&str>,
         residual_tolerance_m: Option<f64>,
+        gap_threshold_factor: Option<f64>,
     ) -> PyResult<PyObject> {
         let report = check_continuity(
             &self.inner.precise_ephemeris_samples(),
-            &continuity_options(orbit_class, residual_tolerance_m)?,
+            &continuity_options(orbit_class, residual_tolerance_m, gap_threshold_factor)?,
         );
 
         let defects = continuity_defects_to_list(py, &report.defects)?;
@@ -377,6 +406,7 @@ impl PySp3 {
         through_j2000_s,
         orbit_class = "meo_gnss",
         residual_tolerance_m = Some(1.0),
+        gap_threshold_factor = None,
     ))]
     fn continuity_verdict(
         &self,
@@ -385,6 +415,7 @@ impl PySp3 {
         through_j2000_s: f64,
         orbit_class: Option<&str>,
         residual_tolerance_m: Option<f64>,
+        gap_threshold_factor: Option<f64>,
     ) -> PyResult<PyObject> {
         let window = EpochWindow::new(from_j2000_s, through_j2000_s)
             .map_err(|error| PyValueError::new_err(error.to_string()))?;
@@ -392,7 +423,7 @@ impl PySp3 {
             .map_err(|error| PyValueError::new_err(error.to_string()))?;
         let report = check_continuity(
             &self.inner.precise_ephemeris_samples(),
-            &continuity_options(orbit_class, residual_tolerance_m)?,
+            &continuity_options(orbit_class, residual_tolerance_m, gap_threshold_factor)?,
         );
         continuity_verdict_to_py(py, report.verdict_for_window(window, stencil))
     }
@@ -528,12 +559,19 @@ impl PySp3 {
     }
 
     /// Build deterministic memory-mappable precise-interpolant artifact bytes.
+    #[pyo3(signature = (gap_threshold_factor = None))]
     fn precise_interpolant_artifact_bytes<'py>(
         &self,
         py: Python<'py>,
+        gap_threshold_factor: Option<f64>,
     ) -> PyResult<Bound<'py, PyBytes>> {
-        let bytes = self
-            .inner
+        let mut product = self.inner.clone();
+        if let Some(factor) = gap_threshold_factor {
+            let options = Sp3InterpolationOptions::new(factor)
+                .map_err(|e| PyValueError::new_err(e.to_string()))?;
+            product = product.with_interpolation_options(options);
+        }
+        let bytes = product
             .precise_interpolant_store_bytes()
             .map_err(precise_artifact_error_without_bytes)?;
         Ok(PyBytes::new(py, &bytes))
@@ -1098,13 +1136,38 @@ impl PyPreciseEphemerisSamples {
     /// scales, a sample is non-finite, or an epoch is not representable as J2000
     /// seconds.
     #[staticmethod]
-    fn from_samples(py: Python<'_>, samples: Vec<Py<PyPreciseEphemerisSample>>) -> PyResult<Self> {
+    #[pyo3(signature = (samples, gap_threshold_factor = None))]
+    fn from_samples(
+        py: Python<'_>,
+        samples: Vec<Py<PyPreciseEphemerisSample>>,
+        gap_threshold_factor: Option<f64>,
+    ) -> PyResult<Self> {
         let samples = samples.iter().map(|s| s.borrow(py).to_core());
-        let inner = PreciseEphemerisSamples::from_samples(samples)
+        let mut inner = PreciseEphemerisSamples::from_samples(samples)
             .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        if let Some(factor) = gap_threshold_factor {
+            let options = Sp3InterpolationOptions::new(factor)
+                .map_err(|e| PyValueError::new_err(e.to_string()))?;
+            inner = inner.with_interpolation_options(options);
+        }
         Ok(Self { inner })
     }
 
+    /// SP3 interpolation gap threshold factor carried by this source.
+    #[getter]
+    fn gap_threshold_factor(&self) -> f64 {
+        self.inner.interpolation_options().gap_threshold_factor()
+    }
+
+    /// Return a copy of these samples with an explicit gap threshold factor.
+    fn with_interpolation_options(&self, gap_threshold_factor: f64) -> PyResult<Self> {
+        let options = Sp3InterpolationOptions::new(gap_threshold_factor)
+            .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        Ok(Self {
+            inner: self.inner.clone().with_interpolation_options(options),
+        })
+    }
+
     /// Time scale every sample epoch is expressed in.
     #[getter]
     fn time_scale(&self) -> PyTimeScale {
@@ -1141,27 +1204,65 @@ pub struct PyPreciseEphemerisInterpolant {
 impl PyPreciseEphemerisInterpolant {
     /// Build a cached interpolant from a parsed SP3 product.
     #[staticmethod]
-    fn from_sp3(source: &PySp3) -> Self {
-        Self {
-            inner: PreciseEphemerisInterpolant::from_sp3(&source.inner),
+    #[pyo3(signature = (source, gap_threshold_factor = None))]
+    fn from_sp3(source: &PySp3, gap_threshold_factor: Option<f64>) -> PyResult<Self> {
+        let mut inner = PreciseEphemerisInterpolant::from_sp3(&source.inner);
+        if let Some(factor) = gap_threshold_factor {
+            let options = Sp3InterpolationOptions::new(factor)
+                .map_err(|e| PyValueError::new_err(e.to_string()))?;
+            inner = inner.with_interpolation_options(options);
         }
+        Ok(Self { inner })
     }
 
     /// Build a cached interpolant directly from precise-ephemeris samples.
     #[staticmethod]
-    fn from_samples(py: Python<'_>, samples: Vec<Py<PyPreciseEphemerisSample>>) -> PyResult<Self> {
+    #[pyo3(signature = (samples, gap_threshold_factor = None))]
+    fn from_samples(
+        py: Python<'_>,
+        samples: Vec<Py<PyPreciseEphemerisSample>>,
+        gap_threshold_factor: Option<f64>,
+    ) -> PyResult<Self> {
         let samples = samples.iter().map(|s| s.borrow(py).to_core());
-        let inner = PreciseEphemerisInterpolant::from_samples(samples)
+        let mut inner = PreciseEphemerisInterpolant::from_samples(samples)
             .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        if let Some(factor) = gap_threshold_factor {
+            let options = Sp3InterpolationOptions::new(factor)
+                .map_err(|e| PyValueError::new_err(e.to_string()))?;
+            inner = inner.with_interpolation_options(options);
+        }
         Ok(Self { inner })
     }
 
     /// Build a cached interpolant from an existing sample-backed source.
     #[staticmethod]
-    fn from_precise_ephemeris_samples(source: &PyPreciseEphemerisSamples) -> Self {
-        Self {
-            inner: PreciseEphemerisInterpolant::from_precise_ephemeris_samples(&source.inner),
+    #[pyo3(signature = (source, gap_threshold_factor = None))]
+    fn from_precise_ephemeris_samples(
+        source: &PyPreciseEphemerisSamples,
+        gap_threshold_factor: Option<f64>,
+    ) -> PyResult<Self> {
+        let mut inner = PreciseEphemerisInterpolant::from_precise_ephemeris_samples(&source.inner);
+        if let Some(factor) = gap_threshold_factor {
+            let options = Sp3InterpolationOptions::new(factor)
+                .map_err(|e| PyValueError::new_err(e.to_string()))?;
+            inner = inner.with_interpolation_options(options);
         }
+        Ok(Self { inner })
+    }
+
+    /// SP3 interpolation gap threshold factor carried by this interpolant.
+    #[getter]
+    fn gap_threshold_factor(&self) -> f64 {
+        self.inner.interpolation_options().gap_threshold_factor()
+    }
+
+    /// Return a copy of this interpolant with an explicit gap threshold factor.
+    fn with_interpolation_options(&self, gap_threshold_factor: f64) -> PyResult<Self> {
+        let options = Sp3InterpolationOptions::new(gap_threshold_factor)
+            .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        Ok(Self {
+            inner: self.inner.clone().with_interpolation_options(options),
+        })
     }
 
     /// Time scale of the source epochs used to build this handle.
@@ -1324,6 +1425,12 @@ impl PyPreciseInterpolantArtifact {
         self.inner.time_scale().into()
     }
 
+    /// SP3 interpolation gap threshold factor read from the artifact header.
+    #[getter]
+    fn gap_threshold_factor(&self) -> f64 {
+        self.inner.interpolation_options().gap_threshold_factor()
+    }
+
     /// Satellite tokens present in the artifact.
     #[getter]
     fn satellites(&self) -> Vec<String> {
@@ -1465,28 +1572,35 @@ fn precise_artifact_error(err: PreciseInterpolantStoreError, truncated: bool) ->
 ///   directly; or
 /// - a path (`str` or `os.PathLike`): the file is read and parsed.
 ///
+/// `gap_threshold_factor` optionally configures the product-carried SP3
+/// coverage-gap interpolation policy; `None` leaves the core default (1.5).
+///
 /// Raises [`Sp3ParseError`](crate::Sp3ParseError) on malformed content, `OSError`
-/// if the path cannot be read, and `TypeError` if `source` is neither bytes nor a
-/// path.
+/// if the path cannot be read, `ValueError` if `gap_threshold_factor` is not
+/// finite or <= 1.0, and `TypeError` if `source` is neither bytes nor a path.
 #[pyfunction]
-fn load_sp3(source: &Bound<'_, PyAny>) -> PyResult<PySp3> {
+#[pyo3(signature = (source, gap_threshold_factor = None))]
+fn load_sp3(source: &Bound<'_, PyAny>, gap_threshold_factor: Option<f64>) -> PyResult<PySp3> {
     // bytes-like first, so a `bytes` argument keeps the prior "content" meaning.
-    if let Ok(bytes) = source.downcast::<PyBytes>() {
-        let inner = sidereon::load_sp3(bytes.as_bytes()).map_err(to_sp3_err)?;
-        return Ok(PySp3 { inner });
-    }
-    if let Ok(buf) = source.downcast::<PyByteArray>() {
+    let mut inner = if let Ok(bytes) = source.downcast::<PyBytes>() {
+        sidereon::load_sp3(bytes.as_bytes()).map_err(to_sp3_err)?
+    } else if let Ok(buf) = source.downcast::<PyByteArray>() {
         // SAFETY: the buffer is copied into the parser synchronously here; no
         // Python code runs in between to mutate or free it.
-        let inner = sidereon::load_sp3(unsafe { buf.as_bytes() }).map_err(to_sp3_err)?;
-        return Ok(PySp3 { inner });
-    }
-    // Otherwise treat it as a path (str / os.PathLike via PyO3's fspath support).
-    let path: PathBuf = source.extract().map_err(|_| {
-        PyValueError::new_err("load_sp3 expects bytes, bytearray, or a path (str/os.PathLike)")
-    })?;
-    let data = std::fs::read(&path)?;
-    let inner = sidereon::load_sp3(&data).map_err(to_sp3_err)?;
+        sidereon::load_sp3(unsafe { buf.as_bytes() }).map_err(to_sp3_err)?
+    } else {
+        // Otherwise treat it as a path (str / os.PathLike via PyO3's fspath support).
+        let path: PathBuf = source.extract().map_err(|_| {
+            PyValueError::new_err("load_sp3 expects bytes, bytearray, or a path (str/os.PathLike)")
+        })?;
+        let data = std::fs::read(&path)?;
+        sidereon::load_sp3(&data).map_err(to_sp3_err)?
+    };
+    if let Some(factor) = gap_threshold_factor {
+        let options = Sp3InterpolationOptions::new(factor)
+            .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        inner = inner.with_interpolation_options(options);
+    }
     Ok(PySp3 { inner })
 }
 
@@ -1645,11 +1759,13 @@ fn _validate_exact_sp3(
 
 /// Build deterministic precise-interpolant artifact bytes from an SP3 product.
 #[pyfunction]
+#[pyo3(signature = (sp3, gap_threshold_factor = None))]
 fn build_precise_interpolant_artifact_bytes<'py>(
     py: Python<'py>,
     sp3: &PySp3,
+    gap_threshold_factor: Option<f64>,
 ) -> PyResult<Bound<'py, PyBytes>> {
-    sp3.precise_interpolant_artifact_bytes(py)
+    sp3.precise_interpolant_artifact_bytes(py, gap_threshold_factor)
 }
 
 pub(crate) fn parse_satellites(tokens: &[String]) -> PyResult<Vec<GnssSatelliteId>> {