Ir al contenido

vibration: impact mobility

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.

Every name on this page is published by phonometry.vibration: from phonometry import vibration, then vibration.<name>.

Mechanical mobility measured by impact excitation (ISO 7626-5:2019).

ISO 7626-5 measures the same frequency-response functions as ISO 7626-2, but excites the structure with a hammer or another impactor that is not attached to it. Each record holds one impact and the free decay it leaves behind, and that shape is what the part is about: the force occupies a small fraction of the record, so the noise around it matters (8.5.1); the response may not have died away by the end of the record, so the spectrum leaks (8.3, 8.5.2); a second impact inside the record cuts notches into the force spectrum (6.4); and the averaging runs over impacts rather than over segments of one long record (8.6). This module holds those pieces and reuses the FRF machinery of .mechanical_mobility for the rest.

Spectra. The records are sampled at fs and transformed with the discrete Fourier transform scaled by the sampling interval, , which for a transient wholly inside the record samples its continuous Fourier transform (8.3). The force energy spectral density is , in N²·s/Hz: the power spectral density of 3.3, , multiplied by the record length as 3.4 prescribes.

Averaging (8.6). Over impacts at one point the estimate is the averaged cross-spectrum of response and force divided by the averaged auto-spectrum of the force,

with the ordinary coherence of 9.1 beside it. The FRF comes out in the kind of the response channel (accelerance, mobility or dynamic compliance) and is converted to mobility with .convert_frf.

Windows (8.5). The force window has unity gain over the part of the record that holds the force pulse and its filter response and sets the rest to exactly zero (8.5.1). The exponential window starts at unity and adds a known decay to the data (8.3 a), 8.5.2). Applied to force and response alike, it replaces every pole of the impulse response by (Annex A, Formula (A.2)), so a mode appears more damped than it is, and Formula (A.3) takes the added damping away again:

with the damping ratio estimated from the windowed data and the damped natural frequency in rad/s. The corrected mobility is synthesized from the corrected modes, and for a lightly damped, well separated mode the measured peak is multiplied by . Annex A leaves the damping estimator open; single_mode_fit is the one this library offers, a rational-fraction fit of one mode over a band.

Formula (A.3) is the first-order form of the pole shift the annex states in words. The synthesis here moves the pole itself, which is exact, and the correction reports both: ExponentialWindowCorrection.damping_ratio is (A.3) as printed and ExponentialWindowCorrection.exact_damping_ratio is the damping of the shifted pole; they differ by about .

Records. Every function that takes a record takes a bare array with its sample rate, or a Signal, which brings its own rate (an explicit fs that disagrees is refused). A calibration factor the Signal carries is deliberately not applied: the records of this part are forces in newtons and motions in m/s², m/s or m, not pressures. The checks hand the samples they judged back as bare arrays, in the unit they arrived in.

Checks. Every record check returns a verdict object with passes: check_double_hit (6.4), check_force_spectrum (6.2, 6.3), check_overload (8.4), check_response_decay (8.3, 8.5.2) and check_coherence (9.1); verify_channel_match judges the channel-to-channel match of the analyser (8.1). The operational calibration of 7.2 is the rigid-mass check of ISO 7626-2:2015, 7.5.2, which 7.2 calls essentially the same procedure: .verify_rigid_mass_calibration.

The part prints no worked example, so the implementation is anchored in closed form: a single-degree-of-freedom structure struck by a smooth pulse gives its mobility back from the averaged estimate, and its damping and mobility back after exponential windowing and the Annex A correction.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

Constant (float).

CHANNEL_MAGNITUDE_TOLERANCE = 0.05

Constant (float).

CHANNEL_PHASE_TOLERANCE_DEG = 5.0
ChannelMatchVerification(
frequencies: NDArray[np.float64],
response: NDArray[np.complex128],
)

Do two analyser channels match in gain and phase? (8.1)

The channel-to-channel match of the filters and the analyser is checked by connecting one broad-band signal to both channels and measuring the frequency response between them: its magnitude should equal unity within +/- 5 % over the frequency range of interest and its phase zero within +/- 5 degrees (8.1).

Attributes

Name Description
frequencies Frequencies in the range of interest, in hertz.
response Complex frequency response between the channels.

ChannelMatchVerification.magnitude_deviation

Section titled “ChannelMatchVerification.magnitude_deviation”

property

Relative deviation of the magnitude from unity, |H| - 1.

property

Per frequency, whether the magnitude is within +/- 5 % of unity.

The magnitude is compared with the bounds 1 - 0,05 and 1 + 0,05 themselves, so a response of exactly 0.95 or 1.05 is within them.

property

Whether both requirements hold at every frequency.

property

Phase of the response, in degrees.

property

Per frequency, whether the phase is within +/- 5 degrees of zero.

ChannelMatchVerification.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
ChannelMatchVerification.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the magnitude and phase deviations against their tolerances.

With no ax a two-panel figure is drawn; with ax only the magnitude deviation.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the magnitude-deviation curve.

Returns: The axes, or the tuple of two axes.

check_coherence(
result: ImpactMobilityResult,
*,
frequency_range_hz: tuple[float, float],
exclude_hz: Sequence[tuple[float, float]] = (),
min_coherence: float = 0.9,
min_n_records: int | np.integer[Any] = 5,
) -> CoherenceCheck

