Duty Cycle — Control Systems/Signal Measurements
Control_Systems/Signal_Measurements/Duty_Cycle · 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.
Duty Cycle
Control Systems / Signal Measurements
The fraction of the last N samples that sat above a reference
level: y = (number of samples with u > ref) / N, a number between 0 and
1. On a bilevel waveform that is the pulse-on fraction, which is
what MATLAB's dutycycle reports.
Ports
- u – the bilevel signal. Scalar – see Notes.
- y – the duty cycle over the window, in [0, 1]. Scalar.
Parameters
- Window Length – N, how many samples the fraction is taken over. A whole number from 2 to 256. It sets the block's resolution as well as its memory: the answer can only ever be a multiple of 1/N.
- Reference Level – the level a sample must exceed to count as on. Strictly greater than: a sample exactly at the level counts as off. Put it midway between the waveform's two logic levels.
- 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.
Window Length and Reference Level are structural and are inlined at export time: the window length decides how many additions the core contains, which no runtime parameter can change. Re-export after changing either. The 1/N is resolved to a constant when the configuration is read, so nothing in any emitted core divides – which is what keeps the three HDL targets genuine synthesizable Q16.16.
Simulink bridge
No equivalent (Support::None). The Signal Processing
Toolbox ships no Simulink library at all, and a scan of the DSP System
Toolbox libraries (dspmathops, dspstat3,
dspsigops, dspxfrm3, dsparch4,
dspsrcs4, dspsnks4) together with
simulink and simulink_extras finds nothing that
measures a duty cycle. 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. - The reference level is a parameter here and is ESTIMATED in MATLAB.
dutycyclerunsstatelevelsover the whole signal first – a two-peak histogram of every sample – and puts its reference halfway between the two levels it finds. A stream has no whole signal to histogram, and a level estimated from a moving window would drift with the signal it is supposed to be measuring. So the level is asked for, and the two answers agree exactly when the level given is the onestatelevelswould have found. - The window is prefilled with OFF, not with zero samples. What is stored is the comparison, not the sample, so the startup transient reads as a duty cycle of 0 whatever the reference level is – including a negative one, where a zero-filled window of samples would have read as fully on.
- The answer is quantized to 1/N. With N = 64 the finest distinction the block can make is about 1.6 %.
- Scalar only. One channel and its own window; wire one block per channel.
- No state space. A threshold is nonlinear, so no A/B/C/D describes the block and model reduction correctly declines to merge it.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Signal_Measurements/Duty_Cycle |
| family | Control_Systems/Signal_Measurements |
| solver environment class | ICoreBlock_0_Control_Systems_1_Signal_Measurements_2_Duty_Cycle |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Signal_Measurements/Duty_Cycle/ICoreBlock_0_Control_Systems_1_Signal_Measurements_2_Duty_Cycle.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Signal_Measurements/Duty_Cycle/ICoreBlock_0_Control_Systems_1_Signal_Measurements_2_Duty_Cycle.h |
| default size on canvas | 120 × 72 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 | 64 | — |
Reference Level | 0.5 | — |
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: dutycycle() is a MATLAB function and the Signal Processing Toolbox ships no Simulink library at all. Measured rather than assumed -- a scan of dspmathops, dspstat3, dspsigops, dspxfrm3, dsparch4, dspsrcs4, dspsnks4, simulink and simulink_extras finds no block that measures a duty cycle. 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).
Duty Cycle -- the fraction of the last N samples that sat ABOVE a reference level ⚠ THE REFERENCE LEVEL IS A PARAMETER HERE AND IS ESTIMATED IN MATLAB, which is the one real difference from dutycycle() and is stated where a user reads it rather than glossed. dutycycle() runs statelevels() over the WHOLE signal first -- a two-peak histogram of every sample -- and puts its reference halfway between the two levels that finds. A stream has no whole signal to histogram, and a level estimated from a moving window would drift with the signal it is supposed to be measuring, so this block asks for the level instead.
⚠ THE WINDOW HOLDS THE COMPARISON, NOT THE SAMPLE. Storing samples and comparing N of them every step is the obvious arrangement and it is worse twice over: N comparisons per sample where this costs one, and a zero-prefilled window of SAMPLES reads as ON for any NEGATIVE reference level -- a startup transient that depends on a parameter rather than on the signal. Storing the indicator makes the prefill unambiguously OFF whatever the level is.
The output is then a plain sum over the register times 1/N, with the reciprocal resolved at configuration load: nothing in any emitted core divides, so the three hardware targets stay genuine synthesizable Q16.16 arithmetic.
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 … 0.01562 |
ramp | Ramp: slope 1 from t = 0 | 0 … 0.8281 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | 0 … 0.3281 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | 0 … 0.3281 |
Plotted: step — Step: 0 -> 1 at t = 1 s
Category dynamic · sample time 0.1 · 60 steps · commit 608c87ca1 · produced by docsSample --out <folder> --blocks Duty_Cycle CUSUM_Detector --steps 60 · data docs/generated/samples/Control_Systems__Signal_Measurements__Duty_Cycle.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).