materials.diffuser_design

Far-field polar response and diffusion coefficient predicted from a diffuser design.

Where phonometry.materials.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_n behaves, at normal incidence and with a rigid bottom, as a locally reacting patch of pressure reflection coefficient R_n = exp(-2 j k d_n) (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 theta for a source at incidence psi is the sum over the wells of the periodic surface (Chapter 5, Equation (5.8), and Chapter 9, Equation (9.32)):

p(theta) = F(theta) * sum_n R_n * exp(j k x_n (sin psi + sin theta))

with x_n the centre of the n-th well and k = 2 pi f / c. The optional prefactor F(theta) collects the single-well aperture directivity sinc(k w (sin psi + sin theta) / 2) (the Fourier transform of one well of width w) and the Kirchhoff obliquity factor (1 + cos theta) / 2 of Equation (9.32); both are absorbed into the constant A of Equation (5.8) and can be switched off to recover the plain Fourier form.

The polar levels L_i = 20 lg|p(theta_i)| 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)):

s_n = n^2 mod N          d_n = s_n * lambda_0 / (2 N),    lambda_0 = c / f_0.

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

Constant (tuple).

DEFAULT_POLAR_ANGLES = (-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

DiffuserPolarResponse(
    frequency: float,
    angles: Real,
    levels: Real,
    coefficient: float,
    source_angle: float = 0.0,
    well_width: float | None = None,
    depths: Real | None = None,
    periods: int | None = None,
)

A predicted far-field polar response of a diffuser at one frequency.

Attributes

Name	Description
frequency	Frequency of the prediction, in hertz.
angles	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	Angle of incidence psi of the source, in degrees.
well_width	Well width w of the predicted surface, in metres, always retained by the predictor (with periods) so plot_geometry can draw the well profile; appended after the original fields and None only for hand-built responses.
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).
periods	Number of repeated periods of the prediction.

DiffuserPolarResponse.plot()

DiffuserPolarResponse.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the predicted polar response with the diffusion coefficient annotated.

Requires matplotlib (pip install phonometry[plot]); returns the polar Axes and never calls plt.show.

DiffuserPolarResponse.plot_geometry()

DiffuserPolarResponse.plot_geometry(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Draw the well profile of the predicted surface to scale.

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

Raises

Exception	When
ValueError	If the response does not retain its well geometry (hand-built, or predicted from an explicit reflection sequence).

plot_qrd_geometry

plot_qrd_geometry(
    depths: ArrayLike,
    well_width: float,
    ax: Axes | None = None,
    *,
    periods: int = 1,
    fin_width: float | None = None,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Draw the well profile of a quadratic-residue diffuser, to scale.

Wells open upward; the profile repeats periods 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.
periods	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.

predict_diffuser_polar_response

predict_diffuser_polar_response(
    well_width: float,
    frequency: float,
    *,
    depths: ArrayLike | None = None,
    reflection: ArrayLike | None = None,
    angles: ArrayLike = (-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: float = 0.0,
    periods: int = 1,
    speed_of_sound: float = 343.0,
    include_aperture: bool = True,
    include_obliquity: bool = True,
) -> DiffuserPolarResponse

Predict 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 (R_n = exp(-2 j k d_n)) 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	Receiver reflection angles theta, in degrees; defaults to the ISO 17497-2 semicircle DEFAULT_POLAR_ANGLES.
source_angle	Angle of incidence psi of the source, in degrees (0 = normal incidence).
periods	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 sinc(k w (sin psi + sin theta) / 2) of Eq. (9.32); defaults to True.
include_obliquity	Include the Kirchhoff obliquity factor (cos theta + cos psi) / 2, the oblique-source generalisation of the normal-incidence (1 + cos theta) / 2 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.

predicted_diffusion_spectrum

predicted_diffusion_spectrum(
    well_width: float,
    frequencies: ArrayLike,
    *,
    depths: ArrayLike | None = None,
    reflection_of: Any | None = None,
    angles: ArrayLike = (-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: float = 0.0,
    periods: int = 1,
    speed_of_sound: float = 343.0,
    include_aperture: bool = True,
    include_obliquity: bool = True,
    normalize: bool = True,
) -> DiffusionSpectrum

Predicted 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	Receiver reflection angles theta, in degrees; defaults to DEFAULT_POLAR_ANGLES.
source_angle	Angle of incidence psi, in degrees.
periods	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.

qrd_well_depths

qrd_well_depths(
    prime: int,
    design_frequency: float,
    *,
    speed_of_sound: float = 343.0,
) -> Real

Well depths of a quadratic residue diffuser (Cox and D’Antonio, Eq. (10.3)).

d_n = s_n * lambda_0 / (2 N) with the quadratic residue sequence s_n of quadratic_residue_sequence and the design wavelength lambda_0 = c / f_0. The depths span 0 to roughly lambda_0 / 2.

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.

quadratic_residue_sequence

quadratic_residue_sequence(prime: int) -> Real

Quadratic residue sequence s_n (Cox and D’Antonio, Eq. (10.2)).

s_n = n^2 mod N for n = 0, 1, ..., N - 1, the least non-negative remainders, where N is the (odd) prime generator and number of wells per period. For N = 7 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.