Convolution Matrix — Control Systems/Correlation And Convolution
Control_Systems/Correlation_And_Convolution/Convolution_Matrix · 1 input / 1 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text
Description#
The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.
Convolution Matrix
Control Systems / Correlation And Convolution
Builds the Toeplitz convolution matrix of the last N samples of
a stream: an (N + M − 1) × M matrix whose column j is
the window pushed down by j rows –
Y(i, j) = a[i−j] inside the window and 0 outside it. It is the
streaming counterpart of MATLAB's convmtx(a, M) for a column
a.
What it is for: Y turns convolution into linear algebra. For any M-vector v, Y·v = conv(a, v), which is what lets a filter fit, a least-squares deconvolution or an identification step be written as one matrix solve instead of a loop.
Nothing is computed. Every entry is a window sample or a literal zero, so the block contains no arithmetic at all – see Code export.
Ports
- u – the stream. Scalar; the block keeps its own window of the last N samples – see Notes.
- Y – the convolution matrix, (N + M − 1) × M. Its size follows from the two parameters alone and does not depend on the input's values. This is the one block in the family whose output is not a column.
Parameters
- Window Length – N, how many samples of the stream the matrix is built from, and therefore how many rows it has beyond M − 1. A whole number from 1 to 32.
- Number of Columns – M, the length of the vector Y is meant to multiply. A whole number from 1 to 32. The bound is a code-size bound: every target writes all (N + M − 1)×M entries explicitly.
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text.
Both sizes are structural – they decide the shape of the emitted output and how many assignments the core contains, which no runtime parameter can change – so they are baked in at export time rather than offered as tunable parameters. Re-export after changing either.
The three HDL targets are genuine synthesizable Q16.16, and they are exact: the core is a shift register and a wiring pattern, with no multiply, no accumulator and therefore no rounding anywhere. Every other block in this family quantizes; this one does not.
Simulink bridge
No equivalent (Support::None). The Signal Processing
Toolbox ships no Simulink library at all, and nothing in the Simulink
standard library or in DSP System Toolbox emits a convolution matrix –
DSP System Toolbox's Convolution block performs the convolution rather
than building the operator for it. The bridge reports this block rather than
dropping it silently, and it therefore has no parity testbench. Code
export verification still covers it across all ten languages.
Notes
- Stateful, and discrete by nature
(
setDiscreteOnlyBlock(true)): the window advances once per sample. - Column, not row. MATLAB's
convmtxtransposes its answer with its argument – a column of length N gives (N + M − 1) × M and a row gives M × (N + M − 1). A stream is a column here, so the tall form is what this block produces. - Oldest-first is the published order. a[0] is the oldest sample still in the window and a[N−1] the newest, which is what makes column j the window pushed down by j rows.
- The window is zero-prefilled, and the zeros count. Before N samples
have arrived the buffer still holds its initial zeros, so the first N−1
matrices of a run are a startup transient. MATLAB's
convmtxis a batch function with the whole vector in hand and has no transient. - Verified against MATLAB. On a = [0.7 −1.3 0.45 2.1 −0.6] with M = 3, R2026a returns a 7×3 matrix that agrees with this layout entry for entry.
- Scalar input. One channel and its own window; wire one block per channel.
- No state space. The block's output is a rearrangement of past inputs rather than a linear system in them, so it carries no A/B/C/D pair and model reduction correctly declines to merge it.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Correlation_And_Convolution/Convolution_Matrix |
| family | Control_Systems/Correlation_And_Convolution |
| solver environment class | ICoreBlock_0_Control_Systems_1_Correlation_And_Convolution_2_Convolution_Matrix |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Correlation_And_Convolution/Convolution_Matrix/ICoreBlock_0_Control_Systems_1_Correlation_And_Convolution_2_Convolution_Matrix.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Correlation_And_Convolution/Convolution_Matrix/ICoreBlock_0_Control_Systems_1_Correlation_And_Convolution_2_Convolution_Matrix.h |
| default size on canvas | 140 × 80 px |
| ports at insert | 1 in, 1 out |
| code generators implemented | Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text |
Ports#
| # | Direction | Signal type | Description label |
|---|---|---|---|
| 1 | in | ICoreDouble | u |
| 2 | out | ICoreDouble | Y |
Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.
Configuration variables#
| Config variable | Default | Simulink parameter |
|---|---|---|
Window Length | 8 | — |
Number of Columns | 3 | — |
Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.
Simulink bridge#
| support | Support::None |
| Simulink path | — |
| port-count rule | PortsParam::None |
SampleTime parameter | yes |
Caveat (shown to the user): no Simulink equivalent: convmtx() is a MATLAB function and the Signal Processing Toolbox ships no Simulink library at all. Nothing in the Simulink standard library or in DSP System Toolbox emits a convolution matrix -- DSP System Toolbox's Convolution block performs the convolution rather than building the operator for it. Reported rather than dropped, and it carries no parity testbench
Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The lists agree. check_block_descriptions.py finds no disagreement between the description's Ports, Parameters, Code export and Simulink bridge lists and the code's.
The verdict above is
tools/docs/check_block_descriptions.py(P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.
File banner (developer view)#
The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).
Convolution Matrix -- the Toeplitz matrix of a windowed stream, Y = convmtx(a, M) NOTHING IS COMPUTED, AND THAT IS THE POINT. Every entry of the (N + M - 1) x M output is either a sample from the window or a literal zero: column j is the window pushed down by j rows. So all ten targets emit assignments and no arithmetic whatever -- no multiply, no accumulator, no rounding -- and the three hardware targets carry the block EXACTLY rather than in Q16.16 approximation, which no other block in this family can say. The block's whole content is WHERE each sample goes.
WHAT IT IS FOR. Y turns convolution into linear algebra: for any M-vector v, Y*v equals conv(a, v). That is what makes a least-squares deconvolution, a filter fit or a system identification step expressible as one matrix solve rather than as a loop.
MEASURED AGAINST MATLAB R2026a rather than asserted. On a = [0.7 -1.3 0.45 2.1 -0.6] with M = 3, R2026a's convmtx(a, 3) is 7x3 and agrees with this layout entry for entry. The probe is recorded in the notes of the toolbox-blocks plan, Family B.
⚠ COLUMN a, NOT ROW a. MATLAB's convmtx transposes its answer with its argument: convmtx of a COLUMN of length N is (N + M - 1) x M, and of a ROW is M x (N + M - 1) -- measured, both. A stream is a column here, so the tall form is the one this block produces.
⚠ THE WINDOW IS ZERO-PREFILLED AND THE ZEROS COUNT -- the convention Detrend and Moving Median carry. The first N - 1 outputs of a run are a startup transient.
Sample results#
The same rig also ran:
| Stimulus | What it is | Output range |
|---|---|---|
impulse | Impulse: one sample of 1 at k = 5, 0 elsewhere (Repeating Sequence Stair) | 0 … 1 |
ramp | Ramp: slope 1 from t = 0 | 0 … 5.2 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | -0.9962 … 0.9996 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | -2 … 3 |
Plotted: step — Step: 0 -> 1 at t = 1 s
Category dynamic · sample time 0.1 · 60 steps · commit 3c100aff6f27235305db4ad4d572f32e342718ad · produced by docsSample --out <folder> --blocks Convolution Circular_Convolution Convolution_Matrix Deconvolution Cross_Correlation Cross_Covariance --steps 60 · data docs/generated/samples/Control_Systems__Correlation_And_Convolution__Convolution_Matrix.json · the SVG is generated from those numbers by tools/docs/plot_svg.py, so it is a run and not a drawing (R-D10).