Is the averaged estimate’s coherence high over the range of interest? (9.1)

The check passes when the coherence exceeds min_coherence (0.9, what 9.1 calls high) at every frequency of the range that is not excluded, and at least min_n_records impacts were averaged (five, the lower end of the five to ten 9.1 says a high coherence needs). A single impact has a coherence of 1 by construction and fails the second condition.

8.6 finds three to five impacts usually enough to verify data quality in a low-noise environment; the coherence estimate itself, 9.1 adds, needs five to ten records to be trusted. Averaging five impacts satisfies both, and a lower min_n_records states that fewer were judged enough.

Parameters

Name Description
result The averaged estimate, from impact_mobility.
frequency_range_hz (f_low, f_high), in hertz.
exclude_hz Bands (f_low, f_high) to leave out of the verdict, such as anti-resonances (9.1, NOTE 1) (Default: none).
min_coherence The coherence to exceed (Default: 0.9).
min_n_records The fewest impacts to accept, a whole number of at least 1 (Default: 5).

Returns: A CoherenceCheck.

Raises

Exception When
ValueError for an invalid range, exclusion or limit, a min_n_records that is not a whole number of at least 1, or exclusions that leave no frequency of the range to judge.
TypeError if min_coherence is not a single number, min_n_records is a flag, a text or an array where a count goes, or frequency_range_hz is not a pair of numbers.
check_double_hit(
force_n: Signal | NumericArrayLike,
fs: float | None = None,
*,
threshold_ratio: float = 0.1,
) -> DoubleHitCheck

Does the force record hold one impact, or a double hit? (6.4)

An impact is a run of samples whose force exceeds threshold_ratio times the largest force in the record, in the direction of that largest force; the check passes when there is exactly one. Run it on the unwindowed, and preferably unfiltered, force: 6.4 recommends watching the unfiltered signal so the anti-aliasing filter does not hide a secondary impact in the ringing of the primary one, and forbids using a force window to remove one.

The threshold is this library’s, not the part’s, which only says that a small second impact shows as a slight ripple and that moderate dips may be tolerated. At the default of 0.1 an undetected second pulse of the same shape as the first ripples the force spectrum by at most dB peak to notch (DoubleHitCheck.ripple_db). A softer, longer rebound, the usual hammer bounce, carries more of the low-frequency spectrum than its peak says: it can stay under the threshold and still ripple the spectrum by several decibels. That is why 6.4 finds multiple impacts most easily in the frequency domain, which check_force_spectrum reads.

A filtered record has a limit of its own. When the spectrum of the pulse reaches the cut-off of the anti-aliasing filter, the ringing the filter leaves after the pulse can itself rise above the threshold, most of all with a steep elliptic or Chebyshev filter, and a single impact then reads as several. The unfiltered force avoids both effects.

Parameters

Name Description
force_n One force record, 1-D, in N. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this record is a force in newtons and not a pressure.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
threshold_ratio Fraction of the largest force an excursion must exceed to count as an impact, in (0, 1) (Default: 0.1).

Returns: A DoubleHitCheck.

Raises

Exception When
ValueError for a record that is not 1-D and finite, a non-positive sample rate, a threshold outside (0, 1), or a record with no force in it.
TypeError if threshold_ratio is not a single number.
check_force_spectrum(
force_n: Signal | NumericArrayLike,
fs: float | None = None,
*,
frequency_range_hz: tuple[float, float],
max_drop_db: float,
) -> ForceSpectrumCheck

Is the force spectrum flat enough across the frequency range of interest?

Computes the energy spectral density of one force record (3.3, 3.4) and reads how far it falls between its highest and lowest value inside the range. The check passes when that fall is at most max_drop_db. The part gives no number for it, so the caller states the one their practice uses; the share of force energy above the range, which 6.3 asks to keep small, is reported beside it as ForceSpectrumCheck.energy_fraction_above.

Parameters

Name Description
force_n One force record, 1-D, in N (windowed or not, as it will be processed). Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this record is a force in newtons and not a pressure.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
frequency_range_hz (f_low, f_high), the frequency range of interest, in hertz.
max_drop_db The largest fall across the range to accept, in dB.

Returns: A ForceSpectrumCheck.

Raises

Exception When
ValueError for an invalid record, sample rate, range or limit.
TypeError if frequency_range_hz is not a pair of numbers, or fs or max_drop_db is not a single number.
check_overload(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
full_scale: float,
) -> OverloadCheck

Did one channel of the record stay below its full scale? (8.4)

Parameters

Name Description
x One record, 1-D, in any unit. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, so the samples stay in the unit the channel recorded them in, the unit of its full scale.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
full_scale The manufacturer’s maximum for linear operation, in the unit of the record.

Returns: An OverloadCheck, which passes when every sample stays strictly below the full scale.

Raises

Exception When
ValueError for an invalid record, sample rate or full scale.
TypeError if full_scale is not a single number.
check_response_decay(
response: Signal | NumericArrayLike,
fs: float | None = None,
*,
exponential_window: bool = False,
segment_s: float | None = None,
start_s: float = 0.0,
force_n: Signal | NumericArrayLike | None = None,
) -> ResponseDecayCheck

Has the response decayed enough by the end of the record? (8.3, 8.5.2)

