Ir al contenido

materials.absorbers.four_microphone

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.

Four-microphone transfer-matrix method for the transmission of a specimen.

ASTM E2611-19, the two-tube method: the specimen sits between an upstream and a downstream tube section with two microphones on each side, and the wave field is decomposed into forward/backward amplitudes on each side (Eqs. (17)-(20)). The face pressures and particle velocities are formed (Eq. (21)) and the transfer matrix [[T11, T12], [T21, T22]] is solved from a two-load (Eq. (22)) or a symmetric one-load (Eq. (24)) measurement. Transmission loss (Eq. (26)), hard-backed reflection/absorption (Eqs. (27)/(28)) and the material wavenumber/characteristic impedance (Eqs. (29)/(30)) all read out of those four poles, which is what makes the standard one subject: everything here exists to fill the matrix or to interpret it.

Time convention with the forward wave carried by (Eq. (21)); air properties from Clause 8.2/8.3, Eqs. (4)/(5), use temperature in degrees Celsius. Both differ from the ISO 10534-2 ansatz of impedance_tube, whose wavenumber is and whose air properties take kelvin; the two are not interchangeable, so the air-property and working-range helpers are named per standard and each stays with the method that prescribes it. What the two transfer methods genuinely share, the tube cross-section and the plane-wave working-range arithmetic, is imported from that module.

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

