gri-multitrack 0.1.0__py3-none-any.whl

gri_multitrack/__init__.py

@@ -0,0 +1,100 @@
+"""gri-multitrack -- multi-target geolocation tracking.
+
+gri-multitrack combines the gri per-target Kalman-IMM (``gri-kalman``, fed by
+``gri-obs`` observables) with a multi-target policy layer: ingest/routing of the
+feed-in data tiers, measurement-space scoring, per-scan association, track
+lifecycle, existence (Labeled Multi-Bernoulli), and a Poisson-binomial count
+distribution.
+
+The governing seam is "gri scores, gri-multitrack assigns": gri-kalman owns
+per-track estimation and the measurement-space likelihoods; gri-multitrack owns
+everything multi-target. v1 is loose coupling with a GNN scaffold associator (a
+local scipy Hungarian); the local-MHT ``MfaTracker`` is the v1 deferred-decision
+associator. The layer is DIY on numpy/scipy (Stone-Soup-free); an optional
+``crosscheck`` extra pulls Stone Soup only as a dev-time GOSPA/OSPA cross-check.
+
+The primary tracker class is ``MultiTracker`` (formerly ``Crucible``; the
+"Crucible" name now belongs to the companion 3D app).
+
+Typical use::
+
+    from gri_multitrack import MultiTracker
+    tracker = MultiTracker()
+    outputs = tracker.process([(ell, 0.0), (ell2, 1.0), ...])
+"""
+
+from __future__ import annotations
+
+from .association import (
+    AssociationResult,
+    Associator,
+    GnnAssociator,
+    Hypothesis,
+    score_matrix,
+)
+from .cardinality import count_distribution, expected_count, most_likely_count
+from .ingest import (
+    Channel,
+    PresenceObs,
+    RoutedItem,
+    Scan,
+    group_into_scans,
+    ingest,
+    route,
+)
+from .lifecycle import LifecycleConfig, TrackManager
+from .mfa import MfaConfig, MfaTracker
+from .output import (
+    AssociationDiagnostic,
+    GateEntry,
+    JointHypothesis,
+    LabeledTrack,
+    MarginalEntry,
+    PredictedState,
+    TrackerOutput,
+)
+from .scoring import GateScore, score
+from .track import (
+    Track,
+    default_motion_models,
+    make_imm,
+    make_smart_segmented,
+)
+from .tracker import MultiTracker, MultiTrackerConfig
+
+__all__ = [
+    "AssociationDiagnostic",
+    "AssociationResult",
+    "Associator",
+    "Channel",
+    "GateEntry",
+    "GateScore",
+    "GnnAssociator",
+    "Hypothesis",
+    "JointHypothesis",
+    "LabeledTrack",
+    "LifecycleConfig",
+    "MarginalEntry",
+    "MfaConfig",
+    "MfaTracker",
+    "MultiTracker",
+    "MultiTrackerConfig",
+    "PredictedState",
+    "PresenceObs",
+    "RoutedItem",
+    "Scan",
+    "Track",
+    "TrackManager",
+    "TrackerOutput",
+    "count_distribution",
+    "default_motion_models",
+    "expected_count",
+    "group_into_scans",
+    "ingest",
+    "make_imm",
+    "make_smart_segmented",
+    "most_likely_count",
+    "route",
+    "score",
+    "score_matrix",
+]

gri_multitrack/association.py