Without an exponential window the response should end at about 1 % of its highest peak (8.3, 8.5.2); with one, its natural decay should reach 25 % or less, the general guideline of 8.5.2. The level at the end is read at the last sample and compared with the figure to a whole per cent, so any level below 1.5 % passes “about 1 %” (see ResponseDecayCheck). 8.3 calls the 1 % a compromise, and the check is one-sided: it asks whether the response has decayed far enough, not whether it decayed too far. Pass the response as recorded, before any window.

Parameters

Name Description
response One response record, 1-D, in any unit. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this record is a motion and not a pressure.
fs Sample rate, in Hz. Required when the records are bare arrays; a Signal brings its own, and an explicit value, or a force Signal, that disagrees with it raises instead of silently winning.
exponential_window Whether the record is to be processed with an exponential window (Default: False).
segment_s Length of the segments the levels are read over, in seconds; make it at least one period of the lowest mode (Default: None, one tenth of the record).
start_s Time from which the highest peak is sought, in seconds (Default: 0, the whole record, as the clause reads).
force_n The force record of the same impact, same length (Default: None). When given, the highest peak is sought only after the force pulse, where the force has fallen back to 1 % of its peak, so a driving-point acceleration is judged on its free decay and not on the impact it follows (the mass line). The later of this and start_s is used. A Signal likewise, its factor not applied.

Returns: A ResponseDecayCheck.

Raises

Exception When
ValueError for an invalid record, sample rate, segment or start, a response that is zero at every sample or at every sample from the start on (a dead channel has measured nothing, so it has not decayed either), or a force record of another length, without force or whose pulse does not end inside the record.
TypeError if segment_s or start_s is not a single number.

Constant (int).

COHERENCE_RECORDS = 5
CoherenceCheck(
frequencies: NDArray[np.float64],
coherence: NDArray[np.float64],
judged: NDArray[np.bool_],
*,
n_impacts: int,
min_coherence: float = 0.9,
min_n_records: int = 5,
)

Is the coherence high, over enough impacts to trust it? (9.1)

The coherence expresses how linearly the response follows the force at each frequency; a value below 1 flags possible poor data (9.1). The clause calls a coherence above 0.9 high, and says only a few records, five to ten, are then needed for high statistical confidence in its estimate. NOTE 1 adds that low coherence at an anti-resonance is not generally a concern: the response is near the noise floor there. Such frequencies can be excluded from the judgement.

Attributes

Name Description
frequencies Frequencies in the range of interest, in hertz.
coherence Ordinary coherence at each.
judged Per frequency, whether it enters the verdict (False where excluded as an anti-resonance).
n_impacts Number of impacts averaged.
min_coherence The coherence each judged frequency must exceed.
min_n_records The fewest impacts the check accepts.

property

Whether enough impacts were averaged for the coherence to be trusted.

property

Per frequency, whether the coherence exceeds the minimum.

property

Whether every judged frequency is high and the records are enough.

CoherenceCheck.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the coherence against its minimum, excluded frequencies shaded.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the coherence curve.

Returns: The axes.

property

Normalized random error of the FRF magnitude, in percent (ISO 7626-2 Annex A).

NaN where the coherence is zero.

DoubleHitCheck(
force_n: NDArray[np.float64],
fs: float,
impact_indices: NDArray[np.intp],
*,
threshold_ratio: float,
)

Was there more than one impact in the force record? (ISO 7626-5, 6.4)

If more than a single impact occurs within the record, the Fourier transforms of the pulses tend to cancel at certain frequencies and cut sharp notches into the force spectrum (Figure 5), where the low signal-to-noise ratio spoils the mobility. For two pulses of the same shape, the second times the first and later, the spectrum is the single pulse’s times : it ripples with a period of in frequency between and , so the notches are deep only when the second impact is about as strong as the first. That is why 6.4 says a small second impact shows as a slight ripple, and why moderate dips “may normally be tolerated”.

Attributes

Name Description
force_n The force record judged, in N, as a bare array (a Signal passed in is read without its calibration factor, and its samples are what is kept).
fs Its sample rate, in Hz.
impact_indices Sample index of the peak of every impact found, in time order; the first entry is not necessarily the largest.
threshold_ratio The fraction of the largest peak an excursion had to exceed to count as an impact.

property

Time from the primary impact to the largest secondary one, in s.

None for a single impact.

property

Force at the peak of every impact, in N.

property

Time of the peak of every impact, in seconds.

property

How many impacts the record holds.

property

Spacing of the notches the two largest impacts cut, .

None for a single impact.

property

Whether the record holds a single impact.

DoubleHitCheck.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
DoubleHitCheck.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the force record with its impacts, and its energy spectral density.

With no ax a two-panel figure is drawn: the time history with every impact marked, and the energy spectral density with the notches the two largest impacts cut (Figure 5). With ax only the time history is drawn on it.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the force curve.

Returns: The axes, or the tuple of two axes.

property

Peak-to-notch ripple of the force spectrum, in dB.

for a secondary impact r times the primary one, the same shape and the only other; 0 dB for a single impact and infinite for two equal ones, whose notches go to zero.

property

Largest secondary peak over the primary one (0 for a single impact).

property

Time of every sample of the record, in seconds.

energy_spectral_density(
x: Signal | NumericArrayLike,
fs: float | None = None,
) -> EnergySpectralDensity

