Ir al contenido

building.prediction.ceiling_plenum

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.

Suspended-ceiling plenum flanking path (Vigran 9.2.3 after Mechel 1980; ISO 140-9 / ISO 10848-2; ASTM E1414 / ASTM E413).

Two offices separated by a partition that stops at the suspended ceiling share one continuous plenum above it. Sound leaves the source room through the ceiling tiles, travels sideways over the partition and comes back down through the tiles of the receiving room. That path is often the weakest link in an open-plan fit-out, and it is not what a partition’s Rw describes.

The one-dimensional model (Vigran Eqs. (9.14) to (9.20)). Mechel’s one-dimensional variant treats the plenum as a duct lined on one side. The ceiling on each side has a transmission factor (plates times the prospective plenum absorber, Eq. (9.14)); the power injected into the plenum splits, a fraction heading for the partition, and decays as with the power attenuation coefficient (Eqs. (9.15) and (9.16)). Integrating over the ceiling length on both sides gives

with the receiving-side coefficient increased by the leakage back into the room, (Eq. (9.17)). Vigran prints the exponents with a factor 2 for totally reflecting plenum sidewalls and states that totally absorbing ones give the same expression “without the factor 2”, so the factor is the same that the compact form carries.

For a plenum with little attenuation on both sides ( and , which needs a fairly insulating ceiling as well as a weakly damped plenum, since never falls below ) and it collapses to the result that makes the geometry visible:

with for totally absorbing plenum sidewalls and for totally reflecting ones. Referred to the partition area instead of the ceiling, (Eq. (9.13)). A deep plenum helps (the term shrinks), a long room hurts, and doubling the tile insulation helps twice over because and both appear.

The measured quantity (ISO 140-9:1985 clause 3.3, ISO 10848-2). A ceiling is not rated by but by the normalized ceiling attenuation , with A the receiving-room equivalent absorption area and the reference m2. The laboratory has two rooms of at least 50 m3 whose volumes differ by at least 10 %, a dividing wall tapered to at most 100 mm at the top, and a plenum 650 mm to 760 mm deep with one sidewall and both end walls lined; the standard prints the required lining absorption at 125 Hz and from 250 Hz to 4000 Hz, and requires on the other sidewall and on the plenum ceiling. The North American counterpart, ASTM E1414, uses m2, so an ASTM value runs about dB higher than the ISO one.

Single number. ISO rates with the ISO 717-1 curve (phonometry.building.weighted_rating, giving Dn,c,w); ASTM E1414 rates it through ASTM E413 as the ceiling attenuation class (CAC). E413 rounds the data to the nearest integer (clause 5.2), shifts its reference contour upward in 1 dB steps while the sum of the deficiencies stays at or below 32 dB and no single deficiency exceeds 8 dB (clauses 5.3 and 5.4), and reads the rating off the shifted contour at 500 Hz (clause 5.5). See ceiling_attenuation_class.

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

ceiling_attenuation_class(
attenuation: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
) -> CeilingAttenuationResult

Ceiling attenuation class CAC (ASTM E413-22 clause 5, via ASTM E1414).

Rounds the data to the nearest integer (clause 5.2), then raises the CEILING_ATTENUATION_CONTOUR in 1 dB steps to the highest position at which the sum of the deficiencies is at most 32 dB (clause 5.4.1) and no single deficiency exceeds 8 dB (clause 5.4.2). The rating is the shifted contour read at 500 Hz (clause 5.5).

Parameters

Name Description
attenuation Normalized ceiling attenuation Dn,c in the 16 one-third-octave bands 125 Hz to 4000 Hz, in dB.
frequencies Optional band centre frequencies, in Hz; when given they must be exactly the 16 contour bands.

Returns: A CeilingAttenuationResult.

Raises

Exception When
ValueError for a wrong number of bands or mismatched frequencies.
TypeError if attenuation or frequencies holds a text or a value that is not a real number.

Constant (mapping).

CEILING_ATTENUATION_CONTOUR = {125.0: -16.0, 160.0: -13.0, 200.0: -10.0, 250.0: -7.0, 315.0: -4.0, 400.0: -1.0, 500.0: 0.0, 630.0: 1.0, 800.0: 2.0, 1000.0: 3.0, 1250.0: 4.0, 1600.0: 4.0, 2000.0: 4.0, 2500.0: 4.0, 3150.0: 4.0, 4000.0: 4.0}
CeilingAttenuationResult(
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
shifted_reference: NDArray[np.float64],
deficiencies: NDArray[np.float64],
deficiency_sum: float,
max_deficiency: float,
rating: int,
)