air_density_astm_e2611(
*,
temperature_c: float | np.floating[Any] | np.integer[Any],
static_pressure_kpa: float | np.floating[Any] | np.integer[Any] = ...,
) -> float
air_density_astm_e2611(
*,
temperature_c: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
static_pressure_kpa: NumericArrayLike = ...,
) -> NDArray[np.float64]
air_density_astm_e2611(
*,
temperature_c: float | np.floating[Any] | np.integer[Any],
static_pressure_kpa: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
air_density_astm_e2611(
*,
temperature_c: NumericArrayLike,
static_pressure_kpa: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Air density (ASTM E2611-19, Eq. (5)).

.

Parameters

Name Description
temperature_c Room temperature, in degrees Celsius.
static_pressure_kpa Atmospheric pressure P, in kilopascals (default 101.325 kPa).

Returns: Air density rho, in kilograms per cubic metre. A float when temperature_c and static_pressure_kpa are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any temperature is at or below -273.15 degC, or any pressure is not positive.
TypeError if static_pressure_kpa or temperature_c holds a text or a value that is not a real number.
air_layer_transfer_matrix(
wavenumber: NumericArrayLike,
thickness_m: float,
characteristic_impedance: float,
) -> TransferMatrix

Analytic transfer matrix of a pure air layer of thickness d.

the classical loss-free layer used to validate the ASTM E2611-19 reduction (it is reciprocal, , and symmetric, ).

Parameters

Name Description
wavenumber Air wavenumber k.
thickness_m Layer thickness d, in metres.
characteristic_impedance Characteristic impedance rho c, in rayls.

Returns: The air-layer TransferMatrix.

Raises

Exception When
TypeError if characteristic_impedance or thickness_m is not a single number, or wavenumber holds a text or a value that is not a number.
face_quantities(
a: NumericArrayLike,
b: NumericArrayLike,
c: NumericArrayLike,
d: NumericArrayLike,
*,
wavenumber: NumericArrayLike,
thickness_m: float,
characteristic_impedance: float,
) -> FaceQuantities

Face pressures and particle velocities (ASTM E2611-19, Eq. (21)).

Parameters

Name Description
a Upstream forward amplitude A.
b Upstream backward amplitude B.
c Downstream forward amplitude C.
d Downstream backward amplitude D.
wavenumber Air wavenumber k.
thickness_m Specimen thickness d, in metres.
characteristic_impedance Characteristic impedance rho c, in rayls.

Returns: The face pressures and velocities, as a FaceQuantities.

Raises

Exception When
TypeError if characteristic_impedance or thickness_m is not a single number, or b, c, d or wavenumber holds a text or a value that is not a number.
FaceQuantities(
p0: NDArray[np.complex128],
pd: NDArray[np.complex128],
u0: NDArray[np.complex128],
ud: NDArray[np.complex128],
)

The pressures and particle velocities on the two faces of a specimen.

What face_quantities returns (ASTM E2611-19 Eq. (21)): named as the standard prints them, where a (p0, pd, u0, ud) tuple used to be unpacked by position.

Attributes

Name Description
p0 The sound pressure on the upstream face, x = 0.
pd The sound pressure on the downstream face, x = d.
u0 The particle velocity on the upstream face.
ud The particle velocity on the downstream face.
plane_wave_frequency_range_astm_e2611(
spacing_m: float,
speed_of_sound: float,
*,
diameter_m: float | None = None,
shape: Literal['circular', 'rectangular', 'square'] = 'circular',
) -> tuple[float, float]

Working plane-wave frequency range (f_l, f_u) (ASTM E2611-19).

The upper limit is the smaller of the microphone-spacing bound , i.e. (6.5.4), and, when the tube diameter_m is given, the cut-on bound with for a circular tube (6.2.4.1, Eq. (2)) or for a rectangular tube with d the largest section dimension (6.2.5). The lower limit follows 6.2.3: the spacing shall be greater than 1 % of the wavelength, i.e. .

With two different spacings s1/s2, call with the larger one for the upper bound and the smaller one for the lower bound (each bound is binding for every microphone pair).

Parameters

Name Description
spacing_m Microphone spacing s, in metres.
speed_of_sound Speed of sound c, in metres per second.
diameter_m Tube diameter (circular) or largest section dimension (rectangular/square) d, in metres; None applies only the spacing bound.
shape "circular", "rectangular" or "square".

Returns: Tuple (f_l, f_u) of the lower and upper frequency limits, in Hz.

Raises

Exception When
TypeError if spacing_m is not a single number, or shape is not a text.
speed_of_sound_astm_e2611(
*,
temperature_c: float | np.floating[Any] | np.integer[Any],
) -> float
speed_of_sound_astm_e2611(
*,
temperature_c: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
speed_of_sound_astm_e2611(
*,
temperature_c: NumericArrayLike,
) -> float | NDArray[np.float64]

Speed of sound in air (ASTM E2611-19, Eq. (4)).

.

Parameters

Name Description
temperature_c Room temperature, in degrees Celsius.

Returns: Speed of sound c, in metres per second. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any temperature is at or below -273.15 degC.
TypeError if temperature_c holds a text or a value that is not a real number.
transfer_matrix_one_load(
load: tuple[NumericArrayLike, NumericArrayLike, NumericArrayLike, NumericArrayLike],
*,
l1: float,
s1: float,
l2: float,
s2: float,
thickness_m: float,
wavenumber: NumericArrayLike,
characteristic_impedance: float,
frequencies: NumericArrayLike | None = None,
diameter_m: float | None = None,
shape: Literal['circular', 'rectangular', 'square'] = 'circular',
) -> TransferMatrix

One-load transfer matrix, symmetric specimen (ASTM E2611-19, Eqs. (23)-(24)).

Valid only for a reciprocal and symmetric specimen ( and , Eq. (23)). A single termination suffices:

Parameters

Name Description
load Microphone transfer functions (H1, H2, H3, H4).
l1 Upstream reference distance l1, in metres.
s1 Upstream microphone spacing s1, in metres.
l2 Downstream reference distance l2, in metres.
s2 Downstream microphone spacing s2, in metres.
thickness_m Specimen thickness d, in metres.
wavenumber Air wavenumber k.
characteristic_impedance Characteristic impedance rho c.
frequencies Optional frequency vector f, in hertz, retained on the result so TransferMatrix.plot needs no arguments.
diameter_m Optional tube diameter (circular) or largest section dimension (rectangular/square), in metres, that activates the plane-wave working-range check (6.2.3-6.2.5, 6.5.4).
shape Tube cross-section, "circular", "rectangular" or "square".

Returns: The specimen TransferMatrix (measurement context retained on the result).

Raises

Exception When
TypeError if characteristic_impedance, diameter_m, l1, l2, s1, s2 or thickness_m is not a single number, or shape is not a text, or frequencies holds a text or a value that is not a real number, or load or wavenumber holds a text or a value that is not a number.
transfer_matrix_two_load(
load_a: tuple[NumericArrayLike, NumericArrayLike, NumericArrayLike, NumericArrayLike],
load_b: tuple[NumericArrayLike, NumericArrayLike, NumericArrayLike, NumericArrayLike],
*,
l1: float,
s1: float,
l2: float,
s2: float,
thickness_m: float,
wavenumber: NumericArrayLike,
characteristic_impedance: float,
frequencies: NumericArrayLike | None = None,
diameter_m: float | None = None,
shape: Literal['circular', 'rectangular', 'square'] = 'circular',
) -> TransferMatrix

Two-load transfer matrix (ASTM E2611-19, Eqs. (17)-(22)).

Each load is the tuple (H1, H2, H3, H4) of the four microphone transfer functions measured with a different downstream termination. The two loads give four equations for the four unknowns (Eq. (22)):

Parameters

Name Description
load_a Microphone transfer functions (H1, H2, H3, H4) for load a.
load_b Microphone transfer functions (H1, H2, H3, H4) for load b.
l1 Upstream reference distance l1, in metres.
s1 Upstream microphone spacing s1, in metres.
l2 Downstream reference distance l2, in metres.
s2 Downstream microphone spacing s2, in metres.
thickness_m Specimen thickness d, in metres.
wavenumber Air wavenumber k.
characteristic_impedance Characteristic impedance rho c.
frequencies Optional frequency vector f, in hertz, retained on the result so TransferMatrix.plot needs no arguments.
diameter_m Optional tube diameter (circular) or largest section dimension (rectangular/square), in metres, that activates the plane-wave working-range check (6.2.3-6.2.5, 6.5.4).
shape Tube cross-section, "circular", "rectangular" or "square".

Returns: The specimen TransferMatrix (measurement context retained on the result).

Raises

Exception When
TypeError if characteristic_impedance, diameter_m, l1, l2, s1, s2 or thickness_m is not a single number, or shape is not a text, or frequencies holds a text or a value that is not a real number, or load_a, load_b or wavenumber holds a text or a value that is not a number.
TransferMatrix(
t11: NumericArrayLike,
t12: NumericArrayLike,
t21: NumericArrayLike,
t22: NumericArrayLike,
*,
l1: float | None = None,
s1: float | None = None,
l2: float | None = None,
s2: float | None = None,
thickness_m: float | None = None,
diameter_m: float | None = None,
shape: Literal['circular', 'rectangular', 'square'] | None = None,
frequencies: NumericArrayLike | None = None,
air_characteristic_impedance: float | None = None,
)

Acoustic transfer matrix [[T11, T12], [T21, T22]] (ASTM E2611-19).

Relates the pressure and normal particle velocity across a specimen, (Eq. (16)). Each entry is given as a number or as a per-frequency array of matching shape (a list, a tuple or any array-like), and is stored as a read-only complex128 array: a scalar entry as a 0-d array, which complex(m.t11) or m.t11.item() reads back as a number, and a real entry with a zero imaginary part. frequencies, when given, is stored as a read-only float64 array.

The trailing fields retain the measurement context when the matrix comes out of transfer_matrix_two_load / transfer_matrix_one_load (tube geometry l1/s1/l2/s2, specimen thickness_m, tube diameter_m and canonical cross-section shape, the frequencies vector when supplied to the solver, and the air air_characteristic_impedance rho c); all default to None so a hand-built matrix (for example air_layer_transfer_matrix) is unchanged.

Attributes

Name Description
shape One of "circular", "rectangular" or "square".
TransferMatrix.absorption_hard_backed(
characteristic_impedance: float,
) -> NDArray[np.float64]

Hard-backed absorption coefficient (ASTM E2611-19, Eq. (28)).

.

Parameters

Name Description
characteristic_impedance Characteristic impedance rho c.

Returns: Absorption coefficient alpha.

TransferMatrix.characteristic_impedance_material()

Section titled “TransferMatrix.characteristic_impedance_material()”
TransferMatrix.characteristic_impedance_material() -> NDArray[np.complex128]

Characteristic impedance of the material (ASTM E2611-19, Eq. (30)).

.

Returns: Complex characteristic impedance Z, in rayls.

TransferMatrix.determinant() -> NDArray[np.complex128]

Determinant (unity for a reciprocal specimen).

TransferMatrix.material_wavenumber(
thickness_m: float,
) -> NDArray[np.complex128]

Propagation wavenumber inside the material (ASTM E2611-19, Eq. (29)).

(complex arccos).

Parameters

Name Description
thickness_m Specimen thickness d, in metres.

Returns: Complex material wavenumber k', in reciprocal metres.

Raises

Exception When
TypeError if thickness_m is not a single number.
TransferMatrix.plot(
ax: Axes | None = None,
*,
frequencies: NumericArrayLike | None = None,
characteristic_impedance: float | None = None,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the transmission loss with the hard-backed absorption overlaid.

Reads the four-pole entries out as the two ASTM E2611-19 spectra a laboratory quotes: the normal-incidence transmission loss TLn(f) (Eq. (26), the primary curve, left axis) and the hard-backed absorption coefficient alpha(f) (Eq. (28), a muted companion on a 0..1 right axis). The four-pole entries carry no frequency axis of their own, so the plot needs the measurement’s frequencies vector (matching the shape of the entries) and the air characteristic impedance rho c. A matrix built by the solvers retains both (self.frequencies / self.air_characteristic_impedance), so plot() takes no arguments there; only a hand-built matrix (for example air_layer_transfer_matrix) must supply them.

Requires matplotlib (the [plot] extra); returns the Axes of the transmission-loss curve.

Parameters

Name Description
ax Existing axes, or None to create a figure.
frequencies Frequency vector f, in hertz, matching the shape of the matrix entries; None uses the stored frequencies.
characteristic_impedance Characteristic impedance rho c of the air in the tube, in rayls; None uses the stored air_characteristic_impedance.
language Plot language: "en" (default) or "es".
kwargs Forwarded to the transmission-loss plot call.

Returns: The axes.

Raises

Exception When
ValueError If frequencies or characteristic_impedance is neither supplied nor stored on the matrix.
TypeError if frequencies holds a text or a value that is not a real number.
TransferMatrix.plot_geometry(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the four-microphone tube to scale (dimensioned side view).

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

Parameters

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

Raises

Exception When
ValueError If the matrix does not retain its tube geometry (l1/s1/l2/s2/thickness_m).
TransferMatrix.reflection_hard_backed(
characteristic_impedance: float,
) -> NDArray[np.complex128]

Hard-backed reflection coefficient (ASTM E2611-19, Eq. (27)).

.

Parameters

Name Description
characteristic_impedance Characteristic impedance rho c.

Returns: Complex reflection coefficient R.

Raises

Exception When
TypeError if characteristic_impedance is not a single number.
TransferMatrix.transmission_loss(
characteristic_impedance: float,
) -> NDArray[np.float64]

Normal-incidence transmission loss in dB (ASTM E2611-19, Eq. (26)).

With

(the factor has unit magnitude for a real wavenumber).

Parameters

Name Description
characteristic_impedance Characteristic impedance rho c.

Returns: Transmission loss TLn, in decibels.

Raises

Exception When
TypeError if characteristic_impedance is not a single number.
wave_decomposition(
h1: NumericArrayLike,
h2: NumericArrayLike,
h3: NumericArrayLike,
h4: NumericArrayLike,
*,
l1: float,
s1: float,
l2: float,
s2: float,
wavenumber: NumericArrayLike,
diameter_m: float | None = None,
shape: Literal['circular', 'rectangular', 'square'] = 'circular',
) -> WaveAmplitudes

Decompose the wave field into (A, B, C, D) (ASTM E2611-19, Eqs. (17)-(20)).

The exponents are implemented exactly as printed:

A/B are the forward/backward complex amplitudes on the upstream (source) side and C/D those on the downstream side, all referenced to the front face . With the / forward- convention these exponents correspond to the microphone whose transfer function is H2 sitting nearest the front face at distance l1 (and H1 at ), and to H3 nearest the downstream side at l2 (and H4 at ), with l1, l2 measured from the front reference plane. The convention was locked down against the analytic air-layer transfer matrix (see air_layer_transfer_matrix).

Parameters

Name Description
h1 Transfer function H1,ref (upstream, farther microphone).
h2 Transfer function H2,ref (upstream, nearer microphone).
h3 Transfer function H3,ref (downstream, nearer microphone).
h4 Transfer function H4,ref (downstream, farther microphone).
l1 Distance l1 from the front reference plane, in metres.
s1 Upstream microphone spacing s1, in metres.
l2 Distance l2 from the front reference plane, in metres.
s2 Downstream microphone spacing s2, in metres.
wavenumber Air wavenumber k (real or complex), scalar or per band.
diameter_m Optional tube diameter (circular) or largest section dimension (rectangular/square), in metres, that activates the plane-wave working-range check (6.2.3-6.2.5, 6.5.4).
shape Tube cross-section, "circular", "rectangular" or "square".

Returns: The four complex amplitudes, as a WaveAmplitudes.

Raises

Exception When
TypeError if diameter_m, s1 or s2 is not a single number, or shape is not a text, or l1 or l2 is not a single number, or h1, h2, h3, h4 or wavenumber holds a text or a value that is not a number.
WaveAmplitudes(
a: NDArray[np.complex128],
b: NDArray[np.complex128],
c: NDArray[np.complex128],
d: NDArray[np.complex128],
)

The four plane-wave amplitudes of a four-microphone tube (ASTM E2611-19 Eqs. (17)-(20)).

What wave_decomposition returns: the amplitudes, named as the standard prints them, where an (A, B, C, D) tuple used to be unpacked by position. They are what face_quantities takes.

Attributes

Name Description
a A, the forward wave upstream of the specimen.
b B, the backward wave upstream.
c C, the forward wave downstream.
d D, the backward wave downstream.