building.prediction.aperture_transmission
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
Section titled “ApertureTransmissionResult”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()
Section titled “ApertureTransmissionResult.plot()”ApertureTransmissionResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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,) -> AxesDraw 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,) -> ApertureTransmissionResultTransmission 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
Section titled “composite_transmission_loss”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
Section titled “plot_aperture_geometry”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,) -> AxesDraw 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
Section titled “slit_resonance_frequencies”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
Section titled “slit_transmission_coefficient”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,) -> ApertureTransmissionResultTransmission 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
Section titled “transmission_loss_from_coefficient”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. |