Ceiling attenuation class (ASTM E1414 rated through ASTM E413).

Attributes

Name Description
frequencies One-third-octave band centre frequencies, in Hz.
measured Normalized ceiling attenuation Dn,c per band, in dB, as supplied.
shifted_reference The fitted reference contour, in dB.
deficiencies Per-band deficiency (shifted contour minus data, floored at zero), in dB.
deficiency_sum Sum of deficiencies, in dB (at most 32).
max_deficiency Largest entry of deficiencies, in dB (at most 8).
rating The ceiling attenuation class CAC, read off the shifted contour at 500 Hz (clause 5.5), in dB.
CeilingAttenuationResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot Dn,c against the fitted ASTM E413 contour.

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

Parameters

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

property

The measured data rounded to the nearest integer, which the contour is fitted to.

ASTM E413 clause 5.2 rounds the data to the nearest integer before the contour is fitted. The clause does not say which way a half goes; the library rounds it up (floor(measured + 0.5)). Read from measured, so it cannot disagree with it.

normalized_ceiling_attenuation(
level_source: float | np.floating[Any] | np.integer[Any],
level_receiving: float | np.floating[Any] | np.integer[Any],
absorption_area: float | np.floating[Any] | np.integer[Any],
*,
reference_area: float = ...,
) -> float
normalized_ceiling_attenuation(
level_source: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
level_receiving: NumericArrayLike,
absorption_area: NumericArrayLike,
*,
reference_area: float = ...,
) -> NDArray[np.float64]
normalized_ceiling_attenuation(
level_source: float | np.floating[Any] | np.integer[Any],
level_receiving: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
absorption_area: NumericArrayLike,
*,
reference_area: float = ...,
) -> NDArray[np.float64]
normalized_ceiling_attenuation(
level_source: float | np.floating[Any] | np.integer[Any],
level_receiving: float | np.floating[Any] | np.integer[Any],
absorption_area: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
reference_area: float = ...,
) -> NDArray[np.float64]
normalized_ceiling_attenuation(
level_source: NumericArrayLike,
level_receiving: NumericArrayLike,
absorption_area: NumericArrayLike,
*,
reference_area: float = ...,
) -> float | NDArray[np.float64]

Normalized ceiling attenuation Dn,c (ISO 140-9:1985, clause 3.3).

, the level difference between two rooms sharing a common ceiling plenum, normalized to a reference equivalent absorption area. ISO 140-9 and ISO 10848-2 use m2; ASTM E1414 uses m2, which makes an ASTM value about 0.79 dB higher for the same rooms.

Parameters

Name Description
level_source Source-room sound pressure level L1 per band, in dB.
level_receiving Receiving-room level L2 per band, in dB.
absorption_area Receiving-room equivalent absorption area A per band, in m2 (> 0); a scalar is broadcast over the bands.
reference_area Reference area A0, in m2 (Default: 10 m2).

Returns: The normalized ceiling attenuation Dn,c per band, in dB. A float when level_source, level_receiving and absorption_area are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for mismatched shapes or a non-positive area.
TypeError if reference_area is not a single number, or absorption_area, level_receiving or level_source holds a text or a value that is not a real number.
partition_referenced_reduction_index(
reduction_index: float | np.floating[Any] | np.integer[Any],
room_height_m: float,
room_length: float,
) -> float
partition_referenced_reduction_index(
reduction_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
room_height_m: float,
room_length: float,
) -> NDArray[np.float64]
partition_referenced_reduction_index(
reduction_index: NumericArrayLike,
room_height_m: float,
room_length: float,
) -> float | NDArray[np.float64]

Refer Rcl to the partition area instead of the ceiling (Eq. (9.13)).

, with HS the height and LS the length of the sending room. Referring every path to one common area (the partition) is what lets the ceiling path be added to the direct path as transmission factors.

Parameters

Name Description
reduction_index Ceiling/plenum path Rcl per band, in dB.
room_height_m Sending-room height HS, in m (> 0).
room_length Sending-room length LS, in m (> 0).

