DSP - BLOCK ENERGY

Introduction link

The Block Energy block chops the input stream into consecutive blocks of N samples and, at the end of each block, publishes the energy of that block:

$$ S_2 = \sum_{i=0}^{N-1} x_i^2 , \qquad \mathrm{ENERGY} = S_2 $$

That is the whole block. One multiplier for $x^2$, one accumulator, one requantisation.

The sum is NOT divided by N, on purpose. This is the discrete equivalent of $\int x^2,dt$, which is what energy means for a sampled signal: it is an extensive quantity and it grows with the block length. Double N and the number doubles.

Both of the length-independent forms are exactly one shift or one square root away from this number, and both already exist as their own IP - do not build them out of this one.

N is a runtime input, not a property. You drive the exponent on the EXP pin and the block size is $N = 2^{\mathrm{EXP}}$:

Because the energy has no $1/N$ in it, the latched exponent is not even used by the arithmetic here: it only decides when the block ends. That is why this is the one block of the family whose tail is a constant.

What it is FOR link

Energy is the natural number wherever a quantity of signal matters rather than an average level:

• pulse integration - the energy of a gate is proportional to the charge collected in it, which is the basis of energy spectroscopy in a detector chain;
• power over a fixed window - divide by the (constant) gate length in software once, instead of paying for a divider per block in the fabric;
• feeding a downstream ratio - two energies over the same block length compare directly, so a fast/slow energy ratio for pulse shape discrimination needs no normalisation at all;
• the raw material for RMS and mean square, when you want the sum itself on a bus and the derived numbers computed by a CPU.

Cost link

One multiplier for $x^2$ (unavoidable at one sample per clock), one accumulator of $2\cdot\mathrm{IN_SW}-1+\mathit{MaxBlockExponent}$ bits and one requantiser. No divider, no square root, no serial arithmetic and no exponent shift. Together with Block Sum this is the cheapest block of the family, and it has the shortest tail of all of them: $L = 2$ clocks.

When to use this instead of Block Statistics link

This is the one statistic of this round that the all-in-one Block Statistics block already computes - it is its SUM_SQ output, bit for bit the same quantity from the same accumulator. (That is why the regression can compile both cores into one binary and compare them on every clock; see “Verification”.) The rule is the usual one:

• you want several statistics of the SAME block - the energy and the RMS and the min/max of the same N samples - use Block Statistics. They share one accumulator and one serial tail, so the second and third statistic are nearly free, and SUM_SQ in particular is already there next to RMS and MEAN_SQ, which are derived from the very same $S_2$.
• you want exactly one number - use this block. Then you synthesise only that number: the pin list, the accumulator and the two-clock tail are all that the energy needs, and nothing else reaches the synthesiser.

Two Block Statistics blocks side by side would duplicate the accumulators; two per-operator blocks side by side duplicate them too. One Block Statistics block never does.

Pin Description link

Properties link

Accuracy link

The accumulator $S_2$ is an exact integer: each sample is squared at full width and added, with no rounding and no truncated intermediate anywhere. The only error in this block is the single final requantisation into the Q format you chose for the ENERGY pin.

That is not an aspiration. The host regression (tb/block-ops/run_tb.ps1) demands tolerance ZERO against a Python golden (tb/block-ops/ gen_golden.py) that evaluates $\sum x_i^2$ in exact integer arithmetic - not “within 1 LSB”, not “within a few counts”. Any deviation at all fails the build.

Sizing the ENERGY output - the one thing to get right here link

Energy grows with both the sample width and the block length, so it is the one block of the family where the default output format is not automatically safe. Internally the accumulator is sized for the worst case:

$$ S_2 \le 2^{,2\cdot\mathrm{IN_SW}-2}\cdot 2^{\mathrm{EXP}} \qquad\Longrightarrow\qquad \text{accumulator width} = 2\cdot\mathrm{IN_SW}-1+\mathit{MaxBlockExponent} $$

