Generated reference › Instantaneous Bandwidth — Control Systems/Spectral Measurements
kind: generated#block#control-systems-spectral-measurements

Instantaneous Bandwidth — Control Systems/Spectral Measurements

Control_Systems/Spectral_Measurements/Instantaneous_Bandwidth · 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.

Instantaneous Bandwidth

Control Systems / Spectral Measurements

The second central moment of a power spectral density – how widely its mass is spread about its own centre – scaled by a constant:

b = s·√(Σk(fk − f̄)²·Pk ÷ ΣkPk), with f̄ = Σkfk·Pk ÷ ΣkPk

This is MATLAB's instbw given a time-frequency distribution, and Mean Frequency is the first moment of the same spectrum – the two are the centre and the width of one distribution. The block is three weighted sums, two divisions and a square root: no branch and nothing carried between samples.

Ports

  • p – the power spectral density, one nonnegative value per bin. A vector, either an [N,1] column or a [1,N] row, with N between 2 and 256. Bin k is the frequency k·Δ.
  • b – the bandwidth, in the same units as Bin Spacing times Scale Factor. Always scalar, whatever the input's length.

Parameters

  • Bin Spacing – Δ, the frequency step between neighbouring bins, a positive number. Left at 1 the answer comes out in bins; set it to fs÷(2·(N−1)) for a one-sided spectrum reaching the Nyquist frequency and the answer comes out in Hz.
  • Integration Range – which bins the moments are taken over:
    • Full spectrum – every bin. This is instbw(P, F, T), and it is the default.
    • Frequency band – only the bins inside the band. This is instbw(..., 'FrequencyLimits', [flo fhi]).
  • Frequency Band – [flo fhi], a two element vector in the same units as Bin Spacing, read only in Frequency band mode. The band is narrowed to the bins it contains: a bin counts when flo ≤ fk ≤ fhi, which is instbw's own rule and Mean Frequency's. Band Power snaps the other way – see Notes.
  • Scale Factor – s, a positive number the moment is multiplied by. The default 3.5449077018110318 is 2·√π, which is instbw's own default, measured rather than read off a page. Set it to 1 for the plain standard deviation of the spectrum.
  • Epsilon – ε, added to the total power before each division. It is what makes an all-zero band return 0 instead of a NaN – a degeneracy guard, not an accuracy knob, so the default is 1e−30: far below any total power a real spectrum carries, and small enough not to move the answer.
  • 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.

All three weight vectors are structural and are inlined into the arithmetic at export time rather than exposed as tunable parameters – they follow from the bin spacing, the bin count and the band, and changing any of them changes how many multiplies the core contains, which no runtime parameter can do. Scale Factor and Epsilon are inlined too. Re-export after changing any of them.

The three HDL targets are simulation-only: the block divides twice and takes a square root, and neither belongs in this tree's Q16.16 fixed-point base. They compute in real and quantize only at the port boundary, so they simulate correctly and are not offered as synthesizable.

Simulink bridge

No equivalent (Support::None). Signal Processing Toolbox ships no Simulink library at all, and instbw is one of its MATLAB functions. The bridge reports this block rather than dropping it silently, and it therefore has no parity testbench. Code export verification covers it across all ten languages.

Notes

  • Stateless. The answer depends on this sample's spectrum and nothing else, so there is no startup transient and no history to seed.
  • ⚠ This is not the Spread that Spectral Features reports. That one weights by the magnitude spectrum and centres on its own magnitude centroid; this one weights by power. On the same data the two differ in the first decimal – 2.0637 against 1.5146, from centroids 4.1603 and 4.0643 – so they are different statistics of one signal rather than two spellings of one.
  • ⚠ The emitted form is the raw-moment identity, and it costs a cancellation. f̄ is not known until the spectrum arrives, so a centred sum would need it inside every term; the block emits (A − (B÷D)·B) ÷ D with A = Σf²P, B = ΣfP and D = ΣP + ε instead, which is three sums rather than one sum per bin. Measured on an eight-bin spectrum the two forms differ by 5.3e−15 on a moment of 2.294. The error grows when the spread is small against the centre frequency: a spectrum concentrated in one bin of a high-frequency axis is where to be careful.
  • The moment is taken through an absolute value before the square root. The identity above can land a hair below zero when the spread is at the edge of what the arithmetic can resolve, and a negative under a square root is an error in several of the ten targets rather than a NaN. Taking the magnitude of a quantity that cannot truly be negative removes the question without a branch.
  • The band is narrowed, not widened – and Band Power does the opposite. This block keeps the bins inside the band, as instbw and Mean Frequency do; Band Power keeps the bins that bracket it.
  • An all-zero band answers 0, where MATLAB answers NaN. That is the deliberate divergence Epsilon exists for, and it is the same one Mean Frequency makes for the same reason.
  • No state space. A ratio of weighted sums is not linear in the input, so there is no A/B/C/D pair and model reduction correctly declines to merge the block.

