Ir al contenido

building.prediction.detailed_model

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.

Detailed per-band building prediction (EN/ISO 12354-1/-2:2017).

This is the detailed model of the building-prediction chain, the per-band counterpart of the simplified single-number model implemented in phonometry.building.prediction.simplified_model. Where the simplified model combines the weighted ratings of the elements (Rw, ΔRw, Kij) into a single R'w / L'n,w, the detailed model carries every quantity through the one-third-octave (or octave) bands, converts the laboratory element data to their in-situ values, forms each transmission path per band and only then rates the result through ISO 717. It is what a consultant runs when the element spectra are known and the dominant path per band matters.

Chain, airborne (ISO 12354-1:2017, Clause 4.2).

  1. Element data per band. For homogeneous elements the sound reduction index follows from the material properties with the Annex B model: the radiation factor for free bending waves σ (Formulae B.4 to B.6, bending_radiation_factor), the radiation factor for forced waves σf (Formula B.3, forced_radiation_factor) and the three-branch transmission factor of Formula (B.2) (calculated_sound_reduction_index).

  2. In-situ conversion (Clause 4.2.2). The total loss factor in situ follows from Annex C Formula (C.1),

    (in_situ_total_loss_factor), with the perimeter absorption coefficients deduced from the junctions’ vibration reduction indices (Formula C.4, perimeter_absorption_coefficient). From it come the structural reverberation time (structural_reverberation_time), the in-situ index (Formula 9, in_situ_reduction_index) and the equivalent absorption length (Formula 11).

  3. Junctions (Formula 10). , floored at 0 dB (in_situ_velocity_level_difference).

  4. Paths. The direct path is (Formula 14) and each flanking path (Formula 15) is with the geometry term (flanking_reduction_index).

  5. Assembly. over the direct path and all flanking paths (Formulae 1 to 4), then R'w (C; Ctr) per ISO 717-1 (detailed_airborne_prediction).

Chain, impact (ISO 12354-2:2017, Clause 4.2). The bare floor’s normalized impact sound pressure level per band follows from Annex B Formula (B.2), (bare_floor_impact_level); the direct path is (Formula 11) and each flanking path (Formula 12) is (flanking_impact_level), combined energetically into L'n and rated L'n,w (CI) per ISO 717-2 (detailed_impact_prediction).

The two parts share the same in-situ machinery, so a building is described once (HomogeneousElement per element, in_situ_element per band) and both the airborne and the impact chain read the same InSituElementResult.

Type A and Type B elements. HomogeneousElement and in_situ_element describe a Type A element, one whose structural reverberation time is set by the elements connected to it. For a Type B element the standard takes (so no in-situ transfer is needed) and describes the junction with the normalized direction-averaged velocity level difference Dv,ij,n instead of Kij, or with a laboratory measurement of the flanking level difference Dn,f. Those branches are flanking_reduction_index_from_normalized_difference (Formula 17), flanking_impact_level_from_normalized_difference (Part 2, Formula 14) and flanking_reduction_index_from_flanking_level (Formula 16), with resonant_sound_reduction_index for the Annex B.1 correction their element indices need below fc.

Clause and formula citations refer to ISO 12354-1:2017 (airborne) or ISO 12354-2:2017 (impact). The worked example of ISO 12354-1:2017 Annex L and ISO 12354-2:2017 Annex G (one heavy homogeneous building driving both parts) is reproduced band by band in the test suite; the defects found in its printed tables are recorded in docs/ERRATA.md.

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