@@ -0,0 +1,196 @@
+"""Per-scan track<->observation association (the "Stone Soup assigns" half).
+
+This module owns the ASSIGNMENT half of the seam. v1 ships a Global Nearest
+Neighbor (GNN) scaffold: a one-to-one assignment that minimizes total cost
+(negative log-likelihood) over the gated score matrix, solved with a local
+Hungarian (``scipy.optimize.linear_sum_assignment``) so the Phase-1 skeleton
+needs no Stone Soup install.
+
+GNN is a BRING-UP SCAFFOLD and debug baseline only. It commits one best match
+per scan and so will visibly mishandle the crossing / ambiguous-TDOA case (a
+single TDOA gates to many tracks). The real v1 associator is Stone Soup's MFA
+(multi-frame assignment), which defers ambiguous assignments across a window;
+the :class:`Associator` protocol keeps that a component swap, not a rewrite.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+from .scoring import GateScore, score
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from gri_ell import Ell
+    from gri_obs import Observation
+
+    from .track import Track
+
+    Measurement = Ell | Observation
+
+# Sentinel cost for a pair that is not a valid candidate (outside the gate).
+# Large enough that the assignment never prefers it over any real pairing.
+_NO_MATCH_COST = 1e12
+
+
+@dataclass
+class Hypothesis:
+    """One joint assignment hypothesis over a scan.
+
+    Attributes:
+        weight: Normalized weight of this hypothesis in [0, 1] (weights over the
+            reported hypotheses sum to ~1).
+        assign: Mapping ``measurement_index -> track_index`` for the
+            measurements this hypothesis assigns (unassigned measurements /
+            tracks are simply absent).
+    """
+
+    weight: float
+    assign: dict[int, int] = field(default_factory=dict)
+
+
+@dataclass
+class AssociationResult:
+    """Outcome of associating one scan's measurements to the track set.
+
+    The committed one-to-one ``assignments`` are what the tracker applies this
+    scan. ``marginals`` and ``hypotheses`` are the associator-agnostic
+    diagnostic: a GNN fills them degenerately (weight-1 hypothesis, marginal 1.0
+    to the winner); an MFA fills them richly (spread marginals, several surviving
+    window hypotheses). Indices here are translated to obs-ids / track labels at
+    the output boundary.
+
+    Attributes:
+        assignments: ``(track_index, measurement_index)`` pairs that matched.
+        unassigned_tracks: Indices of tracks that got no measurement.
+        unassigned_measurements: Indices of measurements that matched no track
+            (candidates for birth).
+        scores: The full ``tracks x measurements`` score matrix (for inspection
+            and metrics).
+        marginals: ``(measurement_index, track_index) -> probability`` that the
+            measurement is assigned to the track.
+        hypotheses: Top-K joint assignment hypotheses with weights.
+    """
+
+    assignments: list[tuple[int, int]] = field(default_factory=list)
+    unassigned_tracks: list[int] = field(default_factory=list)
+    unassigned_measurements: list[int] = field(default_factory=list)
+    scores: list[list[GateScore]] = field(default_factory=list)
+    marginals: dict[tuple[int, int], float] = field(default_factory=dict)
+    hypotheses: list[Hypothesis] = field(default_factory=list)
+
+
+def score_matrix(
+    tracks: Sequence[Track],
+    measurements: Sequence[Measurement],
+    time_s: float,
+    gate_prob: float = 0.99,
+) -> list[list[GateScore]]:
+    """Compute the ``tracks x measurements`` gated score matrix for a scan.
+
+    Args:
+        tracks: Current tracks.
+        measurements: This scan's kinematic measurements.
+        time_s: Scan time in seconds.
+        gate_prob: Chi-squared gate probability passed to the scorer.
+
+    Returns:
+        A list of rows, one per track; each row holds a :class:`GateScore` per
+        measurement.
+    """
+    return [
+        [score(track, meas, time_s, gate_prob) for meas in measurements]
+        for track in tracks
+    ]
+
+
+class Associator(Protocol):
+    """Per-scan associator interface (GNN now, MFA later)."""
+
+    def associate(
+        self,
+        tracks: Sequence[Track],
+        measurements: Sequence[Measurement],
+        time_s: float,
+    ) -> AssociationResult:
+        """Assign this scan's measurements to tracks."""
+        ...
+
+
+class GnnAssociator:
+    """Global Nearest Neighbor associator over the gated score matrix.
+
+    Minimizes total negative-log-likelihood across a one-to-one matching, with
+    ungated pairs blocked by a sentinel cost so they are never chosen.
+    """
+
+    def __init__(self, gate_prob: float = 0.99) -> None:
+        """Initialize the GNN associator.
+
+        Args:
+            gate_prob: Chi-squared gate probability for candidate pairs.
+        """
+        self._gate_prob = gate_prob
+
+    def associate(
+        self,
+        tracks: Sequence[Track],
+        measurements: Sequence[Measurement],
+        time_s: float,
+    ) -> AssociationResult:
+        """Assign measurements to tracks by minimum total cost.
+
+        Args:
+            tracks: Current tracks.
+            measurements: This scan's kinematic measurements.
+            time_s: Scan time in seconds.
+
+        Returns:
+            The :class:`AssociationResult` for this scan.
+        """
+        n_t = len(tracks)
+        n_m = len(measurements)
+        if n_t == 0 or n_m == 0:
+            return AssociationResult(
+                unassigned_tracks=list(range(n_t)),
+                unassigned_measurements=list(range(n_m)),
+                scores=score_matrix(tracks, measurements, time_s, self._gate_prob),
+            )
+
+        scores = score_matrix(tracks, measurements, time_s, self._gate_prob)
+        cost = np.full((n_t, n_m), _NO_MATCH_COST, dtype=np.float64)
+        for i, row in enumerate(scores):
+            for j, gs in enumerate(row):
+                if gs.gated and np.isfinite(gs.log_likelihood):
+                    cost[i, j] = -gs.log_likelihood
+
+        rows, cols = linear_sum_assignment(cost)
+
+        assignments: list[tuple[int, int]] = []
+        assigned_t: set[int] = set()
+        assigned_m: set[int] = set()
+        for i, j in zip(rows, cols, strict=True):
+            if cost[i, j] < _NO_MATCH_COST:
+                assignments.append((int(i), int(j)))
+                assigned_t.add(int(i))
+                assigned_m.add(int(j))
+
+        # GNN commits one hypothesis: every assigned pair gets marginal 1.0 and
+        # the single joint hypothesis carries all of weight. MFA fills these
+        # with spread marginals and several window hypotheses (same shape).
+        marginals = {(j, i): 1.0 for i, j in assignments}
+        hypotheses = [Hypothesis(weight=1.0, assign={j: i for i, j in assignments})]
+
+        return AssociationResult(
+            assignments=assignments,
+            unassigned_tracks=[i for i in range(n_t) if i not in assigned_t],
+            unassigned_measurements=[j for j in range(n_m) if j not in assigned_m],
+            scores=scores,
+            marginals=marginals,
+            hypotheses=hypotheses,
+        )