One-sided energy spectral density of a transient record (3.3, 3.4).

, with the discrete Fourier transform scaled by the sampling interval: the power spectral density of 3.3, , multiplied by the record length as 3.4 prescribes for a transient wholly inside the record. For a force in newtons the unit is N²·s/Hz, the unit of Figures 3, 4, 5, 7 and 8. The DC bin and, for an even record, the Nyquist bin are not doubled.

Parameters

Name Description
x One record, 1-D. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is not applied.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.

Returns: The DFT bin frequencies from 0 Hz to the Nyquist frequency, in hertz, and the density at each, in the record’s unit squared times s/Hz, as an EnergySpectralDensity.

Raises

Exception When
ValueError for a record that is not 1-D and finite, or a non-positive sample rate.
EnergySpectralDensity(
frequencies: NDArray[np.float64],
density: NDArray[np.float64],
)

The one-sided energy spectral density of a transient record (3.3, 3.4).

What energy_spectral_density returns: the bins and the density, named, where a (frequencies, esd) tuple used to be unpacked by position.

Attributes

Name Description
frequencies The DFT bin frequencies from 0 Hz to the Nyquist frequency, in hertz.
density The energy spectral density at each, in the record’s unit squared times s/Hz.
EnergySpectralDensity.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the density in dB re its highest bin against frequency.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the density curve.

Returns: The axes.

exponential_decay_rate(
n_samples: int | np.integer[Any],
fs: float,
*,
final_value: float,
) -> float

The decay rate of an exponential window that ends the record at a value.

8.5.2 describes an exponential window by the value it decays to at the end of the record: Figure 10 uses one that decays to 5 % of its initial value. The end of the record is its last sample, at , so and exponential_window(n_samples, fs, decay_rate_per_s=a)[-1] is final_value.

Parameters

Name Description
n_samples Record length N, in samples.
fs Sample rate, in Hz.
final_value Window value at the last sample, in (0, 1] (dimensionless; 0.05 for the window of Figure 10).

Returns: The decay rate a, in 1/s.

Raises

Exception When
ValueError for fewer than 16 samples, a non-positive sample rate or a final value outside (0, 1].
TypeError if final_value or fs is not a single number, or n_samples is a flag, a text or an array where a count goes.
exponential_window(
n_samples: int | np.integer[Any],
fs: float,
*,
decay_rate_per_s: float,
) -> NDArray[np.float64]

The exponential window of 8.5.2: .

The window has an initial value of unity at the start of the record and decreases exponentially towards its end, adding a known amount of artificial decay to the data (8.3 a), 8.5.2). Applied to force and response alike it moves every pole of the impulse response by -a (Annex A, Formula (A.2)); exponential_window_correction takes the added damping away again.

Parameters

Name Description
n_samples Record length N, in samples.
fs Sample rate, in Hz.
decay_rate_per_s Decay rate a, in 1/s (>= 0; 0 is no window). exponential_decay_rate finds the rate that ends the record at a stated value.

Returns: The window, one value per sample, .

Raises

Exception When
ValueError for fewer than 16 samples, a non-positive sample rate or a negative decay rate.
TypeError if decay_rate_per_s or fs is not a single number, or n_samples is a flag, a text or an array where a count goes.
exponential_window_correction(
apparent_damping_ratio: NumericArrayLike,
*,
damped_natural_frequency_hz: NumericArrayLike,
exponential_decay_rate_per_s: float,
) -> ExponentialWindowCorrection

Remove an exponential window’s damping from estimated modes (Formula (A.3)).

for each mode, with the damped natural frequency. Estimate from the windowed data with any curve fitter (Annex A leaves the method open; single_mode_fit is one).

Parameters

Name Description
apparent_damping_ratio Damping ratio estimated from the windowed data, per mode, in (0, 1).
damped_natural_frequency_hz Damped natural frequency of each mode, in hertz (scalar or 1-D, the shape of apparent_damping_ratio).
exponential_decay_rate_per_s Decay rate a of the window, in 1/s.

Returns: An ExponentialWindowCorrection.

Raises

Exception When
ValueError for mismatched or invalid inputs, or a window whose damping reaches a mode’s apparent damping.
TypeError if apparent_damping_ratio or damped_natural_frequency_hz holds a text or a value that is not a real number, or exponential_decay_rate_per_s is not a single number.
ExponentialWindowCorrection(
damped_natural_frequency_hz: NDArray[np.float64],
apparent_damping_ratio: NDArray[np.float64],
*,
exponential_decay_rate_per_s: float,
)

The damping an exponential window added, taken away (Annex A).

Formula (A.3), , per mode, with the damping ratio estimated from the windowed data, the window’s decay rate and the damped natural frequency in rad/s. For a lightly damped, well separated mode the measured peak is multiplied by to give the true one.

Attributes

Name Description
damped_natural_frequency_hz Damped natural frequency of each mode, , in hertz.
apparent_damping_ratio Damping ratio of each mode estimated from the windowed data, .
exponential_decay_rate_per_s The window’s decay rate a, in 1/s.

property

True damping ratio of each mode, Formula (A.3): .

ExponentialWindowCorrection.exact_damping_ratio

Section titled “ExponentialWindowCorrection.exact_damping_ratio”

property

Damping ratio of the pole moved back by a, of which (A.3) is the first order.