where $\mathrm{IN_SW}$ is the total input width, plus one bit if the input is UNSIGNED (a sample has to be promoted to signed before it can be squared). The accumulator therefore never overflows. The ENERGY pin is a different matter:

(the table assumes IN and ENERGY both have zero fractional bits; each ENERGY fractional bit adds one to the width needed, each IN fractional bit removes two.)

The default ENERGY format is Q40.0 unsigned, which is wide but not 51 bits - a 51 bit pin is worse than a saturating one for almost every design. Work out what you actually need:

• 16 bit signed samples reach $|x| = 32768$, so $x^2 \le 2^{30}$;
• a full scale block of N samples therefore reaches $N\cdot 2^{30}$;
• at N = 512 that is $2^{39}$ and fits in 40 bits; at N = 1024 it is exactly $2^{40}$ and saturates by one LSB, because a 40 bit unsigned stops at $2^{40}-1$;
• a half scale sine over the same N = 1024 block is far smaller - $\tfrac{1}{2}(16384)^2\cdot 1024 \approx 1.37\times10^{11} \approx 2^{37}$ - and fits comfortably.

So the default is right for a real signal at a sane level and wrong for a deliberately clipped one. If you cannot tolerate saturation, size ENERGY from the table above; if you can, leave 40 bits and keep the routing. With Saturation = YES an over-range block clamps to the format maximum, which at least stays monotonic; with Saturation = NO it wraps, which does not.

The one-bit trap. $S_2$ is an unsigned accumulator and the requantiser takes a signed value, so the core widens it by one bit before handing it over. A same-width signed cast would read a top-bit-set accumulator back as negative and the saturation path would then clamp to zero instead of to the maximum - the exact opposite of the right answer. That widening is done for you; it is mentioned only because it is the kind of thing that looks like a mysterious “loud blocks read zero” bug if it is ever removed.

Accumulation and IN_DV link

IN_DV is the only qualifier. It says “this clock carries a sample”: a sample is squared, accumulated, and counts towards N, exactly on the clocks where IN_DV is high. Clocks with IN_DV low are ignored completely - whatever sits on IN during them cannot corrupt the block - while the tail keeps running, which is what you want: the tail has nothing to do with the input stream.

Unconnected, IN_DV ties to '1' and EXP ties to 10 (N = 1024), so the block free-runs with nothing wired except IN.

There is deliberately no CE pin. On the all-in-one Block Statistics block an earlier revision had one, and it did not survive synthesis: with nothing but internal state gated by it, Vitis could reason the frozen path away and delete the port from the generated entity while SciCompiler’s wrapper still wired it, which failed a real Vivado build with [VRFC 10-718] formal port <ce> does not exist in entity. The whole per-operator family was built without one. To stall this block, gate its IN_DV - a block that only accumulates on IN_DV has no need to be frozen.

When EXP changes link

EXP is clamped to Max Block Exponent and then latched on the first accepted sample of a block, and held for that whole block. A change therefore takes effect on the NEXT block: a block in progress always finishes against the N it was started with, and a block is never emitted against a different N than the one it was accumulated with.

Because the energy carries no $1/N$, the latched exponent never reaches the arithmetic - it only decides where the block ends. That also means an energy is only comparable with another energy taken over the same N: if you sweep EXP at run time, latch SAMPLE_COUNT alongside every result and normalise downstream.

Timing: the latency contract link

OUT_DV pulses for one clock, L clocks after the clock on which the N-th sample of the block was accepted - not when that sample arrives. ENERGY is updated on that same clock and on no other. For this block

$$ L = 2 $$

and it is a constant: there is no serial arithmetic here at all, so L does not depend on the input width, on the output width, on Max Block Exponent or on EXP. The two clocks are one to enter the final state and one to present the registered result. This is the shortest tail in the family.

The rule that governs the whole family is that the tail of one block must finish before the next block completes, i.e.

$$ 2^{\mathrm{EXP}} \ge L $$

If a block completes while the previous tail is still running, that block’s result is DROPPED: no OUT_DV for it, the accumulator is unaffected and later blocks come out correctly, but a result is silently skipped. There is no error pin for it.

