Python Accumulator API¶

Running-sum accumulators backed by dp_acc_f32_t and dp_acc_cf64_t. Used as the integrate-and-dump register in polyphase resamplers.

Source: src/doppler/accumulator/__init__.py

Classes¶

Class	Accumulator type	Coefficient type	Use when
`AccF32`	float32 scalar	float32	real-valued sums, power estimation
`AccCf64`	complex128 scalar	float32	polyphase resampler I&D path
`AccTrace`	float64 per-bin	—	trace averaging (mean / EMA / hold)

AccTrace differs from the scalar accumulators above: it keeps one running value per bin over a fixed-length frame rather than reducing the frame to a single sum. Choose the reduction with mode — "mean" (linear average), "exp" (exponential moving average using alpha), "maxhold", or "minhold". It is the averaging engine behind doppler.spectral.PSD, and is reusable for waterfall / spectrogram and video-averaged displays.

Examples¶

AccF32 — running sum¶

from doppler.accumulator import AccF32

acc = AccF32()
acc.step(1.0)
acc.step(2.5)
print(acc.get())    # 3.5 — read without clearing
print(acc.dump())   # 3.5 — read and zero
print(acc.dump())   # 0.0 — cleared by previous dump

AccF32 — multiply-accumulate (dot product)¶

madd(x, h) computes acc += sum(x[k] * h[k]) in C — the inner loop of a polyphase FIR branch.

from doppler.accumulator import AccF32
import numpy as np

x = np.array([1, 2, 3, 4], dtype=np.float32)
h = np.array([0.25, 0.25, 0.25, 0.25], dtype=np.float32)

acc = AccF32()
acc.madd(x, h)
print(acc.dump())   # 2.5 = mean([1,2,3,4])

AccCf64 — complex accumulator for resampler I&D¶

from doppler.accumulator import AccCf64
import numpy as np

x = np.array([1+2j, 3+4j], dtype=np.complex128)
h = np.array([0.5, 0.5], dtype=np.float32)

acc = AccCf64()
acc.madd(x, h)
print(acc.dump())   # (2+3j) = mean([1+2j, 3+4j])

steps vs step¶

step(v) — add a scalar to the accumulator.
steps(x) — add all elements of a NumPy array to the accumulator.

acc = AccF32()
acc.step(1.0)           # acc = 1.0
acc.steps(np.array([2.0, 3.0], dtype=np.float32))  # acc = 6.0

AccTrace — per-bin trace averaging¶

from doppler.accumulator import AccTrace
import numpy as np

# Linear (PSD (PSD-method)) average of two power frames, per bin.
acc = AccTrace(n=4, mode="mean")
acc.accumulate(np.array([1, 3, 5, 7], dtype=np.float32))
acc.accumulate(np.array([3, 5, 7, 9], dtype=np.float32))
print(acc.value())   # [2. 4. 6. 8.]
print(acc.count)     # 2

# Max-hold catches per-bin transients across frames.
mh = AccTrace(n=3, mode="maxhold")
mh.accumulate(np.array([1, 5, 2], dtype=np.float32))
mh.accumulate(np.array([4, 3, 6], dtype=np.float32))
print(mh.value())    # [4. 5. 6.]

value() returns None until the first frame is accumulated.

AccF32 ¶

Single-precision floating-point scalar accumulator. Maintains one running sum (acc) that persists across calls to step, steps, madd, add2d, and madd2d. Use get to read without side-effects or dump to read and atomically zero in a single call.

Parameters:

Name	Type	Description	Default
`acc`	`float`	acc state variable.	`0.0`

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.get_acc()
0.0
>>> obj.set_acc(5.0)
>>> obj.get_acc()
5.0
>>> obj.reset()
>>> obj.get_acc()
0.0

reset ¶

reset() -> None

Zero the accumulator, restoring the same state as a fresh AccF32(0.0) — regardless of the value supplied to acc_f32_create. Subsequent get / dump calls return 0.0 until new samples are processed.

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.step(7.0)
>>> obj.reset()
>>> obj.get_acc()
0.0

step ¶

step(x: float) -> None

Add one sample to the running sum (acc += x). This is the hot-path entry point for sample-by-sample processing. For block inputs prefer acc_f32_steps to amortise call overhead and allow auto-vectorisation.

Parameters:

Name	Type	Description	Default
`x`	`float`	Input sample (float).	required

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.step(3.0)
>>> obj.get()
3.0

