Skip to content

vibration.structural.mechanical_mobility

Mechanical mobility and the frequency-response-function family (ISO 7626-1:2011).

Mechanical mobility is the complex ratio of a velocity response to the excitation force that produces it, (ISO 7626-1, 3.1.2). It is one of a family of motion-per-force frequency-response functions (FRFs); which member is used depends only on whether the motion is expressed as displacement, velocity or acceleration, and each has a force-per-motion reciprocal (ISO 7626-1, Table 1):

Motion FRF (motion / force) Unit Reciprocal (force / motion)
displacement dynamic compliance / receptance H m/N dynamic stiffness (N/m)
velocity mobility Y m/(N.s) impedance (N.s/m)
acceleration accelerance A 1/kg apparent mass (kg)

For a harmonic motion the velocity is and the acceleration , so every FRF follows from the receptance H:

These element-wise reciprocals are the free quantities of ISO 7626-1, 3.1.4; the blocked matrix quantities of Table 1 do not invert element-wise ( for multi-coordinate systems); see convert_frf.

convert_frf moves between any two of the six FRFs through the receptance pivot. A driving-point FRF has the response and force at the same point (); a transfer FRF has them at different points.

The canonical closed-form reference is the single-degree-of-freedom resonator of mass m, viscous damping c and stiffness k, whose receptance is (consistent with the ISO 7626-1 Table 1 / 3.1.2 definitions). At its resonance the driving-point mobility is purely real and equal to , the mobility peak measures the damping. This module is the FRF backbone for the structure-borne source and transmission standards (ISO 9611, ISO 10846, EN 15657, EN 12354-5).

Measured FRFs (ISO 7626-2:2015). The single-point measurement side is covered by the library’s spectral estimators: processing of random-excitation records per ISO 7626-2, 8.1.3 (the H1 estimator ) and the ordinary coherence used for its data-quality checks are phonometry.electroacoustics.frequency_response.transfer_function (with estimator="H1", the default) and phonometry.electroacoustics.frequency_response.coherence; both are exported at the package top level. This module adds the ISO 7626-2 acceptance criteria on top of them: the operational rigid-mass calibration of 7.5.2 (verify_rigid_mass_calibration, +/- 5 %) and the Annex A normalized random error with its < 5 % averaging criterion (random_error_percent).

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

convert_frf(
value: complex | np.number[Any],
source: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
*,
frequency: float | np.floating[Any] | np.integer[Any],
) -> complex
convert_frf(
value: Sequence[complex] | Sequence[np.number[Any]] | NDArray[np.bool_ | np.number[Any]],
source: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
*,
frequency: NumericArrayLike,
) -> NDArray[np.complex128]
convert_frf(
value: complex | np.number[Any],
source: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
*,
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.complex128]
convert_frf(
value: NumericArrayLike,
source: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
*,
frequency: NumericArrayLike,
) -> complex | NDArray[np.complex128]

Convert a frequency-response function between any two kinds (Table 1).

Parameters

Name Description
value The (complex) FRF value(s) of kind source.
frequency Frequency f, in hertz (scalar or array, broadcast with value).
source The FRF kind of value: one of "receptance", "mobility", "accelerance", "dynamic_stiffness", "impedance" or "apparent_mass".
target The FRF kind to convert to (same set). One of "receptance", "mobility", "accelerance", "dynamic_stiffness", "impedance" or "apparent_mass".

Returns: The FRF value(s) of kind target, as a complex array. A complex when value and frequency are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for an unknown FRF name, a non-positive frequency, or a zero value (dead channel) when the conversion involves a force-per-motion reciprocal.
TypeError if source or target is not a text, or frequency holds a text or a value that is not a real number.

Constant (mapping).

FRF_UNITS = {'receptance': 'm/N', 'mobility': 'm/(N·s)', 'accelerance': '1/kg', 'dynamic_stiffness': 'N/m', 'impedance': 'N·s/m', 'apparent_mass': 'kg'}
MobilityResult(
frequencies: NDArray[np.float64],
mobility: NDArray[np.complex128],
*,
driving_point: bool = True,
)

A measured or modelled mobility FRF over frequency.

Attributes

Name Description
frequencies Frequencies, in hertz.
mobility Complex mobility Y per frequency, in m/(N.s).
driving_point True if response and force are co-located (i = j).

property

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

property

Mobility phase, in radians.

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

Plot the mobility magnitude |Y(f)|.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
MobilityResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render a mechanical-mobility measurement fiche to a PDF (ISO 7626).

