Python Loop Filter API¶

Advance the loop one update with error x and return the control value the tracker should apply.

The PI recurrence is integ += ki*x; control = integ + kp*x: the integrator accumulates the running frequency/rate estimate while the proportional term kp*x is the instantaneous phase nudge.

Fed a constant error with nothing closing the loop, the integrator — and therefore the control — ramps without bound; measured at 1.84x between updates 200 and 400 at bn = 0.02. That is the accumulation working, not a defect, and it is what pulls a Costas/DLL/timing loop into lock once the loop IS closed, because a converging loop is one whose error is being driven to zero by the correction. Convergence is a property of the closed loop; this function is one term in it.

Parameters:

Returns:

Examples:

>>> from doppler.track import LoopFilter
>>> lf = LoopFilter(bn=0.02, zeta=0.707, t=1.0)
>>> round(lf.step(1.0), 6)   # unit error: control = ki + kp
0.05331
>>> round(lf.integ, 6)       # integrator now holds ki
0.001385

Filter a whole block of loop errors, returning the control value for each update.

Equivalent to calling loop_filter_step() once per element of x in order, carrying the integrator across the block, so the loop's memory and lock state persist from one call to the next. This is the block path used to run a captured error sequence through the filter in one shot — a plain per-element loop, not a vectorized one: the recurrence is sequential, so each update depends on the one before it.

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.track import LoopFilter
>>> lf = LoopFilter(bn=0.05, zeta=0.707, t=1.0)
>>> ctl = lf.steps(np.full(50, 0.1))   # constant error into the loop
>>> round(float(ctl[0]), 4)            # first control nudge
0.0133
>>> round(float(ctl[-1]), 4)           # open loop: ramping
0.0541

Recompute the loop gains for a new (bn, zeta, t); preserves the integrator.

Recomputes the proportional and integral gains from the standard 2nd-order form but leaves integ untouched, so a loop can be widened for fast acquisition and then narrowed for steady-state tracking while holding its accumulated frequency/rate estimate — the retune preserves lock.

Parameters:

Examples:

>>> from doppler.track import LoopFilter
>>> lf = LoopFilter(bn=0.01, zeta=0.707, t=1.0)
>>> _ = lf.step(1.0)
>>> before = round(lf.integ, 6)
>>> lf.configure(0.05, 0.707, 1.0)   # widen the loop, keep lock
>>> round(lf.integ, 6) == before     # integrator preserved
True
>>> round(lf.kp, 6)                  # proportional gain rose
0.124728

Zero the integrator; keep the configured gains.

Clears the accumulated frequency/rate estimate (integ) back to zero but leaves kp / ki as configured, so the loop reacquires from a clean slate at its current bandwidth — the right thing when a tracker drops lock and must restart, without re-deriving gains.

Examples:

>>> from doppler.track import LoopFilter
>>> lf = LoopFilter(bn=0.02, zeta=0.707, t=1.0)
>>> for _ in range(10):
...     _ = lf.step(1.0)             # ramp the integrator
>>> round(lf.integ, 6)
0.013849
>>> lf.reset()
>>> lf.integ                          # integrator cleared, gains kept
0.0

Size in bytes of this object's serialized state.

The exact length get_state returns and set_state requires. It depends on how the object was constructed (state arrays are sized at construction), so read it from the instance rather than assuming a constant.

Raises RuntimeError if the LoopFilter has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures exactly the state that evolves as the object runs, so a blob taken now and restored later resumes from this point. Construction parameters are not included: restore into an object built the same way.

The blob is opaque and always state_bytes() long. Its layout is an implementation detail of the C core and is not a stable format across builds.

Raises RuntimeError if the LoopFilter has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place; the object keeps the parameters it was constructed with. Length is validated against state_bytes() before the blob is handed to the C core, and the core may reject it as well.

Raises TypeError if blob is not bytes, ValueError if its length differs from state_bytes() or the core rejects it, and RuntimeError if the LoopFilter has already been destroyed.

