Python Correlation & Detection API¶

Zero the accumulator and reset the integration counter to 0. Equivalent to starting a fresh dwell cycle without rebuilding FFT plans or recomputing ref_spec.

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=3)
>>> _ = c.execute(np.ones((2, 2), dtype=np.complex64))
>>> c.count
1
>>> c.reset()
>>> c.count
0

Correlate one 2-D frame and optionally dump the coherent accumulator. Runs the 2-D pipeline: FFT2 → pointwise multiply with ref_spec → accumulate the cross-spectrum; on dump, IFFT2 → normalise (÷ nynx). Accumulating in the frequency domain and inverting once is exactly the per-frame inverse summed, by linearity of the IFFT — valid because the dwell is coherent* (a complex sum); a non-coherent (magnitude) integration could not defer the inverse.

Layout. A frame is nynx complex samples in row-major order: row i is samples inx .. (i+1)*nx - 1. For Corr2D that is a (ny, nx) image; for DelayDoppler it is the raw stream, ny code periods of nx = code_len samples back to back. The map a dump produces is flat, n_out = ny_out * nx_out values (ny values with col_out), also row-major: reshape it to (ny_out, nx_out). On a DelayDoppler, axis 0 is Doppler (centered, zero Doppler on row ny_out / 2) and axis 1 is delay (the lag, in samples).

Ownership. In Python, a call that dumps returns a new array when no out= is given, and a view of out= when one is (a 1-D array holding at least n_out values; it is written on a dump only, and the next dump overwrites it). A call that does not dump returns None and touches neither.

Parameters:

Returns:

Raises:

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=2)
>>> x = np.ones((2, 2), dtype=np.complex64)
>>> c.execute(x) is None   # frame 1 — no dump
True
>>> c.execute(x).tolist()  # frame 2 — dump
[(2+0j), (2+0j), (2+0j), (2+0j)]

Maximum output samples per execute call (dp_correlator_state_t::n_out -- ny_out*nx_out normally, or ny when a single dp_correlator_state_t::col_out was selected).

Returns:

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 Corr has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures the state that evolves as the object runs, including any value a setter changed after construction, so a blob taken now and restored later resumes from this point. Construction parameters are not restored: restore into an object built the same way. A core may check some of them and refuse a blob built differently.

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 Corr has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place, including any value a setter changed after construction. Construction parameters are not restored: restore into an object built the same way. Length is validated against state_bytes() before the blob is handed to the C core, which may reject it too: a core may check some construction parameters and refuse a blob built differently.

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

Parameters:

Raises:

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 Corr 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 Corr.

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

Parameters:

Zero the accumulator and reset the integration counter to 0. Equivalent to starting a fresh dwell cycle without rebuilding FFT plans or recomputing ref_spec.

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=3)
>>> _ = c.execute(np.ones((2, 2), dtype=np.complex64))
>>> c.count
1
>>> c.reset()
>>> c.count
0

Correlate one 2-D frame and optionally dump the coherent accumulator. Runs the 2-D pipeline: FFT2 → pointwise multiply with ref_spec → accumulate the cross-spectrum; on dump, IFFT2 → normalise (÷ nynx). Accumulating in the frequency domain and inverting once is exactly the per-frame inverse summed, by linearity of the IFFT — valid because the dwell is coherent* (a complex sum); a non-coherent (magnitude) integration could not defer the inverse.

Layout. A frame is nynx complex samples in row-major order: row i is samples inx .. (i+1)*nx - 1. For Corr2D that is a (ny, nx) image; for DelayDoppler it is the raw stream, ny code periods of nx = code_len samples back to back. The map a dump produces is flat, n_out = ny_out * nx_out values (ny values with col_out), also row-major: reshape it to (ny_out, nx_out). On a DelayDoppler, axis 0 is Doppler (centered, zero Doppler on row ny_out / 2) and axis 1 is delay (the lag, in samples).

