# `Sidereon.GNSS.SP3`
[🔗](https://github.com/neilberkman/sidereon-ex/blob/main/lib/sidereon/gnss/sp3.ex#L1)

SP3-c / SP3-d precise-ephemeris products (IGS precise orbits + clocks).

This is the Elixir surface over the `sidereon-core` SP3 parser and
`scipy.interpolate`-matched position/clock interpolation. It is **not** the
JPL-SPK reader (`Sidereon.Ephemeris`): SP3 carries GNSS satellite states in the
ITRF/IGS ECEF frame, in meters, tagged by a GNSS satellite id like `"G01"`.

A file is parsed **once** into a resource handle held by the BEAM; evaluation
operates on that handle and never re-reads the file.

## Example

    {:ok, sp3} = Sidereon.GNSS.SP3.load("/path/to/igs.sp3")
    {:ok, state} =
      Sidereon.GNSS.SP3.position(sp3, "G01", ~N[2020-06-24 00:00:00])

    state.x_m       # ITRF/IGS ECEF X, meters
    state.clock_s   # satellite clock offset, seconds (or nil if no estimate)

## Epochs

The query epoch is interpreted in the file's **own** time scale (read from the
SP3 header, typically GPST). Pass a `NaiveDateTime` or a
`{{year, month, day}, {hour, minute, second}}` tuple; it is converted to the
split Julian date with the same midnight-boundary convention the parser uses
(no leap-second shifting; the epoch stays in the file's scale).

# `exact_coverage`

```elixir
@type exact_coverage() :: :half_open | :inclusive
```

Exact declared-span representation found by the core validator.

# `t`

```elixir
@type t() :: %Sidereon.GNSS.SP3{
  coverage_end: float(),
  coverage_start: float(),
  handle: reference(),
  time_scale: String.t()
}
```

# `align_clock_reference`

```elixir
@spec align_clock_reference(t(), t(), keyword()) :: {:ok, t()} | {:error, term()}
```

Return a copy of `other` with its clocks shifted onto `reference`'s clock datum
(the clock-datum primitive, applied).

At every epoch the offset could be estimated, each clocked satellite's offset
has the datum subtracted, so the result's clocks are directly comparable to
`reference`'s. Positions are untouched. Epochs without an estimate are left
unchanged. The returned product interpolates like any other SP3.

Returns `{:ok, %Sidereon.GNSS.SP3{}}` or `{:error, reason}`.

## Options

  * `:min_common`: minimum common clocked satellites per epoch (default `5`)

# `clock_reference_offset`

```elixir
@spec clock_reference_offset(t(), t(), keyword()) :: [map()]
```

Estimate the per-epoch reference-clock offset of `other` relative to
`reference` (the clock-datum primitive).

Precise clock products from different centers are referenced to different
station/ensemble clocks, so their raw clocks differ by a per-epoch common
offset that drifts over the day. This returns that datum: a list of maps
`%{jd_whole: float, jd_fraction: float, offset_s: float, satellites: integer}`,
one per epoch where at least `:min_common` common clocked satellites let the
(robust median) offset be estimated. Subtract `offset_s` from `other`'s clocks
to put both products on `reference`'s datum. Orbit positions need no such
treatment; every center reports ITRF center-of-mass coordinates.

## Options

  * `:min_common`: minimum common clocked satellites per epoch (default `5`)

# `coverage`

```elixir
@spec coverage(t()) :: %{
  start_j2000_s: float(),
  end_j2000_s: float(),
  time_scale: String.t()
}
```

Return the product coverage interval.

The start and end are the first and last SP3 node epochs, expressed as
seconds since J2000 in the product's own time scale. Public evaluators reject
epochs outside this interval by default; pass `extrapolate: true` to the
evaluator to opt into the lower-level interpolation behavior.

# `declared_epoch_count`

```elixir
@spec declared_epoch_count(t()) :: non_neg_integer()
```

Return the epoch count declared on SP3 header line 1.

This can differ from `epoch_count/1` for a truncated or inconsistent product
accepted by the compatibility parser. `validate_exact/2` requires equality.

# `declared_start_j2000_s`

```elixir
@spec declared_start_j2000_s(t()) :: float() | nil
```

Alias for `declared_start_j2000_seconds/1`.

# `declared_start_j2000_seconds`

```elixir
@spec declared_start_j2000_seconds(t()) :: float() | nil
```

Return the start epoch declared on SP3 header line 1.

The value is seconds since J2000 in the product's own time scale, or `nil`
when the permissive parser could not interpret the declaration.

# `epoch_count`

```elixir
@spec epoch_count(t()) :: non_neg_integer()
```

Number of parsed epochs held by the SP3 product.

This is the count of actual `*` epoch nodes parsed from the file, not just the
header declaration. The value matches `length(epochs_j2000_seconds(sp3))` for
ordinary SP3 products.

# `epochs_j2000_seconds`

```elixir
@spec epochs_j2000_seconds(t()) :: [float()]
```

Return the parsed SP3 epoch grid as seconds since J2000.

Values are in the product's own time scale, ascending, and correspond exactly
to the parsed SP3 node epochs. Use this accessor when a caller needs the
original sample grid rather than an interpolated state.

# `interpolate`

```elixir
@spec interpolate(t(), String.t(), [number()]) ::
  {:ok, Sidereon.GNSS.PreciseEphemeris.StateBatch.t()} | {:error, term()}
```

Interpolate one satellite at J2000-second epochs in the product time scale.

This returns the same `Sidereon.GNSS.PreciseEphemeris.StateBatch` used by the
precise-interpolant accessors.

# `load`

```elixir
@spec load(String.t()) :: {:ok, t()} | {:error, term()}
```

Load and parse an SP3-c / SP3-d file into a product handle.

Returns `{:ok, %Sidereon.GNSS.SP3{}}` or `{:error, reason}`. The file is read and
parsed exactly once; the parsed product is held as a resource handle.

# `load!`

```elixir
@spec load!(String.t()) :: t()
```

Like `load/1` but raises on failure.

# `merge`

```elixir
@spec merge(
  [t()],
  keyword()
) :: {:ok, t(), map()} | {:error, term()}
```

Merge several SP3 products from different analysis centers into one consistent
precise-ephemeris dataset.

`sources` is a list of loaded products **in precedence order** (earlier wins
ties). This is orthogonal to time-stitching: it combines providers at the same
epochs on one shared time grid. Mixed-cadence products are unioned onto the
finest input cadence by default, using only records actually present in an
input and never interpolating. For every `(epoch, satellite)` cell:

  * **Union satellite coverage**: a satellite present in any input may appear
    in the merged product wherever a source actually carries it.
  * **Consensus**: the largest subset of sources agreeing within tolerance is
    combined; sources outside it are recorded as outliers. A cell with no
    agreeing subset of `:min_agree` is *quarantined* (omitted), never averaged
    across disagreeing centers. A lone source is carried through.
  * **Cell precedence**: with `combine: :precedence`, the earliest source
    present in each cell wins, so a lower-precedence source fills a preferred
    source's missing cell. Set `precedence_scope: :satellite_arc` to retain
    one owner for a whole satellite arc.
  * **Optional precedence guard**: `:outlier_reject` makes a contested
    precedence cell require a mutually agreeing cluster of at least
    `max(:min_agree, 2)` sources. A corrupt preferred value is replaced by the
    earliest member of the deterministic largest cluster and recorded.

Returns `{:ok, %Sidereon.GNSS.SP3{}, report}` or `{:error, reason}`, where
`report` is a map with `:quarantined`, `:single_source`, and
`:position_outliers`, and `:clock_outliers` lists. Each entry is a map
`%{satellite: "G03", jd_whole: float, jd_fraction: float, sources: [0, 2]}`
(`sources` are zero-based indices into `sources`).

`report.agreement` quantifies how tightly the consensus sources clustered about
the combined product. It is a map with the whole-product aggregates
`:position_rms_m`, `:position_max_m`, `:clock_rms_s`, and `:clock_max_s`, plus
`:cells` (per-(epoch, satellite) statistics, one per accepted cell) and
`:epochs` (per-epoch aggregates). The RMS fields are `nil` when no
multi-source consensus exists for that channel. Position maximum covers every
accepted cell; clock maximum covers every clock-bearing accepted cell, so
either maximum may be `0.0` for a single-source cell. The clock fields of a
cell are `nil` only when the cell carries no clock.

## Options

  * `:position_tolerance_m`: position agreement tolerance, meters (default `0.5`)
  * `:clock_tolerance_s`: clock agreement tolerance, seconds (default `5.0e-9`)
  * `:min_agree`: agreeing sources required to accept a contested cell (default `2`)
  * `:clock_min_common`: common clocked satellites for the clock-datum estimate (default `5`)
  * `:combine`: `:mean` (default), `:median`, or `:precedence`
  * `:precedence_scope`: `:cell` (default) or `:satellite_arc`
  * `:outlier_reject`: `nil` (default/current behavior), or a map/keyword list
    with `:position_m` and `:clock_ns` tolerances
  * `:epoch_interval_s`: require this target epoch interval, seconds
  * `:systems`: restrict output to systems such as `[:gps]` or `["G", "E"]`
  * `:asserted_frame_label_sets`: coordinate-label sets the caller asserts
    are equivalent without frame math
  * `:helmert`: enable catalog Helmert reconciliation for known ITRF/IGS
    labels

# `merge_input_identity`

```elixir
@spec merge_input_identity(
  [map()],
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Build the versioned stable identity for exact SP3 artifacts and merge policy.

Contributor order and map order do not affect mean or median identity. With
`combine: :precedence`, source order is an effective policy control and is
therefore bound in order. Every contributor must carry complete
requested/resolved identity, distributor, product and archive digests and
lengths, official filename, and compression. Cache and HTTP observations are
intentionally excluded. The returned map includes core's complete canonical
`:contributors` and, for precedence combination, the ordered
`:precedence_contributors`.

# `parse`

```elixir
@spec parse(binary()) :: {:ok, t()} | {:error, term()}
```

Parse an in-memory SP3 byte buffer (already decompressed) into a handle.

# `parse_exact`

```elixir
@spec parse_exact(binary(), Sidereon.GNSS.SP3.ExactRequest.t()) ::
  {:ok, t(), exact_coverage()} | {:error, term()}
```

Parse and validate decompressed SP3 bytes against an exact request.

Returns the parsed product together with `:half_open` or `:inclusive` to
identify the accepted boundary representation. Parse, identity, cadence,
grid, and span failures are returned as exact-product integrity errors.

# `position`

```elixir
@spec position(t(), String.t(), NaiveDateTime.t() | tuple(), keyword()) ::
  {:ok, Sidereon.GNSS.SP3.State.t()} | {:error, term()}
```

Interpolate the state of satellite `sat_id` at `epoch`.

`sat_id` is the canonical SP3/RINEX token, e.g. `"G01"` (GPS PRN 1), `"E12"`,
`"C30"`. `epoch` is a `NaiveDateTime` or a
`{{year, month, day}, {hour, minute, second}}` tuple, interpreted in the
file's own time scale.

By default, epochs outside the parsed SP3 node coverage return
`{:error, :outside_coverage}`. Pass `extrapolate: true` to opt into the
lower-level interpolation behavior near the product edges.

Returns `{:ok, %Sidereon.GNSS.SP3.State{}}` or `{:error, reason}`.

# `precise_ephemeris_samples`

```elixir
@spec precise_ephemeris_samples(t()) :: [Sidereon.GNSS.PreciseEphemerisSample.t()]
```

Extract the product as the canonical precise-ephemeris samples, in SI units,
one per real position record in ascending epoch order.

Each element is a `Sidereon.GNSS.PreciseEphemerisSample` carrying the satellite
token, the epoch (split Julian date tagged with the product's time scale), the
ECEF position in meters, the optional clock in seconds, and the SP3 `E`
clock-event flag. Round-tripping these back through
`Sidereon.GNSS.PreciseEphemeris.from_samples/1` rebuilds the same interpolatable
source.

## Examples

    {:ok, sp3} = Sidereon.GNSS.SP3.load("igs.sp3")
    samples = Sidereon.GNSS.SP3.precise_ephemeris_samples(sp3)
    {:ok, source} = Sidereon.GNSS.PreciseEphemeris.from_samples(samples)

# `precise_interpolant_artifact_bytes`

```elixir
@spec precise_interpolant_artifact_bytes(t()) :: {:ok, binary()} | {:error, term()}
```

Build canonical precise-interpolant artifact bytes from this SP3 product.

# `prediction_summary`

```elixir
@spec prediction_summary(t()) :: %{epochs: [map()], observed_through: map() | nil}
```

Return observed/predicted status derived from the SP3 record flags.

`:epochs` contains one entry per parsed epoch with `:observed`,
`:orbit_predicted_satellites`, and `:clock_predicted_satellites`. The
`:observed_through` split-Julian-date map is the last epoch before the first
predicted record, or the final epoch for a fully observed product. It is
`nil` when the first epoch is already predicted or the product is empty.

This metadata uses the file's actual per-record `P` flags and never assumes a
fixed ultra-rapid observed duration. Per-cell flags are also available from
`state/3` and `states_at/2`.

# `satellite_ids`

```elixir
@spec satellite_ids(t()) :: [String.t()]
```

Return the SP3/RINEX satellite identifiers declared by the product header.

These are canonical three-character tokens such as `"G01"`, `"E12"`, or
`"C30"`. The list is read from the already-loaded SP3 handle; no file I/O or
interpolation is performed.

## Examples

    {:ok, sp3} = Sidereon.GNSS.SP3.parse(sp3_bytes)
    ids = Sidereon.GNSS.SP3.satellite_ids(sp3)
    "G01" in ids

# `satellites`

```elixir
@spec satellites(t()) :: [String.t()]
```

Alias for `satellite_ids/1`, matching the Python/WASM `satellites` accessor.

# `state`

```elixir
@spec state(t(), String.t(), non_neg_integer()) ::
  {:ok, Sidereon.GNSS.SP3.State.t()} | {:error, term()}
```

Return the exact parsed state of `sat_id` at `epoch_index`.

`epoch_index` is zero-based into `epochs_j2000_seconds/1`. This accessor does
no interpolation: the returned state is the record stored in the SP3 file,
including optional velocity, optional clock-rate, and the SP3 status flags.
Missing all-zero orbit records are not fabricated; querying such a cell returns
`{:error, {:unknown_satellite, sat_id}}`.

Returns `{:ok, %Sidereon.GNSS.SP3.State{}}` or `{:error, reason}`.

# `states_at`

```elixir
@spec states_at(t(), non_neg_integer()) ::
  {:ok, [{String.t(), Sidereon.GNSS.SP3.State.t()}]} | {:error, term()}
```

Return all exact parsed states at `epoch_index`.

The result is an ascending satellite-id list of `{satellite_id, state}` pairs
for records actually present at that SP3 epoch. Satellites whose position
record is the SP3 missing-orbit sentinel are absent from the list.

Returns `{:ok, [{satellite_id, %Sidereon.GNSS.SP3.State{}}]}` or
`{:error, reason}`.

# `to_iodata`

```elixir
@spec to_iodata(
  t(),
  keyword()
) :: iodata()
```

Serialize the product to standard SP3-c / SP3-d text as iodata. Pure, no I/O.

This is the inverse of `load/1` / `parse/1`: a read → (`merge/2`) → write
pipeline round-trips to a single standard SP3 file any reader consumes. The
output is deterministic (same product → identical bytes). Header fields
(version, epoch count, satellite list, time system, week / seconds-of-week /
MJD / interval) are derived from the product. A satellite absent at an epoch is
written as the SP3 missing-orbit sentinel, so a quarantined `merge/2` cell
re-reads as missing, never a fabricated position.

## Examples

    {:ok, sp3} = Sidereon.GNSS.SP3.load("igs.sp3")
    iodata = Sidereon.GNSS.SP3.to_iodata(sp3)
    {:ok, reparsed} = Sidereon.GNSS.SP3.parse(IO.iodata_to_binary(iodata))
    Sidereon.GNSS.SP3.satellite_ids(reparsed) == Sidereon.GNSS.SP3.satellite_ids(sp3)
    #=> true

# `to_sp3_string`

```elixir
@spec to_sp3_string(
  t(),
  keyword()
) :: binary()
```

Serialize the product to an SP3 text binary.

# `validate_exact`

```elixir
@spec validate_exact(t(), Sidereon.GNSS.SP3.ExactRequest.t()) ::
  {:ok, exact_coverage()} | {:error, term()}
```

Validate an already parsed SP3 product against an exact request.

The returned coverage atom has the same meaning as `parse_exact/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*