steps ¶

steps(x: NDArray[float32]) -> None

Add all samples in input to the running sum. Equivalent to calling acc_f32_step for each element, but SIMD-vectorised on platforms that provide it (AVX-512 / AVX2 / SSE2). The loop uses JM_RESTRICT so the compiler can assume no aliasing between state and input.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[float32]`	Input.	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.steps(np.array([1.0, 2.0, 3.0], dtype=np.float32))
>>> obj.get()
6.0

get ¶

get() -> float

Return the current accumulated sum without resetting state. Identical to reading the acc property directly; retained as an explicit method so call sites that need the value can be uniform with dump without a conditional.

Returns:

Type	Description
`float`	Current value of `acc` (float).

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.step(2.0)
>>> obj.step(3.0)
>>> obj.get()
5.0

dump ¶

dump() -> float

Return the accumulated sum and atomically reset it to zero. This is the canonical "drain" primitive: read the period total, then start a fresh accumulation interval without a separate reset call. The zero-reset is unconditional and always writes 0.0f.

Returns:

Type	Description
`float`	Value of `acc` just before the reset (float).

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.step(3.0)
>>> obj.step(4.0)
>>> obj.dump()
7.0
>>> obj.get()
0.0

madd ¶

madd(x: NDArray[float32], h: NDArray[float32]) -> None

Dot-product accumulate: acc += sum(x[i] * h[i]) for i in 0 .. min(x_len, h_len) - 1. The shorter of the two arrays limits the iteration count; no out-of-bounds access occurs. Typical use: apply a short FIR weight vector to one block of signal samples and fold the result into a running total.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[float32]`	Signal samples (float32 array).	required
`h`	`NDArray[float32]`	Coefficient / weight array (float32 array).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> x = np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32)
>>> h = np.array([0.5, 0.5, 0.5, 0.5], dtype=np.float32)
>>> obj.madd(x, h)
>>> obj.get()
5.0

add2d ¶

add2d(x: NDArray[float32]) -> None

Sum all elements of a (logically) 2-D float array into the accumulator. The array is treated as a flat C-order buffer of x_len floats regardless of the original shape; the caller is responsible for passing the total element count.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[float32]`	Input array (float32, any shape — passed as flat buffer).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> grid = np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float32)
>>> obj.add2d(grid)
>>> obj.get()
10.0

madd2d ¶

madd2d(x: NDArray[float32], h: NDArray[float32]) -> None

Dot-product accumulate over a flat 2-D buffer: acc += sum(x[i] * h[i]) for i in 0 .. min(x_len, h_len) - 1. Combines add2d and madd semantics — a 2-D signal array is weighted element-wise by a coefficient buffer and the scalar total is folded into the running sum.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[float32]`	Signal samples (float32, flat buffer of the 2-D array).	required
`h`	`NDArray[float32]`	Coefficient / weight array (float32).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> x = np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32)
>>> h = np.array([0.5, 0.5, 0.5, 0.5], dtype=np.float32)
>>> obj.madd2d(x, h)
>>> obj.get()
5.0

state_bytes ¶

state_bytes() -> int

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

Returns:

Type	Description
`int`	Byte length of one serialized state blob.

get_state ¶

get_state() -> bytes

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

Returns:

Type	Description
`bytes`	Opaque snapshot, `state_bytes()` bytes long.

set_state ¶

set_state(blob: bytes) -> None

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

Parameters:

Name	Type	Description	Default
`blob`	`bytes`	A `get_state()` blob from this type, exactly `state_bytes()` long.	required

get_acc ¶

get_acc() -> float

Return the current accumulator value without modifying state. Use this when you need to read the running sum mid-accumulation without disturbing it. For a read-and-reset in one call use acc_f32_dump.

Returns:

Type	Description
`float`	Current value of `acc` (float).

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.step(4.0)
>>> obj.get_acc()          # non-destructive read
4.0
>>> obj.get_acc()          # still there — get_acc never drains
4.0

set_acc ¶

set_acc(value: float) -> None

Overwrite the accumulator with a new value. Useful for seeding the accumulator to a known baseline before processing a new segment without a full reset; subsequent step / steps samples accumulate on top of the seeded value.

Parameters:

Name	Type	Description	Default
`value`	`float`	New accumulator value.	required

Examples:

