Ir al contenido

materials.absorbers.sound_absorption

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.

Sound absorption in a reverberation room: BS EN ISO 354:2003.

The mean reverberation time of a reverberation room is measured empty and with the test specimen installed. From those two reverberation times the equivalent sound absorption area of the specimen is obtained via Sabine’s equation, and for a plane absorber the sound absorption coefficient follows by dividing by the covered area (ISO 354:2003, Clauses 4 and 8.1).

Equivalent sound absorption area (ISO 354:2003, Eq. (5) empty room / Eq. (7) with specimen; identical form):

with V the room volume (m3), c the speed of sound (m/s), T the reverberation time (s) and m the power attenuation coefficient of air (1/m). The speed of sound follows Eq. (6), valid for 15 degC to 30 degC:

The equivalent sound absorption area of the specimen and its absorption coefficient (ISO 354:2003, Eq. (8) and Eq. (9)):

alpha_s may exceed 1.0 (e.g. from diffraction/edge effects) and is not a percentage (ISO 354:2003, Clause 3.7 NOTE 2); it is therefore never clamped.

The air attenuation coefficient m is defined by ISO 354 only through its conversion from the ISO 9613-1 attenuation coefficient alpha (in dB/m) (ISO 354:2003, 8.1.2.1):

ISO 354 otherwise defers the calculation of alpha entirely to ISO 9613-1. m is therefore a user-supplied per-band parameter here (default 0, i.e. no air correction); a caller holding ISO 9613-1 alpha values can convert them with power_attenuation_from_alpha.

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

