Ir al contenido

room.reverberation_prediction

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.

Reverberation-time prediction from room geometry and absorption.

Predicts the reverberation time T of an enclosed space from its volume, boundary areas and the sound-absorption coefficients of its surfaces, through the classical statistical-acoustics formulae. Given a diffuse field and an exponential energy decay, T is the time for the level to fall by 60 dB.

Five models are provided, in order of increasing account of a non-uniform absorption distribution:

  • Sabine: the original diffuse-field estimate, with the total equivalent absorption area and the air term . Exact only for low, uniform absorption.
  • Eyring (Norris-Eyring): replaces A by with the mean absorption over the total surface S; correct in the strong-absorption limit where Sabine overestimates T.
  • Millington-Sette: sums the Eyring term per surface, so a single perfectly absorbing surface drives T to zero.
  • Fitzroy: an area-weighted arithmetic mean of three axial Eyring reverberation times, one per pair of opposing walls; captures rooms with the absorption concentrated on one axis (e.g. a carpeted, otherwise hard room).
  • Arau-Puchades: an area-weighted geometric mean of the same three axial Eyring times (Arau-Puchades, Acustica 65 (1988) 163): . Recommended by its author over Fitzroy for anisotropic rooms.

The Sabine constant is (); with the default m/s it takes the familiar textbook value 0.161. (The enclosed_space_absorption EN 12354-6 model instead rounds k to 55.3 and uses to pin the factor at exactly 0.16.)

Air absorption enters every model through the air_attenuation_per_m power attenuation coefficient m, in reciprocal metres (ISO 354 8.1.2.1: , with the ISO 9613-1 attenuation in dB/m), as the additive term ; obtain a physical m from temperature and humidity with air_power_attenuation_per_m.

Each model enforces its own mathematical domain on the absorption coefficients. Sabine’s linear sum is finite for any non-negative coefficient, so it accepts measured ISO 354 values at or above 1 (up to a unit-error guard at 2). The logarithmic models are stricter exactly where the maths requires it: Millington-Sette needs every coefficient below 1, while Eyring, Fitzroy and Arau-Puchades need each mean entering below 1.

The Fitzroy and Arau-Puchades models require a rectangular (shoebox) room and take the room dimensions together with the mean absorption of each of the three wall pairs. All five reduce to Eyring for a uniform absorption distribution, and Eyring reduces to Sabine as the absorption tends to zero: the identities the conformance suite anchors on, absent a machine-readable worked example in the source texts.

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

