Envelope Detector — Control Systems/Signal Smoothing
Control_Systems/Signal_Smoothing/Envelope_Detector · 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.
Envelope Detector
Control Systems / Signal Smoothing
Follows the magnitude envelope of a stream: it rectifies the input and then tracks it with a first-order recursion over a single state, the way an analogue detector does. Two methods:
- peak – an asymmetric one-pole follower, e = e + α·(|u| − e), with α taken from Attack Time while the rectified signal is above the envelope and from Release Time while it is below. That is what makes it rise onto a burst quickly and let go slowly.
- hold – peak hold with linear decay, e = max(|u|, e − rate·Ts). No attack lag at all: the envelope jumps straight onto any sample that exceeds it, and otherwise walks down at a fixed rate per second.
Ports
- u – the signal to follow. Its sign is discarded: the envelope is built from |u|. Scalar – see Notes.
- y – the envelope after this sample's update, so never negative. Same size as the input, so scalar.
Parameters
- Method – which recursion runs:
- peak – the asymmetric one-pole follower above. Default.
- hold – peak hold with linear decay.
- Attack Time (s) – the time constant used while the rectified signal is above the envelope (peak only). Zero or less means no attack lag, so the envelope reaches a rising sample in one step.
- Release Time (s) – the time constant used while it is below (peak only). Making it much larger than the attack time is what gives the classic envelope shape; making the two equal turns the block into a plain rectified lowpass.
- Decay Rate (per s) – how fast the held peak walks down, in signal units per second (hold only). Zero or less never decays, so the block becomes a running maximum of |u|.
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period. It also sets both smoothing coefficients, since they are 1 − exp(−Ts/T).
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text.
The two smoothing coefficients are resolved at export time from the time constants and the sampling period and inlined into the arithmetic, so no generated core evaluates an exponential. Re-export after changing a time constant or the rate.
The three HDL targets are genuine synthesizable Q16.16: a rectifier, one comparison and one multiply-accumulate.
Simulink bridge
No equivalent (Support::None). The Signal Processing
Toolbox ships no Simulink library at all, and MATLAB's
envelope is a batch function whose three methods all need the whole
signal – none of them is this recursion. Claiming a mapping onto it would
export a different function under this block's name. The bridge reports the
block rather than dropping it silently, and it has no parity testbench.
Code export verification still covers it across all ten languages.
Notes
- Stateful (one scalar: the envelope, seeded at zero), and discrete
by nature (
setDiscreteOnlyBlock(true)). - Not MATLAB's
envelope. That function's analytic, peak and rms methods each look forward in the signal – a Hilbert transform, a spline through maxima on both sides, a centred window – and none can be evaluated from past samples alone. This block is the streaming detector instead, and it is not offered as a numerical match to any of the three. - The output is the UPDATED envelope, not the previous one. On a rising sample in hold the output equals |u| exactly on the same step.
- The envelope is never negative, and it is not an upper/lower pair: rectifying makes the lower envelope the negative of this one, which is why only one is emitted.
- Scalar only. One channel and its own envelope; wire one block per channel.
- No state space. Rectification and the attack/release choice are both 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_Smoothing/Envelope_Detector |
| family | Control_Systems/Signal_Smoothing |
| solver environment class | ICoreBlock_0_Control_Systems_1_Signal_Smoothing_2_Envelope_Detector |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Signal_Smoothing/Envelope_Detector/ICoreBlock_0_Control_Systems_1_Signal_Smoothing_2_Envelope_Detector.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Signal_Smoothing/Envelope_Detector/ICoreBlock_0_Control_Systems_1_Signal_Smoothing_2_Envelope_Detector.h |
| default size on canvas | 128 × 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 |
|---|---|---|
Method | peak%~%hold~~peak | — |
Attack Time (s) | 0.02 | — |
Release Time (s) | 0.2 | — |
Decay Rate (per s) | 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: the Signal Processing Toolbox ships no Simulink library at all, and MATLAB's envelope() is a batch function whose analytic, peak and rms methods each look forward in the signal -- none of the three is this streaming attack/release recursion, so an entry naming it would export a different function under this block's name. 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).
Envelope Detector -- rectify, then follow. One scalar state, two methods. ⚠ THIS IS THE STREAMING COUNTERPART OF MATLAB's envelope(), NOT A TRANSCRIPTION OF IT. All three of that function's methods need the whole signal in hand: 'analytic' takes a Hilbert transform, 'peak' fits a spline through local maxima it has already found, and 'rms' centres a window on each sample. None can be evaluated at sample k from samples up to k. What a stream can do is what an analogue detector does -- rectify, then follow -- so that is what this block is, and the description says so where a user will read it.
TWO METHODS, one first-order recursion each:
peak : e[k] = e[k-1] + alpha * (|u[k]| - e[k-1]), alpha = aAttack if |u| rises above the envelope and aRelease otherwise hold : e[k] = max(|u[k]|, e[k-1] - rate * Ts)
THE SMOOTHING COEFFICIENTS ARE DERIVED FROM THE TIME CONSTANTS AND THE BLOCK'S OWN SAMPLING PERIOD: alpha = 1 - exp(-Ts / T). What the ten targets inline is a pair of numbers, so no generated core evaluates an exponential and the three hardware targets stay a fixed multiply-accumulate.
⚠ AND THEY ARE READ LATE, NEVER CACHED WHEN THE CONFIGURATION IS READ. The model build assigns every block's sampling period AFTER the port-size convergence loop that loadBlockConfig() runs inside, so a coefficient computed there would come from a period that had not been assigned yet -- and every generator would inline it. Ten backends agreeing with each other and disagreeing with the simulation is precisely what that produces (ADDING_NEW_BLOCKS.md §7), and it is why the coefficients are accessors rather than fields.
⚠ THE OUTPUT IS THE UPDATED ENVELOPE, NOT THE PREVIOUS ONE, and on the three hardware targets that has to be arranged rather than assumed. A state signal written with a deferred assignment still READS as its previous value inside the same tick, so the body computes the new envelope into scratch, publishes the scratch, and only then schedules the write. Reading the state back would publish e[k-1] and lag the reference by exactly one sample.
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.9933 |
ramp | Ramp: slope 1 from t = 0 | 0 … 5.799 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | 0 … 0.9999 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | 0.6258 … 2.993 |
Plotted: step — Step: 0 -> 1 at t = 1 s
Category dynamic · sample time 0.1 · 60 steps · commit 6db3032c0 · produced by docsSample --out <folder> --blocks Detrend Savitzky_Golay_Filter Hampel_Filter Envelope_Detector --steps 60 · data docs/generated/samples/Control_Systems__Signal_Smoothing__Envelope_Detector.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).