DSP - BLOCK COVARIANCE

Introduction link

The Block Covariance block chops two input streams into consecutive blocks of N sample pairs and, at the end of each block, publishes the covariance of that block:

$$ \mathrm{cov}(a,b) = \frac{1}{N}\sum_{i=0}^{N-1} a_i b_i - \left(\frac{1}{N}\sum_{i=0}^{N-1} a_i\right) \left(\frac{1}{N}\sum_{i=0}^{N-1} b_i\right) $$

The covariance is the joint variability of two channels. It is positive when they rise and fall together, negative when one rises as the other falls, and zero when there is no linear relationship between them.

TWO inputs, ONE qualifier link

IN_A and IN_B are sampled on the same clock, by the same IN_DV. The pairing is therefore positional: pair i of a block is whatever was on the two pins on the i-th clock that IN_DV was high, and there is no way for the two streams to slip relative to each other inside a block. There is no second data-valid, no per-stream FIFO and no alignment logic to get wrong - align the two channels upstream, once, and the block does the rest.

For the same reason both pins carry the SAME input Q format: one set of IN properties (integer bits, fractional bits, sign) covers IN_A and IN_B. That is what keeps the internal widths - and therefore the cost - simple. If your two signals genuinely have different formats, requantise one of them upstream with a Fixed P. block so that both arrive in the same format.

N is a runtime input, not a property link

You drive the exponent on the EXP pin and the block size is $N = 2^{\mathrm{EXP}}$ pairs:

Because N is a power of two, both divisions are exact arithmetic shifts. There is no divider anywhere in this block.

What it is FOR link

The covariance is the number you want when the magnitude of the joint variation matters, in the units of the two signals:

• cross-channel coupling / crosstalk measured in real units - “channel B moves by so many LSB per LSB of A” - rather than as a dimensionless score;
• the numerator of a linear fit: the least-squares slope of b against a is $\mathrm{cov}(a,b)/\mathrm{var}(a)$, so this block plus a Block Variance on the same stream gives you a two-channel regression;
• noise covariance between two detector channels, which is what tells you whether a common-mode subtraction will help;
• anti-correlation detection: two channels of a differential pair, or a pair of PMTs on opposite sides of a scintillator, should show a strongly negative covariance, and a covariance that drifts towards zero is a real fault signature.

Tie IN_B to IN_A and the covariance is the variance of that channel - a free, exact self-check you can run on live hardware.

Covariance or correlation? link

Use this block when you care about how much - the answer is in the units of $a \times b$ and it scales with the gain of either channel.

Use Block Correlation when you care about whether - the Pearson coefficient $r = \mathrm{cov}/(\sigma_a\sigma_b)$ is dimensionless, bounded to $[-1,+1]$ and gain independent, which is exactly what the covariance cannot give you. A covariance of 5000 means nothing on its own; an $r$ of 0.98 means the two channels are the same signal.

The price is that Block Correlation has to compute two standard deviations, a square root and a division, and it has the longest tail in the family. This block has a single serial product and a tail of a few tens of clocks.

Cost link

Per clock: one multiplier ($a \cdot b$, unavoidable at one pair per clock), three accumulators ($S_a$, $S_b$, $S_{ab}$) and the block counter. In the tail: one reused shift-add stage for $S_a \cdot S_b$, stepped once per clock. There is no DSP in the tail and no divider anywhere.

When to use this instead of Block Statistics link

The all-in-one Block Statistics block is not deprecated, but it does not compute a covariance: it is a single-stream block and has no cross-product accumulator, so there is no counterpart to this statistic over there. The usual rule still applies to everything else you may want from the same data:

• you want several statistics of the SAME single stream - mean and RMS and 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.
• you want exactly one number - use a per-operator block. Then you synthesise only that number: the pin list, the logic and the tail are all that it needs, and nothing else reaches the synthesiser.

A Block Statistics block placed next to this one to get, say, the mean of channel A will duplicate the $S_a$ accumulator. That duplication is unavoidable here and it is one adder wide - it is not a reason to avoid either block.

Pin Description link

Properties link

The exact-integer form, and why the result is BIT EXACT link

The obvious way to evaluate the definition is $(S_{ab}/N) - (S_a/N)(S_b/N)$, with three truncated quotients that then fight each other. This block does not do that. It uses the same trick Block Variance uses, and clears the denominators first:

