Characteristic Polynomial — Control Systems/Polynomials

Control_Systems/Polynomials/Characteristic_Polynomial · 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.

Characteristic Polynomial

Control Systems / Polynomials

Reports the characteristic polynomial of a square matrix, det(λI − A) = λⁿ + c₁λⁿ⁻¹ + … + c_n, in descending powers. Entry k is (−1)^k times the sum of every k×k principal minor of A, so entry 0 is exactly 1, entry 1 is −trace(A) and the last entry is (−1)ⁿ·det(A). This is MATLAB's charpoly.

It reports the polynomial, not the eigenvalues – see Notes. Wire it into Curve Fitting / Evaluate Fit to evaluate it, or into Curve Fitting / Fit Derivative to differentiate it.

Ports

A – the matrix, square: [n,n], with n at most 6 – see Notes for why.
p – the coefficients, descending powers, as a column of n + 1 entries.

Parameters

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. There is nothing to tune, so nothing is exposed as a parameter on the generated core.

Every entry is emitted as one flat sum of signed products of the matrix's entries, so a generated core carries no scratch matrix, runs no recurrence and performs no division. The three HDL targets are therefore genuine synthesizable Q16.16: each product is accumulated at full width and shifted back once per factor.

Simulink bridge

None (Support::None). charpoly is a MATLAB function, and the Symbolic Math Toolbox it is proposed from ships no Simulink library at all, so there is no library path a diagram could name. 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. No configuration of it crosses either, including "Sampling Time (s)", which has no counterpart to be written to.

Notes

Algebraic, with no state: the output depends only on the current input.
Order six is the ceiling, and the bound is on the generated FILE. The expansion is Σ_k C(n,k)·k! products, unrolled in ten languages – 15 at n = 3, 64 at n = 4, 325 at n = 5 and 1956 at n = 6. A larger matrix is refused, with that reason, rather than truncated.
It gives the polynomial, not the eigenvalues. Finding the roots is an iterative solve every sample in ten backends, and they are complex in general, which a real signal cannot carry. This is the object the eigenvalues are the roots of, and Polynomials / Polynomial Coefficients is its inverse whenever the roots happen to be real.
The summation order is the expansion's, not MATLAB's. Measured on A = [0.7 −1.3 0.45; 2.1 −0.6 1.25; −0.9 0.35 1.8], R2026a's charpoly reports [1, −1.9, 2.4575, −5.402] and this expansion [1, −1.9, 2.4575000000000005, −5.402000000000001] – 2e−16 relative, in the last two entries only. All ten exported targets share this block's order.
No state space: the map is a polynomial in the input rather than a linear one, so there is no A/B/C/D to merge and model reduction correctly declines it.

Code facts#

Fact	Value
registered type	`Control_Systems/Polynomials/Characteristic_Polynomial`
family	`Control_Systems/Polynomials`
solver environment class	`ICoreBlock_0_Control_Systems_1_Polynomials_2_Characteristic_Polynomial`
source	`src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Polynomials/Characteristic_Polynomial/ICoreBlock_0_Control_Systems_1_Polynomials_2_Characteristic_Polynomial.cpp`
header	`src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Polynomials/Characteristic_Polynomial/ICoreBlock_0_Control_Systems_1_Polynomials_2_Characteristic_Polynomial.h`
default size on canvas	130 × 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`	A
2	out	`ICoreDouble`	p

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::None`
Simulink path	—
port-count rule	`PortsParam::None`
`SampleTime` parameter	yes

Caveat (shown to the user): the characteristic polynomial of a matrix is a MATLAB function (charpoly), not a Simulink library block -- the Symbolic Math Toolbox this block answers ships no Simulink library at all -- so there is no path a diagram could name; the block is reported rather than dropped when a model crosses

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.

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

Characteristic Polynomial -- charpoly on a wire Entry k of the output is (-1)^k times the sum of every k-by-k PRINCIPAL MINOR of the input matrix, so the output is det(lambda*I - A) written in descending powers. Entry 0 is the literal 1, entry 1 is -trace(A), and the last entry is (-1)^n * det(A).

WHY THE MINOR FORM AND NOT FADDEEV-LEVERRIER. The recurrence is the cheap way to compute this in one language and the wrong way to emit it in ten: it carries an n-by-n scratch matrix from step to step, and a VHDL process body has two fixed-point scratch variables and no array. The principal-minor form carries nothing at all -- each entry is a flat sum of signed products of the input's entries -- so every target emits straight-line multiply-accumulate and the three fixed-point ones carry it as genuine Q16.16.

Verified against MATLAB R2026a rather than asserted. On A = [0.7 -1.3 0.45; 2.1 -0.6 1.25; -0.9 0.35 1.8]:

charpoly(A) 1 -1.9 2.4575 -5.402 minor expansion 1 -1.9 2.4575000000000005 -5.402000000000001

a 2e-16 relative difference in the last two entries, which is the two summation orders and not a disagreement about the answer. The block's own C++ reference uses the SAME order as the ten emitted bodies, which is what the export comparison actually checks.

Sample results#

t	in ICoreDouble-Out-0	out ICoreDouble-Out-0 [2x1] entry 0
0	-2	[1, 2]
0.4	0.5	[1, -0.5]
0.8	-2	[1, 2]
1.2	0.5	[1, -0.5]
1.6	-2	[1, 2]
2	0.5	[1, -0.5]
2.4	-2	[1, 2]
2.8	0.5	[1, -0.5]
3.2	-2	[1, 2]
3.6	0.5	[1, -0.5]
4	-2	[1, 2]
4.4	0.5	[1, -0.5]
4.8	-2	[1, 2]
5.2	0.5	[1, -0.5]

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)	1 … 1
`ramp`	Ramp: slope 1 from t = 0	1 … 1
`sine`	Sine Wave: amplitude 1, 2 rad/s, no phase, no bias	1 … 1
`step`	Step: 0 -> 1 at t = 1 s	1 … 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 ba0d5f47abbf16b9e248ecce5a0d14210ec2f9d7 · produced by docsSample --out <folder> --blocks Polynomial_Coefficients Characteristic_Polynomial Pade_Approximant --steps 60 · data docs/generated/samples/Control_Systems__Polynomials__Characteristic_Polynomial.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).

Characteristic Polynomial — Control Systems/Polynomials

Description#