The window replaces the pole by (Annex A, after Formula (A.2)), so the decay rate of the windowed mode is at the same damped frequency. From , the true ratio is with . It and (A.3) differ by about .

ExponentialWindowCorrection.peak_correction_factor

Section titled “ExponentialWindowCorrection.peak_correction_factor”

property

Factor on the measured peak of each mode, .

ExponentialWindowCorrection.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot each mode’s apparent damping split into the true and the window’s part.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the bars of the true damping.

Returns: The axes.

ExponentialWindowCorrection.window_damping_ratio

Section titled “ExponentialWindowCorrection.window_damping_ratio”

property

The damping the window added to each mode, .

force_window(
n_samples: int | np.integer[Any],
fs: float,
*,
width_s: float,
start_s: float = 0.0,
taper_s: float = 0.0,
) -> NDArray[np.float64]

The force window of 8.5.1: unity over the pulse, exactly zero elsewhere.

The window has unity gain for the part of the record that holds the force signal, including the filter response, and sets the remaining samples to exactly zero before Fourier processing. It removes broad-band noise from the force auto-spectrum without distortion as long as none of the force data is attenuated (8.5.1, Figure 7). A rectangular window spreads periodic noise and DC offset over a wide band (Figure 8), and 8.5.1 notes that a smooth transition between zero and one narrows that spread: taper_s adds a half-cosine ramp of that length on each side of the unity part, outside it, so the pulse itself is never attenuated. The shape of the ramp is this library’s choice; the part does not prescribe one.

Never use a force window to cut a second impact out of the record (6.4): the response still carries it. check_double_hit finds one.

Parameters

Name Description
n_samples Record length N, in samples.
fs Sample rate, in Hz.
width_s Length of the unity part, in seconds (> 0). Sample n is inside it when start_s <= n / fs < start_s + width_s.
start_s Where the unity part begins, in seconds (Default: 0, the beginning of the record, which keeps the pre-trigger data of 8.2).
taper_s Length of each half-cosine ramp, in seconds (Default: 0, a rectangular window).

Returns: The window, one value per sample.

Raises

Exception When
ValueError for fewer than 16 samples, a non-positive sample rate or width, a negative start or taper, or a window, its falling ramp included, that is still open at the last sample of the record, at .
TypeError if fs, start_s, taper_s or width_s is not a single number, or n_samples is a flag, a text or an array where a count goes.
ForceSpectrumCheck(
frequencies: NDArray[np.float64],
energy_spectral_density: NDArray[np.float64],
*,
frequency_range_hz: tuple[float, float],
max_drop_db: float,
)

Does the force spectrum cover the frequency range of interest? (6.2, 6.3)

The spectrum of a force pulse is a main lobe at low frequency followed by side lobes that fall rapidly, with a usable bandwidth inversely proportional to the pulse duration (6.2). The tip stiffness and the impactor mass set that bandwidth (6.3), and a double hit cuts notches into it (6.4). The check reads how far the energy spectral density falls across the frequency range of interest, from its highest to its lowest value there, against a limit the caller states: the part prints none.

Attributes

Name Description
frequencies Frequencies above 0 Hz, in hertz.
energy_spectral_density One-sided force energy spectral density, in N²·s/Hz (3.4).
frequency_range_hz The frequency range of interest (3.2), in hertz.
max_drop_db The largest fall across the range the check accepts, in dB.

property

How far the density falls across the range, highest to lowest, in dB.

property

Share of the force energy above the range of interest (6.3).

property

Per frequency, whether it lies in the frequency range of interest.

property

The density in dB re its highest value inside the range.

property

Whether the density falls no further than the limit across the range.

ForceSpectrumCheck.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the force energy spectral density against the range and the limit.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the density curve.

Returns: The axes.

Constant (float).

HIGH_COHERENCE = 0.9
impact_mobility(
force_n: Signal | NumericArrayLike,
response: Signal | NumericArrayLike,
fs: float | None = None,
*,
response_quantity: Literal['acceleration', 'velocity', 'displacement'] = 'acceleration',
force_window_s: float | None = None,
force_window_start_s: float = 0.0,
force_window_taper_s: float = 0.0,
exponential_decay_rate_per_s: float = 0.0,
exponential_on_force: bool = True,
driving_point: bool = True,
frequency_range_hz: tuple[float, float] | None = None,
) -> ImpactMobilityResult

Mobility from impact records, averaged as 8.6 prescribes.

Each row of force_n and response is one impact at the same point, triggered as 8.2 describes. The force is multiplied by the force window (8.5.1) and both records by the exponential window (8.5.2), both are transformed, and the estimate is the averaged cross-spectrum of response and force over the averaged auto-spectrum of the force (8.6), with the ordinary coherence of 9.1 beside it.

The DFT runs up to the Nyquist frequency, but a force pulse has a finite usable bandwidth (6.2) and the anti-aliasing filter cuts below the Nyquist frequency (8.3), so the top of the spectrum is noise divided by almost no force. frequency_range_hz keeps the estimate to the frequency range of interest of 3.2, the span at which mobility data are to be obtained, and everything built on the result (its plot, its fiche, its fit) stays there.

