Tracking State

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

TrackState: a NamedTuple of SignalGroups and the Doppler estimator.
SignalGroup: satellites with the same signal tuple, and so one concrete TrackedSat type (the hot loop's type stability), on one RF band and antenna array.
TrackedSat: the carrier/code Doppler and phase its signals share, a tuple of TrackedSignals, and the Doppler-estimator state.
TrackedSignal: correlator, post-correlation filter, C/N₀ estimator, bit buffer and integration progress.

Estimator-driver signal

The first signal of each group's tuple is the estimator-driver signal, the one the Doppler estimator updates the shared carrier and code Doppler from. The conventional estimators (ConventionalPLLAndDLL, ConventionalAssistedPLLAndDLL) run their discriminators on it and take its default loop bandwidths (a carrier loop pulling in at 50 Hz and narrowing to 18 Hz, 1 Hz code). A custom AbstractDopplerEstimator may use any signal.

Bit sync, the post-correlation filter and the C/N₀ estimator run per signal, so a multi-signal satellite has one C/N₀ per signal; see CN0 Estimator and NoCN0Estimator, the per-signal opt-out.

Choosing a `TrackState` constructor

The right constructor depends on when you know which satellites you'll track.

One-shot scripts: acquire once, then track

The Acquisition extension's constructors derive signals, loop bandwidths and satellites from AcquisitionResults:

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(),)),
)

add_satellite! can later add satellites only for the signals those acqs declared, as the groups are frozen at construction. To track more signals, build empty and populate instead.

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

A receiver that re-acquires periodically builds an empty TrackState once with TrackState(; signal = ...) or TrackState(; signals = (...)) and adds and removes satellites with add_satellite! and 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

The TrackState's concrete type stays fixed as satellites come and go. signal = GPSL1CA() is short for signals = (default = (GPSL1CA(),),); with one group, add_satellite! may omit group =.

Power-user: pre-built `TrackedSat`s

To change the correlator or post-correlation filter type, build the TrackedSats yourself, pass them to TrackState(signal, sats), and add more with add_satellite!(track_state, group, sat). The single-signal constructor:

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,
    cn0_estimator         = TrackingLoops.default_cn0_estimator(signal, num_prompts_for_cn0_estimation),
    post_corr_filter      = DefaultPostCorrFilter(),
)

cn0_estimator takes any AbstractCN0Estimator; as a type parameter of TrackedSignal, unlike the correlator and filter, it may change the satellite's type (see CN0 Estimator).

An example with a narrower correlator, a trivial mean-of-antennas beamformer and a larger C/N₀ buffer. A filter declares its combining weights rather than combining the taps itself, so the C/N₀ path can reduce the measured noise covariance through the same weights:

julia> using Tracking, TrackingLoops, GNSSSignals, StaticArrays

julia> using Tracking: Hz

julia> using TrackingLoops: NumAnts, AbstractPostCorrFilter

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

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

julia> TrackingLoops.get_weights(::MyBeamformer, ::NumAnts{1}) = 1.0 + 0.0im;

julia> TrackingLoops.get_weights(::MyBeamformer, ::NumAnts{M}) where {M} =
           SVector{M,ComplexF64}(ntuple(_ -> 1 / M + 0.0im, M));

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, customize individual TrackedSignals with the kwarg-update constructor TrackedSat(sat; signals = (...)).

Tracking.TrackState — Type

The tracking state: the satellites of every signal group and the Doppler estimator.

groups is a NamedTuple of SignalGroups.

noise_estimators is a NamedTuple of AbstractNoiseEstimators keyed by signal id (GNSSSignals.get_signal_id), since the post-correlation floor depends on the despreading modulation. Only signals whose C/N₀ estimator reads a noise density (see requires_noise_density) get one, so the others pay nothing. They average in place.

noise_descriptor is per-call scratch: a heap cell where the correlate step parks the chunk's noise descriptors, so a threaded backend reaches them through one pointer (see _park_noise_items!). Shared by every derived TrackState.

sample_offsets counts, per band (keyed by get_band_id), the samples earlier track! calls consumed: the origin of the current measurement on a sample grid that runs on across calls. The estimate phase adds it to a record's index, so an estimator with per-satellite state of its own (TrackingLoops' VectorPLLAndDLL) sees every satellite on one time grid. The in-place mutators share it; track, merge_sats, add_satellite and remove_satellite give their result a copy.

A fresh TrackState starts every band at 0. To carry such an estimator over into a rebuilt TrackState (e.g. to add a band), pass the old state's offsets as the sample_offsets keyword, or the estimator receives records from its past. A band the old state did not track starts at elapsed_time * sampling_frequency samples of the new band.

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_phase_correction`	What the estimator adds to `get_carrier_phase` for the carrier-phase measurement (vector loop only; takes the band's sampling frequency).
`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_last_fully_integrated_num_code_blocks`	Primary-code block count of the last completed integration.
`get_last_fully_integrated_integration_time`	Integration time `T` of the last completed integration; the post-integration SNR is C/N₀ × `T`.
`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_soft_bits` / `get_num_bits`	Bit buffer, decoded soft bits (sign = the hard bit), 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.