assess_severity
Assess vibration severity using ISO 20816-3 zones A-D and derive alert levels from machine vibration data. Enter a signal ID or RMS velocity to get zone, severity, and threshold exceedance.
Instructions
Assess vibration severity (ISO 20816-3 zones A-D) and alert level.
THE unified severity tool: ISO zone assessment and alert
classification in one call. Zone boundary values are those of
ISO 10816-3:2009 (ISO 20816-3:2022 merges zones A/B — provenance is
noted in the result). Scope: machines rated above 15 kW; a declared
machine_power_kw below 15 kW is refused.
Input routes (exactly ONE required):
- signal_id: a stored signal (load_signal first). Sampling rate AND
declared unit come from the stored metadata; an undeclared unit is
refused, never guessed from amplitude.
- rms_velocity_mm_s: a direct broadband RMS velocity reading in mm/s
(e.g. from a portable instrument) — no unit declaration needed.
Args:
ctx: MCP context. Unused — see this module's docstring on logging.
signal_id: ID of the stored signal (mutually exclusive with
rms_velocity_mm_s).
rms_velocity_mm_s: Direct broadband RMS velocity in mm/s
(mutually exclusive with signal_id).
machine_group: 1 (large, >300 kW) or 2 (medium, 15-300 kW).
Ignored when custom thresholds are given. Default 2.
support_type: 'rigid' or 'flexible'. Ignored when custom
thresholds are given. Default 'rigid'.
thresholds: Optional custom zone boundaries {'warning': A/B,
'alarm': B/C, 'danger': C/D} in mm/s, strictly increasing —
replaces the ISO table for this call.
machine_power_kw: Rated machine power, if known. Declared values
below 15 kW are refused (out of ISO scope); None means
unknown and is not refused.
rpm: Operating speed in RPM (signal route only: selects the 2 Hz
band lower edge below 600 RPM).
Returns:
VibrationSeverityResult (status='assessed') with zone, severity,
boundaries, derived alert_level/exceeded_threshold, and threshold
provenance.
Raises:
ValueError: On route misuse (both/neither inputs), undeclared
signal unit, missing sampling rate, Nyquist below the ISO
band, declared power below 15 kW, negative RMS, or invalid
custom thresholds.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rpm | No | ||
| signal_id | No | ||
| thresholds | No | ||
| support_type | No | rigid | |
| machine_group | No | ||
| machine_power_kw | No | ||
| rms_velocity_mm_s | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | Measurement axis (informational) | vertical |
| zone | Yes | ISO zone: A, B, C, or D | |
| status | No | Always 'assessed' — discriminates from a refused result | assessed |
| signal_id | No | Signal identifier used (None for a direct rms_velocity_mm_s reading) | |
| boundaries | Yes | Zone boundaries {AB, BC, CD} in mm/s (ISO or custom) | |
| color_code | Yes | green, yellow, orange, or red | |
| alert_level | No | Alert level derived from the zone: A=none, B=warning, C=alarm, D=danger (filled automatically) | |
| support_type | Yes | Support type: 'rigid' or 'flexible' | |
| machine_group | Yes | ISO 20816-3 machine group: 1 (large, >300 kW) or 2 (medium, 15-300 kW) | |
| original_unit | No | Original signal unit before conversion | |
| severity_level | Yes | Good, Acceptable, Unsatisfactory, or Unacceptable | |
| frequency_range | Yes | Actual evaluation band used (may be narrower than the ISO nominal 10-1000 Hz when fs limits it); 'not applicable' for direct RMS readings | |
| machine_power_kw | No | Declared rated machine power in kW, when provided. Values below 15 kW are refused as out of ISO 20816-3 scope. | |
| zone_description | Yes | Zone description | |
| rms_velocity_mm_s | Yes | RMS velocity in mm/s | |
| exceeded_threshold | No | The boundary (mm/s) exceeded by the reading (None in zone A; filled automatically from zone + boundaries) | |
| operating_speed_rpm | No | Operating speed in RPM, when provided (selects the band's lower edge) | |
| threshold_provenance | Yes | Provenance of the zone boundary values (ISO edition note, or custom-threshold note) | |
| unit_conversion_performed | Yes | Whether acceleration-to-velocity conversion was done |