Writes a one-page mobility measurement report: the standard-basis line naming whether the mobility is a driving-point or a transfer FRF (ISO 7626-1:2011 definitions; measurement per ISO 7626-2:2015), an optional metadata header, a two-panel body with a compact table of the FRF’s characteristic points (the FRF type, the frequency range, the peak frequency, the peak mobility magnitude and the phase there) beside the mobility magnitude spectrum |Y(f)|, a boxed peak mobility |Y| with the frequency it occurs at, and a footer identity/disclaimer block.

Mechanical mobility is a continuous frequency-response function, so the fiche presents it as a spectrum plus a table of characteristic points; a mobility measurement is a characterisation, so there is no pass/fail verdict.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata supplying the header identity (specimen is the tested structure) and the footer identity; the requirement field is ignored.
engine Rendering back end; only "reportlab" is supported.
verbose Accepted for a uniform .report() signature; the mobility fiche has a single body layout, so it has no effect.
language Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

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. The fiche always embeds the mobility spectrum, so both are required (the [report] and [plot] extras).
MobilityResult.to(
target: Literal['receptance', 'mobility', 'accelerance', 'dynamic_stiffness', 'impedance', 'apparent_mass'],
) -> NDArray[np.complex128]

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

The force-per-motion kinds are element-wise reciprocals, i.e. the free quantities of ISO 7626-1, 3.1.4: on a transfer FRF (driving_point=False), to("impedance") returns the free impedance , not the blocked matrix impedance of Table 1 (which does not invert element-wise).

Parameters

Name Description
target One of "receptance", "mobility", "accelerance", "dynamic_stiffness", "impedance" or "apparent_mass".

Raises

Exception When
TypeError if target is not a text.
random_error_percent(
coherence: float | np.floating[Any] | np.integer[Any],
n_averages: int | np.integer[Any],
) -> float
random_error_percent(
coherence: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
n_averages: int | np.integer[Any],
) -> NDArray[np.float64]
random_error_percent(
coherence: NumericArrayLike,
n_averages: int | np.integer[Any],
) -> float | NDArray[np.float64]

Normalized random error of an averaged FRF magnitude (ISO 7626-2 Annex A).

, the normalized random error of the frequency-response-function magnitude estimated from n averaged spectra with ordinary coherence (the relation behind Figure A.2, from Bendat & Piersol). ISO 7626-2, 8.1.3 requires enough averages that the error at each resonance of a driving-point mobility is below 5 %: e.g. needs about spectra ( %), the Annex A example.

Parameters

Name Description
coherence Ordinary coherence per frequency, in (0, 1].
n_averages Number of averaged spectra n (>= 1).

Returns: The normalized random error, in percent (same shape as input). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for a coherence outside (0, 1] or n_averages < 1.
TypeError if n_averages is a flag, a text or an array where a count goes, or coherence holds a text or a value that is not a real number.
resonance_frequency(mass: float, stiffness: float) -> float

Undamped natural frequency of the SDOF, in Hz.

Parameters

Name Description
mass Mass m, in kg.
stiffness Stiffness k, in N/m.

Returns: The natural frequency f0, in hertz.

Raises

Exception When
TypeError if mass or stiffness is not a single number.
RigidMassCalibrationResult(
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
*,
mass: float,
quantity: Literal['accelerance', 'mobility'],
)

Operational rigid-mass calibration check (ISO 7626-2:2015, 7.5.2).

Only what was measured and the block are fields. The block’s known response, the deviation from it, the +/- 5 % of 7.5.2 and the verdict are read from them, so a check cannot be built against another tolerance.

Attributes

Name Description
frequencies Frequencies of the calibration FRF, in hertz.
measured Measured FRF magnitude per frequency (1/kg for accelerance, m/(N.s) for mobility).
mass Mass m of the calibration block, in kg.
quantity FRF kind checked ("accelerance" or "mobility").

property

Known correct magnitude of the block per frequency.

Returns: (accelerance) or (mobility).

property

True if every frequency is within the tolerance.

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

Plot the rigid-mass calibration check (ISO 7626-2, 7.5.2).

The measured FRF magnitude against the known rigid-mass line with its tolerance band, and the relative deviation against the same band. With no ax a two-panel figure is drawn and its two axes returned as a tuple; with ax the deviation diagnostic is drawn on it and that axes returned.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
language The language of the labels: "en" or "es".

RigidMassCalibrationResult.relative_deviation

Section titled “RigidMassCalibrationResult.relative_deviation”

property

Relative deviation measured/expected - 1 per frequency.

RigidMassCalibrationResult.relative_tolerance

Section titled “RigidMassCalibrationResult.relative_tolerance”

property