arau_puchades_reverberation_time(
dimensions: Sequence[float],
absorptions: Sequence[NumericArrayLike],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Arau-Puchades reverberation time, the area-weighted geometric mean of axial times.

with the Eyring time of the wall pair perpendicular to axis i (Arau-Puchades, Acustica 65 (1988) 163, Formula 18). Preferred by its author over Fitzroy for rooms with an anisotropic absorption distribution. Reduces to Eyring for a uniform distribution. Each input is itself a mean entering , so each must be below 1.

Parameters

Name Description
dimensions Room lengths (Lx, Ly, Lz), m.
absorptions Mean absorption (alpha_x, alpha_y, alpha_z) of the three wall pairs (perpendicular to x, y, z); each a scalar or per-band array.
air_attenuation_per_m Air power-attenuation coefficient m (1/m).
speed_of_sound Speed of sound c0, m/s.

Returns: The reverberation time T, s; a float when the three absorptions and the air attenuation are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if speed_of_sound is not a single number, or an entry of dimensions is not a real number, or absorptions or air_attenuation_per_m holds a text or a value that is not a real number.
eyring_reverberation_time(
volume: float,
surfaces: Sequence[tuple[float, NumericArrayLike]],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Eyring (Norris-Eyring) reverberation time.

with the total surface S and its area-weighted mean absorption alpha_bar.

The formula constrains only the mean: requires , while individual coefficients at or above 1 (a measured ISO 354 outcome) are accepted as long as the mean stays below 1 and each coefficient stays within the shared unit-error ceiling of 2.

Parameters

Name Description
volume Room volume V, m3.
surfaces Sequence of (area, absorption_coefficient) pairs.
air_attenuation_per_m Air power-attenuation coefficient m (1/m).
speed_of_sound Speed of sound c0, m/s.

Returns: The reverberation time T, s; a float when the coefficients and the air attenuation are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if speed_of_sound or volume is not a single number, or an area of surfaces is not a real number, or air_attenuation_per_m holds a text or a value that is not a real number.
fitzroy_reverberation_time(
dimensions: Sequence[float],
absorptions: Sequence[NumericArrayLike],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Fitzroy reverberation time, the area-weighted arithmetic mean of axial times.

with the Eyring time of the wall pair perpendicular to axis i (Fitzroy, J. Acoust. Soc. Am. 31 (1959) 893). Equivalent to without air. Reduces to Eyring for a uniform absorption distribution. Each input is itself a mean entering , so each must be below 1.

Parameters

Name Description
dimensions Room lengths (Lx, Ly, Lz), m.
absorptions Mean absorption (alpha_x, alpha_y, alpha_z) of the three wall pairs (perpendicular to x, y, z); each a scalar or per-band array.
air_attenuation_per_m Air power-attenuation coefficient m (1/m).
speed_of_sound Speed of sound c0, m/s.

Returns: The reverberation time T, s; a float when the three absorptions and the air attenuation are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if speed_of_sound is not a single number, or an entry of dimensions is not a real number, or absorptions or air_attenuation_per_m holds a text or a value that is not a real number.
mean_absorption(
surfaces: Sequence[tuple[float, NumericArrayLike]],
) -> float | NDArray[np.float64]

Area-weighted mean absorption coefficient .

Parameters

Name Description
surfaces Sequence of (area, absorption_coefficient) pairs; each coefficient a scalar or a per-band array.

Returns: The mean absorption ; a float when the coefficients are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if an area of surfaces is not a real number.
millington_sette_reverberation_time(
volume: float,
surfaces: Sequence[tuple[float, NumericArrayLike]],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Millington-Sette reverberation time.

The Eyring absorption term is summed surface by surface rather than through a single mean. A surface approaching total absorption () drives T to zero. Because the logarithm applies per surface, every coefficient must be strictly below 1; measured ISO 354 coefficients at or above 1 are outside this model’s domain (use Sabine, or Eyring while the mean stays below 1).

Parameters

Name Description
volume Room volume V, m3.
surfaces Sequence of (area, absorption_coefficient) pairs.
air_attenuation_per_m Air power-attenuation coefficient m (1/m).
speed_of_sound Speed of sound c0, m/s.

Returns: The reverberation time T, s; a float when the coefficients and the air attenuation are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if speed_of_sound or volume is not a single number, or an area of surfaces is not a real number, or air_attenuation_per_m holds a text or a value that is not a real number.
reverberation_time_models(
dimensions: Sequence[float],
absorptions: Sequence[NumericArrayLike],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
frequencies: NumericArrayLike | None = None,
speed_of_sound: float = 343.0,
) -> ReverberationModelResult

Predict the reverberation time of a rectangular room by all five models.

A convenience front-end that builds the six boundary surfaces of the room from dimensions and the three wall-pair mean absorptions, then evaluates sabine_reverberation_time, eyring_reverberation_time, millington_sette_reverberation_time, fitzroy_reverberation_time and arau_puchades_reverberation_time on a common footing. Because the bundle evaluates the logarithmic models too, the inputs must satisfy the strictest of the five domains: every absorption below 1.

Parameters

Name Description
dimensions Room lengths (Lx, Ly, Lz), m.
absorptions Mean absorption (alpha_x, alpha_y, alpha_z) of the three wall pairs (perpendicular to x, y, z); each a scalar or a per-band array aligned with frequencies.
air_attenuation_per_m Air power-attenuation coefficient m (1/m), scalar or per-band.
frequencies Band centre frequencies, in hertz, used only to label the result and its plot; defaults to an integer index over the bands.
speed_of_sound Speed of sound c0, m/s.

Returns: The ReverberationModelResult.

Raises

Exception When
ValueError for absorptions that are not the three wall pairs, and for what the five models refuse.
TypeError if an entry of dimensions is not a real number, or speed_of_sound is not a single number, or frequencies holds a text or a value that is not a real number.
ReverberationModelResult(
frequencies: NDArray[np.float64],
sabine: NDArray[np.float64],
eyring: NDArray[np.float64],
millington_sette: NDArray[np.float64],
fitzroy: NDArray[np.float64],
arau_puchades: NDArray[np.float64],
volume: float,
surface_area: float,
)

Predicted reverberation time of a rectangular room by five models.

Attributes

Name Description
frequencies Band centre frequencies, in hertz.
sabine Sabine reverberation time per band, s.
eyring Eyring (Norris-Eyring) reverberation time per band, s.
millington_sette Millington-Sette reverberation time per band, s.
fitzroy Fitzroy reverberation time per band, s.
arau_puchades Arau-Puchades reverberation time per band, s.
volume Room volume V, m3.
surface_area Total boundary area S, m2.

property

The five reverberation-time curves keyed by model name.

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

Plot the reverberation-time curves of the five models.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
ReverberationModelResult.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 reverberation-time prediction fiche to a PDF.

Writes a one-page report of the reverberation time predicted by the five statistical-acoustics models (Sabine, Eyring, Millington-Sette, Fitzroy and Arau-Puchades): a standard-basis line marking it a design-stage prediction, an optional metadata header block (client, room, description, room volume, total surface area, climate …), a per-band table with one reverberation-time column per model beside the result’s own model-comparison plot (plot), the boxed mid-frequency reverberation time from Arau-Puchades (the recommended model for a non-uniform absorption distribution) with the per-model spread alongside, and a footer with the fixed disclaimer. This is a prediction, not a measurement: the five models bracket the reverberation time likely to occur. A supplied metadata.requirement is printed as a target reverberation-time reference line without a PASS/FAIL verdict, since a room reverberation time is a target range rather than a strictly higher/lower-is-better quantity.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a bare prediction fiche (body, result and disclaimer only).
engine Rendering back end; only "reportlab" is supported.
verbose Accepted for parity with the other fiches; the model table already shows every computed value, so it has no effect.
language Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab".
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
sabine_reverberation_time(
volume: float,
surfaces: Sequence[tuple[float, NumericArrayLike]],
*,
air_attenuation_per_m: NumericArrayLike = 0.0,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Sabine reverberation time .

is finite for any non-negative coefficient, so unlike the logarithmic models Sabine accepts coefficients at or above 1: measured ISO 354 reverberation-room values of 1.05 to 1.20 (the edge effect) and the exact 1.0 that the ISO 11654 practical rating caps at are legitimate inputs. Coefficients above 2 are rejected as a probable unit error (a percentage passed instead of a fraction).

Parameters

Name Description
volume Room volume V, m3.
surfaces Sequence of (area, absorption_coefficient) pairs; each coefficient a scalar or a per-band array in [0, 2].
air_attenuation_per_m Air power attenuation coefficient m, in reciprocal metres (ISO 354 8.1.2.1, ), scalar or per-band; see air_power_attenuation_per_m. Default 0 (air absorption neglected).
speed_of_sound Speed of sound c0, m/s (default 343 m/s, dry air at 20 °C, giving the factor 0.161).

Returns: The reverberation time T, s; a float when the coefficients and the air attenuation are all numbers, a zero-dimensional array when each is one value and one of them is a zero-dimensional array, otherwise a per-band array.

Raises

Exception When
TypeError if speed_of_sound or volume is not a single number, or an area of surfaces is not a real number, or air_attenuation_per_m holds a text or a value that is not a real number.