$$ \mathrm{cov_num} = N,S_{ab} - S_a S_b, \qquad \mathrm{cov} = \frac{\mathrm{cov_num}}{N^2} $$

with

$$ S_a = \sum_i a_i, \qquad S_b = \sum_i b_i, \qquad S_{ab} = \sum_i a_i b_i $$

All three accumulators are exact integers. $N S_{ab}$ is a shift (N is a power of two). $S_a S_b$ is an exact integer product computed serially. The final division by $N^2$ is a shift again. So:

The only rounding anywhere in this block is the single final requantisation into the Q format you chose for the COVARIANCE pin. There is no accumulated rounding, no truncated intermediate and no approximation in the datapath.

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 the definition above in exact rational arithmetic - not “within 1 LSB”, not “within a few counts”. Any deviation at all fails the build.

The sign is carried as a bit, not through the datapath link

The serial engine that forms $S_a S_b$ is an unsigned shift-add stage. The core hands it the two magnitudes, remembers whether exactly one of $S_a$ and $S_b$ was negative, and negates the product once, at the end. That is cheaper than a signed serial multiplier and it is exact.

THIS ONE CAN BE NEGATIVE link

Block Variance can prove its own result non-negative (Cauchy-Schwarz) and therefore defaults to an UNSIGNED output. The covariance cannot, and must not. $\mathrm{cov_num}$ is a genuine signed quantity and there is no non-negativity clamp in this core - such a clamp would be a bug here, not a guard.

A negative covariance is not an error case, it is the interesting case: two anti-correlated channels. So:

The COVARIANCE output format defaults to SIGNED, and you should leave it that way. An UNSIGNED format silently clamps every anti-correlated block to 0 - the block will look uncorrelated when it is in fact perfectly anti-correlated. Choose UNSIGNED only when you know from the physics that the two channels can never move in opposite directions, and you want the extra bit.

Units and sizing the COVARIANCE format link

A covariance has the units of $a \times b$ - two factors of $2^{-\mathrm{IN_fract}}$, exactly like Block Mean Square, not one like Block Mean. So:

• to keep the natural scale, set $\mathrm{COV_{fract}} = 2 \times \mathrm{IN_{fract}}$;
• for the range, $|\mathrm{cov}| \le \max|a| \cdot \max|b|$, so about twice the input integer bits is always enough.

The default is exactly that: an IN of Q16.0 SIGNED ($|a| \le 2^{15}$) gives $|\mathrm{cov}| \le 2^{30}$, which needs 31 bits plus a sign - and COVARIANCE defaults to Q32.0 SIGNED. If you narrow the format below what the data needs, the requantiser saturates (or wraps, if you turned Saturation off).

Accumulation and IN_DV link

IN_DV is the only qualifier. It says “this clock carries a sample PAIR”: IN_A and IN_B are multiplied together, both are added to their own accumulators, and the pair counts towards N, exactly on the clocks where IN_DV is high. Clocks with IN_DV low are ignored completely - whatever sits on the two input pins 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_A and IN_B.

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, and there is no reason to stall the tail.

When EXP changes link

EXP is clamped to Max Block Exponent and then latched on the first accepted sample pair 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. Both the $N S_{ab}$ shift and the final $N^2$ shift use that latched exponent, so the arithmetic of a block is always self-consistent. You can sweep EXP from a register interface while the streams run and every result stays correct.

Timing: the serial tail link

Why it is serial link

A block has a whole block period of slack after its N-th pair: the next result is not due for another $2^{\mathrm{EXP}}$ clocks. So there is no reason to build a parallel datapath for the post-accumulation arithmetic. II=1 is only needed while ACCUMULATING - one pair per clock, one multiply, three adds.

$S_a \cdot S_b$ is therefore ONE reused shift-add stage stepped once per clock, consuming one bit of $|S_b|$ per clock. The cost is CLOCKS, not multipliers: the only multiplier in the whole block is the $a \cdot b$ during accumulation, and there is no DSP in the tail.

The latency contract link