The +/- 5 % of 7.5.2, as a relative tolerance (0.05).

RigidMassCalibrationResult.within_tolerance

Section titled “RigidMassCalibrationResult.within_tolerance”

property

Per-frequency pass flag |deviation| <= tolerance.

Judged as a settled share of the tolerance, so that a block exactly 5 % off in decimal is within the +/- 5 % whichever side of it the last bits of the ratio fall.

sdof_accelerance(
frequency: float | np.floating[Any] | np.integer[Any],
mass: float,
stiffness: float,
damping: float,
) -> complex
sdof_accelerance(
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
mass: float,
stiffness: float,
damping: float,
) -> NDArray[np.complex128]
sdof_accelerance(
frequency: NumericArrayLike,
mass: float,
stiffness: float,
damping: float,
) -> complex | NDArray[np.complex128]

Accelerance of a viscously damped SDOF resonator: .

Parameters

Name Description
frequency Frequency f, in hertz (scalar or array).
mass Mass m, in kg.
stiffness Stiffness k, N/m.
damping Viscous damping c, N.s/m.

Returns: The complex accelerance A, in 1/kg. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

sdof_mobility(
frequency: float | np.floating[Any] | np.integer[Any],
mass: float,
stiffness: float,
damping: float,
) -> complex
sdof_mobility(
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
mass: float,
stiffness: float,
damping: float,
) -> NDArray[np.complex128]
sdof_mobility(
frequency: NumericArrayLike,
mass: float,
stiffness: float,
damping: float,
) -> complex | NDArray[np.complex128]

Mobility of a viscously damped SDOF resonator: .

Parameters

Name Description
frequency Frequency f, in hertz (scalar or array).
mass Mass m, in kg.
stiffness Stiffness k, N/m.
damping Viscous damping c, N.s/m.

Returns: The complex mobility Y, in m/(N.s). A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

sdof_mobility_result(
frequency: NumericArrayLike,
mass: float,
stiffness: float,
damping: float,
) -> MobilityResult

SDOF driving-point mobility bundled as a MobilityResult.

Parameters

Name Description
frequency Frequency f, in hertz (scalar or array).
mass Mass m, in kg.
stiffness Stiffness k, N/m.
damping Viscous damping c, N.s/m.

Returns: The MobilityResult (driving point).

Raises

Exception When
TypeError if frequency holds a text or a value that is not a real number.
sdof_receptance(
frequency: float | np.floating[Any] | np.integer[Any],
mass: float,
stiffness: float,
damping: float,
) -> complex
sdof_receptance(
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
mass: float,
stiffness: float,
damping: float,
) -> NDArray[np.complex128]
sdof_receptance(
frequency: NumericArrayLike,
mass: float,
stiffness: float,
damping: float,
) -> complex | NDArray[np.complex128]

Receptance of a viscously damped SDOF resonator (closed form).

, the textbook single-degree-of-freedom reference, expressed in the FRF taxonomy of ISO 7626-1 (Table 1 / 3.1.2 definitions).

Parameters

Name Description
frequency Frequency f, in hertz (scalar or array).
mass Mass m, in kg.
stiffness Stiffness k, in N/m.
damping Viscous damping coefficient c, in N.s/m (>= 0).

Returns: The complex receptance H, in m/N. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if damping, mass or stiffness is not a single number, or frequency holds a text or a value that is not a real number.
verify_rigid_mass_calibration(
frf: NumericArrayLike,
mass: float,
*,
frequencies: NumericArrayLike,
quantity: Literal['accelerance', 'mobility'] = 'accelerance',
) -> RigidMassCalibrationResult

Verify an operational calibration on a rigid mass (ISO 7626-2, 7.5.2).

The measured frequency response of a freely suspended rigid calibration block of known mass m shall agree within +/- 5 % with its known correct value: the accelerance magnitude or the mobility magnitude . All components of the measurement chain (including the attachment hardware) are connected as in the test series, so a failure flags transducer, chain or attachment-compliance errors. The 5 % is the clause’s and is not a parameter.

Parameters

Name Description
frf Measured calibration FRF (complex or magnitude, scalar or array), in 1/kg (accelerance) or m/(N.s) (mobility).
frequencies Frequencies of frf, in hertz (> 0, same shape).
mass Known mass m of the calibration block, in kg (> 0).
quantity "accelerance" () or "mobility" (). (Default: "accelerance".)

Returns: A RigidMassCalibrationResult with per-band pass flags.

Raises

Exception When
ValueError for an unknown quantity, non-positive mass or frequency, or mismatched shapes.
TypeError if mass is not a single number, or quantity is not a text, 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.