Discrete Zero Pole — Control Systems/Discrete
Control_Systems/Discrete/Discrete_Zero_Pole · 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.
Discrete Zero-Pole
Control Systems / Discrete
A discrete transfer function written in factored form – by its roots rather than its coefficients:
H(z) = K · (z − z1)…(z − zm) / (z − p1)…(z − pn)
It is the same system Discrete Transfer Function realizes, entered the way you usually think about it: the poles are where the dynamics live, and a pole inside the unit circle is stable. The factors are multiplied out into an ordinary numerator and denominator, then realized in companion form.
Ports
- Input – the signal u, of any size [p,m]. The same system runs on every entry independently, so a matrix input gives a matrix output of the same shape rather than being treated as a vector of one system.
- Output – H(z) applied to the input, the SAME size [p,m].
Parameters
- Zeros – the roots of the numerator, as a list in MATLAB
syntax:
[]for none,[0.4],[0.4 -0.6]. Complex roots are written[0.4+0.2i 0.4-0.2i]and must appear in conjugate pairs, since a real system cannot have an unpaired complex root. Defaults to [1], as Simulink's does. - Poles – the roots of the denominator, in the same syntax and under the same conjugate-pair rule. There must be at least one pole, and no more zeros than poles – an improper H(z) would need future inputs. Defaults to [0 0.5], as Simulink's does.
- Gain – the scalar K multiplying the whole factored form. Defaults to 1. Note this is the zero-pole-gain K, not the DC gain: the DC gain is K·∏(1−zi)/∏(1−pj).
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period. It is the step the recursion advances by.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. The roots are expanded into A/B/C/D at export time, so the generated core carries the companion-form recursion and no root arithmetic at all – there is nothing left in it that knows the system was entered in factored form.
On the three HDL targets the coefficients are carried in Q16.16, so a system whose numerator is very small relative to its denominator can quantize badly. Keeping the relative degree to 1 (one more pole than zeros) is what resolves the numerator properly – the same consideration the continuous Zero-Pole block's rig documents.
Simulink bridge
Import and export, mapped to simulink/Discrete/Discrete Zero-Pole.
"Zeros" to Zeros, "Poles" to Poles, "Gain" to
Gain, and "Sampling Time (s)" to SampleTime as on every
block. All three values are MATLAB-syntax text on both sides, so they cross
unchanged and losslessly, complex roots included.
Notes
- Stateful: one state per pole, per signal entry.
- Discrete by nature – the recursion advances one step per sample; nothing is integrated.
- The state always starts at zero. Simulink's Discrete Zero-Pole offers no initial-state parameter either, so there is nothing to map and nothing to lose – reach for Discrete State Space if you need to seed one.
- An unpaired complex zero or pole is refused with a logged reason rather than quietly expanded into a different polynomial.
- Entering the same system as coefficients gives Discrete Transfer Function; the two are interchangeable and produce identical trajectories.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Discrete/Discrete_Zero_Pole |
| family | Control_Systems/Discrete |
| solver environment class | ICoreBlock_0_Control_Systems_1_Discrete_2_Discrete_Zero_Pole |
| source | src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Discrete/Discrete_Zero_Pole/ICoreBlock_0_Control_Systems_1_Discrete_2_Discrete_Zero_Pole.cpp |
| header | src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Discrete/Discrete_Zero_Pole/ICoreBlock_0_Control_Systems_1_Discrete_2_Discrete_Zero_Pole.h |
| default size on canvas | 130 × 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 | — |
| 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#
| Config variable | Default | Simulink parameter |
|---|---|---|
Zeros | [1] | Zeros |
Poles | [0 0.5] | Poles |
Gain | 1 | Gain |
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/Discrete/Discrete Zero-Pole |
| port-count rule | PortsParam::None |
SampleTime parameter | yes |
| ICore config | Simulink parameter | Value translation |
|---|---|---|
Zeros | Zeros | passes through |
Poles | Poles | passes through |
Gain | Gain | passes through |
Caveat (shown to the user): Zeros and Poles are exchanged as MATLAB-syntax lists, so complex roots cross unchanged in both directions. ICore refuses an unpaired complex root rather than expanding it into a different polynomial
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.
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).
Discrete Zero-Pole block — H(z) = K * prod(z - z_i) / prod(z - p_j) The same system Discrete Transfer Function realizes, entered by its ROOTS instead of its coefficients. The factors are multiplied out by ICoreTransferFunction::fromPolesZeros and the resulting numerator/denominator pair is realized in companion form by ICoreStateSpace::fromTransferFunction — after which this is an ordinary discrete A/B/C/D block and ICoreDiscreteLinearBlockBase supplies everything else.
Verified against Simulink R2026a: K = 2, zeros [0.4], poles [0.5 0.8] gives 0 2 5.8 11.14 17.762 25.4346 33.96018 ... which is identical to the last digit to simulink/Discrete/Discrete Transfer Fcn with num = 2*[1 -0.4] and den = conv([1 -0.5],[1 -0.8]) — so the root expansion and the descending-powers-of-z convention both match the reference.
TWO WAYS TO GET THIS WRONG, both silent, both guarded here:
- Reading Zeros/Poles through getConfig_string()/getConfig_matrix(). Their config TYPE
depends on whether the value happens to contain a complex root, so either accessor misses one of the two cases. Everything goes through rawConfigText() instead — see the header, and the continuous Zero_Pole block, which paid for this lesson first.
- An unpaired complex root. ICorePolynomial::fromRoots expands in complex arithmetic and
keeps only the real part of each coefficient, assuming conjugate pairs; fed an unpaired root it returns a polynomial that is not the one asked for, with no error anywhere. So the pairing is checked up front and refused with a logged reason.
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.5 … 1 |
ramp | Ramp: slope 1 from t = 0 | 0 … 0.2 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | -0.3841 … 0.3842 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | -4.141 … 1.734 |
Plotted: step — Step: 0 -> 1 at t = 1 s
Category dynamic · sample time 0.1 · 60 steps · commit ccf005c8 · produced by docsSample --out <folder> --steps 60 · data docs/generated/samples/Control_Systems__Discrete__Discrete_Zero_Pole.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).