absorption_area(
t60: float | np.floating[Any] | np.integer[Any],
volume: float,
*,
temperature_c: float = ...,
speed_of_sound: float | None = ...,
m: NumericArrayLike = ...,
) -> float
absorption_area(
t60: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
volume: float,
*,
temperature_c: float = ...,
speed_of_sound: float | None = ...,
m: NumericArrayLike = ...,
) -> NDArray[np.float64]
absorption_area(
t60: NumericArrayLike,
volume: float,
*,
temperature_c: float = ...,
speed_of_sound: float | None = ...,
m: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Equivalent sound absorption area of a room (ISO 354:2003, Eq. (5)/(7)).

. This is Sabine’s equation with the air-absorption term; it gives the empty-room area A1 from T1 or the with-specimen area A2 from T2 (both equations have identical form).

Parameters

Name Description
t60 Reverberation time(s) T, in seconds (scalar or per band).
volume Room volume V, in cubic metres.
temperature_c Air temperature, in degrees Celsius, used to compute the speed of sound via Eq. (6) when speed_of_sound is not given (default 20 degC, i.e. c = 343 m/s). A temperature outside 15..30 degC emits an AbsorptionWarning. A room volume below the 150 m3 minimum of clause 6.1.1 likewise emits an advisory AbsorptionWarning.
speed_of_sound Explicit speed of sound c, in m/s; overrides temperature_c and Eq. (6) when supplied.
m Power attenuation coefficient of air m, in 1/m (a scalar or an array matching the shape of t60; default 0, i.e. no air correction). A per-band m whose shape differs from t60 raises ValueError. Obtain it from an ISO 9613-1 attenuation coefficient with power_attenuation_from_alpha.

Returns: Equivalent sound absorption area A, in square metres, with the shape of t60. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if speed_of_sound, temperature_c or volume is not a single number, or m or t60 holds a text or a value that is not a real number.
absorption_coefficient(
t1: float | np.floating[Any] | np.integer[Any],
t2: float | np.floating[Any] | np.integer[Any],
volume: float,
sample_area: float,
*,
temperature1_c: float = ...,
temperature2_c: float | None = ...,
speed_of_sound1: float | None = ...,
speed_of_sound2: float | None = ...,
m1: NumericArrayLike = ...,
m2: NumericArrayLike = ...,
) -> float
absorption_coefficient(
t1: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
t2: NumericArrayLike,
volume: float,
sample_area: float,
*,
temperature1_c: float = ...,
temperature2_c: float | None = ...,
speed_of_sound1: float | None = ...,
speed_of_sound2: float | None = ...,
m1: NumericArrayLike = ...,
m2: NumericArrayLike = ...,
) -> NDArray[np.float64]
absorption_coefficient(
t1: float | np.floating[Any] | np.integer[Any],
t2: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
volume: float,
sample_area: float,
*,
temperature1_c: float = ...,
temperature2_c: float | None = ...,
speed_of_sound1: float | None = ...,
speed_of_sound2: float | None = ...,
m1: NumericArrayLike = ...,
m2: NumericArrayLike = ...,
) -> NDArray[np.float64]
absorption_coefficient(
t1: NumericArrayLike,
t2: NumericArrayLike,
volume: float,
sample_area: float,
*,
temperature1_c: float = ...,
temperature2_c: float | None = ...,
speed_of_sound1: float | None = ...,
speed_of_sound2: float | None = ...,
m1: NumericArrayLike = ...,
m2: NumericArrayLike = ...,
) -> float | NDArray[np.float64]

Sound absorption coefficient of a plane absorber (ISO 354:2003, Eq. (9)).

Builds the equivalent sound absorption area of the specimen from Eq. (8), using the empty-room reverberation time T1 and the with-specimen time T2:

then returns (Eq. (9)).

The two measurements may be at different temperatures; c1 and c2 are resolved independently. alpha_s is returned unclamped and may exceed 1.0 (Clause 3.7 NOTE 2). Because adding an absorber must reduce the reverberation time, () is non-physical and emits an AbsorptionWarning. A room volume below the 150 m3 minimum of clause 6.1.1, or a sample area outside the clause 6.2.1.1 range (, upper limit scaled by when m3), each emit an advisory AbsorptionWarning.

Parameters

Name Description
t1 Empty-room reverberation time(s) T1, in seconds.
t2 With-specimen reverberation time(s) T2, in seconds.
volume Room volume V, in cubic metres.
sample_area Area S covered by the test specimen, in square metres (for both-sides-exposed absorbers, the area of the two sides; Clause 3.7 NOTE 1).
temperature1_c Empty-room air temperature, in degrees Celsius (default 20). Used for c1 via Eq. (6) unless speed_of_sound1 is given.
temperature2_c With-specimen air temperature, in degrees Celsius; defaults to temperature1_c. Used for c2 unless speed_of_sound2 is given.
speed_of_sound1 Explicit c1 in m/s; overrides temperature1_c.
speed_of_sound2 Explicit c2 in m/s; overrides temperature2_c. Defaults to speed_of_sound1 when that is given but c2 is not, so overriding only c1 applies the same speed to both measurements.
m1 Empty-room air attenuation coefficient m1, in 1/m (default 0).
m2 With-specimen air attenuation coefficient m2, in 1/m (default 0).

Returns: Sound absorption coefficient alpha_s with the broadcast shape of t1 and t2. A float when t1 and t2 are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if sample_area, speed_of_sound1, speed_of_sound2, temperature1_c, temperature2_c or volume is not a single number, or m1, m2, t1 or t2 holds a text or a value that is not a real number.

Advisory for out-of-range or non-physical ISO 354 absorption inputs.

measure_sound_absorption(
t_empty: NumericArrayLike,
t_specimen: NumericArrayLike,
*,
frequencies: NumericArrayLike,
volume: float,
area: float,
temperature_c: float = 20.0,
relative_humidity_percent: float | None = None,
speed_of_sound: float | None = None,
m: NumericArrayLike = 0.0,
) -> SoundAbsorptionMeasurement

Measure the sound absorption of a plane absorber (ISO 354:2003).

Assembles a SoundAbsorptionMeasurement from the one-third-octave reverberation times of the empty room (T1) and of the room with the specimen installed (T2). The equivalent sound absorption areas A1 and A2 follow from Sabine’s equation (Eq. (5)/(7), delegated to absorption_area) and the sound absorption coefficient from Eq. (8)/(9) (delegated to absorption_coefficient); no formula is re-derived here.

Both measurements are taken at the same air temperature and, for the air attenuation term, the same climatic conditions (ISO 354:2003, 6.3), so a single temperature_c and m apply to both. Use the lower-level absorption_coefficient directly when the empty-room and with-specimen climates differ.

Parameters

Name Description
frequencies One-third-octave band centre frequencies, in Hz (the ISO 354 range is 100 Hz to 5000 Hz); a 1-D array matching t_empty and t_specimen.
t_empty Empty-room reverberation time T1, per band, in seconds.
t_specimen With-specimen reverberation time T2, per band, in seconds.
volume Reverberation-room volume V, in cubic metres. A volume below the 150 m3 minimum of clause 6.1.1 emits an advisory AbsorptionWarning.
area Area S covered by the test specimen, in square metres. An area outside the clause 6.2.1.1 range (10 m2 to 12 m2, upper limit scaled by for m3) emits an advisory AbsorptionWarning.
temperature_c Air temperature during the test, in degrees Celsius (default 20). Used for the speed of sound via Eq. (6) unless speed_of_sound is given; a temperature outside 15..30 degC emits an AbsorptionWarning.
relative_humidity_percent Relative humidity during the test, in % within [0, 100] (informational; recorded on the result but not used in the computation, which sees the climate only through m). None leaves it unrecorded.
speed_of_sound Explicit speed of sound c, in m/s; overrides temperature_c and Eq. (6) when supplied.
m Power attenuation coefficient of air m, in 1/m (a scalar or a per-band array matching frequencies; default 0, i.e. no air correction). Obtain it from an ISO 9613-1 attenuation coefficient with power_attenuation_from_alpha.

Returns: A frozen SoundAbsorptionMeasurement.

Raises

Exception When
ValueError If the frequency and reverberation-time arrays do not share one shape, relative_humidity_percent is not within [0, 100] %, or an input is non-physical (see absorption_coefficient).
TypeError if area, relative_humidity_percent, speed_of_sound, temperature_c or volume is not a single number, or frequencies, m, t_empty or t_specimen holds a text or a value that is not a real number.
power_attenuation_from_alpha(
attenuation_db_per_m: float | np.floating[Any] | np.integer[Any],
) -> float
power_attenuation_from_alpha(
attenuation_db_per_m: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
power_attenuation_from_alpha(
attenuation_db_per_m: NumericArrayLike,
) -> float | NDArray[np.float64]

Air power attenuation coefficient m from the ISO 9613-1 alpha.

The one conversion both reverberation-room standards make, ISO 354:2003 (8.1.2.1) and ISO 17497-1:2004 (Clause 8, Eq. (3)): , where alpha is the attenuation coefficient in decibels per metre of ISO 9613-1, a sound-pressure level per metre, and m is the power attenuation coefficient in reciprocal metres that ISO 354 Eqs. (5), (7) and (8) and ISO 17497-1 Eqs. (1), (4) and (6) take. Neither standard tabulates alpha: both defer it to ISO 9613-1, so this only converts a value the caller already holds (from air_attenuation, for example, or in one step with air_power_attenuation_per_m).

Parameters

Name Description
attenuation_db_per_m Attenuation coefficient alpha of ISO 9613-1, in dB/m (scalar or per band).

Returns: Power attenuation coefficient m, in 1/m, with the shape of attenuation_db_per_m. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any value is negative or not finite.
TypeError if attenuation_db_per_m holds a text or a value that is not a real number.
SoundAbsorptionMeasurement(
frequencies: NDArray[np.float64],
t_empty: NDArray[np.float64],
t_specimen: NDArray[np.float64],
volume: float,
area: float,
temperature_c: float,
relative_humidity_percent: float | None,
speed_of_sound: float,
air_attenuation_per_m: NDArray[np.float64],
absorption_area_empty: NDArray[np.float64],
absorption_area_with_specimen: NDArray[np.float64],
alpha_s: NDArray[np.float64],
)

A reverberation-room sound absorption measurement (ISO 354:2003).

The one-third-octave outcome of a plane-absorber test: the mean reverberation time measured empty (T1) and with the specimen (T2), the equivalent sound absorption areas A1 (Eq. (5)) and A2 (Eq. (7)) they give through Sabine’s equation, and the sound absorption coefficient alpha_s (Eq. (8)/(9)) of the specimen. Build it with measure_sound_absorption; the frozen instance then exposes plot (alpha_s versus frequency) and report (an accredited ISO 354 test-report PDF).

A single-number rating (the practical coefficient alpha_p and the weighted coefficient alpha_w) is defined by ISO 11654, not ISO 354, and is therefore not produced here; pass alpha_s to weighted_absorption_from_third_octave for it.

Attributes

Name Description
frequencies One-third-octave band centre frequencies, in Hz (the ISO 354 range is 100 Hz to 5000 Hz).
t_empty Mean reverberation time of the empty room T1, per band, in seconds.
t_specimen Mean reverberation time of the room with the specimen T2, per band, in seconds.
volume Reverberation-room volume V, in cubic metres.
area Area S covered by the test specimen, in square metres.
temperature_c Air temperature during the test, in degrees Celsius.
relative_humidity_percent Relative humidity during the test, in %, or None when not recorded. It is informational: humidity enters ISO 354 only through the air attenuation coefficient m (via ISO 9613-1), never directly.
speed_of_sound Propagation speed of sound c used in the Sabine inversion, in m/s (from Eq. (6) unless it was given explicitly).
air_attenuation_per_m Power attenuation coefficient of air m, per band, in 1/m (0 when no air correction was applied).
absorption_area_empty Equivalent sound absorption area of the empty room A1 (Eq. (5)), per band, in square metres.
absorption_area_with_specimen Equivalent sound absorption area of the room containing the specimen A2 (Eq. (7)), per band, in square metres.
alpha_s Sound absorption coefficient alpha_s (Eq. (8)/(9)), per band. It may exceed 1.0 (Clause 3.7 NOTE 2) and is never clamped.

SoundAbsorptionMeasurement.equivalent_absorption_area

Section titled “SoundAbsorptionMeasurement.equivalent_absorption_area”

property

Equivalent sound absorption area .

The ISO 354:2003 Eq. (8) quantity, per band, in square metres; dividing it by the specimen area S gives alpha_s (Eq. (9)).

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

Plot the sound absorption coefficient alpha_s versus frequency.

Draws alpha_s over the one-third-octave band axis (ISO 354). Values above 1.0 are kept (Clause 3.7 NOTE 2), so the axis grows to show them. Requires matplotlib (the [plot] extra); returns the Axes and never calls plt.show.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language "en" (default) or "es".
kwargs Forwarded to the alpha_s curve plot call.

Returns: The axes.

SoundAbsorptionMeasurement.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render an ISO 354 sound-absorption test-report fiche to a PDF.

Writes a one-page accredited reverberation-room report: the standard-basis line, an optional metadata header block (client, specimen, area S, room volume V, mounting, climate …), a two-panel body with the one-third-octave alpha_s table beside the alpha_s curve, and a footer with the fixed disclaimer. ISO 354 is a characterisation, so there is no pass/fail verdict and no single-number rating (the weighted alpha_w is an ISO 11654 quantity, out of scope here).

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a body-and-disclaimer fiche without a metadata header. The requirement field is ignored (ISO 354 has no verdict).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the table adds the reverberation times T1/T2 and the equivalent absorption areas A1/A2.
language Fiche language: "en" (default, English, decimal point) or "es" (Spanish, decimal comma).

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).