Ir al contenido

building.prediction.facade

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.

Façade sound insulation and outdoor radiation prediction (EN 12354-3/-4:2000).

Two companion prediction models for the building envelope, both built on the same energy summation of element transmission factors , area-weighted by (small elements / air paths enter through their element-normalized level difference Dn,e with the reference area m²):

EN 12354-3, outdoor → indoor (façade sound insulation). The apparent sound reduction index of a façade for diffuse incidence (Formula 10):

from which the loudspeaker- and traffic-referenced indices (Formula 11) and (Formula 12), and the primary output, the standardized level difference at 2 m (Formula 13):

with the façade-shape term ΔLfs (Annex C; 0 dB for a flat reflecting façade).

EN 12354-4, indoor → outdoor (sound radiated to the outside). The sound power level radiated by a segment (Formulas 2-3):

with the inside-field diffusivity term Cd (Annex B; -6 dB ideal diffuse, -5 dB average industrial). An opening is modelled here as an element whose “R” is the silencer insertion loss D (a bare opening is ), combined in the same energy sum as the structural elements over the segment area S: a practical extension for a mixed wall-plus-opening segment. This is NOT the standard’s Formula (4), which treats a segment made up only of openings with a different area normalization (S = the opening area) and sums its LW with the envelope segments only at the final energetic stage. The exterior level follows from the simplified Annex E attenuation Atot of a finite radiating side and .

