Matrix Square — Control Systems/Matrix Operations

Control_Systems/Matrix_Operations/Matrix_Square · 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.

Matrix Square

Control Systems / Matrix Operations

Multiplies the input by its own transpose from the left: y = u^T·u. Entry (i,j) of the output is the inner product of the input's column i with its column j, so an [m,n] input leaves as an [n,n] one.

This is not u·u. The name suggests it and the block does something else – the same thing Simulink's block does, verified against it. The result is the Gram matrix of the input's columns: always square, always symmetric, and never negative on its diagonal.

Ports

Input – the matrix u, of any size [m,n]. It does not have to be square: only its column count is felt on the output.
Output – [n,n], where n is the input's COLUMN count. A column vector [m,1] therefore collapses to the scalar sum of its squares, and a row vector [1,n] expands to the [n,n] outer product.

Parameters

Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

There is nothing else to set: the operation is fixed, and the Simulink counterpart's dialog offers only data type and rounding controls, which ICore has no counterpart for.

Code export

All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. The dimensions are resolved at export time, so the generated core carries no shape decision.

The three HDL targets are fully synthesizable. Each entry is a sum of products in the Q16.16 datapath, and the accumulator is not the same width in all three. Verilog and SystemVerilog sum into a double-width register (2*ICORE_WIDTH) and shift back to Q16.16 once per entry. VHDL accumulates in the shared Fx process variable, which is Q16.16 (sfixed(15 downto -16)), so every product is rounded as it is added. The three therefore agree to within the low bits rather than bit-exactly, and on a long inner dimension VHDL is the one that drifts.

Simulink bridge

Import and export, mapped to simulink/Matrix Operations/Matrix Square. There are no parameters to carry: the Simulink block's dialog holds only data type and rounding settings, which do not cross.

It defines no SampleTime parameter, so the rate is not carried across: it stays on the ICore side, and a block configured with an explicit positive rate reports that the rate did not cross.

Notes

Algebraic, with no state.
Deliberately carries no state space. The output is quadratic in the input, so no A/B/C/D reproduces it; model reduction is right to report the block as unmergeable. Gain is the linear sibling – a signal times a constant.
The same result can be built from a Transpose feeding a Matrix Multiply. This block is the single-block form, and is what a Simulink model drawn with it imports onto.

Code facts#

Fact	Value
registered type	`Control_Systems/Matrix_Operations/Matrix_Square`
family	`Control_Systems/Matrix_Operations`
solver environment class	`ICoreBlock_0_Control_Systems_1_Matrix_Operations_2_Matrix_Square`
source	`src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Matrix_Operations/Matrix_Square/ICoreBlock_0_Control_Systems_1_Matrix_Operations_2_Matrix_Square.cpp`
header	`src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Matrix_Operations/Matrix_Square/ICoreBlock_0_Control_Systems_1_Matrix_Operations_2_Matrix_Square.h`
default size on canvas	90 × 70 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`	—
2	out	`ICoreDouble`	—

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#

No config variable beyond the Sampling Time (s) every block carries.

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::Both`
Simulink path	`simulink/Matrix Operations/Matrix Square`
port-count rule	`PortsParam::None`
`SampleTime` parameter	no — the counterpart defines none; the rate stays on the ICore side

Caveat (shown to the user): the Simulink counterpart's dialog carries only data type, rounding and overflow settings, none of which has an ICore counterpart, so nothing but the block itself crosses; the operation is u'*u -- NOT u*u -- on both sides, measured against R2026a rather than inferred from the name

Catalog contract: src/ICoreSDK/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.

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).

Matrix Square -- y = u' * u, the Gram matrix of the input's columns THE NAME IS MISLEADING and the semantics were measured rather than assumed. Against Simulink R2026a:

u = [1 2; 3 4] -> [10 14; 14 20] = u'*u (u*u would be [7 10; 15 22]; u*u' [5 11; 11 25]) u = [1 2 3; 4 5 6] -> the 3x3 u'*u, NOT the 2x2 u*u'

So the input need not be square, and the output's size is set by the input's COLUMN count alone: [m,n] -> [n,n]. The result is always symmetric and positive semidefinite.

HDL is SYNTHESIZABLE: it is the same sum of products Product's matrix mode emits, in the Q16.16 datapath. ⚠ The accumulator is NOT the same width in all three: Verilog and SystemVerilog declare acc as signed [2*ICORE_WIDTH-1:0] and shift back once per entry, while VHDL's is variable acc : Fx -- Fx being sfixed(ICORE_INT_BITS-1 downto -ICORE_FRAC_BITS), i.e. Q16.16 itself -- so the loop resizes every product as it is added. That is a property of the shared VHDL base, not a choice here, and it is why the three HDL rows agree to within the low bits rather than bit-exactly. The description says so too; if either moves, move both.

Algebraic and stateless. No state space -- see the header for why.

Sample results#

t	in ICoreDouble-Out-0	out ICoreDouble-Out-0
0	-2	4
0.4	0.5	0.25
0.8	-2	4
1.2	0.5	0.25
1.6	-2	4
2	0.5	0.25
2.4	-2	4
2.8	0.5	0.25
3.2	-2	4
3.6	0.5	0.25
4	-2	4
4.4	0.5	0.25
4.8	-2	4
5.2	0.5	0.25

Every 4th of 60 samples, from the table stimulus.

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 … 33.64
`sine`	Sine Wave: amplitude 1, 2 rad/s, no phase, no bias	0 … 1
`step`	Step: 0 -> 1 at t = 1 s	0 … 1

Plotted: table — Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample

Category static · sample time 0.1 · 60 steps · commit ccf005c8 · produced by docsSample --out <folder> --steps 60 · data docs/generated/samples/Control_Systems__Matrix_Operations__Matrix_Square.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).