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
Section titled “convert_frf”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. |
FRF_UNITS
Section titled “FRF_UNITS”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
Section titled “MobilityResult”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). |
MobilityResult.magnitude
Section titled “MobilityResult.magnitude”property
Mobility magnitude |Y|, in m/(N.s).
MobilityResult.phase_rad
Section titled “MobilityResult.phase_rad”property
Mobility phase, in radians.
MobilityResult.plot()
Section titled “MobilityResult.plot()”MobilityResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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()
Section titled “MobilityResult.report()”MobilityResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender 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()
Section titled “MobilityResult.to()”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
Section titled “random_error_percent”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
Section titled “resonance_frequency”resonance_frequency(mass: float, stiffness: float) -> floatUndamped 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
Section titled “RigidMassCalibrationResult”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"). |
RigidMassCalibrationResult.expected
Section titled “RigidMassCalibrationResult.expected”property
Known correct magnitude of the block per frequency.
Returns: (accelerance) or (mobility).
RigidMassCalibrationResult.passes
Section titled “RigidMassCalibrationResult.passes”property
True if every frequency is within the tolerance.
RigidMassCalibrationResult.plot()
Section titled “RigidMassCalibrationResult.plot()”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,) -> AxesPlot 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
Section titled “sdof_accelerance”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
Section titled “sdof_mobility”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
Section titled “sdof_mobility_result”sdof_mobility_result( frequency: NumericArrayLike, mass: float, stiffness: float, damping: float,) -> MobilityResultSDOF 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
Section titled “sdof_receptance”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
Section titled “verify_rigid_mass_calibration”verify_rigid_mass_calibration( frf: NumericArrayLike, mass: float, *, frequencies: NumericArrayLike, quantity: Literal['accelerance', 'mobility'] = 'accelerance',) -> RigidMassCalibrationResultVerify 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. |