Where the force spectrum vanishes the frequency response is undefined, and a range that holds such a frequency is refused. A spectrum that vanishes in exact arithmetic, at a notch between two equal impacts for one, comes out of the transform at the level of its rounding rather than at zero, so any bin at or below that level counts as vanished.

With exponential_on_force=False the exponential window multiplies the response only, and the force of each impact is multiplied instead by the window’s value at the instant of its peak, the approximation Annex A describes for the common practice of windowing the response alone.

A force window that zeroes an impact the record holds raises ImpactExcitationWarning: 6.4 forbids removing a second impact that way.

Parameters

Name Description
force_n Force records, in N: one record (1-D) or one per row (2-D). Accepts a phonometry.io.Signal, one channel per impact, for its rate; a calibration factor it carries is deliberately not applied, because this record is a force and not a pressure.
response Response records, same shape, in m/s², m/s or m as response_quantity says; a Signal likewise, its factor not applied.
fs Sample rate, in Hz. Required when both records are bare arrays; a Signal brings its own, and an explicit value, or a second Signal, that disagrees with it raises.
response_quantity "acceleration" (default), "velocity" or "displacement".
force_window_s Width of the unity part of the force window, in seconds (Default: None, no force window).
force_window_start_s Where the unity part begins, in seconds (Default: 0).
force_window_taper_s Half-cosine ramp on each side, in seconds (Default: 0).
exponential_decay_rate_per_s Decay rate a of the exponential window, in 1/s (Default: 0, none).
exponential_on_force Window the force too (Default: True, the exact case of Formula (A.2)).
driving_point Whether force and response are co-located (Default: True).
frequency_range_hz (f_low, f_high), the frequency range of interest in hertz, inside the Nyquist frequency (Default: None, every bin above 0 Hz).

Returns: An ImpactMobilityResult.

Raises

Exception When
ValueError for records of different shapes, not finite or too short, a non-positive sample rate, an unknown response quantity, an invalid window, a range that holds no bin above 0 Hz, or a force spectrum that vanishes at some frequency of the range.
TypeError if response_quantity is not a text, exponential_decay_rate_per_s, force_window_s, force_window_start_s or force_window_taper_s is not a single number, or frequency_range_hz is not a pair of numbers.

Warns

Warning When
ImpactExcitationWarning when the force window removes an impact.

Advisory when an ISO 7626-5 record breaks a rule of the part.

ImpactMobilityResult(
frequencies: NDArray[np.float64],
mobility: NDArray[np.complex128],
coherence: NDArray[np.float64],
force_energy_spectral_density: NDArray[np.float64],
*,
n_impacts: int,
exponential_decay_rate_per_s: float = 0.0,
response_quantity: Literal['acceleration', 'velocity', 'displacement'] = 'acceleration',
driving_point: bool = True,
)

Mobility averaged over impacts at one point (ISO 7626-5:2019, 8.6).

Attributes

Name Description
frequencies DFT bin frequencies above 0 Hz, in hertz: up to the Nyquist frequency, or across the frequency range of interest the estimate was kept to (3.2).
mobility Complex mobility Y per frequency, in m/(N·s): the averaged estimate of 8.6 as measured, exponential window included. Its resonance peaks are therefore lower than the structure’s when a window was used; fit_mode and the correction of Annex A restore them.
coherence Ordinary coherence per frequency (9.1); identically 1 for a single impact.
force_energy_spectral_density Averaged one-sided energy spectral density of the windowed force, in N²·s/Hz (3.4).
n_impacts Number of impacts averaged.
exponential_decay_rate_per_s Decay rate a of the exponential window applied, in 1/s (0 for none).
response_quantity What the response channel measured: "acceleration", "velocity" or "displacement".
driving_point True if force and response are co-located.
ImpactMobilityResult.fit_mode(
band_hz: tuple[float, float],
) -> SingleModeFitResult

Fit the mode in a band, knowing the window this estimate carries.

The fit runs on the FRF kind the response channel measured, because that is the record the exponential window multiplied, and the result carries the window’s decay rate so that SingleModeFitResult.correction applies Annex A.

Parameters

Name Description
band_hz (f_low, f_high) around one resonance, in hertz.

Returns: A SingleModeFitResult.

property

Mobility magnitude |Y|, in m/(N·s).

property

The FRF kind the response channel gives: accelerance, mobility or receptance.

property

The estimate as a .MobilityResult (ISO 7626-1 vocabulary).

property

Mobility phase, in radians.

ImpactMobilityResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
ImpactMobilityResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the averaged mobility and its coherence.

With no ax a two-panel figure is drawn: |Y(f)| on log-log axes and the coherence beneath it. With ax only the magnitude is drawn.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the magnitude curve.

Returns: The axes, or the tuple of two axes.

ImpactMobilityResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render the ISO 7626 mobility fiche for an impact measurement to a PDF.

The one-page fiche of .MobilityResult.report, with the standard-basis line naming ISO 7626-5:2019 and the characteristic points extended by the number of impacts averaged, the exponential window and the coherence at the mobility peak.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata.
engine Rendering back end; only "reportlab" is supported.
verbose Accepted for a uniform .report() signature; the fiche has a single body layout, so it has no effect.
language "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab" or language is unknown.
ImportError If reportlab or matplotlib is not installed.
ImpactMobilityResult.to(
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
) -> NDArray[np.complex128]

Convert the mobility to another FRF kind (see .convert_frf).