Ownership. In Python, a call that dumps returns a new array when no out= is given, and a view of out= when one is (a 1-D array holding at least n_out values; it is written on a dump only, and the next dump overwrites it). A call that does not dump returns None and touches neither.

Parameters:

Returns:

Raises:

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=2)
>>> x = np.ones((2, 2), dtype=np.complex64)
>>> c.execute(x) is None   # frame 1 — no dump
True
>>> c.execute(x).tolist()  # frame 2 — dump
[(2+0j), (2+0j), (2+0j), (2+0j)]

Maximum output samples per execute call (dp_correlator_state_t::n_out -- ny_out*nx_out normally, or ny when a single dp_correlator_state_t::col_out was selected).

Returns:

Every map of a batch, unreduced: row h of the (H, n_out) result is the map of frame h (in C, map h is at out + h * n_out).

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1): frame h is the samples from h * ny * nx up to, not including, (h + 1) * ny * nx. With no out= each call returns a new array; with out= it returns a view of it, and the next call into the same out= overwrites that view. out= is a 2-D complex64 array of shape (rows, n_out) with at least H rows (a shorter one is refused); the result is its first H rows. The object's dwell is untouched.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> maps = dd.execute_all(frames)
>>> maps.shape
(2, 256)
>>> [int(np.argmax(np.abs(m))) % nx for m in maps]   # each map's delay
[3, 11]
>>> dd.count                    # the dwell never moved
0

Samples dp_correlator_execute_all() writes for n_in input samples: H * n_out, H = n_in / (ny * nx).

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_all_max_out(len(frames))   # 2 maps of 8 x 32
512

The coherent sum of a batch's maps, inverted once.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

The frames' product spectra are summed and the sum is inverted, as a dwell does: the result is bit-identical to what a fresh object with dwell = H dumps for the same frames, and equal to the sum of the H maps up to rounding. The object's own dwell is untouched.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> x = np.tile(code, ny)
>>> total = dd.execute_coherent(np.concatenate([x, -x]))
>>> bool(np.abs(total).max() < 1e-3)          # x and -x cancel
True

Samples dp_correlator_execute_coherent() writes: n_out.

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_coherent_max_out()
256

The power of a batch's maps, summed cell by cell: each output cell is the sum over h of that cell's |map_h|^2, summed in h order in float.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Unlike the coherent sum, phase does not cancel: frames x and -x sum to twice one map's power, where their coherent sum is zero.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> x = np.tile(code, ny)
>>> power = dd.execute_power_sum(np.concatenate([x, -x]))
>>> one = np.abs(dd.execute_all(x)[0]) ** 2
>>> bool(np.allclose(power, 2 * one))        # x and -x do not cancel
True

Powers dp_correlator_execute_power_sum() writes: n_out.

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_power_sum_max_out()
256

The largest power over a batch's maps, cell by cell, and the map it came from.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Each cell of out is the largest |map_h|^2 that cell takes over the maps, and the same cell of out1 is the h it came from. A tie goes to the lowest h: a later map replaces the running maximum only when it is strictly greater.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> power, index = dd.execute_power_max(frames)
>>> int(index[4 * nx + 3]), int(index[4 * nx + 11])  # which map peaks
(0, 1)

One record per map of a batch: its peak power, where the peak is, and its mean power.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Entry h of each output describes map h: out its largest |map|^2, out1 and out2 the row and column of that cell (the first in row-major order on a tie), and out3 the mean |map|^2 over its n_out cells. A map is ny_out x nx_out; with col_out it is ny x 1, and the column reported is col_out. The peak-to-mean of each map is out over out3, entry by entry: a statistic of each map, which the same statistic of a pointwise maximum over maps does not give.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> peak, row, col, mean = dd.execute_peaks(frames)
>>> row.tolist(), col.tolist()     # zero Doppler is row ny / 2
([4, 4], [3, 11])
>>> bool(np.all(peak / mean > 100))   # each map's own peak-to-mean
True

