Test and measurement
Bode Plot <smart-bode-plot>
BodePlot displays magnitude and phase against a logarithmic frequency axis, one band above the other.
<smart-bode-plot> · 18 properties, 5 methods, 2 events · source/modules/smart.bodeplot.js
Usage in JavaScript
The component is a custom element: its properties are set on the element, its events are DOM CustomEvents with the data in event.detail, and its methods are called on the element. The properties can also be written as attributes in kebab case (precision-digits="1").
const bodePlot = document.querySelector('smart-bode-plot');
bodePlot.showMargins = true;
bodePlot.addEventListener('cursorChange', (event) => console.log(event.detail));
bodePlot.valueAt('value', 42);
Properties
| Property | Type, default | Description |
|---|---|---|
plots | array | Sets or retrieves the responses. Each is an object with id, label, color, lineWidth, visible and either frequencies, magnitude and phase (measured points, magnitude in dB or linear per magnitudeUnit, phase in degrees) or transferFunction ({ numerator, denominator } as polynomial coefficients in s, highest power first). |
frequencyMin | number? | Sets or retrieves the start of the frequency axis. With frequencyMax, fixes the axis and the range a transfer function is evaluated over; null follows the measured points. |
frequencyMax | number? | Sets or retrieves the end of the frequency axis. |
frequencyUnit | 'Hz' | 'rad/s' | Sets or retrieves the unit of the frequency axis. A transfer function is evaluated at s = jω with ω in rad/s either way.Hz rad/s |
magnitudeUnit | 'dB' | 'linear' | Sets or retrieves how measured magnitude is given. Linear values are converted to dB; the plot always shows dB.dB linear |
magnitudeMin | number? | Sets or retrieves the bottom of the magnitude band in dB. Null follows the data. |
magnitudeMax | number? | Sets or retrieves the top of the magnitude band in dB. Null follows the data. |
phaseMin | number? | Sets or retrieves the bottom of the phase band in degrees. Null follows the data. |
phaseMax | number? | Sets or retrieves the top of the phase band in degrees. Null follows the data. |
showMargins | boolean | Marks the gain and phase margins of the first visible response on both bands and writes them out under the plot. A margin at or below zero is marked as failing. The phase margin is measured to the nearest -180° + k·360° line, so it lies between -180° and 180° and is negative for an unstable loop. With several crossings the smallest phase margin and the gain margin closest to 0 dB are shown; margins() lists every crossing. |
showPhase | boolean | Shows the phase band under the magnitude band. |
showGrid | boolean | Shows the grid lines at the decades and the ticks. |
showLegend | boolean | Shows the legend, where a response is hidden and shown. |
cursor | number? | Sets or retrieves the frequency of the cursor, which reads every response. Null hides it. The cursor is placed by clicking the plot, moved with the arrow keys (Shift for larger steps, Home and End for the ends) and cleared with Escape. |
interactive | boolean | Enables placing and moving the cursor with the pointer and the keyboard. |
label | string | Sets or retrieves the title shown above the plot and used in the accessible name. |
precisionDigits | number | Sets or retrieves the number of significant digits in frequencies. |
lineWidth | number | Sets or retrieves the line width of the responses, in pixels. A response can carry its own. |
Methods
| Method | Description |
|---|---|
valueAt(id, frequency) | Returns a response at a frequency as { magnitude, phase } in dB and degrees, interpolated on the log axis, or NaN outside the record.id string The response.frequency number The frequency. |
margins(id?) | Returns the stability margins of a response as { gainMargin, gainMarginFrequency, phaseMargin, phaseMarginFrequency, gainMargins, phaseMargins }, NaN where there is no crossing. The phase margin at a gain crossover is measured to the nearest -180° + k·360° line (between -180° and 180°, negative when the loop is unstable there); the gain margin is read at every frequency where the phase crosses -180° + k·360°. With several crossings, phaseMargin is the smallest phase margin and gainMargin the one closest to 0 dB; gainMargins and phaseMargins list every crossing as { margin, frequency } in ascending frequency.id string The response; the first visible one when omitted. |
evaluate(transferFunction, frequency) | Evaluates a transfer function at a frequency and returns { magnitude, phase } in dB and degrees. The phase is the continuous phase of the response, anchored at its low-frequency asymptote (-90° for each integrator, +90° for each differentiator, -180° more for a negative gain), not an angle folded into -180°..180°.transferFunction object { numerator, denominator } as coefficients in s, highest power first.frequency number In the element's frequency unit. |
togglePlot(id, visible?) | Shows or hides a response.id string The response.visible boolean Shown when true, hidden when false; toggled when omitted. |
describe() | Returns a sentence describing what the plot shows, as used in its accessible name, with the margins when they are shown. |
Events
The data of an event is in event.detail. The Bode plot moves cursor as the operator drags or presses an arrow key, only while interactive is true, and then raises cursorChange. plotVisibilityChange follows a legend click or a togglePlot() call after the response is already shown or hidden.
| Event | Description and detail |
|---|---|
cursorChange | This event is triggered when the cursor is placed or moved by the operator.frequency number The cursor frequency. |
plotVisibilityChange | This event is triggered when a response is hidden or shown from the legend.id string The response.visible boolean Whether it is now shown. |
Types
type BodePlotFrequencyUnit
'Hz' | 'rad/s'
type BodePlotMagnitudeUnit
'dB' | 'linear'
CSS variables
The component declares 4 CSS variables; the CSS page shows how to set them.
--smart-bode-height --smart-bode-plot-background --smart-bode-grid-color --smart-bode-axis-color