Complex Cepstrum — Control Systems/Transforms

Control_Systems/Transforms/Complex_Cepstrum · 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.

Complex Cepstrum

Control Systems / Transforms

The complex cepstrum of a signal frame: the inverse transform of the complex logarithm of its spectrum, with the phase made continuous first,

y = real( ifft( log|X| + j·rcunwrap(∠X) ) ), X = fft(u, n),

where rcunwrap unwraps the phase across the bins and then removes the linear phase a delay puts on it: nd = round(φ[nh]/π) with nh = fix((n+1)/2), and φ[k] is reduced by π·nd·k/nh. This is MATLAB's cceps; unlike the Real Cepstrum beside it, the phase is kept, so the frame's time order matters.

Ports

u – the signal frame, an [N,1] column, N at least 1.
y – the complex cepstrum (its real part), [n,1], where n is the FFT length: the frame's N, or FFT Length.

Parameters

Inherit FFT Length – on (the default, as Simulink's) or off. On, n = N; off, n is FFT Length, the frame being zero-padded to it or truncated, exactly as fft(u, n) does.
FFT Length – n when not inherited, a whole number of 1 or more; any length, not only a power of two. Defaults to 64, as Simulink's does.
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. n and the n-point cosine and sine tables are baked into the core at export time; the transform is a direct DFT, and the phase is atan(im/re) with its quadrant branches in every target, so all ten run the same arithmetic.

The three HDL targets are simulation-only: they carry the arithmetic in real and quantize only at the port boundary – a logarithm and an arctangent do not belong in a Q16.16 datapath. The cores simulate correctly and are not offered as synthesizable.

Simulink bridge

Import and export, mapped to dspxfrm3/Complex Cepstrum – the DSP System Toolbox block. "Inherit FFT Length" to inheritFFT (on/off, one to one) and "FFT Length" to N.

"Sampling Time (s)" does not cross. dspxfrm3/Complex Cepstrum defines no SampleTime parameter – its dialog is inheritFFT and N alone – and set_param on a parameter a block does not define is a hard error that aborts the whole generated script.

Notes

Stateless and algebraic: the whole transform runs on this sample's frame.
The answer has step decisions in it – each 2π unwrap correction, the rounding of nd, and the angle of a real bin (DC, and Nyquist when n is even) flipping by π when that bin changes sign – so it jumps where an input crosses one of them, which a frame with a bin near zero magnitude does. The three HDL targets quantize their input, and a frame within a quantum of a decision can land on the other side there; that is the input's precision, not the arithmetic's. A frame with one dominant sample keeps every bin away from zero and every decision away from its threshold.
A bin of exactly zero magnitude has log|X| = −∞, and the cepstrum is then not finite, as MATLAB's is not.
The delay nd that rcunwrap removes is not an output, as it is not on the Simulink block; MATLAB's cceps returns it as a second value.

Code facts#

Fact	Value
registered type	`Control_Systems/Transforms/Complex_Cepstrum`
family	`Control_Systems/Transforms`
solver environment class	`ICoreBlock_0_Control_Systems_1_Transforms_2_Complex_Cepstrum`
source	`src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Transforms/Complex_Cepstrum/ICoreBlock_0_Control_Systems_1_Transforms_2_Complex_Cepstrum.cpp`
header	`src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Transforms/Complex_Cepstrum/ICoreBlock_0_Control_Systems_1_Transforms_2_Complex_Cepstrum.h`
default size on canvas	110 × 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`	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
`Inherit FFT Length`	`on%~%off~~on`	`inheritFFT`
`FFT Length`	`64`	`N`

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	`dspxfrm3/Complex Cepstrum`
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
`Inherit FFT Length`	`inheritFFT`	`on` → `on`, `off` → `off`
`FFT Length`	`N`	passes through

Caveat (shown to the user): dspxfrm3/Complex Cepstrum has NO SampleTime parameter - its dialog is inheritFFT and N alone - so "Sampling Time (s)" does not cross. It computes what MATLAB's cceps does (measured against Simulink R2026a: agreement to 6.7e-16 over three FFT-length configurations)

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

Complex Cepstrum block — MATLAB's cceps, and dspxfrm3's Complex Cepstrum y = real( ifft( log|X| + j*rcunwrap(angle(X)) ) ), X = fft(u, n)

rcunwrap is unwrap followed by removing the linear phase that a delay puts on the spectrum: nd = round(phase[nh] / pi) with nh = fix((n+1)/2), and phase[k] -= pi*nd*k/nh. Read out of cceps.m in the installed R2026a, which is also what dspxfrm3/Complex Cepstrum computes: simulated on an 8-point frame, it agrees with cceps exactly.

⚠ ONE CODE PATH IN ALL TEN TARGETS, INCLUDING THE PARTS SOME TARGETS LACK. PLC Structured Text has neither ATAN2 nor FLOOR, so the phase is atan(im/re) plus the quadrant branches, and the round() inside rcunwrap is a bounded counting loop -- in the native solve too, so every software export reproduces this simulation bit for bit rather than to within a libm's atan2.

⚠ THE SIN/COS TABLES ARE EXACT AT THE QUADRANT POINTS. sin(pi) is 1.2e-16 in floating point, so a table built from std::sin gives the Nyquist bin a noise-signed imaginary part -- and angle() of a negative real number is +pi or -pi depending on that sign, which unwrap then carries into every later bin. FFTW's twiddles are exact there, so these are too.

⚠ THE ANSWER HAS STEP DECISIONS IN IT (a 2*pi unwrap correction, the rounding of nd, a real bin's angle flipping by pi when it changes sign), so an input within a quantum of one of them can land differently in the three HDL columns, which quantize the input to Q16.16. Measured: a random sliding frame puts a bin near zero every few hundred samples, and Verilog then scored 75.4 % on ONE sample of a thousand. The parity rigs therefore drive a frame with one dominant tap (cepstrumDominantFrame8() in the rig library), which keeps every bin away from zero; that is a property of the input, and the block's description says so.

Code export: all ten targets. The HDL ones are SIMULATION-ONLY real arithmetic.

Sample results#

8 sample(s) were non-finite (nan/inf) and are absent from the plot; they are in the table below and in the JSON.

t	in ICoreDouble-Out-0	out ICoreDouble-Out-0
0	-2	0.6931
0.4	0.5	-0.6931
0.8	-2	0.6931
1.2	0.5	-0.6931
1.6	-2	0.6931
2	0.5	-0.6931
2.4	-2	0.6931
2.8	0.5	-0.6931
3.2	-2	0.6931
3.6	0.5	-0.6931
4	-2	0.6931
4.4	0.5	-0.6931
4.8	-2	0.6931
5.2	0.5	-0.6931

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)	0 … 0
`ramp`	Ramp: slope 1 from t = 0	-2.303 … 1.775
`sine`	Sine Wave: amplitude 1, 2 rad/s, no phase, no bias	-3.698 … -9.793e-6
`step`	Step: 0 -> 1 at t = 1 s	0 … 0

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 383c0ecf1 · produced by docsSample --out <folder> --blocks Complex_Cepstrum --steps 60 · data docs/generated/samples/Control_Systems__Transforms__Complex_Cepstrum.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).

Complex Cepstrum — Control Systems/Transforms

Description#