materials.diffusers.design
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.
Far-field polar response and diffusion coefficient predicted from a diffuser design.
Where phonometry.materials.diffusers.scattering_diffusion evaluates the measured
directional diffusion coefficient of ISO 17497-2 from a set of reflected
sound-pressure levels, this module predicts those levels from the physical
design of a Schroeder phase-grating diffuser (well-depth sequence and well
width), so the diffusion coefficient can be estimated before a sample is built.
The prediction is the standard single-plane Fraunhofer (Fourier) far-field model of a phase-grating surface, as set out in Cox and D’Antonio, Acoustic Absorbers and Diffusers (3rd ed., CRC Press, 2017):
- Each well of depth
d_nbehaves, at normal incidence and with a rigid bottom, as a locally reacting patch of pressure reflection coefficient (Chapter 10; the phase change of a wave travelling down and back up the well). An arbitrary complex reflection coefficient per well is accepted as well, so admittance or resonator-loaded surfaces computed elsewhere can be fed in directly. - The scattered pressure at reflection angle for a source at
incidence is the sum over the wells of the periodic surface
(Chapter 5, Equation (5.8), and Chapter 9, Equation (9.32)):
,
with
x_nthe centre of then-th well and . The optional prefactor collects the single-well aperture directivity (the Fourier transform of one well of widthw) and the Kirchhoff obliquity factor of Equation (9.32); both are absorbed into the constantAof Equation (5.8) and can be switched off to recover the plain Fourier form.
The polar levels are then passed to the
ISO 17497-2 autocorrelation diffusion coefficient of
directional_diffusion_coefficient,
and normalised against the same-footprint flat reference with
normalized_diffusion_coefficient
(Formula (7)), exactly as a measurement would be reduced.
For a quadratic residue diffuser the depth sequence follows from the prime
generator N and the design frequency f_0 (Cox and D’Antonio,
Equations (10.2) and (10.3)):
The model is a far-field approximation and, like every Fourier diffuser model,
loses accuracy at low frequencies, at grazing angles and for surfaces with
strong absorption; it is meant for design estimation, not for replacing an
ISO 17497-2 measurement. A resonator-loaded “metadiffuser” slit surface is not
modelled here: only its per-well reflection coefficient would change, so such a
surface can be predicted by supplying the complex reflection sequence
directly.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
DEFAULT_POLAR_ANGLES_DEG
Section titled “DEFAULT_POLAR_ANGLES_DEG”Constant (tuple).
DEFAULT_POLAR_ANGLES_DEG = (-90, -85, -80, -75, -70, -65, -60, -55, -50, -45, -40, -35, -30, -25, -20, -15, -10, -5, 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90)DiffuserPolarResponse
Section titled “DiffuserPolarResponse”DiffuserPolarResponse( frequency: float, angles_deg: NDArray[np.float64], levels: NDArray[np.float64], coefficient: float, *, source_angle_deg: float = 0.0, well_width: float, depths: NDArray[np.float64] | None = None, n_repetitions: int,)A predicted far-field polar response of a diffuser at one frequency.
Attributes
| Name | Description |
|---|---|
frequency |
Frequency of the prediction, in hertz. |
angles_deg |
Receiver reflection angles, in degrees. |
levels |
Predicted reflected sound-pressure level at each angle, in decibels, referenced to the peak of the response (peak at 0 dB). |
coefficient |
Directional diffusion coefficient d_theta of the predicted response (ISO 17497-2, Formula (5)). |
source_angle_deg |
Angle of incidence psi of the source, in degrees. |
well_width |
Well width w of the predicted surface, in metres, retained (with n_repetitions) so plot_geometry can draw the well profile. |
depths |
Well depths d_n of one period, in metres, when the response was predicted from depths; None otherwise (explicit reflection surfaces have no drawable well profile). |
n_repetitions |
Number of repeated periods of the prediction. |
DiffuserPolarResponse.plot()
Section titled “DiffuserPolarResponse.plot()”DiffuserPolarResponse.plot( ax: PolarAxes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> PolarAxesPlot the predicted polar response with the diffusion coefficient annotated.
Requires matplotlib (the [plot] extra); returns the polar
axes it drew on and never calls plt.show.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
Returns: The polar axes.
Raises
| Exception | When |
|---|---|
| ValueError | If ax is not a polar axes. |
DiffuserPolarResponse.plot_geometry()
Section titled “DiffuserPolarResponse.plot_geometry()”DiffuserPolarResponse.plot_geometry( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the well profile of the predicted surface to scale.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
Raises
| Exception | When |
|---|---|
| ValueError | If the response was predicted from an explicit reflection sequence, which has no well profile to draw. |
plot_qrd_geometry
Section titled “plot_qrd_geometry”plot_qrd_geometry( depths: NumericArrayLike, well_width: float, *, ax: Axes | None = None, n_repetitions: int | np.integer[Any] = 1, fin_width: float | None = None, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the well profile of a quadratic-residue diffuser, to scale.
Wells open upward; the profile repeats n_repetitions times with thin fins
between wells. Pairs with
qrd_well_depths, which supplies the depth
sequence.
Parameters
| Name | Description |
|---|---|
depths |
Well depths d_n, in metres (one period). |
well_width |
Well width w, in metres. |
ax |
Existing axes, or None to create a figure. |
n_repetitions |
Number of repeated periods (>= 1). |
fin_width |
Fin thickness between wells, in metres; None draws w / 12. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the base-slab rectangle. |
Returns: The axes.
Raises
| Exception | When |
|---|---|
| ValueError | for an empty or non-1-D depth sequence, a depth that is not finite and non-negative, a non-positive well width, a number of periods that is not a whole number from 1, or a negative fin width. |
| TypeError | if fin_width or well_width is not a single number, or n_repetitions is a flag, a text or an array where a count goes, or depths holds a text or a value that is not a real number. |
predict_diffuser_polar_response
Section titled “predict_diffuser_polar_response”predict_diffuser_polar_response( well_width: float, frequency: float, *, depths: NumericArrayLike, angles_deg: NumericArrayLike = ..., source_angle_deg: float = ..., n_repetitions: int | np.integer[Any] = ..., speed_of_sound: float = ..., include_aperture: bool = ..., include_obliquity: bool = ...,) -> DiffuserPolarResponse
predict_diffuser_polar_response( well_width: float, frequency: float, *, reflection: NumericArrayLike, angles_deg: NumericArrayLike = ..., source_angle_deg: float = ..., n_repetitions: int | np.integer[Any] = ..., speed_of_sound: float = ..., include_aperture: bool = ..., include_obliquity: bool = ...,) -> DiffuserPolarResponsePredict the far-field polar response of a diffuser (Cox and D’Antonio, Eq. (5.8)).
Evaluates the single-plane Fraunhofer scattered pressure of a periodic
phase-grating surface and reduces it to the ISO 17497-2 directional
diffusion coefficient. Supply the surface either as rigid-bottom well
depths () or as an explicit per-well complex
reflection sequence (for admittance or resonator-loaded surfaces); give
exactly one.
Parameters
| Name | Description |
|---|---|
well_width |
Well width w, in metres (uniform across wells). |
frequency |
Frequency of the prediction f, in hertz. |
depths |
Well depths d_n of one period, in metres (1-D, at least two wells); mutually exclusive with reflection. |
reflection |
Explicit per-well complex pressure reflection coefficient of one period (1-D, at least two wells); mutually exclusive with depths. |
angles_deg |
Receiver reflection angles theta, in degrees; defaults to the ISO 17497-2 semicircle DEFAULT_POLAR_ANGLES_DEG. |
source_angle_deg |
Angle of incidence psi of the source, in degrees (0 = normal incidence). |
n_repetitions |
Number of repetitions N_p of the single period; the grating lobes that define a Schroeder diffuser require periods >= 2. |
speed_of_sound |
Speed of sound c, in metres per second. |
include_aperture |
Include the single-well aperture directivity of Eq. (9.32); defaults to True. |
include_obliquity |
Include the Kirchhoff obliquity factor , the oblique-source generalisation of the normal-incidence of Eq. (9.32); defaults to True. |
Returns: A DiffuserPolarResponse with the per-angle levels, the directional diffusion coefficient and .plot().
Raises
| Exception | When |
|---|---|
| ValueError | for invalid geometry, or if not exactly one of depths and reflection is supplied. |
| TypeError | if frequency, source_angle_deg, speed_of_sound or well_width is not a single number, or n_repetitions is a flag, a text or an array where a count goes, or angles_deg or depths holds a text or a value that is not a real number, or reflection holds a text or a value that is not a number. |
predicted_diffusion_spectrum
Section titled “predicted_diffusion_spectrum”predicted_diffusion_spectrum( well_width: float, frequencies: NumericArrayLike, *, depths: NumericArrayLike, reflection_of: None = None, angles_deg: NumericArrayLike = (-90, -85, -80, -75, -70, -65, -60, -55, -50, -45, -40, -35, -30, -25, -20, -15, -10, -5, 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90), source_angle_deg: float = 0.0, n_repetitions: int | np.integer[Any] = 1, speed_of_sound: float = 343.0, include_aperture: bool = True, include_obliquity: bool = True, normalize: bool = True,) -> DiffusionSpectrumPredicted diffusion-coefficient spectrum d(f) of a diffuser design.
Predicts the far-field polar response at each frequency with
predict_diffuser_polar_response, forms the ISO 17497-2 directional
diffusion coefficient band by band, and (by default) normalises it against a
same-footprint flat reference surface (all wells of zero depth) with
normalized_diffusion_coefficient
(Formula (7)). The result reuses
DiffusionSpectrum, so it
plots and reports like a measured spectrum.
Only the rigid-bottom well depths path supports the automatic flat
reference; an explicit frequency-dependent reflection model is out of scope
for this helper (build the spectrum yourself from
predict_diffuser_polar_response in that case).
Parameters
| Name | Description |
|---|---|
well_width |
Well width w, in metres. |
frequencies |
Frequencies of the spectrum, in hertz (1-D). |
depths |
Well depths d_n of one period, in metres (1-D, at least two wells). |
reflection_of |
Reserved for future frequency-dependent reflection models; must be None. |
angles_deg |
Receiver reflection angles theta, in degrees; defaults to DEFAULT_POLAR_ANGLES_DEG. |
source_angle_deg |
Angle of incidence psi, in degrees. |
n_repetitions |
Number of repetitions N_p of the single period. |
speed_of_sound |
Speed of sound c, in metres per second. |
include_aperture |
Include the single-well aperture directivity. |
include_obliquity |
Include the Kirchhoff obliquity factor. |
normalize |
If True (default), also compute the normalised coefficient d_n against the flat reference. |
Returns: A DiffusionSpectrum carrying the raw diffusion d(f) and, when normalize is True, the normalised d_n(f).
Raises
| Exception | When |
|---|---|
| ValueError | for invalid geometry, an empty frequencies array, or if reflection_of is not None. |
| TypeError | if depths or frequencies holds a text or a value that is not a real number. |
qrd_well_depths
Section titled “qrd_well_depths”qrd_well_depths( prime: int | np.integer[Any], design_frequency: float, *, speed_of_sound: float = 343.0,) -> NDArray[np.float64]Well depths of a quadratic residue diffuser (Cox and D’Antonio, Eq. (10.3)).
with the quadratic residue sequence
s_n of quadratic_residue_sequence and the design wavelength
. The depths span 0 to roughly
.
Parameters
| Name | Description |
|---|---|
prime |
Prime generator N (odd prime, at least 3). |
design_frequency |
Design frequency f_0, in hertz, normally the lower frequency limit of the device. |
speed_of_sound |
Speed of sound c, in metres per second; defaults to 343 m/s. |
Returns: Well depths d_n, in metres, one per well of a single period.
Raises
| Exception | When |
|---|---|
| ValueError | if prime is not an odd prime, or if design_frequency or speed_of_sound is not positive. |
| TypeError | if design_frequency or speed_of_sound is not a single number, or prime is a flag, a text or an array where a count goes. |
quadratic_residue_sequence
Section titled “quadratic_residue_sequence”quadratic_residue_sequence( prime: int | np.integer[Any],) -> NDArray[np.float64]Quadratic residue sequence s_n (Cox and D’Antonio, Eq. (10.2)).
for , the least
non-negative remainders, where N is the (odd) prime generator and
number of wells per period. For this returns
[0, 1, 4, 2, 2, 4, 1].
Parameters
| Name | Description |
|---|---|
prime |
Prime generator N (odd prime, at least 3). |
Returns: The sequence s_n as an integer-valued float array of length N.
Raises
| Exception | When |
|---|---|
| ValueError | if prime is not an odd prime of at least 3. |
| TypeError | if prime is a flag, a text or an array where a count goes. |