Ir al contenido

building.prediction.aperture_transmission

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.

Sound transmission through slits, holes and apertures (Hopkins 2007, Sound Insulation, Section 4.3.10; Gomperts 1964; Wilson & Soroka 1965).

Air paths are the real limit on the sound insulation of an otherwise heavy construction: a small slit or hole caps the achievable sound reduction index no matter how massive the wall. This module predicts the transmission coefficient tau of the two canonical apertures and combines them with the surrounding wall into a composite sound reduction index, the practical answer to “why do I never reach the catalogue Rw”.

Straight-edged slit (Hopkins Eq. 4.99, Gomperts). With the acoustic wavenumber , (w slit width), (d slit depth) and the end correction :

where (diffuse field) or 4 (normal incidence), and (slit in the middle of a plate) or 0.5 (slit along an edge). The model assumes an inviscid air path; maxima in tau (dips in R) occur at the resonances (Eq. 4.101, ).

Circular aperture (Hopkins Eq. 4.102, Wilson & Soroka). With the piston radiation resistance and reactance ( Bessel, Struve; radius a, depth d):

Composite (Hopkins Eq. 4.92). For elements of area and sound reduction index the resultant is the area-weighted energy sum

so a bare opening (, ) of relative area caps the composite at . This is the same energetic combination used by the EN 12354-3/-4 facade model of phonometry.building.prediction.facade.

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

ApertureTransmissionResult(
*,
frequencies: NDArray[np.float64],
transmission_coefficient: NDArray[np.float64],
kind: Literal['slit', 'circular'],
depth: float,
width_m: float | None = None,
radius: float | None = None,
)

Transmission through a slit or circular aperture (Hopkins 4.3.10).

Attributes

Name Description
frequencies Band centre frequencies, in hertz.
transmission_coefficient Transmission coefficient tau per band.
kind "slit" or "circular".
depth Wall thickness, in metres.
width_m Slit width, in metres, kept (with depth) so plot_geometry can draw the section; given for a slit and None for a circular aperture.
radius Circular-aperture radius, in metres; given for a circular aperture and None for a slit.
ApertureTransmissionResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the aperture sound reduction index R(f).

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

Parameters

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

ApertureTransmissionResult.plot_geometry()