>>> from doppler.accumulator import AccF32
>>> obj = AccF32(0.0)
>>> obj.set_acc(10.0)      # seed a running baseline
>>> obj.step(2.5)          # later samples fold in on top
>>> obj.get_acc()
12.5

destroy ¶

destroy() -> None

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 ¶

__enter__() -> AccF32

Enter a context manager, returning this object.

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

Returns:

Type	Description
`AccF32`	This same object, not a copy.

exit ¶

__exit__(
    exc_type: object | None = ...,
    exc: object | None = ...,
    tb: object | None = ...,
) -> None

Exit a context manager, releasing the AccF32.

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

Parameters:

Name	Type	Description	Default
`exc_type`	`object \| None`	Exception class, or None. Ignored.	`...`
`exc`	`object \| None`	Exception instance, or None. Ignored.	`...`
`tb`	`object \| None`	Traceback object, or None. Ignored.	`...`

AccCf64 ¶

Double-precision complex scalar accumulator. Maintains one running complex sum (acc) across calls to step, steps, madd, add2d, and madd2d. The signal path is double-precision complex (128-bit per sample); coefficient arrays for madd/madd2d are single-precision float to match typical FIR weight storage. Use get to read without side-effects or dump to read and zero atomically.

Parameters:

Name	Type	Description	Default
`acc`	`complex`	acc state variable.	`0j`

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.get_acc()
0j
>>> obj.set_acc(3+4j)
>>> obj.get_acc()
(3+4j)
>>> obj.reset()
>>> obj.get_acc()
0j

reset ¶

reset() -> None

Zero the accumulator, restoring the same state as a fresh AccCf64(0j) — regardless of the value supplied to acc_cf64_create. Both the real and imaginary parts are set to 0.0. Subsequent get / dump calls return 0j until new samples are processed.

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.step(3+2j)
>>> obj.reset()
>>> obj.get_acc()
0j

step ¶

step(x: complex) -> None

Add one complex sample to the running sum (acc += x). This is the hot-path entry for sample-by-sample processing. For block inputs prefer acc_cf64_steps to amortise call overhead.

Parameters:

Name	Type	Description	Default
`x`	`complex`	Input sample (complex).	required

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.step(3+2j)
>>> obj.get()
(3+2j)

steps ¶

steps(x: NDArray[complex128]) -> None

Add all samples in input to the running sum. Equivalent to calling acc_cf64_step for each element; iterates element-by-element over double-precision complex samples.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[complex128]`	Input.	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.steps(np.array([1+0j, 2+1j, 3+2j], dtype=np.complex128))
>>> obj.get()
(6+3j)

get ¶

get() -> complex

Return the current accumulated sum without resetting state. Identical to reading the acc property directly; retained as an explicit method so call sites that need the value can be uniform with dump without a conditional.

Returns:

Type	Description
`complex`	Current value of `acc` (complex).

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.step(2+0j)
>>> obj.step(0+3j)
>>> obj.get()
(2+3j)

dump ¶

dump() -> complex

Return the accumulated sum and atomically reset it to zero. This is the canonical "drain" primitive: read the period total, then start a fresh accumulation interval without a separate reset call. Both real and imaginary parts are zeroed unconditionally.

Returns:

Type	Description
`complex`	Value of `acc` just before the reset (complex).

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.step(3+2j)
>>> obj.step(1+1j)
>>> obj.dump()
(4+3j)
>>> obj.get()
0j

madd ¶

madd(x: NDArray[complex128], h: NDArray[float32]) -> None

Dot-product accumulate with complex signal and float weights: acc += sum(x[i] * h[i]) for i in 0 .. min(x_len, h_len) - 1. The signal array x is double-precision complex; the coefficient array h is single-precision float (widened to double before multiplication). The shorter of the two arrays limits iteration.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[complex128]`	Complex signal samples (complex128 array).	required
`h`	`NDArray[float32]`	Real coefficient / weight array (float32 array).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> x = np.array([1+0j, 2+0j, 3+0j, 4+0j], dtype=np.complex128)
>>> h = np.array([0.5, 0.5, 0.5, 0.5], dtype=np.float32)
>>> obj.madd(x, h)
>>> obj.get()
(5+0j)

add2d ¶

add2d(x: NDArray[complex128]) -> None

