File boxcar_core.h¶

FileList > boxcar > boxcar_core.h

Go to the source code of this file

Boxcar (rectangular) moving-average filter — cf32, fixed window. More...

• #include "clib_common.h"
• #include "dp_state.h"
• #include "jm_perf.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

A sliding-window moving average over the last len complex samples: one output per input sample (no rate change). Each step adds the new sample and subtracts the sample leaving the window, so it is O(1) per sample regardless of window length (a running window sum, not a re-summed convolution). The output is the window mean times an optional output gain: gain·(Σ window)/ len. Because the step must multiply by 1/len anyway, the gain is folded into a single cached scale = gain/len, so applying it is free — a composing loop (e.g. a carrier arm with an AGC) can push its gain into the boxcar and avoid a second multiply.

The delay ring is a fixed in-struct array (BOXCAR_MAX_LEN), so the state is pointer-free POD: it embeds by value into a composing object (a carrier loop's I/Q arm, a smoother ahead of a detector) and serializes as a whole-struct snapshot. A window longer than BOXCAR_MAX_LEN is rejected at create/init time. (A bounded window sum also stays numerically clean — unlike a never-reset CIC integrator-comb, whose integrator drifts in float.)

Until the ring fills (the first len-1 samples after a reset) the ring holds zeros, so the average is taken over a partial window and the output ramps in.

>>> import numpy as np
>>> from doppler.filter import MovingAverage
>>> ma = MovingAverage(2)                       # 2-sample window, unit gain
>>> ma.steps(np.ones(3, np.complex64)).real.tolist()
[0.5, 1.0, 1.0]
>>> ma2 = MovingAverage(2, gain=2.0)            # gain folded into the mean
>>> ma2.steps(np.ones(3, np.complex64)).real.tolist()
[1.0, 2.0, 2.0]

Public Functions Documentation¶

function boxcar_create¶

Create a boxcar instance.

boxcar_state_t * boxcar_create (
    size_t len,
    double gain
) 

Parameters:

• len Window length (1 .. BOXCAR_MAX_LEN; default 4).
• gain Output gain (default 1.0).

Returns:

Heap state, or NULL on invalid length / allocation failure.

Note:

Caller must call boxcar_destroy() when done.

function boxcar_destroy¶

Destroy a boxcar instance.

void boxcar_destroy (
    boxcar_state_t * s
) 

Parameters:

• s May be NULL.

function boxcar_get_gain¶

Current output gain.

JM_FORCEINLINE double boxcar_get_gain (
    const boxcar_state_t * s
) 

function boxcar_get_state¶

Serialize the full state into blob .

void boxcar_get_state (
    const boxcar_state_t * s,
    void * blob
) 

function boxcar_init¶

Initialise a boxcar in place (no allocation).

void boxcar_init (
    boxcar_state_t * s,
    size_t len,
    double gain
) 

Parameters:

• s State to initialise. Must be non-NULL.
• len Window length; clamped to [1, BOXCAR_MAX_LEN].
• gain Output gain (folded into the averaging scale).

function boxcar_reset¶

Clear the window (zero the ring and the running sum); keep config.

void boxcar_reset (
    boxcar_state_t * s
) 

function boxcar_set_gain¶

Set the output gain; refresh the cached scale.

JM_FORCEINLINE void boxcar_set_gain (
    boxcar_state_t * s,
    double gain
) 

Parameters:

• s Boxcar state. Must be non-NULL.
• gain New output gain (folded into scale = gain / len).

function boxcar_set_state¶

Restore state; DP_OK, or DP_ERR_INVALID if the envelope rejects.

int boxcar_set_state (
    boxcar_state_t * s,
    const void * blob
) 

function boxcar_state_bytes¶

Serialized-state byte size.

size_t boxcar_state_bytes (
    const boxcar_state_t * s
) 

function boxcar_step¶

Slide the window by one sample; return the gained moving average.

JM_FORCEINLINE  JM_HOT float complex boxcar_step (
    boxcar_state_t * s,
    float complex x
) 

O(1): add x, drop the sample leaving the window, return acc · scale (= gain · acc / len) — one multiply.

Parameters:

• s Boxcar state. Must be non-NULL.
• x One input sample.

Returns:

The gained window mean after admitting x.

function boxcar_steps¶

Filter a block: write the gained moving average of each sample.

void boxcar_steps (
    boxcar_state_t * s,
    const float complex * input,
    float complex * output,
    size_t n
) 

Parameters:

• s Boxcar state. Must be non-NULL.
• input Input samples.
• output Output (gained window means); may alias input.
• n Number of samples.

Macro Definition Documentation¶

define BOXCAR_MAX_LEN¶

#define BOXCAR_MAX_LEN `64`

define BOXCAR_STATE_MAGIC¶

#define BOXCAR_STATE_MAGIC `DP_FOURCC ('B', 'O', 'X', 'C')`

define BOXCAR_STATE_VERSION¶

#define BOXCAR_STATE_VERSION `1u`

The documentation for this class was generated from the following file native/inc/boxcar/boxcar_core.h