gri_multitrack/cardinality.py

@@ -0,0 +1,68 @@
+"""Count confidence as the Poisson-binomial distribution of {r_i}.
+
+The Labeled Multi-Bernoulli output model carries a per-track existence
+probability r_i. The confidence on the TOTAL emitter count is then the
+Poisson-binomial distribution of those independent existences -- the
+distribution of the number of "successes" among Bernoulli trials with
+different probabilities. This is consistent with the per-track numbers by
+construction, so the two confidences never disagree.
+
+For independent tracks this is a few lines of exact dynamic programming; full
+GLMB/CPHD machinery is not needed for v1.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def count_distribution(existences: Sequence[float]) -> np.ndarray:
+    """Poisson-binomial distribution of independent existence probabilities.
+
+    Args:
+        existences: Per-track existence probabilities r_i, each in [0, 1].
+
+    Returns:
+        Array ``p`` of length ``n + 1`` where ``p[k]`` is the probability that
+        exactly ``k`` of the ``n`` tracks exist. Sums to 1. For ``n == 0`` this
+        is ``[1.0]`` (zero emitters with certainty).
+    """
+    probs = np.asarray(existences, dtype=np.float64)
+    dist = np.zeros(len(probs) + 1, dtype=np.float64)
+    dist[0] = 1.0
+    for p in probs:
+        shifted = np.zeros_like(dist)
+        shifted[1:] = dist[:-1]
+        dist = dist * (1.0 - p) + shifted * p
+    return dist
+
+
+def expected_count(existences: Sequence[float]) -> float:
+    """Expected number of emitters, ``sum(r_i)``.
+
+    Equal to the mean of the Poisson-binomial distribution.
+
+    Args:
+        existences: Per-track existence probabilities r_i.
+
+    Returns:
+        The expected emitter count.
+    """
+    return float(np.sum(np.asarray(existences, dtype=np.float64)))
+
+
+def most_likely_count(existences: Sequence[float]) -> int:
+    """Mode of the count distribution (the single most probable count).
+
+    Args:
+        existences: Per-track existence probabilities r_i.
+
+    Returns:
+        The count ``k`` with the highest Poisson-binomial probability.
+    """
+    return int(np.argmax(count_distribution(existences)))

gri_multitrack/ingest.py

@@ -0,0 +1,232 @@
+"""Ingest and routing for the MultiTracker feed-in data types.
+
+MultiTracker accepts five feed-in types (see ``CLAUDE.md`` "Feed-in data types"):
+
+1. geo -- a ``gri_ell.Ell`` (3D position + covariance), externally solved.
+2. one or two TDOAs (or any ``gri_obs`` observable) -- a partial constraint.
+3. an altitude constraint (``gri_obs.AltitudeObs``) -- an optional modifier
+   applied alongside the partials at the same epoch.
+4. presence ("is it on") -- a MultiTracker-native existence event, no geometry.
+
+Types 1-3 carry geometry and route to the KINEMATIC channel (a per-track
+filter update). Type 4 routes to the EXISTENCE channel (coast + r_i bump).
+Well-determined solving (4+ satellites, mixed receivers, ground-bounce + 2
+TDOAs) happens OUTSIDE MultiTracker and arrives as a type-1 geo; MultiTracker does not
+solve those.
+
+This module normalizes a stream of timestamped, mixed-type inputs into
+time-ordered scans the tracker consumes.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from gri_ell import Ell
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PresenceObs:
+    """A presence ("is it on") event: existence evidence with no geometry.
+
+    A presence event names an emitter that was observed to be transmitting but
+    carries no kinematic information. The tracker responds by coasting the
+    matched track to this time and raising its existence probability -- it is
+    NOT a gri observable and never updates kinematic state.
+
+    Attributes:
+        time: Timestamp of the event in seconds.
+        emitter_id: Identifier of the emitter that was detected. Used to match
+            the event to an existing track; presence cannot birth a track.
+        sensor_id: Identifier of the source that reported the detection.
+        confidence: Detection confidence in [0, 1] (probability the emitter is
+            truly present given this report). Defaults to 1.0.
+    """
+
+    time: float
+    emitter_id: str
+    sensor_id: str = "presence"
+    confidence: float = 1.0
+
+
+class Channel(Enum):
+    """Routing channel for a feed-in item."""
+
+    KINEMATIC = "kinematic"
+    EXISTENCE = "existence"
+
+
+@dataclass(frozen=True)
+class RoutedItem:
+    """A single feed-in item normalized to a channel and timestamp.
+
+    Attributes:
+        time: Timestamp in seconds.
+        channel: KINEMATIC (geometry -> filter update) or EXISTENCE (presence).
+        payload: The original object (``Ell``, a gri-obs observable, or
+            ``PresenceObs``).
+        kind: Short label for the payload type (``"geo"``, ``"tdoa"``,
+            ``"altitude"``, ``"presence"``, ...).
+        id: Stable observation id (e.g. ``"obs_0007"``). Lets the output's
+            association diagnostics point back at the exact observation gated /
+            assigned. Supplied by the caller or auto-generated in input order.
+    """
+
+    time: float
+    channel: Channel
+    payload: Any
+    kind: str
+    id: str
+
+
+@dataclass
+class Scan:
+    """All feed-in items sharing one epoch.
+
+    A scan is the unit the tracker processes: it predicts every track to the
+    scan time, scores and associates the kinematic measurements, then applies
+    the existence events.
+
+    Attributes:
+        time: Epoch timestamp in seconds.
+        kinematic: Geometry payloads (``Ell`` or gri-obs observables) at this
+            epoch.
+        kinematic_ids: Stable observation ids parallel to ``kinematic`` (same
+            order), used to key the association diagnostics back to inputs.
+        existence: Presence events at this epoch.
+    """
+
+    time: float
+    kinematic: list[Any] = field(default_factory=list)
+    kinematic_ids: list[str] = field(default_factory=list)
+    existence: list[PresenceObs] = field(default_factory=list)
+
+
+def _is_observable(payload: object) -> bool:
+    """Return True if ``payload`` satisfies the gri-obs EKF Protocol.
+
+    Args:
+        payload: Candidate object.
+
+    Returns:
+        True if it exposes the EKF Protocol: ``predicted`` / ``jacobian``
+        methods plus a ``noise_covariance`` attribute (a property in gri-obs).
+    """
+    return (
+        callable(getattr(payload, "predicted", None))
+        and callable(getattr(payload, "jacobian", None))
+        and hasattr(payload, "noise_covariance")
+    )
+
+
+def route_one(payload: object, time_s: float, obs_id: str) -> RoutedItem:
+    """Normalize a single payload to a :class:`RoutedItem`.
+
+    Args:
+        payload: An ``Ell`` (geo), a gri-obs observable, or a ``PresenceObs``.
+        time_s: Timestamp in seconds for this item.
+        obs_id: Stable observation id for this item.
+
+    Returns:
+        The routed item with its channel and kind resolved.
+
+    Raises:
+        TypeError: If the payload is not a recognized feed-in type.
+    """
+    if isinstance(payload, Ell):
+        return RoutedItem(time_s, Channel.KINEMATIC, payload, "geo", obs_id)
+    if isinstance(payload, PresenceObs):
+        return RoutedItem(time_s, Channel.EXISTENCE, payload, "presence", obs_id)
+    if _is_observable(payload):
+        kind = type(payload).__name__.removesuffix("Obs").lower()
+        return RoutedItem(time_s, Channel.KINEMATIC, payload, kind, obs_id)
+    raise TypeError(
+        f"Unrecognized feed-in payload of type {type(payload).__name__!r}; "
+        "expected Ell, a gri-obs observable, or PresenceObs",
+    )
+
+
+def route(items: Iterable[tuple[Any, ...]]) -> list[RoutedItem]:
+    """Route a stream of timestamped inputs into time-ordered items.
+
+    Each input is ``(payload, time_s)`` or ``(payload, time_s, obs_id)``. When
+    no id is supplied, a stable id is generated from the INPUT order
+    (``obs_0000``, ``obs_0001``, ...) so ids do not shift when items are sorted
+    by time.
+
+    Args:
+        items: Iterable of ``(payload, time_s)`` or ``(payload, time_s, obs_id)``
+            tuples. ``payload`` is an ``Ell``, a gri-obs observable, or a
+            ``PresenceObs``.
+
+    Returns:
+        Routed items sorted ascending by time (stable for equal times).
+    """
+    routed: list[RoutedItem] = []
+    for i, item in enumerate(items):
+        payload, time_s = item[0], item[1]
+        obs_id = item[2] if len(item) > 2 else f"obs_{i:04d}"  # noqa: PLR2004
+        routed.append(route_one(payload, time_s, obs_id))
+    routed.sort(key=lambda r: r.time)
+    return routed
+
+
+def group_into_scans(
+    routed: Sequence[RoutedItem],
+    time_tol_s: float = 0.0,
+) -> list[Scan]:
+    """Group time-ordered routed items into per-epoch scans.
+
+    Items whose timestamps differ by at most ``time_tol_s`` from the scan's
+    first item are placed in the same scan. This is how an altitude constraint
+    is paired with the TDOA(s) it modifies: same epoch -> same scan -> applied
+    together by the tracker.
+
+    Args:
+        routed: Routed items, assumed sorted ascending by time (as returned by
+            :func:`route`).
+        time_tol_s: Maximum timestamp spread within a single scan, in seconds.
+            Defaults to 0.0 (exact-time grouping).
+
+    Returns:
+        Scans in ascending time order; each scan's ``time`` is its first item's
+        timestamp.
+    """
+    scans: list[Scan] = []
+    current: Scan | None = None
+    for item in routed:
+        if current is None or item.time - current.time > time_tol_s:
+            current = Scan(time=item.time)
+            scans.append(current)
+        if item.channel is Channel.EXISTENCE:
+            current.existence.append(item.payload)
+        else:
+            current.kinematic.append(item.payload)
+            current.kinematic_ids.append(item.id)
+    return scans
+
+
+def ingest(
+    items: Iterable[tuple[Any, ...]],
+    time_tol_s: float = 0.0,
+) -> list[Scan]:
+    """Route and group a raw input stream into scans (the full ingest path).
+
+    Args:
+        items: Iterable of ``(payload, time_s)`` or ``(payload, time_s, obs_id)``
+            tuples.
+        time_tol_s: Epoch grouping tolerance in seconds (see
+            :func:`group_into_scans`).
+
+    Returns:
+        Time-ordered scans ready for the tracker.
+    """
+    return group_into_scans(route(items), time_tol_s=time_tol_s)