Zero Pole — Control Systems/Continues
Control_Systems/Continues/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.
Zero-Pole
Control Systems / Continues
A continuous-time SISO transfer function written in factored form – by where its roots sit rather than by its coefficients:
H(s) = K · (s − z₁)(s − z₂)… / (s − p₁)(s − p₂)…
so zeros [-1] over poles [-2 -3] with gain 5 is 5(s + 1) / ((s + 2)(s + 3)). Reach for this block rather than Transfer Function whenever you are thinking in terms of where the poles are – damping, bandwidth, a resonance – and let it multiply the polynomials out for you.
Ports
- Input – the signal to filter, of any size [p,m].
- Output – the filtered signal, of the same size [p,m].
The function is SISO, but it is applied independently to every entry of the input signal, each entry carrying its own states.
Parameters
- Zeros – the roots of the numerator, as a list in MATLAB
syntax:
[]for none,[-1],[-1 -4]. Complex values are written with i or j –[-0.5+2i -0.5-2i]– and must appear in conjugate pairs, since a real system cannot have an unpaired complex root. Separate entries with spaces, commas or semicolons, and write each number without spaces inside it (-0.5+2i, not-0.5 + 2i). Defaults to[1], matching Simulink. - 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: a function with more zeros than poles is improper and
would have to differentiate its input, which no state space realizes. Defaults
to
[0 -1], matching Simulink – note that the pole at the origin makes the default an integrator, so the default block is only marginally stable. - Gain – scalar K, the overall multiplier on the factored numerator. Defaults to 1. Note this is the zero-pole-gain K, which is the high-frequency gain, not the DC gain.
- 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. The factorization is resolved at export time: the zeros, poles and gain are multiplied out, the resulting transfer function is discretized by the model's method, and every target emits the direct-form difference equation of the result – the same recursion the discrete run realizes, so generated code matches the in-app simulation. The coefficients are therefore inlined constants, not tunable parameters: moving a pole after export means re-exporting.
The three HDL targets carry the recursion in Q16.16 fixed point. A pole close to the imaginary axis, or a wide spread between the fastest and slowest pole, will show quantization error there well before it does on the software targets – the factored form makes such a system easy to ask for without noticing.
Simulink bridge
Import and export, mapped to simulink/Continuous/Zero-Pole. "Zeros" to
Zeros, "Poles" to Poles, "Gain" to Gain.
Nothing is left behind – every parameter has a counterpart, and because
both sides write these lists in the same MATLAB syntax the text crosses
unchanged and losslessly, complex roots included.
This block has no SampleTime parameter in Simulink –
it is a continuous block there – so "Sampling Time (s)" stays on the ICore
side and does not cross.
Notes
- Stateful: as many states per input entry as there are poles.
- Equivalent to Transfer Function once the factors are multiplied out, and built on the same realization, so the two agree exactly for the same system. Use whichever form you know the system in.
- An unpaired complex zero or pole is refused with a logged reason rather than quietly rounded to its real part.
- Pole-zero cancellation is not performed: a factor appearing in both lists still contributes a state, exactly as in Simulink.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Continues/Zero_Pole |
| family | Control_Systems/Continues |
| solver environment class | ICoreBlock_0_Control_Systems_1_Continues_2_Zero_Pole |
| source | src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Continues/Zero_Pole/ICoreBlock_0_Control_Systems_1_Continues_2_Zero_Pole.cpp |
| header | src/ICoreSDK/ICoreBlockLibrary/Blocks/Control_Systems/Continues/Zero_Pole/ICoreBlock_0_Control_Systems_1_Continues_2_Zero_Pole.h |
| default size on canvas | 140 × 90 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 -1] | 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/Continuous/Zero-Pole |
| port-count rule | PortsParam::None |
SampleTime parameter | no — the counterpart defines none; the rate stays on the ICore side |
| 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 keeping only its real part, so a Simulink block carrying one is reported on import
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).
Zero-Pole block — H(s) = K * PROD(s - z_i) / PROD(s - p_j) The factored form of a continuous SISO transfer function. Everything downstream of the factorization is Transfer Function's machinery and deliberately so: once the zeros, poles and gain have been multiplied out into num/den polynomials this block IS a transfer function, and reusing that realization is what makes the two agree to the last bit rather than merely closely. The state space, the discretization, the per-entry IIR emulators and all ten language generators are the same shapes Transfer Function uses.
What this block adds is the FRONT END, and that is where the care is:
- ZEROS AND POLES ARE COMPLEX, and ICore configs are real matrices. They are therefore
STRING configs holding MATLAB-style lists -- "[-0.5+2i -0.5-2i -3]" -- parsed here. That choice is what lets the bridge hand the text straight to Simulink's Zeros/Poles parameters and take it straight back, losslessly, in both directions. A matrix config would have forced real and imaginary parts into separate variables that Simulink has no counterpart for, and the bridge would have carried nothing but the gain. Because the value is an EXPRESSION rather than the name of something in the variables space, both configs opt out of that lookup with setResolvesFromVariablesSpace(false) -- otherwise loadBlockConfig() would try to resolve "[-0.5+2i]" as a variable name and file the config under whichever map the resolved type implied, and getConfig_string() would then miss.
- CONJUGATE PAIRS ARE CHECKED HERE, because nothing below checks them.
ICorePolynomial::fromRoots multiplies the factors out in complex arithmetic and then keeps only the real part of each coefficient -- its comment says "assumes conjugate pairs". Feed it an unpaired complex root and it returns a polynomial that is not the one you asked for, silently, with no error anywhere. So this block verifies the pairing itself and refuses the run with a logged reason instead. That check is the single most important thing in this file.
Sizing: the block defines ONE SISO transfer function, but the input port may carry a [p,m] matrix. The same function is applied INDEPENDENTLY to each of the K = p*m entries, exactly as Transfer Function does, with the per-entry states held as the K columns of X[n, K].
Code export: all ten targets, each emitting the direct-form difference equation of the DISCRETIZED function -- the same recursion the discrete run realizes.
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.099 … 0.08112 |
ramp | Ramp: slope 1 from t = 0 | -7.214 … 0.3238 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | -0.9939 … 0.282 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | -1.118 … 0.503 |
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__Continues__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).