Sum all elements of a (logically) 2-D complex array into the accumulator. The array is treated as a flat C-order buffer of x_len complex128 samples regardless of the original shape; the caller is responsible for passing the total element count.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[complex128]`	Input array (complex128, any shape — passed as flat buffer).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> grid = np.array([[1+0j, 2+0j], [3+0j, 4+0j]], dtype=np.complex128)
>>> obj.add2d(grid)
>>> obj.get()
(10+0j)

madd2d ¶

madd2d(x: NDArray[complex128], h: NDArray[float32]) -> None

Dot-product accumulate over a flat 2-D complex buffer: acc += sum(x[i] * h[i]) for i in 0 .. min(x_len, h_len) - 1. Combines add2d and madd semantics for 2-D data — a complex signal grid is weighted element-wise by a real coefficient buffer and folded into the running sum.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[complex128]`	Complex signal samples (complex128, flat buffer).	required
`h`	`NDArray[float32]`	Real coefficient / weight array (float32).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> x = np.array([1+0j, 2+0j, 3+0j, 4+0j], dtype=np.complex128)
>>> h = np.array([0.5, 0.5, 0.5, 0.5], dtype=np.float32)
>>> obj.madd2d(x, h)
>>> obj.get()
(5+0j)

state_bytes ¶

state_bytes() -> int

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

Returns:

Type	Description
`int`	Byte length of one serialized state blob.

get_state ¶

get_state() -> bytes

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

Returns:

Type	Description
`bytes`	Opaque snapshot, `state_bytes()` bytes long.

set_state ¶

set_state(blob: bytes) -> None

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

Parameters:

Name	Type	Description	Default
`blob`	`bytes`	A `get_state()` blob from this type, exactly `state_bytes()` long.	required

get_acc ¶

get_acc() -> complex

Return the current accumulator value without modifying state. Use this when you need to read the running sum mid-accumulation without disturbing it. For a read-and-reset in one call use acc_cf64_dump.

Returns:

Type	Description
`complex`	Current value of `acc` (complex).

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.step(1+2j)
>>> obj.get_acc()          # non-destructive read
(1+2j)
>>> obj.get_acc()          # still there — get_acc never drains
(1+2j)

set_acc ¶

set_acc(value: complex) -> None

Overwrite the accumulator with a new complex value. Useful for seeding the accumulator to a known baseline before processing a new segment without a full reset; subsequent step / steps samples accumulate on top of the seeded value.

Parameters:

Name	Type	Description	Default
`value`	`complex`	New accumulator value (complex).	required

Examples:

>>> from doppler.accumulator import AccCf64
>>> obj = AccCf64(0j)
>>> obj.set_acc(5+6j)      # seed a complex baseline
>>> obj.step(1+1j)         # later samples fold in on top
>>> obj.get_acc()
(6+7j)

destroy ¶

destroy() -> None

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 ¶

__enter__() -> AccCf64

Enter a context manager, returning this object.

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

Returns:

Type	Description
`AccCf64`	This same object, not a copy.

exit ¶

__exit__(
    exc_type: object | None = ...,
    exc: object | None = ...,
    tb: object | None = ...,
) -> None

Exit a context manager, releasing the AccCf64.

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

Parameters:

Name	Type	Description	Default
`exc_type`	`object \| None`	Exception class, or None. Ignored.	`...`
`exc`	`object \| None`	Exception instance, or None. Ignored.	`...`
`tb`	`object \| None`	Traceback object, or None. Ignored.	`...`

AccTrace ¶

Create a length-n trace accumulator.

Parameters:

Name	Type	Description	Default
`n`	`int`	Trace length in bins. Must be > 0; returns NULL otherwise.	`1024`
`mode`	`Literal['mean', 'exp', 'maxhold', 'minhold']`	Reduction mode index (0=mean, 1=exp, 2=maxhold, 3=minhold).	`"mean"`
`alpha`	`float`	EMA smoothing factor used only by exp mode (0 < alpha <= 1).	`0.1`

Examples:

>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=8, mode="mean")
>>> acc.n, acc.count
(8, 0)

n `property` ¶

n: int

Trace length (bins).

alpha `property` `writable` ¶

alpha: float

EMA smoothing factor (exp mode).

count `property` ¶

count: int

Frames folded in so far.

mode `property` ¶

mode: int

Reduction mode.

accumulate ¶

accumulate(p: NDArray[float32]) -> None

Fold one length-n frame into the running trace.

Parameters:

