@spec drift(
  t(),
  Orbis.GNSS.SP3.t() | [{epoch(), {number(), number(), number()}}],
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Evaluate the piecewise model error against the source ephemeris over the whole span.

Samples the source across the span and compares each truth sample to the covering segment's ECEF position (the single-segment drift NIF is per-model, so the piecewise report is composed in Elixir from position/3). For an Orbis.GNSS.SP3 source it samples over :window (defaulting to the model's full span) at :cadence_s for :satellite_id; for a sample list it uses those directly. Returns

{:ok, %{per_epoch: [%{epoch:, error_m:}], max_m:, rms_m:, threshold_horizon:,
        requested:, used:}}

matching the single-segment Orbis.GNSS.ReducedOrbit.drift/3 report. Epochs outside the model's span are skipped (counted in requested, not used). threshold_horizon is the first epoch the ECEF error exceeds :threshold_m (or nil).

@spec fit(
  Orbis.GNSS.SP3.t() | [{epoch(), {number(), number(), number()}}],
  keyword()
) :: {:ok, t()} | {:error, term()}

Fit a piecewise model over a span, one contiguous Orbis.GNSS.ReducedOrbit segment per :segment_s seconds.

Sources

• an Orbis.GNSS.SP3 handle — requires :satellite_id and :window; each segment is fitted with Orbis.GNSS.ReducedOrbit.fit/2 over its sub-window at :cadence_s;
• a list of {epoch, {x_m, y_m, z_m}} ECEF samples — partitioned by segment interval, each sublist fitted directly.

Options

• :window — {t0, t1} epochs bounding the full span (t1 strictly after t0, else :invalid_window)
• :segment_s — positive segment length in seconds, e.g. 7200 (non-positive → :invalid_segment)
• :cadence_s — positive SP3 sampling step in seconds
• :satellite_id — e.g. "G05" (SP3 source)
• :model — :circular_secular (default) or :eccentric_secular
• :time_scale — for the sample-list source, the scale its epochs are in

Segments are contiguous (seg_t1 of one is seg_t0 of the next); the final segment may be shorter. A :segment_s at least the full span yields a single segment equal to the whole window (piecewise with one segment ≡ single).

Returns {:ok, %Orbis.GNSS.ReducedOrbit.Piecewise{}} or a tagged error. The error set is exactly the single model's fit errors ({:too_few_samples, got, req}, :invalid_window, :invalid_cadence, :satellite_id_required, {:unsupported_model, m}, {:unsupported_source_frame, f}, {:unsupported_time_scale, s}, :transform_unavailable, …) plus :invalid_segment. A too-few-samples failure on a non-terminal segment is surfaced (a genuinely under-covered interior span is an error, not a silent hole); only the terminal short segment may be dropped. If nothing fits at all, {:error, {:too_few_samples, 0, 4}}.

@spec from_map(map()) :: {:ok, t()} | {:error, term()}

Reconstruct a piecewise model from a to_map/1 map. Validates the version and model id.

Returns {:ok, %Orbis.GNSS.ReducedOrbit.Piecewise{}} or {:error, {:unsupported_version, v}} / {:error, {:unsupported_model, m}} / {:error, :malformed_map}. A segment whose inner model fails from_map, or whose model id differs from the container, makes the whole map malformed — never a raise, never a nil-filled struct.

@spec position(t(), epoch(), keyword()) ::
  {:ok, Orbis.GNSS.ReducedOrbit.vec3()} | {:error, term()}

Position of the piecewise model at epoch, ECEF (ITRF) meters by default.

Selects the segment covering epoch and delegates to Orbis.GNSS.ReducedOrbit.position/3. Pass frame: :gcrs for the inertial position. An epoch outside the full span returns {:error, :out_of_range}.

@spec position_velocity(t(), epoch(), keyword()) :: {:ok, map()} | {:error, term()}

Position and velocity of the piecewise model at epoch.

Selects the covering segment and delegates to Orbis.GNSS.ReducedOrbit.position_velocity/3. An epoch outside the full span returns {:error, :out_of_range}.

@spec select_segment(t(), epoch()) :: {:ok, segment()} | {:error, term()}

Select the segment whose coverage interval contains epoch.

Returns {:ok, segment} or {:error, :out_of_range}. Interior boundaries resolve to the later segment; the exact end-of-span epoch resolves to the last segment.

@spec to_map(t()) :: map()

Serialize a piecewise model to a stable, versioned, JSON-safe map (string keys). Each segment's model is serialized via Orbis.GNSS.ReducedOrbit.to_map/1. See from_map/1 for the inverse.