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).
-
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). -
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). -
Junctions (Formula 10). , floored at 0 dB (
in_situ_velocity_level_difference). -
Paths. The direct path is (Formula 14) and each flanking path (Formula 15) is with the geometry term (
flanking_reduction_index). -
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
Section titled “airborne_flanking_path”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,) -> BandPathBuild 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
Section titled “BandPath”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
Section titled “bare_floor_impact_level”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
Section titled “bending_radiation_factor”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
Section titled “calculated_sound_reduction_index”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
Section titled “detailed_airborne_prediction”detailed_airborne_prediction( frequencies: NumericArrayLike, *, direct_index: NumericArrayLike, flanking_paths: Sequence[BandPath] = (), direct_label: str = 'Dd', fraction: Literal[1, 3] | np.integer[Any] = 3,) -> DetailedAirborneResultCombine 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
Section titled “detailed_impact_prediction”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,) -> DetailedImpactResultCombine 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
Section titled “DetailedAirborneResult”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. |
DetailedAirborneResult.dominant
Section titled “DetailedAirborneResult.dominant”property
Label of the path carrying most energy in each band.
DetailedAirborneResult.plot()
Section titled “DetailedAirborneResult.plot()”DetailedAirborneResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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()
Section titled “DetailedAirborneResult.report()”DetailedAirborneResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender 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
Section titled “DetailedImpactResult”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. |
DetailedImpactResult.dominant
Section titled “DetailedImpactResult.dominant”property
Label of the path carrying most energy in each band.
DetailedImpactResult.plot()
Section titled “DetailedImpactResult.plot()”DetailedImpactResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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()
Section titled “DetailedImpactResult.report()”DetailedImpactResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender 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
Section titled “direct_impact_level”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
Section titled “direct_reduction_index”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. |
EN12354_AIR
Section titled “EN12354_AIR”Constant (phonometry.fluids.Fluid).
flanking_impact_level
Section titled “flanking_impact_level”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
Section titled “flanking_impact_level_from_flanking_level”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
Section titled “flanking_reduction_index”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
Section titled “floating_floor_improvement”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
Section titled “forced_radiation_factor”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
Section titled “HomogeneousElement”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.
HomogeneousElement.from_solid()
Section titled “HomogeneousElement.from_solid()”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 = ...,) -> HomogeneousElementThe 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
Section titled “impact_flanking_path”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,) -> BandPathBuild 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
Section titled “in_situ_element”in_situ_element( element: HomogeneousElement, frequencies: NumericArrayLike, *, fraction: Literal[1, 3] | np.integer[Any] = 3, resonant_only: bool = False, fluid: Fluid = ...,) -> InSituElementResultEvaluate 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
Section titled “in_situ_equivalent_absorption_length”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
Section titled “in_situ_impact_level”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
Section titled “in_situ_reduction_index”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
Section titled “in_situ_total_loss_factor”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
Section titled “in_situ_velocity_level_difference”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
Section titled “InSituElementResult”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()
Section titled “InSituElementResult.plot()”InSituElementResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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
Section titled “laboratory_total_loss_factor”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
Section titled “perimeter_absorption_coefficient”perimeter_absorption_coefficient( vibration_reduction_indices: NumericArrayLike, *, critical_frequencies: NumericArrayLike,) -> floatAbsorption 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
Section titled “reciprocity_impact_level”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
Section titled “resonant_sound_reduction_index”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
Section titled “structural_reverberation_time”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. |