Tracking State

Tracking.jl uses a small hierarchy of state types to manage tracking across multiple satellites, multiple signals per satellite, multiple signal groups, and multiple RF bands.

The tracking state nests as TrackState → SignalGroup → TrackedSat → TrackedSignal:

TrackState — top-level container; holds a NamedTuple of SignalGroups plus the Doppler-estimator configuration.
SignalGroup — named group of sats that share the same signal-tuple shape (and therefore the same concrete TrackedSat value type, which is what gives the hot loop type stability). Each group also carries its RF band and antenna count.
TrackedSat — per-satellite state: shared carrier/code Doppler and phase (one set of values per satellite, since all signals on a satellite share the same carrier), a tuple of TrackedSignals, and the per-satellite Doppler-estimator state.
TrackedSignal — per-signal state: correlator, post-correlation filter, CN0 estimator, bit buffer, and integration-progress flags.

Estimator-driver signal

The first signal in each group's tuple is the estimator-driver signal — the one the Doppler estimator uses to update the satellite-shared carrier and code Doppler. With the default ConventionalPLLAndDLL / ConventionalAssistedPLLAndDLL, signals[1]'s correlator is the input to the PLL/DLL discriminator, and the per-signal default loop bandwidths are sized off this signal's primary-code period. A user-supplied AbstractDopplerEstimator is free to use the other signals' state too — signals[1]'s privileged role is a convention of the conventional estimators, not a structural constraint of TrackedSat.

Choosing a `TrackState` constructor

TrackState has several constructors. The right choice depends on when you know which satellites you'll track.

One-shot scripts: acquire once, then track

If you acquire once at the start of a script and hand the results straight to tracking, use the AcquisitionResults-aware constructors from the Acquisition extension. They derive everything (signal, default loop bandwidths, satellite parameters) from the acquisition results, so the whole acquire→track handoff is one line.

using Acquisition  # loads the extension; required for TrackState(acq...)

# Single satellite
acq = acquire(GPSL1CA(), data, sampling_frequency, 7)
track_state = TrackState(acq)

# Many satellites, one signal
acqs = acquire(GPSL1CA(), data, sampling_frequency, 1:32)
track_state = TrackState(filter(is_detected, acqs))

# Many satellites, multiple signals
acqs = vcat(
    acquire(GPSL1CA(),    data, sampling_frequency, 1:32),
    acquire(GalileoE1B(), data, sampling_frequency, 1:36),
)
track_state = TrackState(filter(is_detected, acqs);
    signals = (gps = (GPSL1CA(),), gal = (GalileoE1B(),)),
)

You can still call add_satellite! on a TrackState built this way later — but only for signals already declared by the acqs you handed to the constructor (the groups, and therefore the slot types, are frozen at construction). If you anticipate tracking a wider set of signals than the initial acquisition produced, use the empty-construct-then-populate pattern below instead.

Real-time / repeating loops: build empty, then populate

If you re-acquire periodically (a typical receiver: re-search PRNs every few seconds, hand new detections off to tracking without rebuilding the whole TrackState), build an empty TrackState once with TrackState(; signal = ...) or TrackState(; signals = (...)), then add satellites later with add_satellite! (or remove them with remove_satellite!):

# Build once
track_state = TrackState(;
    signals = (gps = (GPSL1CA(),), gal = (GalileoE1B(),)),
)

# In your acquisition loop
while running
    acqs = acquire(GPSL1CA(), latest_chunk, sampling_frequency, candidate_prns)
    track_state = add_satellite!(track_state, filter(is_detected, acqs))   # routes each acq to the matching group
    track_state = track(latest_chunk, track_state, sampling_frequency)
end

This pattern keeps the TrackState's concrete type fixed across the loop — the satellite-dict's slot type is frozen at construction, so the tracking hot path stays type-stable as sats come and go.

The singular signal = GPSL1CA() keyword is the shortcut for the common one-group, one-signal case. It desugars internally to signals = (default = (GPSL1CA(),),), so the rest of the API can stay uniform. With one group, add_satellite! may omit the group = keyword.

Power-user: pre-built `TrackedSat`s