With $L = 2$ that condition is $2^{\mathrm{EXP}} \ge 2$, i.e. EXP $\ge$ 1, so it cannot bite here: the only value that violates it is EXP = 0, a block of a single sample. The property page still refuses any configuration whose minimum exponent would exceed Max Block Exponent, and CompileHDL still prints the tail length and the minimum usable EXP in the compilation log

• here they will always read 2 and 1. The blocks where this rule really matters are the ones with a serial tail: Block Std Dev, Block Std Error of Mean, Block Coefficient of Variation, Block SNR and Block Crest Factor, whose L runs to tens or hundreds of clocks.

Knowing where the block is: BUSY, INTEGRATING and SAMPLE_COUNT link

Three optional status outputs, all defaulting to NO. They answer different questions:

Every output of this block is a register, so each status bit is observed on the clock after the event that sets it:

• INTEGRATING rises on the clock after the FIRST sample of a block is accepted and falls on the clock after the N-th - it is high exactly while the block is ACCUMULATING.
• BUSY covers the accumulation and the tail. It rises with INTEGRATING, stays high across the tail, and its LAST HIGH CLOCK IS THE OUT_DV PULSE; it falls on the clock after. With a two-clock tail, BUSY high and INTEGRATING low is a two-clock window.
• On a continuous stream the next block starts before the previous tail ends, so BUSY never drops and INTEGRATING dips for exactly one clock per block boundary - which makes it a free block marker.
• SAMPLE_COUNT is a fixed 32 bits and reads 1 after the first accepted sample, N after the N-th. It is NOT cleared at the block end: it HOLDS N through the tail and past OUT_DV, until the first sample of the next block takes it back to 1. so it reads N at OUT_DV only when the input STOPS for the whole tail; on a CONTINUOUS stream the next block has already started and OUT_DV shows how far into it you are. The clock that always reads N is the one INTEGRATING falls on - which is the useful thing to latch alongside the result, and on this block it is the number you need to turn an extensive energy back into an intensive one. Only RESET clears it to 0.

Q formats link

Both ports carry their own fixed point format (integer bits, fractional bits, sign), the same convention as the Fixed P. family. The accumulated sum is requantised into the ENERGY format with the selected rounding (nearest / truncate) and overflow policy (saturate / wrap); saturation is symmetric for signed formats, as everywhere else in the toolchain.

The scaling is the obvious one: a sample carries $2^{-\mathrm{IN_{fract}}}$ per LSB, so its square carries $2^{-2,\mathrm{IN_{fract}}}$, and the requantiser shifts the exact integer sum by $\mathrm{ENERGY_{fract}} - 2,\mathrm{IN_{fract}}$ places. Two input fractional bits are worth one output fractional bit when you are counting the width you need.

A sum of squares is never negative, so UNSIGNED is the right choice for ENERGY and buys you one bit - which is exactly one doubling of block length before saturation. SIGNED is offered only for downstream buses that insist on it.

Verification link

The core is regression tested by a host-side csim harness (tb/block-ops/run_tb.ps1) that runs one simulated clock at a time and follows OUT_DV. The expected values come from tb/block-ops/gen_golden.py, which evaluates $\sum x_i^2$ in exact integer arithmetic and shares no algorithm with the core; the tolerance is 0. Coverage includes pseudo-random and ramp inputs, maximum positive and maximum negative samples, unsigned input, fractional input and output formats, truncate instead of round, a deliberately narrow saturating output format (the case this guide warns about), IN_DV gaps inside the accumulation, an EXP that changes half way through a block, and an EXP driven above Max Block Exponent to exercise the clamp. The status outputs are checked clock by clock against the contract above. Finally - and uniquely among the operators added in this round - a cross-check compiles this core and the all-in-one block_stats.cpp into the same binary, drives them with identical stimulus, and compares this block’s ENERGY against that block’s SUM_SQ bit for bit on every clock.