Name	Type	Description	Default
`p`	`NDArray[float32]`	Input frame (float32).	required

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=4, mode="mean")
>>> acc.accumulate(np.array([1, 3, 5, 7], dtype=np.float32))
>>> acc.accumulate(np.array([3, 5, 7, 9], dtype=np.float32))
>>> acc.value().tolist()
[2.0, 4.0, 6.0, 8.0]

reset ¶

reset() -> None

Discard the running trace; the next accumulate re-seeds it.

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=4, mode="mean")
>>> acc.accumulate(np.ones(4, dtype=np.float32))
>>> acc.reset()
>>> acc.count
0

value ¶

value(
    count: int = 1, out: NDArray[float32] | None = None
) -> NDArray[np.float32]

Copy the current averaged trace (None before any accumulate).

Parameters:

Name	Type	Description	Default
`count`	`int`	How many output samples to ask for. The call may return fewer; size an `out=` buffer with the matching `_max_out()` when you need the worst case.	`1`
`out`	`NDArray[float32] \| None`	Destination, at least n float32 elements.	`None`

Returns:

Type	Description
`NDArray[float32]`	min(n, max_out) samples, or 0 if empty.

Examples:

>>> import numpy as np
>>> from doppler.accumulator import AccTrace
>>> acc = AccTrace(n=3, mode="maxhold")
>>> acc.value() is None            # empty until the first frame
True
>>> acc.accumulate(np.array([1, 5, 2], dtype=np.float32))
>>> acc.accumulate(np.array([4, 3, 6], dtype=np.float32))
>>> acc.value().tolist()           # per-bin running maximum
[4.0, 5.0, 6.0]

value_max_out ¶

value_max_out() -> int

Output capacity hint for value(); equals the trace length n.

Returns:

Type	Description
`int`	Output.

state_bytes ¶

state_bytes() -> int

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

Returns:

Type	Description
`int`	Byte length of one serialized state blob.

get_state ¶

get_state() -> bytes

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

Returns:

Type	Description
`bytes`	Opaque snapshot, `state_bytes()` bytes long.

set_state ¶

set_state(blob: bytes) -> None

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

Parameters:

Name	Type	Description	Default
`blob`	`bytes`	A `get_state()` blob from this type, exactly `state_bytes()` long.	required

destroy ¶

destroy() -> None

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 ¶

__enter__() -> AccTrace

Enter a context manager, returning this object.

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

Returns:

Type	Description
`AccTrace`	This same object, not a copy.

exit ¶

__exit__(
    exc_type: object | None = ...,
    exc: object | None = ...,
    tb: object | None = ...,
) -> None

Exit a context manager, releasing the AccTrace.

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

Parameters:

Name	Type	Description	Default
`exc_type`	`object \| None`	Exception class, or None. Ignored.	`...`
`exc`	`object \| None`	Exception instance, or None. Ignored.	`...`
`tb`	`object \| None`	Traceback object, or None. Ignored.	`...`

Gallery — Gallery, Four WCDMA Carriers — PSD, band_power, AccTrace Guides — Checkpoint & Resume Design — API taxonomy: the DSP building-block hierarchy and its naming axis, State Serialization — the standard bytes interface

Python Accumulator API¶

Classes¶

Examples¶

AccF32 — running sum¶

AccF32 — multiply-accumulate (dot product)¶

AccCf64 — complex accumulator for resampler I&D¶

steps vs step¶

AccTrace — per-bin trace averaging¶

AccF32 ¶

reset ¶

step ¶

steps ¶

get ¶

dump ¶

madd ¶

add2d ¶

madd2d ¶

state_bytes ¶

get_state ¶

set_state ¶

get_acc ¶

set_acc ¶

destroy ¶

__enter__ ¶

__exit__ ¶

AccCf64 ¶

reset ¶

step ¶

steps ¶

get ¶

dump ¶

madd ¶

add2d ¶

madd2d ¶

state_bytes ¶

get_state ¶

set_state ¶

get_acc ¶

set_acc ¶

destroy ¶

__enter__ ¶

__exit__ ¶

AccTrace ¶

n property ¶

alpha property writable ¶

count property ¶

mode property ¶

accumulate ¶

reset ¶

value ¶

value_max_out ¶

state_bytes ¶

get_state ¶

set_state ¶

destroy ¶

__enter__ ¶

__exit__ ¶

Related pages¶

enter ¶

exit ¶

enter ¶

exit ¶

n `property` ¶

alpha `property` `writable` ¶

count `property` ¶

mode `property` ¶

enter ¶

exit ¶