airborne_flanking_path(
*,
label: str,
kind: Literal['Ff', 'Df', 'Fd'],
element_i: InSituElementResult,
element_j: InSituElementResult,
vibration_reduction_index: NumericArrayLike,
coupling_length: float,
separating_area: float,
delta_r_i: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> BandPath

Build one airborne flanking path from two in-situ elements (Formula 15).

The junction velocity level difference is formed from the two elements’ equivalent absorption lengths with Formula (10), then Formula (15) gives Rij per band.

Parameters

Name Description
label Human-readable path name.
kind "Ff", "Df" or "Fd".
element_i The element excited in the source room.
element_j The element radiating in the receiving room.
vibration_reduction_index Kij of this path (per band or a single value), in dB.
coupling_length Common coupling length lij, in m.
separating_area Separating-element area Ss, in m².
delta_r_i ΔRi,situ on element i, per band, in dB.
delta_r_j ΔRj,situ on element j, per band, in dB.

Returns: The BandPath carrying Rij.

Raises

Exception When
ValueError If kind is unknown or a geometry value is not positive.
TypeError if kind is not a text.
BandPath(
*,
label: str,
kind: Literal['Dd', 'Ff', 'Df', 'Fd'],
values: NumericArrayLike,
)

One transmission path of the detailed model, per band.

Attributes

Name Description
label Human-readable path name, e.g. "ext wall 1-Df".
kind "Dd", "Ff", "Df" or "Fd".
values Rij (airborne) or Ln,ij (impact) per band, in dB.
bare_floor_impact_level(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
mass_per_area: float,
structural_reverberation_time: NumericArrayLike,
radiation_factor: NumericArrayLike,
) -> float
bare_floor_impact_level(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
mass_per_area: float,
structural_reverberation_time: NumericArrayLike,
radiation_factor: NumericArrayLike,
) -> NDArray[np.float64]
bare_floor_impact_level(
frequencies: NumericArrayLike,
*,
mass_per_area: float,
structural_reverberation_time: NumericArrayLike,
radiation_factor: NumericArrayLike,
) -> float | NDArray[np.float64]

Normalized impact level of a bare monolithic floor (Part 2, F. B.2).

with Hz, the closed form obtained with the force level of the standard tapping machine on a low-mobility floor. Supplying the in-situ structural reverberation time and radiation factor returns Ln,situ directly.

The reciprocity relation of Part 2 Formulae (B.3)/(B.4), in one-third-octave bands (43 in octave bands), holds where forced transmission is negligible and gives an independent check on the pair.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
mass_per_area Mass per unit area m' of the floor, in kg/m².
structural_reverberation_time Structural reverberation time Ts per band, in s.
radiation_factor Radiation factor for free bending waves σ per band.

Returns: The normalized impact sound pressure level Ln per band, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite or the per-band arrays do not share the band count.
TypeError if mass_per_area is not a single number, or frequencies, radiation_factor or structural_reverberation_time holds a text or a value that is not a real number.
bending_radiation_factor(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
critical_frequency: float,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> float
bending_radiation_factor(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
critical_frequency: float,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
bending_radiation_factor(
frequencies: NumericArrayLike,
*,
critical_frequency: float,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Radiation factor for free bending waves σ (Formulae B.4 to B.6).

The three candidate factors of Formula (B.4) are

  • (above the critical frequency),
  • (the plate acting as a small piston),
  • (corner and edge modes),

and the first plate mode selects between the two regimes. For the element is mode dense at its critical frequency and Formula (B.5) applies: at and above fc, and below it the edge/corner sum with and δ2 vanishing above fc/2. For Formula (B.6) picks σ3 unless σ2 (below fc) or σ1 (above fc) is smaller. Every branch is capped at .

These relations hold for a plate in an infinite baffle; the standard notes that walls and floors surrounded by orthogonal elements radiate 2 (edge modes) to 4 (corner modes) times more efficiently well below fc.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
critical_frequency Critical frequency , Hz.
length1 One side length of the rectangular element, in m.
length2 The other side length, in m.
speed_of_sound Speed of sound in air co, in m/s (Default: 340 m/s, the value ISO 12354-1 Annex A fixes).

Returns: The radiation factor σ per band (dimensionless). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If any input is not positive and finite.
TypeError if critical_frequency, length1, length2 or speed_of_sound is not a single number, or frequencies holds a text or a value that is not a real number.
calculated_sound_reduction_index(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
mass_per_area: float,
critical_frequency: float,
total_loss_factor: NumericArrayLike,
radiation_factor: NumericArrayLike,
forced_radiation_factor: NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] = ...,
resonant_only: bool = ...,
density: float | None = ...,
longitudinal_velocity: float | None = ...,
fluid: Fluid = ...,
) -> float
calculated_sound_reduction_index(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
mass_per_area: float,
critical_frequency: float,
total_loss_factor: NumericArrayLike,
radiation_factor: NumericArrayLike,
forced_radiation_factor: NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] = ...,
resonant_only: bool = ...,
density: float | None = ...,
longitudinal_velocity: float | None = ...,
fluid: Fluid = ...,
) -> NDArray[np.float64]
calculated_sound_reduction_index(
frequencies: NumericArrayLike,
*,
mass_per_area: float,
critical_frequency: float,
total_loss_factor: NumericArrayLike,
radiation_factor: NumericArrayLike,
forced_radiation_factor: NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] = ...,
resonant_only: bool = ...,
density: float | None = ...,
longitudinal_velocity: float | None = ...,
fluid: Fluid = ...,
) -> float | NDArray[np.float64]

Sound reduction index of a homogeneous element (Formulae B.2, B.10).

with the three-branch transmission factor

  • : ,
  • : ,
  • : with the forced term and the resonant term .

The branch is applied to the band whose limits straddle the critical frequency, which is how the Annex L worked example selects it.

Below the critical frequency the first term is the forced contribution. Annex B.1 requires flanking paths to use the resonant transmission only; resonant_only=True drops that term (Annex B.3: “the contribution of forced transmission can be neglected for flanking paths”). The Annex L worked example keeps it on every path, so the default is False.

High-frequency plateau (Formula B.10). At high frequency the index of a thick element stops growing; the standard bounds the transmission factor from below by . Supplying both density and longitudinal_velocity applies that floor, , as the Annex L example does from about 1250 Hz upwards on its lightweight blockwork.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
mass_per_area Mass per unit area m', in kg/m².
critical_frequency Critical frequency fc, in Hz.
total_loss_factor Total loss factor ηtot per band (laboratory or in situ, matching the situation being described).
radiation_factor Radiation factor for free bending waves σ per band (see bending_radiation_factor).
forced_radiation_factor Radiation factor for forced waves σf per band (see forced_radiation_factor); ignored when resonant_only is set.
fraction The band set, 3 for one-third octaves (default) or 1 for octaves, setting the band limits used to locate the branch. One of 1 or 3.
resonant_only Drop the forced-transmission term below fc.
density Density ρ of the material, in kg/m³; with longitudinal_velocity it enables the Formula (B.10) plateau.
longitudinal_velocity Quasi-longitudinal phase velocity cL of the material, in m/s.
fluid The medium, a Fluid (Default: EN12354_AIR, the air EN/ISO 12354 works in, 340 m/s and 1.29 kg/m3).

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

Raises

Exception When
ValueError If an input is not positive/finite or the per-band arrays do not share the band count.
TypeError if fraction is not an integer (a word, a flag or a float), critical_frequency, density, longitudinal_velocity or mass_per_area is not a single number, or forced_radiation_factor, frequencies, radiation_factor or total_loss_factor holds a text or a value that is not a real number.
detailed_airborne_prediction(
frequencies: NumericArrayLike,
*,
direct_index: NumericArrayLike,
flanking_paths: Sequence[BandPath] = (),
direct_label: str = 'Dd',
fraction: Literal[1, 3] | np.integer[Any] = 3,
) -> DetailedAirborneResult

Combine direct and flanking paths into R' per band (F. 1 to 4).

over the direct path RDd and every flanking path Rij. The result exposes each path’s share of the transmitted energy in every band, which is what identifies the path to treat first, and the ISO 717-1 rating of the resulting spectrum whenever the bands cover the rating range (100 Hz to 3150 Hz in one-third octaves, 125 Hz to 2000 Hz in octaves).

Parameters

Name Description
frequencies Band centre frequencies, in Hz.
direct_index RDd per band, in dB (see direct_reduction_index).
flanking_paths The flanking paths (see airborne_flanking_path); may be empty.
direct_label Label of the direct path (Default: "Dd").
fraction The band set, 3 for one-third octaves (default) or 1 for octaves, selecting the ISO 717-1 rating range. One of 1 or 3.

Returns: The DetailedAirborneResult.

Raises

Exception When
ValueError If a path does not match the band count.
TypeError if fraction is not an integer (a word, a flag or a float), or direct_index or frequencies holds a text or a value that is not a real number.
detailed_impact_prediction(
frequencies: NumericArrayLike,
*,
direct_level: NumericArrayLike | None = None,
flanking_paths: Sequence[BandPath] = (),
direct_label: str = 'Dd',
fraction: Literal[1, 3] | np.integer[Any] = 3,
) -> DetailedImpactResult

Combine direct and flanking paths into L'n per band (Part 2, (1)).

over the direct impact path Ln,d and every flanking path Ln,ij, with the ISO 717-2 rating of the resulting spectrum whenever the bands cover the rating range. For rooms next to each other there is no direct impact path and the sum runs over the flanking paths only (Part 2, Formula 2): leave direct_level out and the result carries no direct path at all.

Parameters

Name Description
frequencies Band centre frequencies, in Hz.
direct_level Ln,d per band, in dB (see direct_impact_level), or None for the Formula (2) case of two rooms next to each other, which has no direct path.
flanking_paths The flanking paths (see impact_flanking_path); may be empty when direct_level is given.
direct_label Label of the direct path (Default: "Dd").
fraction The band set, 3 for one-third octaves (default) or 1 for octaves, selecting the ISO 717-2 rating range. One of 1 or 3.

Returns: The DetailedImpactResult.

Raises

Exception When
ValueError If a path does not match the band count, or if neither a direct level nor any flanking path is given.
TypeError if fraction is not an integer (a word, a flag or a float), or direct_level or frequencies holds a text or a value that is not a real number.
DetailedAirborneResult(
frequencies: NDArray[np.float64],
paths: tuple[BandPath, ...],
r_prime: NDArray[np.float64],
energy_fractions: NDArray[np.float64],
rating: WeightedRatingResult | None,
)

Per-band apparent sound reduction index R' (ISO 12354-1, 4.2).

Attributes

Name Description
frequencies Band centre frequencies, in Hz.
paths Every transmission path (the direct path first), each with its Rij per band.
r_prime Apparent sound reduction index R' per band, in dB.
energy_fractions Share of the transmitted energy carried by each path per band (paths x bands), summing to 1 in every band.
rating R'w (C; Ctr) per ISO 717-1, or None when the bands supplied do not cover the rating range.

property

Label of the path carrying most energy in each band.

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

Plot the per-band path contributions and the resulting R'.

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

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the stacked bars’ Axes.bar.

Returns: The axes.

Raises

Exception When
TypeError for bottom, which the plot sets itself: each path’s share stands on the shares of the paths below it.
DetailedAirborneResult.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 detailed airborne prediction fiche (EN/ISO 12354-1).

Writes a one-page prediction report for the per-band detailed model: a basis line naming ISO 12354-1:2017 Clause 4.2, an optional metadata header, a two-panel body with the per-path energy-share table beside the per-band path-contribution figure, the boxed predicted R'w, the prediction statement and, when a requirement is supplied, a PASS/FAIL verdict, followed by the footer.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata.
engine Rendering back end; only "reportlab" is supported.
verbose When True the path table also gives the band in which each path contributes most.
language "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine/language is unknown or the result carries no ISO 717-1 rating.
ImportError If reportlab or matplotlib is missing.
DetailedImpactResult(
frequencies: NDArray[np.float64],
paths: tuple[BandPath, ...],
l_prime_n: NDArray[np.float64],
energy_fractions: NDArray[np.float64],
rating: ImpactRatingResult | None,
)

Per-band apparent impact level L'n (ISO 12354-2, 4.2).

Attributes

Name Description
frequencies Band centre frequencies, in Hz.
paths Every transmission path (the direct path first), each with its Ln,ij per band.
l_prime_n Apparent normalized impact level L'n per band, in dB.
energy_fractions Share of the radiated energy carried by each path per band (paths x bands), summing to 1 in every band.
rating L'n,w (CI) per ISO 717-2, or None when the bands supplied do not cover the rating range.

property

Label of the path carrying most energy in each band.

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

Plot the per-band path contributions and the resulting L'n.

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

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the stacked bars’ Axes.bar.

Returns: The axes.

Raises

Exception When
TypeError for bottom, which the plot sets itself: each path’s share stands on the shares of the paths below it.
DetailedImpactResult.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 detailed impact prediction fiche (EN/ISO 12354-2).

The impact counterpart of DetailedAirborneResult.report: the per-band detailed model of ISO 12354-2:2017 Clause 4.2, with the boxed predicted L'n,w and a PASS/FAIL verdict against a requirement (a lower level passing).

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata.
engine Rendering back end; only "reportlab" is supported.
verbose When True the path table also gives the band in which each path contributes most.
language "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine/language is unknown or the result carries no ISO 717-2 rating.
ImportError If reportlab or matplotlib is missing.
direct_impact_level(
floor_level: float | np.floating[Any] | np.integer[Any],
*,
delta_l: float | np.floating[Any] | np.integer[Any] = ...,
delta_l_ceiling: float | np.floating[Any] | np.integer[Any] = ...,
) -> float
direct_impact_level(
floor_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
delta_l: NumericArrayLike = ...,
delta_l_ceiling: NumericArrayLike = ...,
) -> NDArray[np.float64]
direct_impact_level(
floor_level: float | np.floating[Any] | np.integer[Any],
*,
delta_l: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
delta_l_ceiling: NumericArrayLike = ...,
) -> NDArray[np.float64]
direct_impact_level(
floor_level: float | np.floating[Any] | np.integer[Any],
*,
delta_l: float | np.floating[Any] | np.integer[Any] = ...,
delta_l_ceiling: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
direct_impact_level(
floor_level: NumericArrayLike,
*,
delta_l: NumericArrayLike = ...,
delta_l_ceiling: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Normalized impact level of the direct path Ln,d (Part 2, F. 11).

: the in-situ level of the bare floor reduced by the floor covering and by any additional layer on the receiving side (a suspended ceiling).

Parameters

Name Description
floor_level Ln,situ of the bare separating floor, per band, dB.
delta_l Improvement of the floor covering ΔLsitu, per band, dB.
delta_l_ceiling Improvement ΔLd,situ of a layer on the receiving side, per band, in dB.

Returns: Ln,d per band, in dB. A float when floor_level, delta_l and delta_l_ceiling are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if delta_l, delta_l_ceiling or floor_level holds a text or a value that is not a real number.
direct_reduction_index(
separating_index: float | np.floating[Any] | np.integer[Any],
*,
delta_r_source: float | np.floating[Any] | np.integer[Any] = ...,
delta_r_receiving: float | np.floating[Any] | np.integer[Any] = ...,
) -> float
direct_reduction_index(
separating_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
delta_r_source: NumericArrayLike = ...,
delta_r_receiving: NumericArrayLike = ...,
) -> NDArray[np.float64]
direct_reduction_index(
separating_index: float | np.floating[Any] | np.integer[Any],
*,
delta_r_source: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
delta_r_receiving: NumericArrayLike = ...,
) -> NDArray[np.float64]
direct_reduction_index(
separating_index: float | np.floating[Any] | np.integer[Any],
*,
delta_r_source: float | np.floating[Any] | np.integer[Any] = ...,
delta_r_receiving: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
direct_reduction_index(
separating_index: NumericArrayLike,
*,
delta_r_source: NumericArrayLike = ...,
delta_r_receiving: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Sound reduction index of the direct path RDd (Formula 14).

: the in-situ index of the separating element plus the improvement of any lining on its source and receiving faces (for the in-situ improvement the standard accepts the laboratory value, Formula 8).

Parameters

Name Description
separating_index Rs,situ per band, in dB.
delta_r_source ΔRD,situ on the source side, per band, in dB.
delta_r_receiving ΔRd,situ on the receiving side, in dB.

Returns: RDd per band, in dB. A float when separating_index, delta_r_source and delta_r_receiving are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if delta_r_receiving, delta_r_source or separating_index holds a text or a value that is not a real number.

Constant (phonometry.fluids.Fluid).

flanking_impact_level(
*,
floor_level: NumericArrayLike,
index_i: NumericArrayLike,
index_j: NumericArrayLike,
velocity_level_difference: NumericArrayLike,
area_i: float,
area_j: float,
delta_l: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Flanking normalized impact level Ln,ij per band (Part 2, F. 12).

with the geometry term , i the excited floor and j the flanking element radiating in the receiving room.

Parameters

Name Description
floor_level Ln,situ of the excited floor, per band, in dB.
index_i Ri,situ of the excited floor, per band, in dB.
index_j Rj,situ of the flanking element, per band, in dB.
velocity_level_difference Dv,ij,situ per band, in dB.
area_i Area Si of the excited floor, in m².
area_j Area Sj of the flanking element, in m².
delta_l Improvement of the floor covering ΔLsitu, in dB.
delta_r_j Improvement ΔRj,situ of a lining on the flanking element, per band, in dB.

Returns: Ln,ij per band, in dB. A float when floor_level, index_i, index_j, velocity_level_difference, delta_l and delta_r_j are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an area is not positive and finite.
TypeError if area_i or area_j is not a single number, or delta_l, delta_r_j, floor_level, index_i, index_j or velocity_level_difference holds a text or a value that is not a real number.
flanking_impact_level_from_flanking_level(
normalized_flanking_impact_level: float | np.floating[Any] | np.integer[Any],
*,
area: float,
laboratory_area: float,
coupling_length: float,
laboratory_coupling_length: float,
) -> float
flanking_impact_level_from_flanking_level(
normalized_flanking_impact_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
area: float,
laboratory_area: float,
coupling_length: float,
laboratory_coupling_length: float,
) -> NDArray[np.float64]
flanking_impact_level_from_flanking_level(
normalized_flanking_impact_level: NumericArrayLike,
*,
area: float,
laboratory_area: float,
coupling_length: float,
laboratory_coupling_length: float,
) -> float | NDArray[np.float64]

Flanking impact level from a measured Ln,f (Part 2, Formula 13).

, the impact twin of the airborne flanking_reduction_index_from_flanking_level: the route used when the flanking construction is characterised as a whole by a laboratory measurement of the normalized flanking impact sound pressure level (ISO 10848) instead of by the properties of its elements. The laboratory measurement is transferred to the field situation first, as ISO 12354-2:2017, Annex D indicates.

Parameters

Name Description
normalized_flanking_impact_level Ln,f,ij,situ per band, in dB.
area In-situ area Si of the excited floor, in m².
laboratory_area Laboratory area Si,lab of the excited floor, in m².
coupling_length In-situ coupling length lij, in m.
laboratory_coupling_length Laboratory coupling length llab, in m. ISO 12354-1 Clause 4.4.2 gives the usual values: 4.5 m for horizontal flanking elements, 2.5 m for vertical ones.

Returns: Ln,ij per band, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a geometry value is not positive and finite.
TypeError if area, coupling_length, laboratory_area or laboratory_coupling_length is not a single number, or normalized_flanking_impact_level holds a text or a value that is not a real number.

flanking_impact_level_from_normalized_difference

Section titled “flanking_impact_level_from_normalized_difference”
flanking_impact_level_from_normalized_difference(
*,
floor_level: NumericArrayLike,
index_i: NumericArrayLike,
index_j: NumericArrayLike,
normalized_velocity_level_difference: NumericArrayLike,
area_i: float,
coupling_length: float,
delta_l: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Flanking impact level of a Type B junction (Part 2, Formula 14).

with the reference length m: Formula (12) with the junction described by the normalized direction-averaged velocity level difference instead of Kij, the form used for lightweight constructions.

Parameters

Name Description
floor_level Ln,ii of the excited bare floor, per band, in dB.
index_i Ri of the excited floor, per band, in dB.
index_j Rj of the flanking element, per band, in dB.
normalized_velocity_level_difference Dv,ij,n per band, in dB.
area_i Area Si of the excited floor, in m².
coupling_length Common coupling length lij, in m.
delta_l Improvement of the floor covering ΔLi, per band, dB.
delta_r_j Improvement ΔRj of a lining on the flanking element, per band, in dB.

Returns: Ln,ij per band, in dB. A float when floor_level, index_i, index_j, normalized_velocity_level_difference, delta_l and delta_r_j are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a geometry value is not positive and finite.
TypeError if area_i or coupling_length is not a single number, or delta_l, delta_r_j, floor_level, index_i, index_j or normalized_velocity_level_difference holds a text or a value that is not a real number.
flanking_reduction_index(
*,
index_i: NumericArrayLike,
index_j: NumericArrayLike,
velocity_level_difference: NumericArrayLike,
separating_area: float,
area_i: float,
area_j: float,
delta_r_i: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Flanking sound reduction index Rij per band (Formula 15).

for ij = Ff, Fd, Df, with the geometry term . For diagonal transmission the standard fixes m².

The element indices depend on the path: Ff takes the flanking element on both sides, Fd the flanking element as i and the separating element as j, and Df the separating element as i and the flanking element as j.

Parameters

Name Description
index_i Ri,situ of the element excited in the source room, in dB per band.
index_j Rj,situ of the radiating element in the receiving room, per band, in dB.
velocity_level_difference Dv,ij,situ per band, in dB (see in_situ_velocity_level_difference; for a Type B junction pass the Formula (12) value derived from Dv,ij,n).
separating_area Separating-element area Ss, in m².
area_i Area Si of element i, in m².
area_j Area Sj of element j, in m².
delta_r_i ΔRi,situ on element i, per band, in dB.
delta_r_j ΔRj,situ on element j, per band, in dB.

Returns: Rij per band, in dB. A float when index_i, index_j, velocity_level_difference, delta_r_i and delta_r_j are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an area is not positive and finite.
TypeError if area_i, area_j or separating_area is not a single number, or delta_r_i, delta_r_j, index_i, index_j or velocity_level_difference holds a text or a value that is not a real number.

flanking_reduction_index_from_flanking_level

Section titled “flanking_reduction_index_from_flanking_level”
flanking_reduction_index_from_flanking_level(
flanking_level_difference: float | np.floating[Any] | np.integer[Any],
*,
separating_area: float,
coupling_length: float,
laboratory_coupling_length: float,
reference_absorption_area: float = ...,
) -> float
flanking_reduction_index_from_flanking_level(
flanking_level_difference: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
separating_area: float,
coupling_length: float,
laboratory_coupling_length: float,
reference_absorption_area: float = ...,
) -> NDArray[np.float64]
flanking_reduction_index_from_flanking_level(
flanking_level_difference: NumericArrayLike,
*,
separating_area: float,
coupling_length: float,
laboratory_coupling_length: float,
reference_absorption_area: float = ...,
) -> float | NDArray[np.float64]

Flanking index from a measured Dn,f (Formula 16).

with m², the route used when the flanking construction is characterised as a whole by a laboratory measurement of the flanking normalized level difference (ISO 10848). ISO 12354-1 Clause 4.4.2 gives the usual laboratory coupling lengths: 4.5 m for horizontal flanking elements such as ceilings, 2.5 m for vertical ones such as facades.

Parameters

Name Description
flanking_level_difference Dn,f,ij,situ per band, in dB.
separating_area Separating-element area Ss, in m².
coupling_length In-situ coupling length lij, in m.
laboratory_coupling_length Laboratory coupling length llab, m.
reference_absorption_area Ao, in m² (Default: 10 m²).

Returns: Rij per band, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a geometry value is not positive and finite.
TypeError if coupling_length, laboratory_coupling_length, reference_absorption_area or separating_area is not a single number, or flanking_level_difference holds a text or a value that is not a real number.

flanking_reduction_index_from_normalized_difference

Section titled “flanking_reduction_index_from_normalized_difference”
flanking_reduction_index_from_normalized_difference(
*,
index_i: NumericArrayLike,
index_j: NumericArrayLike,
normalized_velocity_level_difference: NumericArrayLike,
separating_area: float,
coupling_length: float,
delta_r_i: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Flanking index of a Type B junction Rij (Formula 17).

with the geometry term and the reference length m. It is Formula (15) with Formula (12) substituted, so the junction is described by the normalized direction-averaged velocity level difference Dv,ij,n (ISO 12354-1 Annex F) rather than by Kij: the form used for lightweight double-leaf constructions, where the indices refer either to the double element as a whole or to its inner leaf and should relate to resonant transmission only (see resonant_sound_reduction_index).

Parameters

Name Description
index_i Ri,situ of the element excited in the source room, in dB per band.
index_j Rj,situ of the radiating element, per band, in dB.
normalized_velocity_level_difference Dv,ij,n per band, in dB.
separating_area Separating-element area Ss, in m².
coupling_length Common coupling length lij, in m.
delta_r_i ΔRi,situ on element i, per band, in dB.
delta_r_j ΔRj,situ on element j, per band, in dB.

Returns: Rij per band, in dB. A float when index_i, index_j, normalized_velocity_level_difference, delta_r_i and delta_r_j are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a geometry value is not positive and finite.
TypeError if coupling_length or separating_area is not a single number, or delta_r_i, delta_r_j, index_i, index_j or normalized_velocity_level_difference holds a text or a value that is not a real number.
floating_floor_improvement(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
resonance_frequency: float,
slope: float = ...,
) -> float
floating_floor_improvement(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
resonance_frequency: float,
slope: float = ...,
) -> NDArray[np.float64]
floating_floor_improvement(
frequencies: NumericArrayLike,
*,
resonance_frequency: float,
slope: float = ...,
) -> float | NDArray[np.float64]

Improvement of a floating floor ΔL per band (Part 2, Formula C.1).

for sand/cement or calcium-sulfate screeds and (slope=40, Formula C.3) for asphalt or dry floating floors, with the system resonance (Formula C.2) and no improvement at or below it. The Annex L airborne example reuses the same curve as ΔR, noting explicitly that assuming is rough.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
resonance_frequency Resonance frequency fo, in Hz.
slope 30 (screed, Formula C.1) or 40 (asphalt/dry, Formula C.3).

Returns: The improvement ΔL per band, in dB (0 at and below fo). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive and finite.
TypeError if resonance_frequency or slope is not a single number, or frequencies holds a text or a value that is not a real number.
forced_radiation_factor(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> float
forced_radiation_factor(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
forced_radiation_factor(
frequencies: NumericArrayLike,
*,
length1: float,
length2: float,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Radiation factor for forced waves σf (Formula B.3).

capped at , with and, for ,

with .

ISO 12354-1:2017 Table B.1 tabulates for the two standard laboratory openings (2 m² and 10 m²), which this implementation reproduces.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
length1 One side length of the rectangular element, in m.
length2 The other side length, in m.
speed_of_sound Speed of sound in air co, in m/s (Default: 340 m/s).

Returns: The forced radiation factor σf per band (dimensionless), clipped to (the standard prints only the upper bound; the lower one guards the deep low-frequency extrapolation, where the logarithm turns negative). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If any input is not positive and finite.
TypeError if length1, length2 or speed_of_sound is not a single number, or frequencies holds a text or a value that is not a real number.
HomogeneousElement(
*,
label: str,
area: float,
length1: float,
length2: float,
mass_per_area: float,
critical_frequency: float,
internal_loss_factor: float = 0.01,
perimeter_absorption: float = 0.0,
density: float | None = None,
longitudinal_velocity: float | None = None,
)

A Type A homogeneous element of the detailed model.

Attributes

Name Description
label Human-readable element name, e.g. "separating floor".
area Element area S, in m².
length1 One side length of the rectangular element, in m.
length2 The other side length, in m.
mass_per_area Mass per unit area m', in kg/m².
critical_frequency Critical frequency fc, in Hz.
internal_loss_factor Internal loss factor ηint of the material (about 0.01 for common homogeneous building materials; ISO 12354-1 Table B.3 tabulates it per material).
perimeter_absorption over the element’s perimeter, in m (Formula C.1; build it from perimeter_absorption_coefficient times the border lengths).
density Density ρ of the material, in kg/m³; supplied together with longitudinal_velocity it enables the high-frequency plateau of Formula (B.10). None (the default) leaves the plateau off.
longitudinal_velocity Quasi-longitudinal phase velocity cL of the material, in m/s (ISO 12354-1 Table B.3).

from_solid builds one from a solid’s catalogue row and the element’s thickness, and works out m' and fc itself.

classmethod

HomogeneousElement.from_solid(
row: SolidMaterial,
*,
thickness_m: float,
internal_loss_factor: float,
area: float,
length1: float,
length2: float,
perimeter_absorption: float = 0.0,
label: str = '',
fluid: Fluid = ...,
) -> HomogeneousElement

The element a layer of a solid’s catalogue row makes.

Annex B describes a homogeneous element by the material properties Table B.3 lists, the density and the quasi-longitudinal phase velocity of a plate, and by its thickness : the mass per unit area is and the critical frequency (ISO 12354-1:2017, the symbols of Formula (B.2)). A row’s plate speed is that , read with its density through printed, so a cell the page leaves empty or prints as a range is refused in the page’s terms; a row whose page prints a modulus and a Poisson ratio instead holds the plate speed its completion works out of them, marked as derived. The element carries both properties, so the high-frequency limit of Formula (B.10) applies to it.

The internal loss factor is never read from the row. A solid’s row holds up to four loss factors (flexural, longitudinal, in situ and one the page does not say which), and only the caller knows which of them, if any, is the of Annex C: pass row.printed("flexural_loss_factor"), a value of Table B.3 or a measured one.

Parameters

Name Description
row A SolidMaterial, one of PUBLISHED_SOLIDS or one read from a catalogue file of your own.
thickness_m Element thickness t, in metres.
internal_loss_factor Internal loss factor ηint.
area Element area S, in m².
length1 One side length of the rectangular element, in m.
length2 The other side length, in m.
perimeter_absorption over the element’s perimeter, in m (Default: 0).
label The element’s name (Default: the row’s name).
fluid The air whose speed of sound co enters fc (Default: EN12354_AIR, the 340 m/s of Annex A).

Returns: The HomogeneousElement.

Raises

Exception When
TypeError for a row that is not a SolidMaterial, or a thickness_m or internal_loss_factor that is not one number.
ValueError for a thickness or a loss factor that is not positive and finite, or for a density or a plate speed the row holds no number for, in the row’s own terms.
impact_flanking_path(
*,
label: str,
floor: InSituElementResult,
element_j: InSituElementResult,
vibration_reduction_index: NumericArrayLike,
coupling_length: float,
delta_l: NumericArrayLike = 0.0,
delta_r_j: NumericArrayLike = 0.0,
) -> BandPath

Build one impact flanking path Df (Part 2, Formula 12).

Parameters

Name Description
label Human-readable path name.
floor The excited separating floor, in situ.
element_j The flanking element radiating in the receiving room.
vibration_reduction_index Kij of this path, in dB.
coupling_length Common coupling length lij, in m.
delta_l Improvement of the floor covering ΔLsitu, in dB.
delta_r_j ΔRj,situ of a lining on the flanking element, in dB.

Returns: The BandPath carrying Ln,ij.

Raises

Exception When
ValueError If a geometry value is not positive and finite.
in_situ_element(
element: HomogeneousElement,
frequencies: NumericArrayLike,
*,
fraction: Literal[1, 3] | np.integer[Any] = 3,
resonant_only: bool = False,
fluid: Fluid = ...,
) -> InSituElementResult

Evaluate one homogeneous element in situ, per band (Clause 4.2.2).

Runs the whole Annex B / Annex C chain in one call: the two radiation factors, the in-situ total loss factor and structural reverberation time, the equivalent absorption length, the calculated in-situ sound reduction index and, for a floor, the calculated in-situ normalized impact level.

Because the element performance is calculated from material properties, the in-situ loss factor enters Formula (B.2) directly and no transfer is needed (Annex B.3). Use in_situ_reduction_index instead when the element data come from a laboratory measurement.

Parameters

Name Description
element The HomogeneousElement description.
frequencies Band centre frequencies, in Hz.
fraction The band set, 3 for one-third octaves (default) or 1 for octaves. One of 1 or 3.
resonant_only Drop the forced-transmission term of Formula (B.2) below fc (Annex B.1, flanking paths).
fluid The medium, a Fluid (Default: EN12354_AIR, the air EN/ISO 12354 works in, 340 m/s and 1.29 kg/m3).

Returns: The InSituElementResult.

Raises

Exception When
ValueError If any element property is not positive and finite.
TypeError if frequencies holds a text or a value that is not a real number, or fraction is not an integer (a word, a flag or a float).
in_situ_equivalent_absorption_length(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
area: float,
situ_reverberation_time: NumericArrayLike,
speed_of_sound: float = ...,
) -> float
in_situ_equivalent_absorption_length(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
area: float,
situ_reverberation_time: NumericArrayLike,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
in_situ_equivalent_absorption_length(
frequencies: NumericArrayLike,
*,
area: float,
situ_reverberation_time: NumericArrayLike,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

In-situ equivalent absorption length asitu (Formula 11).

with Hz. Note the dependence: the absorption length grows as the element rings shorter at high frequency. For a Type B element the standard replaces it by the element area, (Formula 13).

This is the ISO 10848 Formula (12) quantity (phonometry.building.equivalent_absorption_length) evaluated with the ISO 12354 value m/s.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
area Element area S, in m².
situ_reverberation_time Ts,situ per band, in s.
speed_of_sound Speed of sound in air co, in m/s.

Returns: The equivalent absorption length asitu per band, in m. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite or the band counts disagree.
TypeError if frequencies or situ_reverberation_time holds a text or a value that is not a real number.
in_situ_impact_level(
impact_level: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: float | np.floating[Any] | np.integer[Any],
laboratory_reverberation_time: float | np.floating[Any] | np.integer[Any],
) -> float
in_situ_impact_level(
impact_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
situ_reverberation_time: NumericArrayLike,
laboratory_reverberation_time: NumericArrayLike,
) -> NDArray[np.float64]
in_situ_impact_level(
impact_level: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
laboratory_reverberation_time: NumericArrayLike,
) -> NDArray[np.float64]
in_situ_impact_level(
impact_level: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: float | np.floating[Any] | np.integer[Any],
laboratory_reverberation_time: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
in_situ_impact_level(
impact_level: NumericArrayLike,
situ_reverberation_time: NumericArrayLike,
laboratory_reverberation_time: NumericArrayLike,
) -> float | NDArray[np.float64]

In-situ normalized impact level Ln,situ (Part 2, Formula 5).

, the sign opposite to in_situ_reduction_index: a floor that rings longer in the building than in the laboratory radiates more impact sound.

Parameters

Name Description
impact_level Laboratory level Ln per band, in dB.
situ_reverberation_time Ts,situ per band, in s.
laboratory_reverberation_time Ts,lab per band, in s.

Returns: The in-situ level Ln,situ per band, in dB. A float when impact_level, situ_reverberation_time and laboratory_reverberation_time are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a reverberation time is not positive/finite or the band counts disagree.
TypeError if impact_level, laboratory_reverberation_time or situ_reverberation_time holds a text or a value that is not a real number.
in_situ_reduction_index(
sound_reduction_index: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: float | np.floating[Any] | np.integer[Any],
laboratory_reverberation_time: float | np.floating[Any] | np.integer[Any],
) -> float
in_situ_reduction_index(
sound_reduction_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
situ_reverberation_time: NumericArrayLike,
laboratory_reverberation_time: NumericArrayLike,
) -> NDArray[np.float64]
in_situ_reduction_index(
sound_reduction_index: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
laboratory_reverberation_time: NumericArrayLike,
) -> NDArray[np.float64]
in_situ_reduction_index(
sound_reduction_index: float | np.floating[Any] | np.integer[Any],
situ_reverberation_time: float | np.floating[Any] | np.integer[Any],
laboratory_reverberation_time: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
in_situ_reduction_index(
sound_reduction_index: NumericArrayLike,
situ_reverberation_time: NumericArrayLike,
laboratory_reverberation_time: NumericArrayLike,
) -> float | NDArray[np.float64]

In-situ sound reduction index Rsitu (Formula 9).

: an element that is better damped in the building than in the test frame radiates less and gains index. The standard notes that is a usable first approximation, and the correction is exactly zero for Type B elements (Clause 4.2.2.3).

Parameters

Name Description
sound_reduction_index Laboratory index R per band, in dB.
situ_reverberation_time In-situ structural reverberation time Ts,situ per band, in s.
laboratory_reverberation_time Laboratory structural reverberation time Ts,lab per band, in s.

Returns: The in-situ index Rsitu per band, in dB. A float when sound_reduction_index, situ_reverberation_time and laboratory_reverberation_time are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a reverberation time is not positive/finite or the band counts disagree.
TypeError if laboratory_reverberation_time, situ_reverberation_time or sound_reduction_index holds a text or a value that is not a real number.
in_situ_total_loss_factor(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
internal_loss_factor: float,
mass_per_area: float,
area: float,
critical_frequency: float,
radiation_factor: NumericArrayLike,
perimeter_absorption: float,
fluid: Fluid = ...,
) -> float
in_situ_total_loss_factor(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
internal_loss_factor: float,
mass_per_area: float,
area: float,
critical_frequency: float,
radiation_factor: NumericArrayLike,
perimeter_absorption: float,
fluid: Fluid = ...,
) -> NDArray[np.float64]
in_situ_total_loss_factor(
frequencies: NumericArrayLike,
*,
internal_loss_factor: float,
mass_per_area: float,
area: float,
critical_frequency: float,
radiation_factor: NumericArrayLike,
perimeter_absorption: float,
fluid: Fluid = ...,
) -> float | NDArray[np.float64]

Total loss factor in situ ηtot,situ (Formula C.1).

: the internal losses of the material, the losses by radiation into the air and the losses at the perimeter of the element. is the junction-length-weighted sum of the Formula (C.4) absorption coefficients (see perimeter_absorption_coefficient).

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
internal_loss_factor Internal loss factor ηint of the material (about 0.01 for common homogeneous building materials).
mass_per_area Mass per unit area m', in kg/m².
area Element area S, in m².
critical_frequency Critical frequency fc, in Hz.
radiation_factor Radiation factor σ per band.
perimeter_absorption over the element’s perimeter, in m (may be zero for a free-edged element).
fluid The medium, a Fluid (Default: EN12354_AIR, the air EN/ISO 12354 works in, 340 m/s and 1.29 kg/m3).

Returns: The total loss factor ηtot,situ per band (dimensionless). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite, the perimeter sum is negative, or the band counts disagree.
TypeError if area, critical_frequency, internal_loss_factor, mass_per_area or perimeter_absorption is not a single number, or frequencies or radiation_factor holds a text or a value that is not a real number.
in_situ_velocity_level_difference(
vibration_reduction_index: NumericArrayLike,
*,
coupling_length: float,
absorption_length_i: float | np.floating[Any] | np.integer[Any],
absorption_length_j: float | np.floating[Any] | np.integer[Any],
) -> float
in_situ_velocity_level_difference(
vibration_reduction_index: NumericArrayLike,
*,
coupling_length: float,
absorption_length_i: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
absorption_length_j: NumericArrayLike,
) -> NDArray[np.float64]
in_situ_velocity_level_difference(
vibration_reduction_index: NumericArrayLike,
*,
coupling_length: float,
absorption_length_i: float | np.floating[Any] | np.integer[Any],
absorption_length_j: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
in_situ_velocity_level_difference(
vibration_reduction_index: NumericArrayLike,
*,
coupling_length: float,
absorption_length_i: NumericArrayLike,
absorption_length_j: NumericArrayLike,
) -> float | NDArray[np.float64]

In-situ velocity level difference Dv,ij,situ (Formula 10).

, floored at 0 dB as the formula prescribes. It converts the situation-invariant junction descriptor Kij (ISO 12354-1 Annex E, or measured per ISO 10848) into the level drop the junction actually produces between the two elements as built.

Parameters

Name Description
vibration_reduction_index Kij per band (or a single value broadcast to all bands), in dB.
coupling_length Common coupling length lij, in m.
absorption_length_i ai,situ per band, in m.
absorption_length_j aj,situ per band, in m.

Returns: Dv,ij,situ per band, in dB (never negative). A float when absorption_length_i and absorption_length_j are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a length is not positive/finite or the band counts disagree.
TypeError if coupling_length is not a single number, or absorption_length_i, absorption_length_j or vibration_reduction_index holds a text or a value that is not a real number.
InSituElementResult(
label: str,
frequencies: NDArray[np.float64],
area: float,
radiation_factor: NDArray[np.float64],
forced_radiation_factor: NDArray[np.float64],
total_loss_factor: NDArray[np.float64],
reverberation_time: NDArray[np.float64],
absorption_length: NDArray[np.float64],
sound_reduction_index: NDArray[np.float64],
impact_level: NDArray[np.float64],
)

Per-band in-situ description of one element (Clause 4.2.2).

Attributes

Name Description
label The element name.
frequencies Band centre frequencies, in Hz.
area Element area S, in m².
radiation_factor Radiation factor for free bending waves σ.
forced_radiation_factor Radiation factor for forced waves σf.
total_loss_factor In-situ total loss factor ηtot,situ.
reverberation_time In-situ structural reverberation time Ts,situ, in s.
absorption_length In-situ equivalent absorption length asitu, in m.
sound_reduction_index In-situ sound reduction index Rsitu, dB.
impact_level In-situ normalized impact level Ln,situ of the bare element, in dB (meaningful for the excited floor).
InSituElementResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the in-situ Rsitu and Ln,situ spectra of the element.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
laboratory_total_loss_factor(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
mass_per_area: float,
internal_loss_factor: float = ...,
) -> float
laboratory_total_loss_factor(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
mass_per_area: float,
internal_loss_factor: float = ...,
) -> NDArray[np.float64]
laboratory_total_loss_factor(
frequencies: NumericArrayLike,
*,
mass_per_area: float,
internal_loss_factor: float = ...,
) -> float | NDArray[np.float64]

Total loss factor in the laboratory ηtot,lab (Formula C.3).

, the estimate for the heavy test frame of an ISO 10140 facility. The relation holds for elements below kg/m² and ηint can normally be taken as 0.01.

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
mass_per_area Mass per unit area m', in kg/m².
internal_loss_factor Internal loss factor ηint (Default: 0.01).

Returns: The laboratory total loss factor per band (dimensionless). A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive and finite.
TypeError if internal_loss_factor or mass_per_area is not a single number, or frequencies holds a text or a value that is not a real number.
perimeter_absorption_coefficient(
vibration_reduction_indices: NumericArrayLike,
*,
critical_frequencies: NumericArrayLike,
) -> float

Absorption coefficient for bending waves at one border (Formula C.4).

summed over the elements j connected to the considered element at border k (the standard sums over at most three). Multiplied by the border length and summed over the perimeter it gives the that in_situ_total_loss_factor takes. Annex C.3 places the in-situ coefficients between 0.05 and 0.5.

Parameters

Name Description
vibration_reduction_indices Vibration reduction index Kij of the path to each connected element, in dB.
critical_frequencies Critical frequency fc,j of each connected element, in Hz (same order and length).

Returns: The absorption coefficient αk at that border (dimensionless).

Raises

Exception When
ValueError If the two sequences differ in length, a critical frequency is not positive, or an index is not finite.
TypeError if critical_frequencies or vibration_reduction_indices holds a text or a value that is not a real number.
reciprocity_impact_level(
sound_reduction_index: NumericArrayLike,
*,
frequencies: float | np.floating[Any] | np.integer[Any],
fraction: Literal[1, 3] | np.integer[Any] = ...,
) -> float
reciprocity_impact_level(
sound_reduction_index: NumericArrayLike,
*,
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
fraction: Literal[1, 3] | np.integer[Any] = ...,
) -> NDArray[np.float64]
reciprocity_impact_level(
sound_reduction_index: NumericArrayLike,
*,
frequencies: NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] = ...,
) -> float | NDArray[np.float64]

Impact level of a homogeneous floor by reciprocity (Part 2, B.3/B.4).

in one-third-octave bands and in octave bands: for a homogeneous floor the sum of the airborne index and the normalized impact level depends only on frequency, provided forced transmission is negligible (normally up to about 1 kHz, above which the stiffness of the floor’s top layer matters).

Parameters

Name Description
sound_reduction_index R of the floor per band, in dB.
frequencies Band centre frequencies, in Hz.
fraction The band set, 3 for one-third octaves (default, constant 38) or 1 for octaves (43). One of 1 or 3.

Returns: The normalized impact sound pressure level Ln per band, dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite or the band counts disagree.
TypeError if fraction is not an integer (a word, a flag or a float), or frequencies or sound_reduction_index holds a text or a value that is not a real number.
resonant_sound_reduction_index(
sound_reduction_index: NumericArrayLike,
*,
frequencies: float | np.floating[Any] | np.integer[Any],
critical_frequency: float,
correction: NumericArrayLike = ...,
) -> float
resonant_sound_reduction_index(
sound_reduction_index: NumericArrayLike,
*,
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
critical_frequency: float,
correction: NumericArrayLike = ...,
) -> NDArray[np.float64]
resonant_sound_reduction_index(
sound_reduction_index: NumericArrayLike,
*,
frequencies: NumericArrayLike,
critical_frequency: float,
correction: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Correct a measured R to resonant transmission only (Formula B.1).

. No standardized method exists to measure the two radiation factors, so Annex B.2 gives the estimate this function applies: no correction for elements separated by one or two cavities, and a fixed correction (8 dB, the standard’s figure for single homogeneous or layered wood or steel frame elements without a cavity) below the critical frequency only. Above fc the laboratory index already describes resonant transmission and is returned unchanged.

Parameters

Name Description
sound_reduction_index Measured index R per band, in dB.
frequencies Band centre frequencies, in Hz.
critical_frequency Critical frequency fc, in Hz.
correction Correction applied below fc, in dB, one value or one per band (Default: 8 dB; Annex B.2 caps the estimate of Formula (B.8) at this value, and the Annex L lightweight example reduces it around the cavity resonance).

Returns: The resonant-only index R* per band, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite or the band counts disagree.
TypeError if critical_frequency is not a single number, or correction, frequencies or sound_reduction_index holds a text or a value that is not a real number.
structural_reverberation_time(
total_loss_factor: NumericArrayLike,
*,
frequencies: float | np.floating[Any] | np.integer[Any],
) -> float
structural_reverberation_time(
total_loss_factor: NumericArrayLike,
*,
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
structural_reverberation_time(
total_loss_factor: NumericArrayLike,
*,
frequencies: NumericArrayLike,
) -> float | NDArray[np.float64]

Structural reverberation time (C.1).

Parameters

Name Description
frequencies Band centre frequencies f, in Hz.
total_loss_factor Total loss factor ηtot per band.

Returns: The structural reverberation time Ts per band, in s. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If an input is not positive/finite or the band counts disagree.
TypeError if frequencies or total_loss_factor holds a text or a value that is not a real number.