OUT_DV pulses for one clock when the tail COMPLETES, L clocks after the clock on which the N-th pair of the block was accepted - not when that pair arrives. COVARIANCE is updated on that same clock and on no other. The state walk is IDLE -(go)-> MUL x (IN_SW + EXP) -> VAR -> FIN -> IDLE with OUT_DV registered, so

$$ L = 2 + (\mathrm{IN_SW} + \mathrm{EXP} + 1) $$

where $\mathrm{IN_SW}$ is the signed working width of a sample: the input width, +1 if the input is UNSIGNED (a sample has to be promoted to signed before it can be accumulated). $|S_b|$ is at most $\mathrm{IN_SW} - 1 + \mathrm{EXP}$ bits wide for a block of $2^{\mathrm{EXP}}$ pairs, so $\mathrm{IN_SW} + \mathrm{EXP}$ shift-add steps always clear it.

Two things are absent from that formula and both are worth noticing:

• the output format does not appear. Widening COVARIANCE costs registers, not clocks.
• MaxBlockExponent does not appear either. Raising it widens the accumulators but does not lengthen this tail - only the runtime exponent does. Block Correlation and Block Autocorrelation are not so kind.

Like Block Variance, this is one of the blocks whose latency depends on the runtime exponent. But a longer block also gives more slack: the block grows exponentially in EXP while the tail grows only linearly, so the $2^{\mathrm{EXP}} \ge L$ constraint gets easier as EXP grows, not harder.

Worked numbers link

For the default configuration - IN Q16.0 SIGNED, so $\mathrm{IN_SW} = 16$ - at EXP = 10:

• $L = 2 + (16 + 10 + 1) = \mathbf{29}$ clocks
• $2^{10} = 1024 \ge 29$, with a factor of 35 to spare

and the smallest usable exponent is the smallest EXP with $2^{\mathrm{EXP}} \ge 19 + \mathrm{EXP}$:

• EXP = 4: $16 \ge 23$? no
• EXP = 5: $32 \ge 24$? yes - so EXP $\ge$ 5, i.e. N $\ge$ 32

A few configurations, to show where the clocks go:

The 2^EXP >= L rule, and what happens when it is broken link

The tail of one block must finish before the next block completes:

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

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

The property page refuses a configuration whose minimum exponent exceeds Max Block Exponent, and CompileHDL prints both numbers - the worst case tail length and the minimum usable EXP - in the compilation log, so the static half of the problem is caught for you.

But EXP is a PIN. Nothing can stop a design driving it too low at RUN TIME. On this block the margin is generous - the minimum is EXP = 5 for a 16 bit input - but if EXP is under software control, clamp it in software to the minimum the compiler printed.

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 pair of a block is accepted and falls on the clock after the N-th - it is high exactly while the block is ACCUMULATING. BUSY high with INTEGRATING low is precisely the serial multiply.
• 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.
• 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 pair, 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 pair of the next block takes it back to 1. 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 by then, so OUT_DV shows how far into it the input has got, not N - the clock that always reads N is the one INTEGRATING falls on - which is the useful thing to latch alongside the result, and the cheapest way to confirm at run time that the block was long enough for the tail. Only RESET clears it to 0.

Q formats link

IN_A, IN_B (one shared format) and COVARIANCE carry fixed point formats (integer bits, fractional bits, sign), the same convention as the Fixed P. family. The result is requantised into the COVARIANCE format with the selected rounding (nearest / truncate) and overflow policy (saturate / wrap); saturation is symmetric for signed formats, as everywhere else in the toolchain.

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 $\mathrm{mean}(ab) - \mathrm{mean}(a)\mathrm{mean}(b)$ in exact rational arithmetic and shares no algorithm with the core; the tolerance is 0. Coverage pins the two-stream behaviour with second streams derived from the first so the answer is known in advance:

The tail length is checked against the formula at compile time: three copies of it exist - the BCV_TAIL macro in the core, tail_len() in the generator and TailClocks() in the plugin - and the testbench refuses to build if they disagree. tb/block-ops/port_check.py preprocesses the real core and checks the symbol’s pin list against the generated entity’s ports for every enable combination. The status outputs are checked clock by clock against the contract above. Unlike Block Mean or Block Variance there is no all-in-one counterpart to cross-check against - Block Statistics has no covariance - so the exact-rational golden is the only reference, which is why its tolerance is zero.