Section titled “ApertureTransmissionResult.plot_geometry()”
ApertureTransmissionResult.plot_geometry(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the wall-aperture cross-section to scale.

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

Parameters

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

ApertureTransmissionResult.transmission_loss

Section titled “ApertureTransmissionResult.transmission_loss”

property

Aperture sound reduction index per band, dB.

circular_aperture_transmission_coefficient

Section titled “circular_aperture_transmission_coefficient”
circular_aperture_transmission_coefficient(
frequency: NumericArrayLike,
radius: float,
depth: float,
*,
speed_of_sound: float = 343.0,
) -> ApertureTransmissionResult

Transmission coefficient of a circular aperture (Hopkins Eq. 4.102).

Parameters

Name Description
frequency Band centre frequency f, in hertz (scalar or array, > 0).
radius Aperture radius a, in m (> 0).
depth Aperture depth d (wall thickness), in m (> 0).
speed_of_sound Speed of sound in air c0 (Default: 343 m/s).

Returns: An ApertureTransmissionResult (kind "circular").

Raises

Exception When
ValueError for a non-positive input.
TypeError if depth, radius or speed_of_sound is not a single number, or frequency holds a text or a value that is not a real number.
composite_transmission_loss(
areas: NumericArrayLike,
reduction_indices: NumericArrayLike,
) -> float | NDArray[np.float64]

Composite sound reduction index of parallel elements (Hopkins Eq. 4.92).

The area-weighted energy combination of N elements (wall, window, slit, open aperture …) sharing a partition:

A bare opening enters with ().

Parameters

Name Description
areas Element areas S_n, in m^2 (1-D, length N, all > 0).
reduction_indices Element sound reduction indices R_n, in dB. Either a 1-D array of length N (one value per element) or a 2-D array of shape (N, M) (N elements over M bands).

Returns: The composite R: a float for 1-D input, or one value per band (length M) for 2-D input.

Raises

Exception When
ValueError for a non-positive area, mismatched shapes, or an empty element set.
TypeError if areas or reduction_indices holds a text or a value that is not a real number.
plot_aperture_geometry(
depth: float,
*,
ax: Axes | None = ...,
width_m: float,
language: Literal['en', 'es'] = ...,
**kwargs: Any,
) -> Axes
plot_aperture_geometry(
depth: float,
*,
ax: Axes | None = ...,
radius: float,
language: Literal['en', 'es'] = ...,
**kwargs: Any,
) -> Axes

Draw the section through a wall aperture to scale.

Wall of thickness depth with a slit of the given width_m (or the diametral section of a circular hole of the given radius), incident sound on the left and the transmitted wavefronts sketched on the right. Give exactly one of width_m/radius, matching slit_transmission_coefficient / circular_aperture_transmission_coefficient.

Parameters

Name Description
depth Wall thickness d, in metres.
ax Existing axes, or None to create a figure.
width_m Slit width w, in metres.
radius Circular-hole radius, in metres.
language Label language, "en" (default) or "es".
kwargs Forwarded to the wall rectangles.

Returns: The axes.

Raises

Exception When
ValueError for a depth, width_m or radius that is not finite and positive, or for anything other than exactly one of width_m/radius.
TypeError if depth, radius or width_m is not a single number.
slit_resonance_frequencies(
depth: float,
width_m: float,
*,
n_orders: int | np.integer[Any] = 3,
speed_of_sound: float = 343.0,
) -> NDArray[np.float64]

Slit resonance frequencies (Hopkins Eq. 4.101).

Maxima in the transmission coefficient (dips in R) occur where the effective slit depth is a half-wavelength multiple. Solved iteratively because the end correction e depends weakly on frequency.

Parameters

Name Description
depth Slit depth d, in m (> 0).
width_m Slit width w, in m (> 0).
n_orders Number of resonance orders z = 1..n_orders (>= 1).
speed_of_sound Speed of sound in air c0 (Default: 343 m/s).

Returns: The resonance frequencies (Hz), one per order.

Raises

Exception When
ValueError for a non-positive input, an n_orders that is not a whole number from 1, or a slit so wide relative to its depth that the effective depth is non-positive (no resonance exists; width_m must be much less than the wavelength).
TypeError if depth, speed_of_sound or width_m is not a single number, or n_orders is a flag, a text or an array where a count goes.
slit_transmission_coefficient(
frequency: NumericArrayLike,
width_m: float,
depth: float,
*,
field: Literal['diffuse', 'normal'] = 'diffuse',
position: Literal['mid', 'edge'] = 'mid',
speed_of_sound: float = 343.0,
) -> ApertureTransmissionResult

Transmission coefficient of a straight-edged slit (Hopkins Eq. 4.99).

Parameters

Name Description
frequency Band centre frequency f, in hertz (scalar or array, > 0).
width_m Slit width w, in m (> 0).
depth Slit depth d (wall thickness across the slit), in m (> 0).
field "diffuse" () or "normal" ().
position "mid" () or "edge" ().
speed_of_sound Speed of sound in air c0 (Default: 343 m/s).

Returns: An ApertureTransmissionResult (kind "slit").

Raises

Exception When
ValueError for a non-positive input or unknown field/position.
TypeError if field or position is not a text, or depth, speed_of_sound or width_m is not a single number, or frequency holds a text or a value that is not a real number.
transmission_loss_from_coefficient(
tau: float | np.floating[Any] | np.integer[Any],
) -> float
transmission_loss_from_coefficient(
tau: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
transmission_loss_from_coefficient(
tau: NumericArrayLike,
) -> float | NDArray[np.float64]

Sound reduction index from a transmission coefficient.

Parameters

Name Description
tau Transmission coefficient(s) tau (> 0). Values above 1 (a resonating aperture that transmits more than the incident intensity) give a negative R.

Returns: The sound reduction index R, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for a non-positive coefficient.
TypeError if tau holds a text or a value that is not a real number.