If you need to customize the correlator or post-correlation filter type (the slot type itself), build the TrackedSats yourself and hand them to the positional constructor TrackState(signal, sats) or the add_satellite!(track_state, group, sat) escape hatch. The kwarg-based constructors only let you customize the satellite's values, not its concrete type.

The single-signal TrackedSat constructor surface:

TrackedSat(
    signal,                # e.g. GPSL1CA()
    prn::Int,
    code_phase,
    carrier_doppler;
    # all kwargs below are optional and have signal-derived defaults
    doppler_estimator     = ConventionalAssistedPLLAndDLL(...),
    num_ants              = NumAnts(1),
    correlator            = get_default_correlator(signal, num_ants),
    carrier_phase         = 0.0,
    code_doppler          = carrier_doppler * get_code_center_frequency_ratio(signal),
    num_prompts_for_cn0_estimation = 100,
    post_corr_filter      = DefaultPostCorrFilter(),
)

A worked example combining a narrower-than-default correlator, a custom post-correlation filter (beamformer), and a larger CN0 buffer. The beamformer here is a trivial mean-of-antennas — a real receiver would plug in an actual beamforming algorithm:

julia> using Tracking, GNSSSignals

julia> using Tracking: Hz, NumAnts, AbstractPostCorrFilter

julia> # Trivial beamformer — averages across antenna elements
       struct MyBeamformer <: AbstractPostCorrFilter end

julia> Tracking.update(f::MyBeamformer, prompt) = f;

julia> (::MyBeamformer)(x::AbstractVector) = sum(x) / length(x);

julia> (::MyBeamformer)(x) = x;

julia> sat = TrackedSat(GPSL1CA(), 1, 50.0, 1000.0Hz;
           num_ants                       = NumAnts(4),
           correlator                     = EarlyPromptLateCorrelator(
               num_ants = NumAnts(4),
               preferred_early_late_to_prompt_code_shift = 0.1,
           ),
           post_corr_filter               = MyBeamformer(),
           num_prompts_for_cn0_estimation = 200,
       );

julia> track_state = TrackState(GPSL1CA(), sat);

julia> get_num_ants(track_state, 1)
4

julia> get_correlator(track_state, 1).preferred_early_late_to_prompt_code_shift
0.1

For a multi-signal satellite, the empty TrackState(; signals = (group = (sig1, sig2, …),)) path will build a default template sat the first time you add_satellite! to that group; customize individual TrackedSignals afterwards via the TrackedSat kwarg-update constructor (TrackedSat(sat; signals = (...))).

Tracking.TrackState — Type

Main tracking state container holding satellite states for multiple GNSS systems and the Doppler estimator (e.g., PLL/DLL). This is the primary struct used for tracking operations.

groups is a NamedTuple of SignalGroups. Each group bundles its per-group satellites dictionary, signal-instance tuple, band, and antenna count.

Form	Meaning
`f(track_state)`	Single-group, single-sat — folds via `only(...)` at each level.
`f(track_state, prn)`	Single-group, multi-sat — picks the sat by PRN.
`f(track_state, group, prn)`	Multi-group — picks the sat in the named group.
`f(track_state, group, prn, sig)`	Per-signal — picks one `TrackedSignal` within a multi-signal sat.

Accessor	Returns
`get_prn`	PRN number.
`get_num_ants`	Number of antenna elements.
`get_code_phase`	Shared code phase (wraps at `max_code_length`).
`get_code_doppler`	Shared code Doppler.
`get_carrier_phase`	Shared carrier phase in radians.
`get_carrier_doppler`	Shared carrier Doppler.
`get_signal_start_sample`	Index of the next sample to integrate.

Accessor	Returns
`get_correlator`	The working correlator (in-flight accumulator).
`get_last_fully_integrated_correlator`	Correlator value from the last completed integration.
`get_last_fully_integrated_filtered_prompt`	Filtered prompt value from the last completed integration.
`get_post_corr_filter`	The post-correlation filter.
`get_cn0_estimator`	The CN0 estimator.
`estimate_cn0`	CN0 estimate in dB-Hz.
`get_bit_buffer` / `get_bits` / `get_num_bits`	Bit buffer, decoded bits, bit count.
`get_integrated_samples`	Number of samples accumulated into the current integration so far.
`has_bit_or_secondary_code_been_found`	`true` once bit/secondary-code synchronization has been achieved.