Parameters:

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Enter a context manager, returning this object.

Lets a LoopFilter be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the LoopFilter.

Equivalent to calling destroy(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters:

De-rotate a cf32 block with the integer-NCO carrier, coherently integrate over each tsamps-sample symbol, run the decision-directed Costas discriminator, and emit one complex prompt symbol per symbol.

The streaming Python face of the loop. For every input sample it wipes the (tracked) carrier off x with the integer-phase NCO, sums the result into the coherent integrate-and-dump accumulator, and on each symbol boundary (one every tsamps samples) dumps the accumulator as the prompt, runs the BPSK Costas discriminator to steer the NCO frequency and phase, and appends the mean-scaled prompt to the output. Loop state carries across calls, so a long capture can be fed block by block; exactly one prompt symbol comes out per tsamps input samples.

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.track import Costas
>>> tsamps = 16
>>> rng = np.random.default_rng(1)
>>> bits = rng.integers(0, 2, 4000) * 2 - 1
>>> sig = np.repeat(bits.astype(np.complex64), tsamps)
>>> k = np.arange(len(sig))
>>> rx = (sig * np.exp(2j * np.pi * 0.003 * k)).astype(np.complex64)
>>> c = Costas(bn=0.05, zeta=0.707, tsamps=tsamps)
>>> sym = c.steps(rx)             # one prompt per tsamps samples
>>> sym.shape
(4000,)
>>> round(c.norm_freq, 4)         # pulled onto the 0.003 residual
0.003
>>> c.lock_metric > 0.9
True

Largest number of samples steps() can return in the current state.

Size an out= buffer with this before calling steps(), or use it to allocate one up front. The bound is this object's own: what it depends on is a property of the algorithm, so a header block on steps_max_out() replaces this text.

Returns:

Attach (or detach) a telemetry context and register the carrier loop's probes on it. Registers four probes, emitted once per dumped symbol and further thinned by decim: ".lock" (the |Re P|/|P| lock-metric EMA, 1 = phase-locked), ".e" (the PLL discriminator output — the loop stress), ".freq" (the tracked NCO frequency, cycles/sample) and ".locked" (the verify-counted lock decision, 0/1 — see costas_configure_lock). Passing NULL detaches. Setup path, never hot: call before the producer thread starts stepping; the context is borrowed and must outlive the attachment (SPSC rules in dp_tlm/dp_tlm_core.h).

Parameters:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.track import Costas
>>> from doppler.telemetry import Telemetry
>>> tlm = Telemetry(1 << 12)
>>> c = Costas(bn=0.05, zeta=0.707, tsamps=64)
>>> c.set_telemetry(tlm, "car")
>>> sorted(tlm.probe_names)
['car.e', 'car.freq', 'car.lock', 'car.locked']
>>> x = np.ones(64 * 100, dtype=np.complex64)
>>> _ = c.steps(x)
>>> recs = tlm.read()   # four records per dumped symbol
>>> len(recs) == 4 * 100
True

Recompute the loop gains for a new (bn, zeta); preserves the frequency/phase estimate.

Re-derives the PI coefficients from the loop bandwidth and damping and installs them live. The NCO frequency, phase and loop integrator are left untouched, so a converged loop keeps tracking straight through the re-tune — narrow the bandwidth once pulled in for lower phase jitter, or widen it to chase a faster-moving residual.

Parameters:

Examples:

>>> from doppler.track import Costas
>>> c = Costas(bn=0.05, zeta=0.707, init_norm_freq=0.01, tsamps=16)
>>> c.configure(0.02, 1.0)              # narrow the loop, over-damp
>>> (round(c.bn, 3), round(c.norm_freq, 3))  # new gains, est kept
(0.02, 0.01)

Re-tune the carrier lock detector: locked flips up after n_up consecutive dumped symbols with the lock-metric EMA above up_thresh, and drops after n_down consecutive symbols below down_thresh (level + time hysteresis; see detection.LockDet). The defaults (0.85/0.78, 8 up / 32 down) derive from the metric's no-carrier statistics: |Re P|/|P| averages 2/pi (~0.64) under H0 with an EMA-smoothed std of ~0.07, so the declare threshold sits ~3 sigma above the no-carrier mean. A live lock survives the re-tune; the in-flight verify run restarts.

The always-on lock decision steps a verify-counted detector (lockdet_core.h) on the |Re P|/|P| lock-metric EMA once per dumped symbol: locked flips up after n_up consecutive symbols with the metric above up_thresh and drops after n_down consecutive symbols below down_thresh. The defaults derive from the metric's own H0 statistics — with no carrier, |Re P|/|P| = |cos(theta)| for a uniform theta, whose mean is 2/pi (~0.637) and per-symbol std ~0.31; the COSTAS_LOCK_ALPHA = 0.1 EMA reduces that to ~0.071, so the default declare threshold 0.85 sits ~3 sigma above the no-carrier mean, with the drop threshold at 0.78 for level hysteresis and 8-up/32-down verify counts for time hysteresis (declare fast, drop reluctantly — the EMA already correlates adjacent looks, so the counts guard against band-edge dwell rather than compounding i.i.d. probabilities). A live lock survives the re-tune; the in-flight verify run restarts.

Parameters:

Examples:

>>> from doppler.track import Costas
>>> c = Costas(bn=0.05, zeta=0.707, tsamps=64)
>>> c.locked
False
>>> c.configure_lock(0.9, 0.8, 4, 16)   # tighter declare, faster drop

Re-seed the loop to the create-time frequency/phase; preserve config.

Drops the lock and rewinds the NCO, loop integrator and integrate-and-dump accumulators to the create-time seed frequency, while retaining the configured loop bandwidth, damping and lock-detector thresholds. Reprocess the same input after a reset and the output is bit-identical.

Examples:

>>> import numpy as np
>>> from doppler.track import Costas
>>> tsamps = 16
>>> rng = np.random.default_rng(3)
>>> bits = rng.integers(0, 2, 1500) * 2 - 1
>>> sig = np.repeat(bits.astype(np.complex64), tsamps)
>>> k = np.arange(len(sig))
>>> rx = (sig * np.exp(2j * np.pi * 0.002 * k)).astype(np.complex64)
>>> c = Costas(bn=0.05, zeta=0.707, tsamps=tsamps)
>>> _ = c.steps(rx)
>>> round(c.norm_freq, 4) != 0.0     # loop pulled onto the residual
True
>>> c.reset()
>>> c.norm_freq                       # back to the create-time seed
0.0
>>> c.lock_metric
0.0

Size in bytes of this object's serialized state.

The exact length get_state returns and set_state requires. It depends on how the object was constructed (state arrays are sized at construction), so read it from the instance rather than assuming a constant.

Raises RuntimeError if the Costas has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures exactly the state that evolves as the object runs, so a blob taken now and restored later resumes from this point. Construction parameters are not included: restore into an object built the same way.

The blob is opaque and always state_bytes() long. Its layout is an implementation detail of the C core and is not a stable format across builds.

Raises RuntimeError if the Costas has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place; the object keeps the parameters it was constructed with. Length is validated against state_bytes() before the blob is handed to the C core, and the core may reject it as well.

Raises TypeError if blob is not bytes, ValueError if its length differs from state_bytes() or the core rejects it, and RuntimeError if the Costas has already been destroyed.

Parameters:

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Enter a context manager, returning this object.

Lets a Costas be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the Costas.

Equivalent to calling destroy(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters:

De-rotate a cf32 block with the integer-NCO carrier, coherently integrate over each tsamps-sample symbol, run the decision-directed M-PSK discriminator (slice to the nearest constellation point, error Im(P*conj(ahat))/|P|), and emit one complex prompt symbol per symbol. The loop tracks a small residual carrier (bulk Doppler removed upstream); it locks to one of m phases, so resolve the M-fold ambiguity downstream (mpsk_diff_demap or a sync word). At m=2 this is exactly the BPSK Costas loop.

The block form of the inline wipeoff/update pair: for each input sample it de-rotates by the carrier NCO and accumulates the coherent integrate-and-dump; every tsamps samples it dumps the prompt, runs the decision-directed M-PSK discriminator (slice to the nearest constellation point, error Im(P conj(ahat))/|P|, plus the optional cross-product FLL assist), filters the error, and steers the NCO frequency and phase. Exactly one de-rotated prompt is emitted per completed symbol; a trailing partial symbol is carried in the accumulator to the next call, so a stream can be fed in blocks of any length with no seam.

The loop locks to one of m carrier phases — an M-fold ambiguity on the absolute constellation orientation. Resolve it downstream (differential demapping or a sync word); this call only recovers the carrier and returns the prompts. At m = 2 it is exactly the BPSK Costas loop.

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.mpsk import mpsk_map
>>> from doppler.track import CarrierMpsk
>>> rng = np.random.default_rng(0)
>>> sps = 16
>>> labels = rng.integers(0, 4, 400).astype(np.uint8)
>>> sig = np.repeat(mpsk_map(labels, 4), sps).astype(np.complex64)
>>> k = np.arange(len(sig))
>>> rx = (sig * np.exp(2j * np.pi * 0.002 * k)).astype(np.complex64)
>>> c = CarrierMpsk(bn=0.04, zeta=0.707, init_norm_freq=0.0,
...                 tsamps=sps, bn_fll=0.02, m=4)
>>> prompts = c.steps(rx)          # one prompt per symbol
>>> prompts.shape
(400,)
>>> round(c.norm_freq, 4)       # tracked the residual carrier 0.002
0.002
>>> round(c.lock_metric, 2)        # decision-aligned lock metric -> 1
1.0

Largest number of samples steps() can return in the current state.

Size an out= buffer with this before calling steps(), or use it to allocate one up front. The bound is this object's own: what it depends on is a property of the algorithm, so a header block on steps_max_out() replaces this text.

Returns:

Recompute the loop gains for a new (bn, zeta); preserves the frequency/phase estimate.

Re-derives the proportional/integral gains of the embedded 2nd-order loop filter for the new noise bandwidth and damping, leaving the running frequency and phase estimate (the NCO and the loop integrator) untouched — a live lock survives a re-tune. Use it to widen the loop for fast pull-in and then narrow it for low-jitter tracking, mid-stream.

Parameters:

Examples:

>>> from doppler.track import CarrierMpsk
>>> c = CarrierMpsk(bn=0.02, zeta=0.707, init_norm_freq=0.01,
...                 tsamps=16, bn_fll=0.0, m=4)
>>> round(c.bn, 3)
0.02
>>> c.configure(bn=0.05, zeta=1.0)   # widen the loop mid-stream
>>> round(c.bn, 3)
0.05
>>> round(c.norm_freq, 3)            # frequency estimate preserved
0.01

Re-seed the loop to the create-time frequency/phase; preserve config.

Returns the NCO to the seed carrier passed at construction, zeroes the integrate-and-dump accumulator, the FLL history, and the lock/error diagnostics, and re-primes the loop integrator to the matching per-symbol frequency — the exact state a fresh carrier_mpsk_create() leaves. The tuning (bn, zeta, bn_fll, tsamps, m) is untouched. Call it at a capture boundary so a lock reached on one segment does not bias an unrelated next one.

Examples:

>>> import numpy as np
>>> from doppler.mpsk import mpsk_map
>>> from doppler.track import CarrierMpsk
>>> rng = np.random.default_rng(1)
>>> sig = np.repeat(
...     mpsk_map(rng.integers(0, 4, 100).astype(np.uint8), 4),
...                 16).astype(np.complex64)
>>> rx = (sig * np.exp(2j * np.pi * 0.003 * np.arange(len(sig)))
...       ).astype(np.complex64)
>>> c = CarrierMpsk(bn=0.04, zeta=0.707, init_norm_freq=0.0,
...                 tsamps=16, bn_fll=0.02, m=4)
>>> _ = c.steps(rx)
>>> round(c.norm_freq, 3)   # loop pulled onto the residual carrier
0.003
>>> c.reset()               # back to the create-time seed
>>> round(c.norm_freq, 3)
0.0

Size in bytes of this object's serialized state.

The exact length get_state returns and set_state requires. It depends on how the object was constructed (state arrays are sized at construction), so read it from the instance rather than assuming a constant.

Raises RuntimeError if the CarrierMpsk has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures exactly the state that evolves as the object runs, so a blob taken now and restored later resumes from this point. Construction parameters are not included: restore into an object built the same way.

The blob is opaque and always state_bytes() long. Its layout is an implementation detail of the C core and is not a stable format across builds.

Raises RuntimeError if the CarrierMpsk has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place; the object keeps the parameters it was constructed with. Length is validated against state_bytes() before the blob is handed to the C core, and the core may reject it as well.

Raises TypeError if blob is not bytes, ValueError if its length differs from state_bytes() or the core rejects it, and RuntimeError if the CarrierMpsk has already been destroyed.

Parameters:

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Enter a context manager, returning this object.

Lets a CarrierMpsk be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the CarrierMpsk.

Equivalent to calling destroy(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters:

De-rotate a cf32 block with the integer-NCO carrier and return the de-rotated samples (one per input sample). Internally the loop runs a non-data-aided M-th-power discriminator on an I/Q arm integrate-and-dump at n dumps per symbol and steers the NCO, so it acquires the carrier with no symbol timing and no data present (it strips the M-PSK modulation by raising the arm sample to the Mth power). It locks to one of m phases (M-fold ambiguity), resolved downstream. Read norm_freq for the tracked carrier and lock for the carrier lock metric.

Runs the non-data-aided carrier loop over the block: each sample is wiped off by the integer-phase NCO, the de-rotated sample slides the I/Q moving-average arm, and the M-th-power discriminator (which strips the M-PSK data modulation) steers the NCO frequency and phase. Because the discriminator is data- and timing-independent, this acquires the carrier with no symbol timing and no data present — a bare carrier, or a modulated carrier before timing lock. It resolves to one of m carrier phases (M-fold ambiguity, resolved downstream). Read norm_freq for the tracked carrier (cycles/sample) and lock for the carrier lock metric.

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.track import CarrierNda
>>> c = CarrierNda(bn=0.01, zeta=0.707, init_norm_freq=0.0,
...                sps=8, n=4, m=4)
>>> rng = np.random.default_rng(0)
>>> k = np.arange(40000)
>>> x = (np.exp(2j * np.pi * 0.001 * k) + 0.05 * (
...      rng.standard_normal(k.size)
...      + 1j * rng.standard_normal(k.size))).astype(np.complex64)
>>> y = c.steps(x)                 # de-rotated toward DC
>>> y.shape[0]
40000
>>> round(c.norm_freq, 4)          # tracked carrier, cycles/sample
0.001
>>> c.lock > 0.5                    # carrier lock metric, ~1 at lock
True

Largest number of samples steps() can return in the current state.

Size an out= buffer with this before calling steps(), or use it to allocate one up front. The bound is this object's own: what it depends on is a property of the algorithm, so a header block on steps_max_out() replaces this text.

Returns:

Attach (or detach) a telemetry context and register the carrier loop's probes on it. Registers four probes, emitted once per input sample (this is a sample-rate loop — use decim to thin the stream): ".lock" (the lock-signal EMA, ~1 when phase-locked), ".e" (the M-th-power phase discriminator — the loop stress), ".freq" (the tracked carrier frequency, cycles/sample) and ".locked" (the verify-counted lockdet decision, 0/1). Passing NULL detaches. Setup path, never hot: call before the producer thread starts stepping; the context is borrowed and must outlive the attachment (SPSC rules in dp_tlm/dp_tlm_core.h).

Parameters:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.track import CarrierNda
>>> from doppler.telemetry import Telemetry
>>> tlm = Telemetry(1 << 14)
>>> c = CarrierNda(bn=0.01, sps=8, n=4, m=4)
>>> c.set_telemetry(tlm, "car", decim=8)
>>> sorted(tlm.probe_names)
['car.e', 'car.freq', 'car.lock', 'car.locked']
>>> x = np.exp(2j * np.pi * 0.005 * np.arange(4096)).astype(
...     np.complex64)
>>> _ = c.steps(x)
>>> recs = tlm.read()
>>> len(recs[recs["probe"] == tlm.probe_id("car.e")]) == 4096 // 8
True

Re-tune the carrier lock detector: locked flips up after n_up consecutive samples with the lock-signal EMA above up_thresh, and drops after n_down consecutive samples below down_thresh (level + time hysteresis; see detection.LockDet). Defaults are 0.5/0.4 with 64 up / 32 down. The THRESHOLDS are Pfa-derived: 0.5 is 4.416 sigma on the statistic's H0 spread, a per-look false-alarm rate of 5e-6, and it means that at every M because the limited statistic's H0 variance is 1/2 for all of them. The VERIFY COUNT is not derived that way and must not be. Compounding a per-look Pfa over n_up assumes successive looks are independent; this detector steps once per sample and its lock EMA stays correlated for roughly 39 samples, so a shorter count is counting one look several times. Measured against noise-only input, n_up=8 -- the value MpskReceiver uses on this same statistic -- false-locked 4 trials in 30, while 64 was the smallest count clean over 300. Raise n_up rather than lower it unless you have re-measured. A live lock survives the re-tune; the in-flight verify run restarts.

Full lockdet control, mirroring costas_configure_lock(): a split declare/drop threshold pair on the lock-signal EMA (level hysteresis) and both verify counts (time hysteresis). Defaults (0.5/0.4, 64 up / 32 down) start from MpskReceiver's own pre-existing acquisition<-> tracking handover thresholds, but size n_up independently: lock is a fast per-sample EMA, so consecutive looks are highly autocorrelated and MpskReceiver's own n_up=8 does not compound the false-declare rate the way it would for independent looks (direct Monte Carlo against a noise-only, no-carrier input found real false locks at n_up=8; n_up=64 was the smallest verify count that reliably eliminated them -- see carrier_nda_core.c's CARRIER_NDA_LOCK_DEFAULT_* comment for the exact trial data). A live lock survives the re-tune; the in-flight verify run restarts.

Parameters:

Examples:

>>> from doppler.track import CarrierNda
>>> c = CarrierNda(bn=0.01, sps=8, n=4, m=4)
>>> c.locked
False
>>> c.configure_lock(0.6, 0.5, 16, 64)   # tighter declare, slower drop

Re-seed the loop to the create-time frequency/phase; preserve config.

Restores the object to its post-create state: the carrier NCO is reset to the seed frequency it was constructed with (init_norm_freq) with zero phase, the moving-average arm, the loop-filter integrator and the lock EMA are cleared, and the lock detector is dropped. The configured (bn, zeta), the arm geometry (sps, n) and the constellation order m are preserved, so the same object can re-acquire a fresh capture.

Examples:

>>> import numpy as np
>>> from doppler.track import CarrierNda
>>> c = CarrierNda(bn=0.01, zeta=0.707, init_norm_freq=0.0,
...                sps=8, n=4, m=4)
>>> rng = np.random.default_rng(0)
>>> k = np.arange(40000)
>>> x = (np.exp(2j * np.pi * 0.001 * k) + 0.05 * (
...      rng.standard_normal(k.size)
...      + 1j * rng.standard_normal(k.size))).astype(np.complex64)
>>> _ = c.steps(x)
>>> round(c.norm_freq, 4), round(c.lock, 2)   # acquired the carrier
(0.001, 0.99)
>>> c.reset()
>>> round(c.norm_freq, 4), round(c.lock, 2)   # back to seed, unlocked
(0.0, 0.0)

Size in bytes of this object's serialized state.

The exact length get_state returns and set_state requires. It depends on how the object was constructed (state arrays are sized at construction), so read it from the instance rather than assuming a constant.

Raises RuntimeError if the CarrierNda has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures exactly the state that evolves as the object runs, so a blob taken now and restored later resumes from this point. Construction parameters are not included: restore into an object built the same way.

The blob is opaque and always state_bytes() long. Its layout is an implementation detail of the C core and is not a stable format across builds.

Raises RuntimeError if the CarrierNda has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place; the object keeps the parameters it was constructed with. Length is validated against state_bytes() before the blob is handed to the C core, and the core may reject it as well.

Raises TypeError if blob is not bytes, ValueError if its length differs from state_bytes() or the core rejects it, and RuntimeError if the CarrierNda has already been destroyed.

Parameters:

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Enter a context manager, returning this object.

Lets a CarrierNda be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the CarrierNda.

Equivalent to calling destroy(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters:

Correlate a cf32 block against the local code with early/prompt/late taps and steer the code NCO each code period on the non-coherent (sum|E|-sum|L|)/(sum|E|+sum|L|) discriminator. With segments=1 (default) this is a coherent full-epoch integrate-and-dump: one prompt symbol per period. With segments>1 each epoch is split into that many sub-epoch partial correlations: it emits that many partial prompts per period (a stream at ~segments samples/symbol when the symbol rate is near the code rate) and tracks the code non-coherently across the partials, which a data flip cannot collapse (robust to an asynchronous data-symbol clock). segments>1 is the streaming despreader: it removes the PN code and outputs samples. The non-coherent loop is carrier-blind, so it tracks with a residual carrier still on the input; carrier recovery (Costas) and symbol-timing recovery (SymbolSync) are downstream stages fed from the partial output. Returned blocks are safe to keep across calls (block-size invariant): a block whose array is still referenced is never overwritten by a later call (jm gh-437).

The Python face of the loop. Each code period the early/prompt/late correlators dump, the power-domain non-coherent early-minus-late discriminator runs, and the fixed-point code-phase NCO is re-steered; the prompt correlator value is emitted as one output symbol per period (or segments partial prompts per period when segments > 1). The loop is carrier-blind — it tracks with a residual carrier still on the input, so carrier recovery (Costas) and symbol-timing recovery are downstream stages fed from this output. Returned blocks are block-size invariant and safe to keep across calls (a block still referenced is never overwritten, jm gh-437).

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.track import Dll
>>> rng = np.random.default_rng(1)
>>> code = rng.integers(0, 2, 31).astype(np.uint8)
>>> chip = np.where(code & 1, -1.0, 1.0)    # BPSK spreading code
>>> x = np.tile(np.repeat(chip, 2), 40).astype(np.complex64)
>>> d = Dll(code=code, sps=2)
>>> sym = d.steps(x)                        # one prompt per period
>>> sym.dtype
dtype('complex64')
>>> round(float(np.mean(sym.real[-10:])), 1)  # despread to a clean +1
1.0
>>> round(d.code_rate, 3)                   # locked at nominal rate
1.0

Largest number of samples steps() can return in the current state.

Size an out= buffer with this before calling steps(), or use it to allocate one up front. The bound is this object's own: what it depends on is a property of the algorithm, so a header block on steps_max_out() replaces this text.

Returns:

Attach (or detach) a telemetry context and register the code loop's probes on it. Registers four probes, emitted once per code epoch (period) and further thinned by decim: ".e" (the early-minus-late envelope discriminator — the loop stress), ".rate" (the tracked code rate, chips advanced per nominal chip, ~1.0 at lock), ".lock" (the CFAR lock statistic R; compare against the configured threshold) and ".locked" (the verify-counted lock decision, 0/1 — the lockdet output, so a consumer sees where the declare/drop rule fired without re-deriving it from the statistic). Passing NULL detaches. Setup path, never hot: call before the producer thread starts stepping; the context is borrowed and must outlive the attachment (SPSC rules in dp_tlm/dp_tlm_core.h).

Parameters:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.track import Dll
>>> from doppler.telemetry import Telemetry
>>> tlm = Telemetry(1 << 12)
>>> code = np.zeros(31, dtype=np.uint8)
>>> d = Dll(code=code, sps=2)
>>> d.set_telemetry(tlm, "code")
>>> sorted(tlm.probe_names)
['code.e', 'code.lock', 'code.locked', 'code.rate']
>>> x = np.ones(31 * 2 * 50, dtype=np.complex64)
>>> _ = d.steps(x)
>>> recs = tlm.read()   # four records per code epoch
>>> len(recs) > 0 and len(recs) % 4 == 0
True

Recompute the loop gains for a new (bn, zeta); preserves the code phase/rate.

Re-derives the 2nd-order loop filter's proportional and integral gains for a new noise bandwidth and damping, leaving the tracked code phase, code rate and correlator accumulators untouched — retune the loop mid-run (e.g. narrow the bandwidth once pulled in) without dropping lock.

Parameters:

Examples:

>>> import numpy as np
>>> from doppler.track import Dll
>>> rng = np.random.default_rng(1)
>>> code = rng.integers(0, 2, 31).astype(np.uint8)
>>> d = Dll(code=code, sps=2, bn=0.01)
>>> d.configure(bn=0.02, zeta=0.707)   # widen the bandwidth mid-run
>>> round(d.bn, 3)
0.02

Set the carrier-aiding code-rate deviation (ratio; 0 = off): a fixed fractional rate bias summed into the code NCO's phase_inc every epoch, on top of the loop's own control. For physically-coupled Doppler, pass carrier_offset_hz / carrier_freq_hz so the code NCO rides the code-rate dilation the discriminator alone can't pull in at low SNR. Applied continuously across the epoch (not a phase pulse), and nudges the current phase_inc so the aid takes effect before the first period update. code_rate stays the loop's own observable and is unaffected.

A fixed fractional rate bias summed into the sample-and-hold phase_inc on top of the loop's own control every epoch -- for physically-coupled Doppler, carrier_offset_hz / carrier_freq_hz, so the code NCO rides the code-rate dilation the discriminator alone can't pull in at low SNR. Applied continuously across the epoch (via phase_inc), not as a phase pulse. Also nudges the current phase_inc so the aid takes effect before the first period update. code_rate stays the loop's own observable and is unaffected.

Parameters:

Examples:

>>> import numpy as np
>>> from doppler.track import Dll
>>> rng = np.random.default_rng(11)
>>> code = rng.integers(0, 2, 63).astype(np.uint8)
>>> delta = 5e-4                                   # code-rate Doppler
>>> idx = (np.arange(63 * 4 * 300) * (1 + delta) / 4).astype(
...     np.int64) % 63
>>> x = np.where(code[idx] & 1, -1.0, 1.0).astype(np.complex64)
>>> plain = Dll(code, sps=4, bn=0.005)
>>> _ = plain.steps(x)
>>> round(plain.code_rate, 4)      # loop had to pull the whole Doppler
1.0005
>>> aided = Dll(code, sps=4, bn=0.005)
>>> aided.set_rate_aid(delta)      # feed the Doppler forward instead
>>> _ = aided.steps(x)
>>> round(aided.code_rate, 4)      # loop integrator stays at nominal
1.0