vibration.machinery.diagnostics
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
Kinematic fault frequencies of rotating machinery (Norton & Karczub Ch. 8).
Condition monitoring starts with arithmetic, not with signal processing: every rolling-contact bearing, gear pair, induction motor and bladed rotor excites a family of discrete frequencies fixed by its geometry and its shaft speed. Knowing where those lines fall turns a featureless envelope spectrum into a diagnosis, because a peak is only evidence when it sits on a named line.
This module computes the families set out in M. P. Norton and D. G. Karczub,
Fundamentals of Noise and Vibration Analysis for Engineers (2nd ed., CUP
2003), Section 8.4 (8.4.1 gears, 8.4.3 bearings, 8.4.4 fans and blowers,
8.4.7 pumps, 8.4.8 electrical equipment), and hands them to the signal chain
that already exists in phonometry.signals: band-pass the structural
resonance the defect impacts ring, detect its envelope and transform it
(envelope_spectrum), average
synchronously with the shaft
(time_synchronous_average)
or collapse the harmonic families in the cepstrum
(cepstrum). The result object’s
FaultFrequencyResult.plot draws the predicted lines on top of a
measured envelope spectrum, which is the working view.
Rolling-contact bearings (Eqs. 8.4 to 8.14, after Shahan & Kamperman).
With shaft speed N in r/min, Z rolling elements of diameter d on
a pitch diameter D and a contact angle phi, writing
and :
so exactly, and
. Norton notes that
Eqs. (8.8) and (8.14), and (8.9) and (8.13), are identical: BPFO and
BPFI do not depend on which race turns. Only the cage does, and with the
outer race rotating it becomes (Eq. 8.6).
Gears (Eq. 8.3). The gear-meshing (tooth-passing) frequency of a wheel
with n_teeth teeth is , with
integer harmonics. A discrete tooth fault adds shaft-rate lines and low,
flat sidebands around every mesh harmonic; distributed wear raises tall
sideband groups at .
Induction motors (Eqs. 8.19, 8.20). The three lines always present in a
motor bearing signal are fs (mechanical unbalance),
(misalignment with the driven load) and (non-uniform air gap,
torque pulses and the electrical faults). Norton’s Eq. (8.19) writes the
supply frequency as for p magnetic poles, which
is the synchronous, zero-slip form; this module uses the slip-consistent
, identical at and the only
version that makes the rotor-slot harmonics of Eq. (8.20),
collapse to the physical rotor-bar passing rate at
for R rotor bars. Dynamic eccentricity dresses that line
with sidebands at the shaft rate and the slip
frequency.
Fans, blowers and pumps (Eqs. 8.15 to 8.18). The blade-passing frequency
of an impeller with N blades is ; a pump’s
hydraulic pulsations follow the same form with N pumping events per
revolution (Eq. 8.18), and a rotary positive-displacement blower repeats
four times per revolution. In a ducted axial fan the blade-vane interaction
sets up rotating pressure patterns with lobes for
V vanes (Eq. 8.16), turning at r/min
(Eq. 8.17). That is a speed of rotation, not a tone: the noise of every pattern
is at the blade-passing harmonic it comes from (Norton, p. 525), so the
patterns come back as LobePattern records beside the lines of a
BladePassResult, never as lines, and the sign of
is kept, because it is the sense in which the pattern turns. The faster a
pattern turns, the more sound power it radiates, the reason a careful choice of
N and V matters.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
bearing_fault_frequencies
Section titled “bearing_fault_frequencies”bearing_fault_frequencies( speed_rpm: float, n_elements: int | np.integer[Any], element_diameter: float, pitch_diameter: float, *, contact_angle_deg: float = 0.0, rotating_race: Literal['inner', 'outer'] = 'inner',) -> FaultFrequencyResultKinematic frequencies of a rolling-contact bearing (Norton 8.4-8.14).
Returns the seven lines a bearing generates, named with the acronyms used in condition monitoring:
| Name | Meaning | Norton eq. |
|---|---|---|
shaft |
shaft rotational frequency fs |
(8.4) |
FTF |
cage (fundamental train) frequency | (8.5)/(8.6) |
FTF_rel |
cage rotation relative to the rotating race | (8.11)/(8.12) |
BSF |
rolling-element rotational frequency | (8.7) |
BDF |
rolling-element spin frequency, 2 BSF |
(8.10) |
BPFO |
element pass frequency on the outer race | (8.8)/(8.14) |
BPFI |
element pass frequency on the inner race | (8.9)/(8.13) |
BPFO and BPFI are the outer- and inner-race defect lines and
BDF the rolling-element/cage defect line; all three are exact
kinematics of a pure-rolling contact, so a real bearing’s lines wander by
1 % to 2 % with load-dependent slip.
always, and
both are independent of which race turns (Norton’s Eqs. 8.8 and 8.14, and
8.9 and 8.13, are identical); rotating_race only moves the cage.
Parameters
| Name | Description |
|---|---|
speed_rpm |
Shaft speed N, in r/min (> 0). |
n_elements |
Number of rolling elements Z (integer >= 1). |
element_diameter |
Rolling-element diameter d, in the same unit as pitch_diameter (> 0); only the ratio d/D enters. |
pitch_diameter |
Bearing pitch diameter D (> d). |
contact_angle_deg |
Contact angle phi between element and raceway, in degrees (Default: 0, a radial ball bearing); 0 <= phi < 90. |
rotating_race |
Which race turns with the shaft, "inner" (Default) or "outer". |
Returns: A FaultFrequencyResult (source "rolling-contact bearing").
Raises
| Exception | When |
|---|---|
| ValueError | for a non-positive or inconsistent geometry. |
| TypeError | if rotating_race is not a text, contact_angle_deg, element_diameter or pitch_diameter is not a single number, or n_elements is a flag, a text or an array where a count goes. |
blade_pass_frequencies
Section titled “blade_pass_frequencies”blade_pass_frequencies( speed_rpm: float, n_blades: int | np.integer[Any], *, n_harmonics: int | np.integer[Any] = 3, n_vanes: int | np.integer[Any] | None = None, n_lobe_orders: int | np.integer[Any] = 1,) -> BladePassResultBlade-passing frequency and interaction patterns (Norton 8.15-8.17).
for n = 1 .. n_harmonics,
the discrete tone
family of any fan, blower or pump impeller; a rotary positive-displacement
blower repeats four times per revolution, so pass 4 x its speed.
In a ducted axial fan the blades also interact with the stator vanes and
set up rotating pressure patterns with
lobes (Eq. 8.16) turning at
r/min (Eq. 8.17).
Each speed is a rate of rotation and not a tone of its own:
lobes turning at pass a fixed point
times a minute, so the noise of every
pattern is at the blade-passing harmonic it comes from (Norton, p. 525).
The lobe count is what a duct sees, since a pattern can set up a
higher-order duct mode with the same pressure distribution, and the faster
a pattern turns, the more sound power it radiates. Give n_vanes and the
patterns come back in BladePassResult.lobe_patterns, one
LobePattern per (n, k), never among the lines, so neither
plot nor combine_fault_lines marks
one on a spectrum. A negative , which Eq. (8.16) gives
when exceeds , is
a pattern turning against the rotor, and its speed keeps that sign.
Parameters
| Name | Description |
|---|---|
speed_rpm |
Shaft speed N, in r/min (> 0). |
n_blades |
Number of blades (integer >= 1). |
n_harmonics |
Number of blade-pass harmonics (integer >= 1, Default: 3). |
n_vanes |
Number of stator vanes V (integer >= 1) to include the lobed interaction patterns (Default: None, blade tones only and no patterns). |
n_lobe_orders |
Highest |k| in (integer >= 1, Default: 1). |
Returns: A BladePassResult (source "bladed rotor"): the shaft and blade-passing lines, and the lobe patterns apart from them.
Raises
| Exception | When |
|---|---|
| ValueError | for a non-positive or non-integer input. |
| TypeError | if speed_rpm is not a single number, or n_blades, n_harmonics, n_lobe_orders or n_vanes is a flag, a text or an array where a count goes. |
BladePassResult
Section titled “BladePassResult”BladePassResult( *, lines: tuple[FaultLine, ...], shaft_rate: float, source: str, lobe_patterns: tuple[LobePattern, ...] = (),)The blade-passing lines of a bladed rotor and its interaction patterns.
A FaultFrequencyResult whose lines are the shaft rate and the
blade-passing harmonics alone, so that plot,
within and combine_fault_lines treat
it as any other family of lines. The lobe patterns of a ducted fan are
speeds of rotation, not lines, and are held apart in
lobe_patterns: no plot marks them on a spectrum and no merge
carries them as frequencies.
Attributes
| Name | Description |
|---|---|
lobe_patterns |
The LobePattern records of Eqs. (8.16) and (8.17), by blade harmonic, then by , the minus sign first; empty when no vane count was given. |
lines |
The predicted FaultLine entries, in the order the generating function produced them. |
shaft_rate |
Shaft rotational frequency fs, in hertz. |
source |
Description of the element ("rolling-contact bearing", "gear pair", …), used as the plot title. |
combine_fault_lines
Section titled “combine_fault_lines”combine_fault_lines( *results: FaultFrequencyResult, source: str | None = None,) -> FaultFrequencyResultMerge several fault-line families into one overlay.
A gearbox bearing carries its own bearing lines, the mesh family of the
gear it supports and the shaft harmonics; this puts them on one axes.
Duplicate names are disambiguated by appending the source of the family
they came from. Only lines are merged: the lobe patterns of a
BladePassResult are speeds of rotation, not frequencies, and are
not carried into the merged family.
Parameters
| Name | Description |
|---|---|
results |
Two or more FaultFrequencyResult objects. |
source |
Label for the merged family (Default: the sources joined by " + "). |
Returns: A FaultFrequencyResult holding every line.
Raises
| Exception | When |
|---|---|
| ValueError | If no result is given, or the shaft rates disagree. |
FaultFrequencyResult
Section titled “FaultFrequencyResult”FaultFrequencyResult( *, lines: tuple[FaultLine, ...], shaft_rate: float, source: str,)A family of predicted fault lines for one machine element.
Attributes
| Name | Description |
|---|---|
lines |
The predicted FaultLine entries, in the order the generating function produced them. |
shaft_rate |
Shaft rotational frequency fs, in hertz. |
source |
Description of the element ("rolling-contact bearing", "gear pair", …), used as the plot title. |
FaultFrequencyResult.as_dict()
Section titled “FaultFrequencyResult.as_dict()”FaultFrequencyResult.as_dict() -> dict[str, float]The lines as a {name: frequency} mapping.
FaultFrequencyResult.frequencies
Section titled “FaultFrequencyResult.frequencies”property
Predicted frequencies, in hertz, in order.
FaultFrequencyResult.harmonics()
Section titled “FaultFrequencyResult.harmonics()”FaultFrequencyResult.harmonics( name: str, n_harmonics: int | np.integer[Any],) -> NDArray[np.float64]The first n_harmonics integer harmonics of the line called name.
Parameters
| Name | Description |
|---|---|
name |
Line name (see names). |
n_harmonics |
Number of harmonics, (the fundamental first). |
Returns: Frequencies for n = 1 .. n_harmonics, in hertz.
Raises
| Exception | When |
|---|---|
| KeyError | If no line carries that name. |
| ValueError | If n_harmonics is not a positive integer. |
| TypeError | if n_harmonics is a flag, a text or an array where a count goes. |
FaultFrequencyResult.names
Section titled “FaultFrequencyResult.names”property
Names of the predicted lines, in order.
FaultFrequencyResult.orders
Section titled “FaultFrequencyResult.orders”property
Predicted frequencies in shaft orders, in order.
FaultFrequencyResult.plot()
Section titled “FaultFrequencyResult.plot()”FaultFrequencyResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesOverlay the predicted lines on a measured envelope spectrum.
Pass the measurement as spectrum= (an
EnvelopeSpectrumResult, or any
object exposing frequencies and amplitude); without it the
predicted lines are drawn alone as a labelled stem plot.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
language |
Label language, "en" (default) or "es". |
kwargs |
spectrum, max_frequency and anything forwarded to the spectrum curve; see phonometry._plot.vibration.plot_fault_frequencies. |
FaultFrequencyResult.within()
Section titled “FaultFrequencyResult.within()”FaultFrequencyResult.within(low: float, high: float) -> SelfThe lines falling in [low, high] hertz, as a new result.
Handy before plotting on an envelope spectrum whose useful span is much narrower than the highest predicted harmonic.
Parameters
| Name | Description |
|---|---|
low |
Lower edge, in hertz (>= 0). |
high |
Upper edge, in hertz (> low). |
Returns: A result of the same class with the surviving lines, and everything else it holds unchanged.
Raises
| Exception | When |
|---|---|
| ValueError | If the edges are invalid. |
| TypeError | if high or low is not a single number. |
FaultLine
Section titled “FaultLine”FaultLine( *, name: str, frequency: float, order: float, family: Literal['shaft', 'bearing', 'gear', 'motor', 'blade'], description: str,)One predicted discrete line of a machine’s kinematic signature.
Attributes
| Name | Description |
|---|---|
name |
Short label, unique within a result ("BPFO", "2xGMF", "GMF-1x", …). Acronyms are language neutral and are what the FaultFrequencyResult.plot overlay annotates. |
frequency |
Predicted frequency, in hertz. |
order |
Frequency expressed in shaft orders, frequency / fs. |
family |
One of "shaft", "bearing", "gear", "motor" or "blade". |
description |
One-line English description of the mechanism. |
gear_mesh_frequencies
Section titled “gear_mesh_frequencies”gear_mesh_frequencies( speed_rpm: float, n_teeth: int | np.integer[Any], *, n_harmonics: int | np.integer[Any] = 3, n_sidebands: int | np.integer[Any] = 0, sideband_rate: float | None = None,) -> FaultFrequencyResultGear-meshing frequency and its sideband family (Norton Eq. 8.3).
, with integer
harmonics k GMF (k = 1 .. n_harmonics) named "GMF",
"2xGMF", … Each harmonic can carry a
modulation family at k GMF +/- m f_mod (m = 1 .. n_sidebands), named
"GMF-1x", "2xGMF+2x", and so on. The default modulation rate is
the shaft rate of the wheel: a chipped tooth or an eccentric wheel
modulates the mesh once per revolution, which is what produces those
sidebands (Norton Figs. 8.23 and 8.24). Pass sideband_rate to modulate
at the mating wheel’s shaft rate instead.
Only positive sideband frequencies are returned.
Parameters
| Name | Description |
|---|---|
speed_rpm |
Shaft speed N of the wheel, in r/min (> 0). |
n_teeth |
Number of teeth on that wheel (integer >= 1). |
n_harmonics |
Number of mesh harmonics (integer >= 1, Default: 3). |
n_sidebands |
Sideband order per harmonic (integer >= 0, Default: 0, no sidebands). |
sideband_rate |
Modulation rate f_mod, in hertz (> 0, Default: the wheel’s own shaft rate). |
Returns: A FaultFrequencyResult (source "gear pair").
Raises
| Exception | When |
|---|---|
| ValueError | for a non-positive or non-integer input. |
| TypeError | if sideband_rate is not a single number, or n_harmonics, n_sidebands or n_teeth is a flag, a text or an array where a count goes. |
induction_motor_frequencies
Section titled “induction_motor_frequencies”induction_motor_frequencies( speed_rpm: float, n_poles: int | np.integer[Any], n_rotor_bars: int | np.integer[Any], *, slip: float = 0.0, supply_frequency: float | None = None, n_slot_harmonics: int | np.integer[Any] = 1, n_sidebands: int | np.integer[Any] = 0,) -> FaultFrequencyResultElectrical and slot lines of an induction motor (Norton 8.19, 8.20).
The three lines always present in a motor bearing vibration signal are
1x (mechanical unbalance), 2x (misalignment with the driven load)
and 2fe (a non-uniform air gap, torque pulses and the winding/rotor-bar
electrical faults). Rotor defects that produce static or dynamic air-gap
eccentricity are read on the slot harmonics of the stator core,
for R rotor bars, p magnetic poles (not pole pairs), unit slip
s and n = 1, 2, .... Dynamic eccentricity modulates the dominant
slot harmonic at +/- the shaft rate and +/- the slip frequency, which is
what n_sidebands adds around fsh.
Give the slip directly, or give the mains supply_frequency and let it be
derived from fe and the measured shaft speed. The supply frequency is
taken as : Norton’s Eq. (8.19) writes
, which is the same expression at zero slip but
does not reduce Eq. (8.20) to the physical rotor-bar passing rate
R fs when the machine is loaded.
With a non-zero slip the pole-pass line is included as well. That name is standard condition-monitoring practice rather than Norton’s: he gives the slip frequency itself as the sideband spacing of a broken rotor bar (his Section 8.4.8) and does not multiply it by the pole count.
Parameters
| Name | Description |
|---|---|
speed_rpm |
Shaft speed N, in r/min (> 0). |
n_poles |
Number of magnetic poles p (even integer >= 2). |
n_rotor_bars |
Number of rotor bars/slots R (integer >= 1). |
slip |
Unit slip s (0 <= s < 1, Default: 0); typically 0.02 to 0.05 under load. Ignored when supply_frequency is given. |
supply_frequency |
Mains frequency fe, in hertz (> 0), from which the slip is derived (Default: None, use slip). |
n_slot_harmonics |
Number of slot-harmonic orders n (integer >= 1, Default: 1, the fundamental R fs alone). |
n_sidebands |
Sideband order around the fundamental slot harmonic at +/- the shaft rate and +/- the slip frequency (integer >= 0, Default: 0). |
Returns: A FaultFrequencyResult (source "induction motor").
Raises
| Exception | When |
|---|---|
| ValueError | for a non-positive, non-integer or inconsistent input. |
| TypeError | if slip or supply_frequency is not a single number, or n_poles, n_rotor_bars, n_sidebands or n_slot_harmonics is a flag, a text or an array where a count goes. |
LobePattern
Section titled “LobePattern”LobePattern( *, harmonic: int, vane_order: int, n_lobes: int, speed_rpm: float,)One rotating blade-vane interaction pattern of a ducted fan (Norton 8.16-8.17).
The blades of an axial fan pass the stator vanes and set up a rotating pattern of pressure lobes (Eq. 8.16), turning at (Eq. 8.17). That is a speed of rotation, not a frequency: lobes turning times a minute pass a fixed point times a minute, the blade-passing harmonic the pattern comes from, which is where its noise is (Norton, p. 525).
Attributes
| Name | Description |
|---|---|
harmonic |
The blade harmonic the pattern comes from. |
vane_order |
of Eq. (8.16), with its sign (). |
n_lobes |
, with its sign: positive when the pattern turns the way the rotor does, negative when it turns against it. |
speed_rpm |
, the speed at which the pattern turns, in r/min, of the sign of . |
shaft_rate
Section titled “shaft_rate”shaft_rate(speed_rpm: float) -> floatShaft rotational frequency (Norton Eq. 8.4).
Parameters
| Name | Description |
|---|---|
speed_rpm |
Shaft speed N, in r/min (> 0). |
Returns: The shaft rotational frequency , in hertz.
Raises
| Exception | When |
|---|---|
| ValueError | for a non-positive speed. |
| TypeError | if speed_rpm is not a single number. |