Single-number ratings reuse EN ISO 717-1 via phonometry.building.weighted_rating (exact for , a good approximation for R'w, Part 3 NOTE 7).

Clause/formula citations refer to EN 12354-3:2000 or EN 12354-4:2000.

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

facade_shape_level_difference(
shape: Literal['plane_facade', 'gallery_2', 'gallery_3', 'gallery_4', 'gallery_5', 'balcony_6', 'balcony_7', 'balcony_8', 'terrace_open', 'terrace_closed'],
*,
line_of_sight: float = 0.0,
absorption: float = 0.3,
) -> float

Façade-shape level difference ΔLfs (EN 12354-3:2000 Annex C).

Looks up Figure C.2 for the level difference caused by the exterior shape of the façade (gallery, balcony or terrace), as a function of the height of the line of sight from the source on the façade plane and the weighted sound absorption coefficient αw (EN ISO 11654) of the underside of the balcony/roof above. The value feeds delta_l_fs of facade_sound_reduction (Formula 13). Intermediate αw values are interpolated linearly between the tabulated 0.3 / 0.6 / 0.9 columns, as the annex allows; outside that range the edge column applies. The 2017 edition tabulates the same values (Tabelle C.1).

Shapes follow the Figure C.2 numbering: "plane_facade" (1, always 0 dB), "gallery_2" to "gallery_5" (2-5), "balcony_6" to "balcony_8" (6-8) and "terrace_open" / "terrace_closed" (9, open or closed fence).

Parameters

Name Description
shape Façade shape key (see above). One of "plane_facade", "gallery_2", "gallery_3", "gallery_4", "gallery_5", "balcony_6", "balcony_7", "balcony_8", "terrace_open" or "terrace_closed".
line_of_sight Height of the line of sight from the source at the façade plane, in m (bins: below 1.5 m; 1.5 m to 2.5 m; above 2.5 m).
absorption Weighted absorption coefficient αw of the underside above the façade (default 0.3; reflecting).

Returns: ΔLfs, in dB.

Raises

Exception When
ValueError For an unknown shape, a negative height/absorption, or a shape/height combination the figure marks “does not apply”.
TypeError if absorption or line_of_sight is not a single number, or shape is not a text.
facade_sound_reduction(
elements: Sequence[FacadeElement],
*,
area: float,
volume: float,
delta_l_fs: float = 0.0,
fraction: Literal[1, 3] | np.integer[Any] | None = None,
frequencies: NumericArrayLike | None = None,
) -> FacadePredictionResult

Predict façade airborne sound insulation D2m,nT (EN 12354-3:2000).

Energetically combines the element transmission factors (Formula 10) into the apparent sound reduction index R', then derives the loudspeaker/traffic indices (Formulas 11-12) and the standardized level difference (Formula 13).

Parameters

Name Description
elements Façade elements (see FacadeElement); per-band arrays must share a common length (5 octave or 16 third-octave bands to get single-number ratings).
area Total façade area S seen from inside, in m².
volume Receiving-room volume V, in m³ (Formula 13).
delta_l_fs Façade-shape term ΔLfs in dB (Annex C; 0 for a flat reflecting façade).
fraction The band set of the single-number ratings, passed to weighted_rating: 3 for one-third octaves, 1 for octaves or None (Default) to read it from the number of bands. One of 1 or 3.
frequencies Optional band centre frequencies (Hz), stored on the result for plotting; must match the element band count.

Returns: A FacadePredictionResult.

Raises

Exception When
TypeError if area or volume is not a single number, or fraction is not an integer (a word, a flag or a float), or frequencies holds a text or a value that is not a real number. delta_l_fs is refused the same way when it is not one real number.
FacadeElement(
*,
name: str,
area: float | None = None,
r: NumericArrayLike | None = None,
dn_e: NumericArrayLike | None = None,
insertion_loss: NumericArrayLike | None = None,
)

One façade element as a transmission path (EN 12354-3/-4).

Provide exactly one of r (an area element, Formula 15 / Part 4 Formula 3), dn_e (a small element or air path, Formula 14) or insertion_loss (an opening in Part 4, modelled as an element whose reduction is the silencer’s insertion loss D and combined in the same energy sum: a practical extension, not the standard’s separate segment-of-openings Formula 4). Per-band values may be scalars or equal-length arrays.

Attributes

Name Description
name Label used in results and plots.
area Element area Sᵢ in m² (required for r / insertion_loss; ignored for dn_e small elements, which use A₀ instead).
r Sound reduction index Rᵢ in dB.
dn_e Element-normalized level difference Dn,e,i in dB.
insertion_loss Opening silencer insertion loss Dᵢ in dB.
FacadeElement.tau(
total_area: float,
n_bands: int | np.integer[Any],
) -> NDArray[np.float64]

Transmission factor τ of this element for the whole façade area.

Raises

Exception When
ValueError for a total_area that is not positive, an n_bands that is not a whole number from 1, or an element whose area is not positive or whose bands are not n_bands.
TypeError if total_area is not a single number, or n_bands is a flag, a text or an array where a count goes.
FacadePredictionResult(
r_prime: NDArray[np.float64],
r_45: NDArray[np.float64],
r_tr_s: NDArray[np.float64],
d_2m_nt: NDArray[np.float64],
element_r: Mapping[str, NDArray[np.float64]],
elements: tuple[FacadeElement, ...],
r_tr_s_w: int | None = None,
d_2m_nt_w: int | None = None,
c_tr: int | None = None,
frequencies: NDArray[np.float64] | None = None,
)

Predicted façade airborne insulation (EN 12354-3:2000).

Attributes

Name Description
r_prime Apparent sound reduction index R' per band, in dB (Formula 10).
r_45 (loudspeaker method, Formula 11), in dB.
r_tr_s (traffic, Formula 12), in dB.
d_2m_nt Standardized level difference D2m,nT per band, in dB (Formula 13).
element_r Per-element partial index per band, in dB.
r_tr_s_w Single-number Rtr,s,w (ISO 717-1); None if the bands are not the ISO 717-1 octave/third-octave set.
d_2m_nt_w Single-number D2m,nT,w (ISO 717-1); None as above.
c_tr Spectrum adaptation term Ctr of R' (ISO 717-1).
frequencies Band centre frequencies (Hz) for plotting; None labels the axis by band index.
elements The element sequence the prediction was run with, kept so plot_geometry can draw the elevation.
FacadePredictionResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the per-element partial indices and the façade R' / D2m,nT.

Parameters

Name Description
language The language of the labels: "en" or "es".
FacadePredictionResult.plot_geometry(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the composite facade elevation, element areas to scale.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
FacadePredictionResult.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 predicted façade sound insulation report to a PDF (EN 12354-3).

Writes a one-page prediction report for the predicted standardized level difference of a façade D2m,nT estimated by the EN/ISO 12354-3:2000 model (Formula 13): a standard-basis line that states the sheet is a prediction from element data and not a measurement, an optional metadata header block, a two-panel body with the façade-element table (each element’s weighted partial index Rp,w) beside the per-element partial-index and R' / D2m,nT plot, the boxed predicted rating D2m,nT,w, the prediction statement and, when a requirement is supplied, a PASS/FAIL verdict (the level difference passes at or above the requirement), followed by a footer.

The applicable ReportMetadata fields describe the predicted situation: specimen (the façade element set), area (the exposed façade area S), receiving_volume (the receiving room volume V), test_room (the traffic / outdoor situation), client, manufacturer, measurement_standard, laboratory (the calculator / laboratory), operator, report_id and test_date. A summary of the façade shape (ΔLfs) and the model assumptions is recorded in notes (free text), and requirement supplies the target D2m,nT,w.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a lightweight fiche (body, rating, statement, disclaimer).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the element table also shows each element’s share of the transmitted sound energy.
language Fiche language: "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is unknown, language is not supported, or the result lacks the ISO 717-1 single-number ratings (build it on the 5 octave or 16 one-third-octave bands).
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
outdoor_attenuation(
width_m: float,
height_m: float,
distance: float,
) -> float

Simplified attenuation Atot of a finite side (EN 12354-4 Annex E).

Reception point in front of the centre of a rectangular side at perpendicular distance d. Uses the finite-side Formula (E.2a) up to the largest side dimension and the point-source Formula (E.2b) beyond it, following the Annex E Note 3 switching rule. The two branches do not join continuously at the switch distance: for a square 10 m x 10 m side the step is about -0.7 dB (about -0.3 dB for a 60 m x 10 m side), an artefact of the standard’s own simplification. The +6 dB for radiation into the quarter-space over hard ground is built into the formula.

Parameters

Name Description
width_m Side width L, in m.
height_m Side height H, in m.
distance Perpendicular distance d to the reception point, in m.

Returns: Atot in dB (subtract from LW to get the exterior Lp).

Raises

Exception When
TypeError if distance, height_m or width_m is not a single number.
outdoor_level(l_w: NumericArrayLike, attenuation: NumericArrayLike) -> float

Exterior level from one or more radiating sides (EN 12354-4 Formula E.1).

for sides sharing a reception point, or the per-side LW - Atot energetically summed. Pass matching sequences of side power levels and their attenuations, or scalars for a single side; a scalar broadcasts against an array (e.g. several sides, one common Atot).

Parameters

Name Description
l_w Radiated power level(s) LW (dB), scalar or per side.
attenuation Attenuation(s) Atot (dB), scalar or per side.

Returns: Exterior sound pressure level Lp in dB.

Raises

Exception When
TypeError if attenuation or l_w holds a text or a value that is not a real number.
plot_facade_elements(
elements: Sequence[FacadeElement],
*,
ax: Axes | None = None,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw a composite facade elevation with element areas to scale.

Each element of facade_sound_reduction is a tile whose drawn area equals its real area (small-area elements without an area, such as airbricks rated by dn_e, get a nominal 0.1 m2 tile).

Parameters

Name Description
elements The FacadeElement sequence.
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the first element rectangle.

Returns: The axes.

Raises

Exception When
ValueError for an empty sequence, or an element that supplies an area which is not positive and finite. An element with no area at all is the nominal tile above, not a refusal.
radiated_sound_power(
elements: Sequence[FacadeElement],
*,
lp_in: NumericArrayLike,
area: float,
c_d: float = -6.0,
r_prime_cap: float | None = None,
octave_bands: NumericArrayLike | None = None,
) -> RadiatedPowerResult

Predict the sound power radiated outside by a segment (EN 12354-4).

R' combines the element transmission factors (Formula 3); the radiated power level is (Formula 2). Openings may be included as FacadeElement entries with an insertion_loss (0 for a bare opening); see the module docstring for how this differs from the standard’s separate segment-of-openings Formula (4).

Parameters

Name Description
elements Segment elements (see FacadeElement).
lp_in Inside sound pressure level Lp,in per band, in dB.
area Segment area S, in m².
c_d Inside-field diffusivity term Cd in dB (Annex B: -6 ideal diffuse, -5 average industrial building).
r_prime_cap Optional practical maximum on R' per band, in dB. This cap is not part of Formula (2)/(3): it appears only as a footnote of the Annex G worked example (“R’ limited to 40 dB” for field situations with unavoidable leaks). Pass 40.0 to reproduce Annex G; the default None computes the bare formulas.
octave_bands Optional octave-band centre frequencies (Hz) matching the per-band data; enables the A-weighted single number.

Returns: A RadiatedPowerResult.

Raises

Exception When
TypeError if area is not a single number, or lp_in or octave_bands holds a text or a value that is not a real number. c_d or r_prime_cap are refused the same way when any is not one real number.
RadiatedPowerResult(
l_w: NDArray[np.float64],
r_prime: NDArray[np.float64],
l_w_dba: float | None = None,
frequencies: NDArray[np.float64] | None = None,
)

Predicted sound power radiated to the outside by a segment (EN 12354-4).

Attributes

Name Description
l_w Radiated sound power level LW per band, in dB re 1 pW (Formula 2).
r_prime Apparent sound reduction index R' per band, in dB (Formula 3).
l_w_dba A-weighted LW in dB(A), if the bands are known octave bands; else None.
frequencies Band centre frequencies (Hz) for plotting; None labels the axis by band index.
RadiatedPowerResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the radiated sound power level LW per band.

Parameters

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