Returns: The partition-referenced Rcl,p 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 for a non-positive dimension.
TypeError if room_height_m or room_length is not a single number, or reduction_index holds a text or a value that is not a real number.
plenum_flanking_reduction_index(
reduction_index_source: NumericArrayLike,
reduction_index_receiving: NumericArrayLike,
*,
ceiling_length: float,
plenum_height_m: float,
sidewalls: Literal['absorbing', 'reflecting'] = ...,
frequencies: NumericArrayLike | None = ...,
attenuation_source_per_m: NumericArrayLike,
attenuation_receiving_per_m: NumericArrayLike,
source_length: float | None = ...,
split_source: float = ...,
split_receiving: float = ...,
) -> PlenumFlankingResult
plenum_flanking_reduction_index(
reduction_index_source: NumericArrayLike,
reduction_index_receiving: NumericArrayLike,
*,
ceiling_length: float,
plenum_height_m: float,
sidewalls: Literal['absorbing', 'reflecting'] = ...,
frequencies: NumericArrayLike | None = ...,
source_length: float | None = ...,
split_source: float = ...,
split_receiving: float = ...,
) -> PlenumFlankingResult

Ceiling/plenum flanking reduction index Rcl (Vigran Eqs. (9.18)-(9.20)).

With no attenuation coefficients this is the compact undamped form (Eq. (9.20)). Supplying the plenum power attenuation coefficients and (Eq. (9.16), of the lined duct) switches to the full Eq. (9.18), whose receiving side carries the leakage term (Eq. (9.17)) in both the exponent and the denominator. Vigran prints the denominator with the unprimed ; that is a misprint and the derived reading is implemented here (see docs/ERRATA.md).

Because never falls below , the attenuated form approaches Eq. (9.20) only when the ceiling is insulating enough for to be small as well; at dB with the geometry of Vigran’s own example the leakage term is still worth about 0.24 dB.

Parameters

Name Description
reduction_index_source Source-side ceiling RS per band, in dB (the ceiling plates and any plenum absorber together, Eq. (9.14)).
reduction_index_receiving Receiving-side ceiling RR per band, in dB.
ceiling_length Receiving-side ceiling length LR, in m (> 0).
plenum_height_m Plenum height h, in m (> 0).
sidewalls "reflecting" (, Default) or "absorbing" (); scales both the geometry penalty of Eq. (9.20) and the exponents of Eq. (9.18).
frequencies Optional band centre frequencies, in Hz.
attenuation_source_per_m Optional plenum power attenuation coefficient mS per band, in 1/m (> 0); switches to Eq. (9.18).
attenuation_receiving_per_m Optional mR per band, in 1/m (> 0); required together with attenuation_source_per_m.
source_length Source-side ceiling length LS, in m (Default: equal to ceiling_length).
split_source Power split sS towards the partition, in (0, 1] (Default: 0.5).
split_receiving Power split sR on the receiving side, in (0, 1] (Default: 0.5).

Returns: A PlenumFlankingResult.

Raises

Exception When
ValueError for mismatched shapes, an unknown sidewall case, or a non-positive dimension.
TypeError if sidewalls is not a text, ceiling_length, plenum_height_m, source_length, split_receiving or split_source is not a single number, or attenuation_receiving_per_m, attenuation_source_per_m, frequencies, reduction_index_receiving or reduction_index_source holds a text or a value that is not a real number.
PlenumFlankingResult(
frequencies: NDArray[np.float64] | None,
reduction_index: NDArray[np.float64],
transmission_factor: NDArray[np.float64],
reduction_index_source: NDArray[np.float64],
reduction_index_receiving: NDArray[np.float64],
geometry_term: float | None,
penalty: NDArray[np.float64],
model: Literal['undamped', 'attenuated'],
epsilon: float,
plenum_height_m: float,
ceiling_length: float,
)

Ceiling/plenum flanking path of a suspended ceiling (Vigran 9.2.3).

Attributes

Name Description
frequencies Band centre frequencies, in Hz, or None.
reduction_index Sound reduction index Rcl of the ceiling/plenum path per band, in dB.
transmission_factor The transmission factor tau_cl per band.
reduction_index_source Source-side ceiling RS per band, in dB.
reduction_index_receiving Receiving-side ceiling RR per band, in dB.
geometry_term The geometry penalty , in dB, or None for the attenuated model, whose penalty is per band.
penalty The per-band difference , in dB: what the plenum takes off the sum of the two ceilings.
model "undamped" (Eq. (9.20)) or "attenuated" (Eq. (9.18)).
epsilon The sidewall constant eps (1 absorbing, 2 reflecting).
plenum_height_m Plenum height h, in m.
ceiling_length Receiving-side ceiling length LR, in m.
PlenumFlankingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot Rcl against the two ceiling reduction indices.

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

Parameters

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