The strongest power at every cell over a bank, and which hypothesis it came from.

dp_correlator_bank_fold() with the POWER_MAX reducer: at each cell, out holds the largest |map_h|^2 over every hypothesis h, and out1 that h, (g - g_min) * R + r, the lowest h on a tie. Every argument and refusal is dp_correlator_bank_fold()'s; in addition max_out below n_out is refused with nothing written.

As dp_correlator_bank_fold().

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx, d = 8, 32, 5                  # code delayed by 5 samples
>>> code = rng.choice([-1.0, 1.0], nx).astype(np.complex64)
>>> m = np.arange(ny * nx)
>>> x = (np.tile(np.roll(code, d), ny)    # on a carrier 1.5 bins off
...      * np.exp(2j * np.pi * 1.5 / nx * m)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> no_rates = np.empty(0, np.complex64)
>>> pw, h = dd.bank_power_max(x, 2, -4, 4, no_rates)  # g / (2 nx), -4..4
>>> cell = int(np.argmax(pw))
>>> cell % nx, int(h[cell]) - 4           # (delay, g = h + g_min)
(5, 3)

Detect on a coarse carrier grid, refine each candidate at its own cell on a fine one, and keep what confirms.

The bank searches on L_d and resolves on L_r (docs/design/corr2d-hypotheses.md section 6):

1. Detect. dp_correlator_bank_power_max() over carriers g_min .. g_max on the 1 / (L_d nx) grid, with every rate.
2. Candidates. Every cell whose power exceeds t_candidate and is at least each of its 8 neighbors, both axes circular (a delay lag and a Doppler bin both wrap).
3. Refine. For a candidate found by coarse carrier g_d and rate r, the map value at its cell under every fine carrier g_r from m g_d - (m - 1) to m g_d + (m - 1), m = L_r / L_d: the carriers between its coarse neighbors, on the 1 / (L_r nx) grid. On the fast path and DelayDoppler with a native delay axis each is a time-domain correlation at the cell's lag and a slow-time DFT at its Doppler row, in double, with no FFT: 2 ny nx multiply-adds a carrier. Any other object makes that hypothesis's map and reads the cell. The best g_r wins, the lowest on a tie.
4. Confirm. A candidate whose refined power exceeds t_confirm is a record.

Records come out in cell order (row-major), one entry of each output per record: out the refined power, out1 g_r on the fine grid, out2 the rate r, out3 the row and out4 the column, the cell as execute() lays out the map. Measured at 64 x 512 against an oracle that corrects the exact offset, L_d = 2 with L_r = 4 holds L = 4's sensitivity within 0.16 dB, for about half the bank (the design page). L_d = L_r is the one-stage bank. Thresholds are powers in the map's own units; the caller sets them for its noise, as for any detector.

As dp_correlator_bank_fold(); g_min and g_max are on the coarse grid.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx, d = 8, 32, 5
>>> code = rng.choice([-1.0, 1.0], nx).astype(np.complex64)
>>> m = np.arange(ny * nx)
>>> x = (np.tile(np.roll(code, d), ny)    # 1.25 bins: between L_d = 2
...      * np.exp(2j * np.pi * 1.25 / nx * m)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> no_rates = np.empty(0, np.complex64)
>>> coarse, _ = dd.bank_power_max(x, 2, -4, 4, no_rates)
>>> t = 0.5 * coarse.max()
>>> power, g, rate, row, col = dd.bank_detect(x, 2, 4, -4, 4, t, t,
...                                           no_rates)
>>> len(power), int(g[0]), int(col[0])    # g on the 1/(4 nx) grid
(1, 5, 5)
>>> round(float(power[0] / coarse.max()), 3)  # the straddle recovered
1.233

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 Corr2D has already been destroyed.

Returns:

Serialize this object's mutable state to bytes.

Captures the state that evolves as the object runs, including any value a setter changed after construction, so a blob taken now and restored later resumes from this point. Construction parameters are not restored: restore into an object built the same way. A core may check some of them and refuse a blob built differently.

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 Corr2D has already been destroyed.

Returns:

Restore mutable state from a get_state() blob.

Overwrites the live state in place, including any value a setter changed after construction. Construction parameters are not restored: restore into an object built the same way. Length is validated against state_bytes() before the blob is handed to the C core, which may reject it too: a core may check some construction parameters and refuse a blob built differently.

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

Parameters:

Raises:

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 Corr2D 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 Corr2D.

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

Parameters:

Zero the accumulator and reset the integration counter to 0. Equivalent to starting a fresh dwell cycle without rebuilding FFT plans or recomputing ref_spec.

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=3)
>>> _ = c.execute(np.ones((2, 2), dtype=np.complex64))
>>> c.count
1
>>> c.reset()
>>> c.count
0

Correlate one 2-D frame and optionally dump the coherent accumulator. Runs the 2-D pipeline: FFT2 → pointwise multiply with ref_spec → accumulate the cross-spectrum; on dump, IFFT2 → normalise (÷ nynx). Accumulating in the frequency domain and inverting once is exactly the per-frame inverse summed, by linearity of the IFFT — valid because the dwell is coherent* (a complex sum); a non-coherent (magnitude) integration could not defer the inverse.

Layout. A frame is nynx complex samples in row-major order: row i is samples inx .. (i+1)*nx - 1. For Corr2D that is a (ny, nx) image; for DelayDoppler it is the raw stream, ny code periods of nx = code_len samples back to back. The map a dump produces is flat, n_out = ny_out * nx_out values (ny values with col_out), also row-major: reshape it to (ny_out, nx_out). On a DelayDoppler, axis 0 is Doppler (centered, zero Doppler on row ny_out / 2) and axis 1 is delay (the lag, in samples).

Ownership. In Python, a call that dumps returns a new array when no out= is given, and a view of out= when one is (a 1-D array holding at least n_out values; it is written on a dump only, and the next dump overwrites it). A call that does not dump returns None and touches neither.

Parameters:

Returns:

Raises:

Examples:

>>> from doppler.spectral import Corr2D
>>> import numpy as np
>>> ref = np.zeros((2, 2), dtype=np.complex64); ref[0, 0] = 1.0
>>> c = Corr2D(ref=ref, dwell=2)
>>> x = np.ones((2, 2), dtype=np.complex64)
>>> c.execute(x) is None   # frame 1 — no dump
True
>>> c.execute(x).tolist()  # frame 2 — dump
[(2+0j), (2+0j), (2+0j), (2+0j)]

Maximum output samples per execute call (dp_correlator_state_t::n_out -- ny_out*nx_out normally, or ny when a single dp_correlator_state_t::col_out was selected).

Returns:

Every map of a batch, unreduced: row h of the (H, n_out) result is the map of frame h (in C, map h is at out + h * n_out).

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1): frame h is the samples from h * ny * nx up to, not including, (h + 1) * ny * nx. With no out= each call returns a new array; with out= it returns a view of it, and the next call into the same out= overwrites that view. out= is a 2-D complex64 array of shape (rows, n_out) with at least H rows (a shorter one is refused); the result is its first H rows. The object's dwell is untouched.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> maps = dd.execute_all(frames)
>>> maps.shape
(2, 256)
>>> [int(np.argmax(np.abs(m))) % nx for m in maps]   # each map's delay
[3, 11]
>>> dd.count                    # the dwell never moved
0