Code facts#

FactValue
registered typeControl_Systems/Spectral_Measurements/Instantaneous_Bandwidth
familyControl_Systems/Spectral_Measurements
solver environment classICoreBlock_0_Control_Systems_1_Spectral_Measurements_2_Instantaneous_Bandwidth
sourcesrc/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Spectral_Measurements/Instantaneous_Bandwidth/ICoreBlock_0_Control_Systems_1_Spectral_Measurements_2_Instantaneous_Bandwidth.cpp
headersrc/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Spectral_Measurements/Instantaneous_Bandwidth/ICoreBlock_0_Control_Systems_1_Spectral_Measurements_2_Instantaneous_Bandwidth.h
default size on canvas146 × 72 px
ports at insert1 in, 1 out
code generators implementedPython, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text

Ports#

#DirectionSignal typeDescription label
1inICoreDoublep
2outICoreDoubleb

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 variableDefaultSimulink parameter
Bin Spacing1—
Integration RangeFull spectrum%~%Frequency band~~Full spectrum—
Frequency Band[0 1]—
Scale FactoribFmt(DEFAULT_SCALE)—
Epsilon1e-30—

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.

supportSupport::None
Simulink path—
port-count rulePortsParam::None
SampleTime parameteryes

Caveat (shown to the user): no Simulink equivalent: instbw() is a MATLAB function and Signal Processing Toolbox ships no Simulink library at all. Reported rather than dropped, and it carries no parity testbench

Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h

Description vs code#

The checker has a blind spot here — it could not resolve something (a grouped port bullet, a computed config name), which is reported and never counted as a pass. A reader has to settle it:

  • B0 every stimulus in the sample errored — cross-checks skipped

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

Instantaneous Bandwidth -- the second central moment of a power spectral density, scaled b = s * sqrt( SUM_k (f_k - fbar)^2 * P_k / SUM_k P_k ), fbar = SUM f_k*P_k / SUM P_k

MATLAB's instbw given a time-frequency distribution, and every part of that claim was measured on R2026a before a line was written. On the eight-bin spectrum [0.1 0.4 1.7 3.2 2.1 0.9 0.3 0.05] at a bin spacing of 1.25:

  • instbw at ScaleFactor 1 answers 1.5146226040347679 and the moment above is

1.5146226040347677 -- a difference of 2.2e-16.

  • Its DEFAULT scale factor is 2*sqrt(pi) EXACTLY: the ratio comes out

3.5449077018110784 here and 3.5449077018107267 on a second, different spectrum, against 3.5449077018110318. That is thirteen digits on two inputs, which is what makes it a constant rather than a coincidence.

  • Its FrequencyLimits narrows INWARD -- the bins with flo <= f_k <= fhi -- which is

the same rule Mean_Frequency follows and the opposite of Band_Power's.

⚠ THE SIBLING ROW IS NOT A BLOCK, AND THE SAME MEASUREMENT IS WHAT SAYS SO. instfreq on the same input is the FIRST moment, which Spectral_Measurements/Mean_Frequency already computes: instfreq, meanfreq and that block agree to 1.8e-15 on this spectrum. The board's Instantaneous Frequency row is therefore covered under rule 4 and closed, and this one is not.

⚠ NOR DOES Machine_Learning/Feature_Engineering/Spectral_Features COVER IT. Its Spread weights by the MAGNITUDE spectrum and centres on its own magnitude centroid; this weights by POWER. On the same data: spread 2.0637 against 1.5146, centroid 4.1603 against 4.0643. Two different statistics of one signal.

⚠ AND THE EMITTED FORM IS THE RAW-MOMENT IDENTITY, NOT THE TEXTBOOK ONE, because fbar is not known until the spectrum arrives and a centred sum would need it inside every term -- which in VHDL means repeating both sums once per bin. The identity

SUM (f-fbar)^2 P / SUM P == (A - (B/D)*B) / D, A = SUM f^2 P, B = SUM f P, D = SUM P

keeps it to three sums. It costs a cancellation: measured on the spectrum above the two forms differ by 5.3e-15 on a moment of 2.294, which is 2.3e-15 relative. That is the price, it is quoted rather than hidden, and it grows when the spread is small against the centre frequency -- a spectrum concentrated in one bin of a high-frequency axis is where to be careful.

Sample results#

No stimulus produced a sampled output in this rig — Invalid input size at: ICore Blocks/Home/Instantaneous Bandwidth. That is a fact about the single-block rig, not a verdict on the block: an offline batch fit, a block whose output only appears at onSolverFinish, or one that needs a driven environment cannot be exercised alone.

Category unsampled · sample time 0.1 · 60 steps · commit 34944baa9199c75506097cae40f12e8f305f3dc7 · produced by docsSample --out <folder> --blocks Instantaneous_Bandwidth --steps 60

Sample data: docs/generated/samples/Control_Systems__Spectral_Measurements__Instantaneous_Bandwidth.json