Raises

Exception When
TypeError if target is not a text.
OverloadCheck(x: NDArray[np.float64], fs: float, *, full_scale: float)

Did the record stay inside the linear range of its channel? (8.4)

Impact excitation risks saturating the measurement system, because the signals carry out-of-band energy and the dynamic range is used to its limit (8.4). Saturation is not always visible as a clipped waveform, so 8.4 asks that the manufacturer’s maximum for linear operation be observed, and warns that filtered digital records give poor definition of the actual waveform: pass the widest-band record available. A pass here is necessary, not sufficient.

Attributes

Name Description
x The record judged, in its own unit, as a bare array (a Signal passed in is read without its calibration factor, and its samples are what is kept).
fs Its sample rate, in Hz.
full_scale The largest magnitude the channel handles linearly, in the unit of the record.

property

Distance from the peak to the full scale, in dB (infinite for silence).

property

How many samples reach the full scale.

property

Whether every sample stays below the full scale.

property

Largest magnitude in the record, in its unit.

OverloadCheck.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the record against its full scale, clipped samples marked.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the record curve.

Returns: The axes.

Constant (float).

RESPONSE_END_RATIO = 0.01

Constant (float).

RESPONSE_MIDPOINT_RATIO = 0.1
ResponseDecayCheck(
response: NDArray[np.float64],
fs: float,
*,
segment_s: float,
exponential_window: bool,
start_s: float = 0.0,
)

Did the response decay far enough within the record? (8.3, 8.5.2)

Without a window the response should decay to about 1 % of its initial magnitude at the end of the record, or truncation leaks (8.3). 8.3 calls that figure a compromise: a longer record, reaching further down, improves the frequency resolution but can lower the signal-to-noise ratio, so a much faster decay is no better. With an exponential window, as a general guideline, the natural decay should reach 25 % or less, or the corrections of Annex A become very sensitive to errors in the damping estimates (8.5.2). 8.5.2 also offers a convenient check: the peak response at the midpoint of the record is about 10 % of the highest one, which for a steady exponential decay is the same statement as 1 % at the end.

Levels are peaks of the magnitude over segments of the record, relative to the highest peak from start_s on; a segment needs at least one period of the lowest mode for its peak to be a peak. The midpoint level is the peak over the segment that starts at the midpoint. The level at the end is read at the last sample: the peak over the last segment sits at its start, so it is carried to the last sample at the rate the peaks decay from the midpoint segment to the last one, the steady decay the midpoint check itself assumes. A response that has stopped decaying, on a noise floor, is read at the peak of its last segment, never higher.

The verdict compares the level at the end, rounded to a whole per cent (the precision both figures are printed in), with the figure: “about 1 %” accepts any level below 1.5 %, which rounds to 1 %, and “25 % or less” any level below 25.5 %.

A driving-point acceleration follows the force itself during the impact (the mass line of the structure), so its highest peak can be the impact rather than the decay. start_s just after the force pulse, or the force record passed to check_response_decay, judges the free decay alone.

Attributes

Name Description
response The response record judged, unwindowed, in its own unit, as a bare array (a Signal passed in is read without its calibration factor, and its samples are what is kept).
fs Its sample rate, in Hz.
segment_s Length of the segments the end and midpoint levels are read over, in seconds.
exponential_window Whether the record is to be processed with an exponential window (25 % limit) or without (1 %).
start_s Time from which the highest peak is sought, in seconds.

property

Level at the last sample of the record, relative to the highest peak.

The peak over the last segment, carried over the rest of the segment at the rate the segment peaks decay from the midpoint to the last segment (never raised).

property

Peak over the last segment, relative to the highest peak.

For a response still decaying this is its level at the start of the segment, above the level at the end of the record.

property

The figure the clause prints: 0.01 without a window, 0.25 with one.

property

Peak over the segment starting at the midpoint, relative to the highest peak.

property

Whether the level at the end, to a whole per cent, is at most the figure.

property

The highest peak of the response from start_s on, in its unit.

property

When the highest peak from start_s on occurs, in seconds.

ResponseDecayCheck.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the response with the levels it reaches at the midpoint and the end.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the response curve.

Returns: The axes.

single_mode_fit(
frf: NumericArrayLike,
*,
frequencies: NumericArrayLike,
band_hz: tuple[float, float],
kind: Literal['accelerance', 'mobility', 'receptance'] = 'mobility',
exponential_decay_rate_per_s: float = 0.0,
) -> SingleModeFitResult

Fit one mode to an FRF over a band around its resonance.

Annex A needs the apparent damping of each mode and leaves the estimator open (“suitable parameter estimation capability is now widely available through a variety of curve-fitting methods”). This is a rational-fraction fit of one mode: the FRF over the band is fitted by in linear least squares, reweighted by the previous denominator until it settles (Sanathanan and Koerner), and the result is written as a pole, its residue and a direct term (SingleModeFitResult). The model is exact for a single-degree-of-freedom structure; on a real one, choose a band that holds one resonance and little else.

Annex A asks that the apparent damping of each mode “can be accurately determined”, and a band without a resonance determines none: a constant, a mass line or a spring line fits the numerator alone and leaves the pole to rounding. The fit is refused when its system does not determine the five coefficients to half the digits of a double, or when the pole it finds has no decay rate or no damped natural frequency above that same fraction of the band’s centre frequency.

