Ir al contenido

room.modes

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.

Normal modes of a rectangular room: frequencies, kinds, count and density.

Below the Schroeder frequency a room is not a diffuse field but a handful of discrete standing waves. For the idealised rigid-walled rectangular room of dimensions the wave equation separates and the eigen- frequencies are known in closed form (Long, Architectural Acoustics 2nd ed., Equation (8.43); Kuttruff, Room Acoustics 6th ed., 3.1):

with non-negative integer orders nx, ny, nz counting the nodal planes perpendicular to each axis. Each mode is classified by how many of its orders are non-zero:

  • axial (one non-zero order): a wave bouncing between one pair of walls, the strongest and most audible family, e.g. the 1,0,0 fundamental;
  • tangential (two): a wave grazing four walls, about 3 dB weaker;
  • oblique (three): a wave involving all six walls, weaker still.

How many modes. Counting lattice points of the k-space grid inside the positive octant of a sphere of radius , with the half- and quarter-weight corrections for the points lying on the coordinate planes and axes, gives the integrated mode count (Long Equation (8.45), after Morse 1948 and Pierce 1981):

with the room volume V, the total wall area S and the sum L of the twelve edge lengths. Its derivative is the modal density in modes per hertz (Long Equation (8.46)):

The smooth count is an asymptotic estimate: at low frequency, where only a few modes exist, the exact enumeration of room_modes is the honest answer, while above the Schroeder frequency (phonometry.room.schroeder_frequency) the modes overlap so densely that only the statistical description of phonometry.room.steady_field remains useful. Marking that frequency on the mode ladder is the point of RoomModesResult.plot.

This module describes the eigenfrequencies of an empty rectangular box. It is not a prediction of the level at a receiver: for that, use the image-source model (phonometry.room.image_source) or the steady-state statistical field (phonometry.room.steady_field).

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

Constant (tuple).

MODE_KINDS = ('axial', 'tangential', 'oblique')
room_modal_density(
dimensions: NumericArrayLike,
*,
frequency: float | np.floating[Any] | np.integer[Any],
speed_of_sound: float = 343.0,
) -> float
room_modal_density(
dimensions: NumericArrayLike,
*,
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
speed_of_sound: float = 343.0,
) -> NDArray[np.float64]
room_modal_density(
dimensions: NumericArrayLike,
*,
frequency: NumericArrayLike,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Modal density in modes per hertz (Long Equation (8.46)).

This is the derivative of room_mode_count. Its reciprocal is the mean spacing between adjacent eigenfrequencies.

Parameters

Name Description
frequency Frequency f, Hz (scalar or array).
dimensions Room dimensions (lx, ly, lz), m.
speed_of_sound Speed of sound c0, m/s.

Returns: The modal density, modes/Hz; 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 is not a single number, or dimensions or frequency holds a text or a value that is not a real number.
room_mode_count(
dimensions: NumericArrayLike,
*,
frequency: float | np.floating[Any] | np.integer[Any],
speed_of_sound: float = 343.0,
) -> float
room_mode_count(
dimensions: NumericArrayLike,
*,
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
speed_of_sound: float = 343.0,
) -> NDArray[np.float64]
room_mode_count(
dimensions: NumericArrayLike,
*,
frequency: NumericArrayLike,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Integrated number of modes below frequency (Long Equation (8.45)).

This is the Morse/Pierce lattice count with its wall-plane and axis corrections. It is a smooth asymptotic estimate, so it is only meaningful once several modes fit below f; the exact enumeration is room_modes.

Parameters

Name Description
frequency Upper frequency f, Hz (scalar or array).
dimensions Room dimensions (lx, ly, lz), m.
speed_of_sound Speed of sound c0, m/s.

Returns: The (non-integer) mode count; 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 is not a single number, or dimensions or frequency holds a text or a value that is not a real number.
room_mode_frequency(
orders: NumericArrayLike,
dimensions: NumericArrayLike,
*,
speed_of_sound: float = 343.0,
) -> float | NDArray[np.float64]

Eigenfrequency of a rectangular-room mode (Long Equation (8.43)).

Parameters

Name Description
orders Mode orders (nx, ny, nz), non-negative integers; either a single triple or an (N, 3) array of triples.
dimensions Room dimensions (lx, ly, lz), m.
speed_of_sound Speed of sound c0, m/s (default 343 m/s, dry air at 20 °C).

Returns: The modal frequency in Hz; a float for a single triple, otherwise one frequency per row.

Raises

Exception When
TypeError if speed_of_sound is not a single number, or dimensions or orders holds a text or a value that is not a real number.
room_modes(
dimensions: NumericArrayLike,
*,
max_frequency: float = 200.0,
speed_of_sound: float = 343.0,
reverberation_time: float | None = None,
) -> RoomModesResult

Enumerate the normal modes of a rectangular room (Long Chapter 8).

Every order triple (nx, ny, nz) whose frequency does not exceed max_frequency is listed, sorted by frequency and classified as axial, tangential or oblique. The trivial (0, 0, 0) mode (the static pressure solution) is excluded.

Parameters

Name Description
dimensions Room dimensions (lx, ly, lz), m.
max_frequency Highest modal frequency to enumerate, Hz.
speed_of_sound Speed of sound c0, m/s (default 343 m/s, dry air at 20 °C).
reverberation_time Optional reverberation time T, s. When given, the Schroeder frequency is computed and carried in the result (and marked by RoomModesResult.plot).

Returns: A RoomModesResult.

Raises

Exception When
TypeError if max_frequency or speed_of_sound is not a single number, or dimensions holds a text or a value that is not a real number.
RoomModesResult(
orders: NDArray[np.intp],
frequencies: NDArray[np.float64],
kinds: NDArray[np.str_],
dimensions: tuple[float, float, float],
speed_of_sound: float,
max_frequency: float,
schroeder_frequency: float | None = None,
)

The normal modes of a rectangular room up to a frequency limit.

Attributes

Name Description
orders Mode orders, an (N, 3) integer array of (nx, ny, nz) sorted by frequency.
frequencies Modal frequencies in ascending order, Hz.
kinds Mode kind per row, one of MODE_KINDS.
dimensions Room dimensions (lx, ly, lz), m.
speed_of_sound Speed of sound c0 used, m/s.
max_frequency Frequency limit of the enumeration, Hz.
schroeder_frequency Schroeder frequency, Hz, when a reverberation time was supplied; otherwise None.
RoomModesResult.count_by_kind() -> dict[Literal['axial', 'tangential', 'oblique'], int]

Number of enumerated modes of each kind, keyed by MODE_KINDS.

RoomModesResult.density(
frequency: float | np.floating[Any] | np.integer[Any],
) -> float
RoomModesResult.density(
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
RoomModesResult.density(
frequency: NumericArrayLike,
) -> float | NDArray[np.float64]

Modal density at frequency for this room (Long Equation (8.46)).

Parameters

Name Description
frequency Frequency, in hertz (scalar or array).

Returns: The modal density, in modes per hertz, of the shape of frequency; a float for a number; an array for a sequence or an array, a zero-dimensional one included.

property

Sum L of the twelve edge lengths, m.

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

Plot the mode ladder by kind and the modal density.

The upper panel stems every enumerated mode at its frequency, coloured axial / tangential / oblique; the lower panel draws the smooth modal density (Long Equation (8.46)). The Schroeder frequency, when known, is marked on both. Requires matplotlib (the [plot] extra).

Parameters

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

property

Total area S of the six walls, m2.

property

Room volume V, m3.