Samples dp_correlator_execute_all() writes for n_in input samples: H * n_out, H = n_in / (ny * nx).

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_all_max_out(len(frames))   # 2 maps of 8 x 32
512

The coherent sum of a batch's maps, inverted once.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

The frames' product spectra are summed and the sum is inverted, as a dwell does: the result is bit-identical to what a fresh object with dwell = H dumps for the same frames, and equal to the sum of the H maps up to rounding. The object's own dwell is untouched.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> x = np.tile(code, ny)
>>> total = dd.execute_coherent(np.concatenate([x, -x]))
>>> bool(np.abs(total).max() < 1e-3)          # x and -x cancel
True

Samples dp_correlator_execute_coherent() writes: n_out.

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_coherent_max_out()
256

The power of a batch's maps, summed cell by cell: each output cell is the sum over h of that cell's |map_h|^2, summed in h order in float.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Unlike the coherent sum, phase does not cancel: frames x and -x sum to twice one map's power, where their coherent sum is zero.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> x = np.tile(code, ny)
>>> power = dd.execute_power_sum(np.concatenate([x, -x]))
>>> one = np.abs(dd.execute_all(x)[0]) ** 2
>>> bool(np.allclose(power, 2 * one))        # x and -x do not cancel
True

Powers dp_correlator_execute_power_sum() writes: n_out.