Fit the FRF in the kind the response channel measured, because that is the record the exponential window multiplied: ImpactMobilityResult.fit_mode does so.

Parameters

Name Description
frequencies Frequencies of the FRF, in hertz (> 0).
frf Complex FRF of kind kind, same length.
band_hz (f_low, f_high), in hertz, holding at least three frequencies.
kind "accelerance", "mobility" (default) or "receptance".
exponential_decay_rate_per_s Decay rate of the exponential window the data carry, in 1/s (Default: 0).

Returns: A SingleModeFitResult.

Raises

Exception When
ValueError for mismatched or non-finite data, a band that is not a pair of positive numbers or holds fewer than three frequencies, an unknown kind, or a band whose data hold no lightly damped mode.
TypeError if exponential_decay_rate_per_s is not a single number, kind is not a text, or band_hz is not a pair of numbers, or frequencies holds a text or a value that is not a real number, or frf holds a text or a value that is not a number.
SingleModeFitResult(
frequencies: NDArray[np.float64],
frf: NDArray[np.complex128],
pole_rad_s: complex,
residue: complex,
direct_term: complex,
*,
kind: Literal['accelerance', 'mobility', 'receptance'] = 'mobility',
exponential_decay_rate_per_s: float = 0.0,
)

One mode fitted over a band: pole, residue and a direct term.

The model is , with the pole of the data fitted, its residue and a real constant that stands in for the modes outside the band. For a single-degree-of-freedom structure the model is exact in every FRF kind: for dynamic compliance and mobility and for accelerance.

Attributes

Name Description
frequencies The frequencies fitted, in hertz.
frf The FRF fitted, complex, of kind kind.
pole_rad_s The pole of the data, upper half plane, in rad/s.
residue Its residue , in the FRF’s unit times rad/s.
direct_term The constant , in the FRF’s unit.
kind The FRF kind fitted: "accelerance", "mobility" or "receptance".
exponential_decay_rate_per_s Decay rate of the exponential window the data carry, in 1/s (0 for none).

SingleModeFitResult.apparent_damping_ratio

Section titled “SingleModeFitResult.apparent_damping_ratio”

property

Damping ratio of the fitted pole, .

With an exponential window this is the apparent damping of Annex A, the window’s included.

SingleModeFitResult.corrected_frf(
frequencies: float | np.floating[Any] | np.integer[Any],
) -> complex
SingleModeFitResult.corrected_frf(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.complex128]
SingleModeFitResult.corrected_frf(
frequencies: NumericArrayLike,
) -> complex | NDArray[np.complex128]

The mode with the window taken out, of kind kind (Annex A).

The pole is moved back by the decay rate, , and the residue and direct term are kept: the window multiplies the impulse response by , which changes the pole and nothing else (Formula (A.2)).

Parameters

Name Description
frequencies Frequencies, in hertz.

Returns: The complex FRF. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

SingleModeFitResult.corrected_mobility(
frequencies: float | np.floating[Any] | np.integer[Any],
) -> complex
SingleModeFitResult.corrected_mobility(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.complex128]
SingleModeFitResult.corrected_mobility(
frequencies: NumericArrayLike,
) -> complex | NDArray[np.complex128]

The corrected mode as mobility, in m/(N·s).

Parameters

Name Description
frequencies Frequencies, in hertz (> 0).

Returns: The complex mobility. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

property

The Annex A correction of this mode for the window its data carry.

SingleModeFitResult.damped_natural_frequency_hz

Section titled “SingleModeFitResult.damped_natural_frequency_hz”

property

Damped natural frequency , in hertz.

SingleModeFitResult.fitted_frf(
frequencies: float | np.floating[Any] | np.integer[Any],
) -> complex
SingleModeFitResult.fitted_frf(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.complex128]
SingleModeFitResult.fitted_frf(
frequencies: NumericArrayLike,
) -> complex | NDArray[np.complex128]

The fitted model at any frequencies, window included, of kind kind.

Parameters

Name Description
frequencies Frequencies, in hertz.

Returns: The complex FRF. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

SingleModeFitResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the data fitted, the fitted mode and the mode with the window taken out.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the fitted curve.

Returns: The axes.

verify_channel_match(
response: NumericArrayLike,
*,
frequencies: NumericArrayLike,
frequency_range_hz: tuple[float, float],
) -> ChannelMatchVerification

Is the analyser’s channel-to-channel match inside 8.1’s tolerances?

Feed the same broad-band signal to both channels, estimate the frequency response between them (for instance with phonometry.electroacoustics.frequency_response.transfer_function), and pass it here. The verification passes when its magnitude is unity within +/- 5 % and its phase zero within +/- 5 degrees at every frequency of the range of interest.

Parameters

Name Description
frequencies Frequencies of the response, in hertz.
response Complex frequency response between the channels.
frequency_range_hz (f_low, f_high), in hertz.

Returns: A ChannelMatchVerification over the range.

Raises

Exception When
ValueError for mismatched or non-finite data, or a range that holds none of the frequencies.
TypeError if frequency_range_hz is not a pair of numbers, or frequencies holds a text or a value that is not a real number, or response holds a text or a value that is not a number.

Constant (float).

WINDOWED_RESPONSE_END_RATIO = 0.25