Returns:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> dd.execute_power_sum_max_out()
256

The largest power over a batch's maps, cell by cell, and the map it came from.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Each cell of out is the largest |map_h|^2 that cell takes over the maps, and the same cell of out1 is the h it came from. A tie goes to the lowest h: a later map replaces the running maximum only when it is strictly greater.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> power, index = dd.execute_power_max(frames)
>>> int(index[4 * nx + 3]), int(index[4 * nx + 11])  # which map peaks
(0, 1)

One record per map of a batch: its peak power, where the peak is, and its mean power.

Python: x is the H frames back to back, a flat array of H * ny * nx samples (H >= 1).

Entry h of each output describes map h: out its largest |map|^2, out1 and out2 the row and column of that cell (the first in row-major order on a tie), and out3 the mean |map|^2 over its n_out cells. A map is ny_out x nx_out; with col_out it is ny x 1, and the column reported is col_out. The peak-to-mean of each map is out over out3, entry by entry: a statistic of each map, which the same statistic of a pointwise maximum over maps does not give.

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx = 8, 32
>>> code = np.exp(2j * np.pi * rng.random(nx)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> frames = np.concatenate([np.tile(np.roll(code, d), ny)
...                          for d in (3, 11)])   # delays 3 and 11
>>> peak, row, col, mean = dd.execute_peaks(frames)
>>> row.tolist(), col.tolist()     # zero Doppler is row ny / 2
([4, 4], [3, 11])
>>> bool(np.all(peak / mean > 100))   # each map's own peak-to-mean
True

The strongest power at every cell over a bank, and which hypothesis it came from.

dp_correlator_bank_fold() with the POWER_MAX reducer: at each cell, out holds the largest |map_h|^2 over every hypothesis h, and out1 that h, (g - g_min) * R + r, the lowest h on a tie. Every argument and refusal is dp_correlator_bank_fold()'s; in addition max_out below n_out is refused with nothing written.

As dp_correlator_bank_fold().

Parameters:

Returns:

Raises:

Examples:

>>> import numpy as np
>>> from doppler.spectral import DelayDoppler
>>> rng = np.random.default_rng(0)
>>> ny, nx, d = 8, 32, 5                  # code delayed by 5 samples
>>> code = rng.choice([-1.0, 1.0], nx).astype(np.complex64)
>>> m = np.arange(ny * nx)
>>> x = (np.tile(np.roll(code, d), ny)    # on a carrier 1.5 bins off
...      * np.exp(2j * np.pi * 1.5 / nx * m)).astype(np.complex64)
>>> dd = DelayDoppler(code, ny=ny)
>>> no_rates = np.empty(0, np.complex64)
>>> pw, h = dd.bank_power_max(x, 2, -4, 4, no_rates)  # g / (2 nx), -4..4
>>> cell = int(np.argmax(pw))
>>> cell % nx, int(h[cell]) - 4           # (delay, g = h + g_min)
(5, 3)