materials.surfaces.road_absorption
In-situ sound absorption of road surfaces (ISO 13472-1 / ISO 13472-2).
Two complementary standardised in-situ methods are supported here. They target opposite ends of the absorption scale and are not interchangeable:
-
BS ISO 13472-1:2002: the extended surface method. A free-field impulse response is measured over the road, the direct (incident) and surface (reflected) components are separated in the time domain by the subtraction technique and an Adrienne-type temporal window (Clause 6.4), transformed to frequency, and ratioed. The normal-incidence sound absorption coefficient is (Clause 4.1):
with
Hi/Hrthe incident/reflected transfer functions andKrthe geometrical-spreading factor for the mandatory geometry m (source-to-plane) and m (mic-to-plane), giving (Clause 4.2 / Annex C). The complex pressure reflection factor with (Annex C) is available for theory comparison. A highly reflective reference surface removes the electro-acoustic chain error and the geometry factor by a ratio (Annex B), and non-normal incidence uses (Annex F). -
BS ISO 13472-2:2010: the spot method. This is an in-situ application of the ISO 10534-2 two-microphone impedance tube for reflective surfaces (measured
alphabelow ~0.15). Part 2 does not restate the transfer-function / reflection-factor / absorption mathematics; Clauses 4, 5.7 and 6.6 defer it to ISO 10534-2. The core computation therefore lives intwo_microphone_impedanceand is not reimplemented here. This module contributes only the Part-2 tube geometry/validity helpers (upper usable frequency, microphone-spacing bounds, the 250-1600 Hz one-third-octave working range) and the Annex A internal-loss system correction .
Sign / normalisation convention (ISO 13472-1): the forward transform is
NumPy’s rfft with kernel (unnormalised); every
quantity here is a ratio of two transforms from the same processing chain, so
the transform normalisation cancels (Clause 6.1). A pure time delay tau of
the reflected path scales its spectrum by ; the
optional phase restoration multiplies by to
recover Qp (Annex C /
Annex G, resolving the Clause 4.1 NOTE shorthand to the frequency-dependent
form).
The window durations of the Adrienne window are not fixed by the standard: Clause 6.4 mandates only a sharp leading edge, a 5 ms flat portion and a cosine-squared or Blackman-Harris trailing edge, with the shape and lengths reported per measurement. They are therefore configurable here and default to a short leading edge, a 5 ms flat top and a Blackman-Harris trailing edge (the Annex E example report); the historical fixed edge timings are not hard-coded as if normative.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
absorption_reference_corrected
Section titled “absorption_reference_corrected”absorption_reference_corrected( road_reflection: complex | np.number[Any], reference_reflection: complex | np.number[Any],) -> float
absorption_reference_corrected( road_reflection: Sequence[complex] | Sequence[np.number[Any]] | NDArray[np.bool_ | np.number[Any]], reference_reflection: NumericArrayLike,) -> NDArray[np.float64]
absorption_reference_corrected( road_reflection: complex | np.number[Any], reference_reflection: Sequence[complex] | Sequence[np.number[Any]] | NDArray[np.bool_ | np.number[Any]],) -> NDArray[np.float64]
absorption_reference_corrected( road_reflection: NumericArrayLike, reference_reflection: NumericArrayLike,) -> float | NDArray[np.float64]Reference-corrected road absorption (ISO 13472-1:2002, Annex B).
Dividing the road and reference measured pressure reflection factors removes
both the electro-acoustic chain error e(f) and, because the geometry is
identical, the Kr factor:
The reference surface is assumed totally reflecting (, checked in an impedance tube to have absorption < 0.05, Annex B).
Parameters
| Name | Description |
|---|---|
road_reflection |
Measured road pressure reflection factor Qp,road,meas (complex; the 1 / Kr scaling need not be removed as it cancels). |
reference_reflection |
Measured reference pressure reflection factor Qp,ref,meas (complex, same geometry and chain). |
Returns: Reference-corrected road absorption coefficient alpha_road(f). A float when road_reflection and reference_reflection are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if reference_reflection or road_reflection holds a text or a value that is not a number. |
adrienne_window
Section titled “adrienne_window”adrienne_window( fs: float, *, flat_duration_s: float = 0.005, leading_duration_s: float = 0.0005, trailing_duration_s: float = 0.005, leading_edge: Literal['blackman-harris', 'cosine-squared'] = 'blackman-harris', trailing_edge: Literal['blackman-harris', 'cosine-squared'] = 'blackman-harris',) -> NDArray[np.float64]Adrienne-type temporal window (ISO 13472-1:2002, Clause 6.4).
Clause 6.4 mandates a sharp leading edge, a 5 ms flat portion and a cosine-squared or Blackman-Harris trailing edge so as to suppress frequency-domain oscillations (Figure 4); the shape and the durations are reported per measurement rather than fixed by the standard. All three durations are therefore configurable. The window is the concatenation of a rising leading half-taper, a unit-valued flat portion and a falling trailing half-taper:
w = [ rising_edge (0 -> 1) | flat (== 1) | trailing_edge (1 -> 0) ]The defaults (short 0.5 ms leading edge, 5 ms flat top, 5 ms Blackman-Harris
trailing edge) follow the Annex E example report; they are not a
normative fixed set of timings. The lower usable frequency scales as
~ 1 / T_window (Clause 6.4), so report the durations used.
Parameters
| Name | Description |
|---|---|
fs |
Sampling frequency, in hertz (ISO 13472-1 Clause 6.2 requires fs > 40 kHz in practice). |
flat_duration_s |
Flat-portion duration, in seconds (default 5 ms). |
leading_duration_s |
Leading-edge (rise) duration, in seconds; 0 gives a sharp step onset. |
trailing_duration_s |
Trailing-edge (fall) duration, in seconds. |
leading_edge |
Leading-edge shape, "blackman-harris" or "cosine-squared". |
trailing_edge |
Trailing-edge shape, "blackman-harris" or "cosine-squared". |
Returns: The time-domain window, one sample per 1 / fs (length round((leading + flat + trailing) * fs) samples).
Raises
| Exception | When |
|---|---|
| ValueError | If fs is not positive, a duration is negative, the flat duration is not positive, or an edge shape is unknown. |
| TypeError | if flat_duration_s, fs, leading_duration_s or trailing_duration_s is not a single number, or leading_edge or trailing_edge is not a text. |
check_spot_frequency_range
Section titled “check_spot_frequency_range”check_spot_frequency_range(frequency: NumericArrayLike) -> NoneAdvise when a spot-method frequency is out of range (ISO 13472-2, Scope).
The spot method is valid over the one-third-octave bands 250-1600 Hz
(narrow-band 220-1800 Hz). Frequencies outside SPOT_FREQUENCY_RANGE_HZ
raise a RoadAbsorptionWarning; results there are advisory.
Parameters
| Name | Description |
|---|---|
frequency |
Frequency or frequencies to check, in hertz. |
Raises
| Exception | When |
|---|---|
| ValueError | If any frequency is negative. |
| TypeError | if frequency holds a text or a value that is not a real number. |
DEFAULT_MICROPHONE_HEIGHT_M
Section titled “DEFAULT_MICROPHONE_HEIGHT_M”Constant (float).
DEFAULT_MICROPHONE_HEIGHT_M = 0.25DEFAULT_SOURCE_HEIGHT_M
Section titled “DEFAULT_SOURCE_HEIGHT_M”Constant (float).
DEFAULT_SOURCE_HEIGHT_M = 1.25geometric_spreading_factor
Section titled “geometric_spreading_factor”geometric_spreading_factor( *, source_height_m: float = 1.25, microphone_height_m: float = 0.25,) -> floatGeometrical-spreading factor Kr (ISO 13472-1:2002, Clause 4.1).
. It corrects the reflected path for the extra spherical spreading over the image-source distance relative to the direct distance (Annex C). The mandatory geometry m, m gives (Clause 4.2).
Parameters
| Name | Description |
|---|---|
source_height_m |
Source-to-reference-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-reference-plane distance dm, in metres. |
Returns: Geometrical-spreading factor Kr (dimensionless, ).
Raises
| Exception | When |
|---|---|
| ValueError | If ds or dm is not positive or . |
| TypeError | if microphone_height_m or source_height_m is not a single number. |
geometric_spreading_factor_angle
Section titled “geometric_spreading_factor_angle”geometric_spreading_factor_angle( incidence_angle_rad: float, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25,) -> floatOblique geometrical-spreading factor (ISO 13472-1, Annex F).
with Kr the
normal-incidence factor of geometric_spreading_factor. At
the
cosine is unity and Kr,theta collapses to Kr (Clause 4.1).
Parameters
| Name | Description |
|---|---|
incidence_angle_rad |
Incidence angle theta, in radians. |
source_height_m |
Source-to-reference-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-reference-plane distance dm, in metres. |
Returns: Oblique factor Kr,theta (positive root, dimensionless).
Raises
| Exception | When |
|---|---|
| TypeError | if incidence_angle_rad is not a single number. |
in_situ_absorption_coefficient
Section titled “in_situ_absorption_coefficient”in_situ_absorption_coefficient( incident_ir: Signal | NumericArrayLike, reflected_ir: Signal | NumericArrayLike, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, incidence_angle_rad: float = 0.0, n: int | np.integer[Any] | None = None,) -> NDArray[np.float64]Normal-incidence absorption coefficient alpha(f) (ISO 13472-1, 4.1).
(the direct
energy route via power_reflection_coefficient; for oblique incidence
Kr is replaced by Kr,theta, Annex F). Non-specularly reflected energy
is treated as absorbed, so alpha may be slightly overestimated
(Clause 4.1).
Parameters
| Name | Description |
|---|---|
incident_ir |
Windowed incident impulse response hi(t), real. Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: what is read off the pair is the ratio of their transfer functions, so a factor the two share divides out. |
reflected_ir |
Windowed reflected impulse response hr(t), real. Same treatment as incident_ir; two Signals recorded at different rates are refused rather than arbitrated. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
incidence_angle_rad |
Incidence angle theta, in radians (0 = normal). |
n |
FFT length; defaults to the longer input. |
Returns: Absorption coefficient alpha(f) at the rfft frequency bins.
in_situ_absorption_from_reflection
Section titled “in_situ_absorption_from_reflection”in_situ_absorption_from_reflection( reflection: complex | np.number[Any],) -> float
in_situ_absorption_from_reflection( reflection: Sequence[complex] | Sequence[np.number[Any]] | NDArray[np.bool_ | np.number[Any]],) -> NDArray[np.float64]
in_situ_absorption_from_reflection( reflection: NumericArrayLike,) -> float | NDArray[np.float64]Absorption coefficient from the reflection factor (ISO 13472-1, 4.1).
. With r already carrying the
factor
(see in_situ_reflection_factor) this is the reflection-factor route to
alpha and equals the direct energy route of
in_situ_absorption_coefficient.
Parameters
| Name | Description |
|---|---|
reflection |
Complex reflection factor r. |
Returns: Absorption coefficient alpha (real). A float for a number, an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if reflection holds a text or a value that is not a number. |
in_situ_absorption_spectrum
Section titled “in_situ_absorption_spectrum”in_situ_absorption_spectrum( incident_ir: Signal | NumericArrayLike, reflected_ir: Signal | NumericArrayLike, fs: float | None = None, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, incidence_angle_rad: float = 0.0, n: int | np.integer[Any] | None = None, f_min: float = 250.0, f_max: float = 4000.0, clip_negative: bool = True,) -> InSituAbsorptionResultIn-situ one-third-octave absorption spectrum (ISO 13472-1, Clause 4.1).
End-to-end convenience: the windowed incident and reflected impulse
responses give the narrow-band absorption via
in_situ_absorption_coefficient, which is then reduced to
one-third-octave bands with one_third_octave_absorption and wrapped
in a plottable InSituAbsorptionResult.
Parameters
| Name | Description |
|---|---|
incident_ir |
Windowed incident (direct-path) impulse response hi. Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: what is read off the pair is the ratio of their transfer functions, so a factor the two share divides out. |
reflected_ir |
Windowed reflected-path impulse response hr. Same treatment as incident_ir: its calibration is applied too, which is what makes the shared factor cancel rather than skew the ratio. |
fs |
Sampling frequency, in hertz. Required when both records are bare arrays; either may be a Signal and supply it, and two Signals recorded at different rates are refused rather than arbitrated. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
incidence_angle_rad |
Incidence angle theta, in radians (0 = normal). |
n |
FFT length; defaults to the longer of the two impulse responses. |
f_min |
Lowest band centre to report, in hertz (default 250 Hz). |
f_max |
Highest band centre to report, in hertz (default 4000 Hz). |
clip_negative |
Clip negative band results to zero (default True). |
Returns: An InSituAbsorptionResult with .plot().
Raises
| Exception | When |
|---|---|
| ValueError | On empty inputs, invalid geometry, or a non-positive fs. |
| TypeError | if fs is not a single number, or incident_ir or reflected_ir holds a text or a value that is not a real number. |
in_situ_reflection_factor
Section titled “in_situ_reflection_factor”in_situ_reflection_factor( incident_ir: Signal | NumericArrayLike, reflected_ir: Signal | NumericArrayLike, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, incidence_angle_rad: float = 0.0, fs: float | None = None, delay: float | None = None, n: int | np.integer[Any] | None = None,) -> NDArray[np.complex128]Complex pressure reflection factor r(f) (ISO 13472-1, Clause 4.1).
from the windowed reflected and
incident
impulse responses, with Hr/Hi their real FFTs and Kr the
geometrical-spreading factor (or Kr,theta when incidence_angle_rad is
given, Annex F). When both fs and delay are supplied the
reflected-path time offset is undone by
, yielding
the complex Qp of the Clause 4.1 NOTE (with delay set to
,
Annex C; the frequency-dependent form of Annex G).
Parameters
| Name | Description |
|---|---|
incident_ir |
Windowed incident (direct-path) impulse response hi(t), real, one sample per 1 / fs. Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: what is read off the pair is the ratio of their transfer functions, so a factor the two share divides out. |
reflected_ir |
Windowed reflected-path impulse response hr(t), real, same sampling as incident_ir. Same treatment as incident_ir: its calibration is applied too, which is what makes the shared factor cancel rather than skew the ratio. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
incidence_angle_rad |
Incidence angle theta, in radians (0 = normal). |
fs |
Sampling frequency, in hertz; required with delay for phase restoration, and otherwise unused. Either record may be a Signal and supply it; an explicit value that disagrees with one raises, and two Signals recorded at different rates are refused rather than arbitrated. |
delay |
Reflected-path delay dtau to undo, in seconds; None returns the raw spectral ratio. |
n |
FFT length; defaults to the longer of the two impulse responses. |
Returns: Complex reflection factor r(f) at the rfft frequency bins.
Raises
| Exception | When |
|---|---|
| ValueError | On empty inputs, invalid geometry, or delay given without fs. |
| TypeError | if fs is not a single number, delay is not one real number, n is not a whole number, or incident_ir or reflected_ir holds a text or a value that is not a real number. |
InSituAbsorptionResult
Section titled “InSituAbsorptionResult”InSituAbsorptionResult( frequencies: NDArray[np.float64], absorption: NDArray[np.float64], *, source_height_m: float, microphone_height_m: float,)An in-situ one-third-octave absorption spectrum (ISO 13472-1).
Attributes
| Name | Description |
|---|---|
frequencies |
One-third-octave band centre frequencies, in hertz. |
absorption |
Sound-absorption coefficient alpha per band (a band with no contributing narrow-band samples is nan). |
source_height_m |
Source height the spectrum was reduced with, in metres, retained (with microphone_height_m) so plot_geometry can draw the set-up. |
microphone_height_m |
Microphone height, in metres. |
InSituAbsorptionResult.plot()
Section titled “InSituAbsorptionResult.plot()”InSituAbsorptionResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the in-situ absorption spectrum alpha(f).
Requires matplotlib (the [plot] extra); returns the
Axes and never calls plt.show.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
InSituAbsorptionResult.plot_geometry()
Section titled “InSituAbsorptionResult.plot_geometry()”InSituAbsorptionResult.plot_geometry( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the measurement set-up to scale.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
ISO13472_SPEED_OF_SOUND_M_S
Section titled “ISO13472_SPEED_OF_SOUND_M_S”Constant (float).
ISO13472_SPEED_OF_SOUND_M_S = 340.0max_sampled_area_radius
Section titled “max_sampled_area_radius”max_sampled_area_radius( window_width: float, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, speed_of_sound: float = 340.0,) -> floatRadius of the maximum sampled area (ISO 13472-1:2002, Annex A).
For normal incidence the maximum sampled area is a circle of radius (m):
with Tw the width of the temporal window isolating the reflected wave.
The Annex A worked example (, ,
m/s, and the 5 ms flat window) gives
m.
Parameters
| Name | Description |
|---|---|
window_width |
Temporal-window width Tw (reflected wave), seconds. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
speed_of_sound |
Speed of sound c, in metres per second. |
Returns: Maximum-sampled-area radius r, in metres.
Raises
| Exception | When |
|---|---|
| ValueError | On non-positive geometry or window width. |
| TypeError | if microphone_height_m, source_height_m, speed_of_sound or window_width is not a single number. |
msa_major_axis
Section titled “msa_major_axis”msa_major_axis( window_width: float, projected_distance: float, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, speed_of_sound: float = 340.0,) -> floatMajor axis of the oblique sampled-area ellipsoid (ISO 13472-1, Annex F).
for the ellipsoid of
revolution with the source and microphone at its foci; dp is the
source-to-microphone distance projected on the reference plane.
Parameters
| Name | Description |
|---|---|
window_width |
Temporal-window width Tw, in seconds. |
projected_distance |
Projected source-to-mic distance dp, in metres. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
speed_of_sound |
Speed of sound c, in metres per second. |
Returns: Major axis a, in metres.
Raises
| Exception | When |
|---|---|
| ValueError | On non-positive window width, speed, or negative dp. |
| TypeError | if microphone_height_m, projected_distance, source_height_m, speed_of_sound or window_width is not a single number. |
one_third_octave_absorption
Section titled “one_third_octave_absorption”one_third_octave_absorption( absorption: NumericArrayLike, *, frequencies: NumericArrayLike, f_min: float = 250.0, f_max: float = 4000.0, clip_negative: bool = True,) -> OneThirdOctaveAbsorptionAggregate narrow-band absorption into one-third-octave bands.
Both parts require a linear average of the narrow-band absorption over
each one-third-octave band (ISO 13472-1 Clause 4.1; ISO 13472-2 Clause 6.6),
keeping negative narrow-band values during the averaging. The band edges are
the IEC base-two limits . Negative one-third-octave
results are set to zero when clip_negative is true (ISO 13472-2
Clause 6.6 step 5); Part 1 does not mandate clipping, so pass
clip_negative=False to reproduce its raw output.
Parameters
| Name | Description |
|---|---|
frequencies |
Narrow-band frequencies, in hertz. |
absorption |
Narrow-band absorption values aligned with frequencies. |
f_min |
Lowest band centre to report, in hertz (default 250 Hz). |
f_max |
Highest band centre to report, in hertz (4000 Hz for Part 1; pass 1600 Hz for the Part-2 range). |
clip_negative |
Set negative band results to zero (default True). |
Returns: The band centres and the band absorption, as a OneThirdOctaveAbsorption; a band with no narrow-band samples yields nan.
Raises
| Exception | When |
|---|---|
| ValueError | If frequencies and absorption differ in shape or are empty. |
| TypeError | if absorption or frequencies holds a text or a value that is not a real number, or f_max or f_min is not a single number. |
OneThirdOctaveAbsorption
Section titled “OneThirdOctaveAbsorption”OneThirdOctaveAbsorption( frequencies: NDArray[np.float64], absorption: NDArray[np.float64],)Narrow-band absorption averaged into one-third-octave bands.
What one_third_octave_absorption returns: the band centres and
the band absorption, named, where a (band_centres, band_absorption)
tuple used to be unpacked by position.
Attributes
| Name | Description |
|---|---|
frequencies |
The one-third-octave band centres, in Hz. |
absorption |
The linear average of the narrow-band absorption in each band; nan for a band with no narrow-band sample. |
OneThirdOctaveAbsorption.plot()
Section titled “OneThirdOctaveAbsorption.plot()”OneThirdOctaveAbsorption.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the band absorption against the band centres.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the absorption curve. |
Returns: The axes.
PART1_FREQUENCY_RANGE_HZ
Section titled “PART1_FREQUENCY_RANGE_HZ”Constant (tuple).
PART1_FREQUENCY_RANGE_HZ = (250.0, 4000.0)plot_in_situ_geometry
Section titled “plot_in_situ_geometry”plot_in_situ_geometry( *, ax: Axes | None = None, source_height_m: float = 1.25, microphone_height_m: float = 0.25, sampled_radius: float | None = 1.34, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the in-situ surface-absorption set-up to scale.
Loudspeaker on its mast above the surface, microphone below it, direct and surface-reflected paths, and the sampled-area radius on the ground. Defaults are the standard heights (1.25 m source, 0.25 m microphone) with the sampled radius of the standard 5 ms window.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
source_height_m |
Source height above the surface, in metres. |
microphone_height_m |
Microphone height, in metres (< source_height_m). |
sampled_radius |
Sampled-area radius drawn on the ground, in metres; None omits it. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the surface rectangle. |
Returns: The axes.
Raises
| Exception | When |
|---|---|
| ValueError | for a height or sampled radius that is not finite and positive, or a source no higher than the microphone. |
| TypeError | if microphone_height_m, sampled_radius or source_height_m is not a single number. |
power_reflection_coefficient
Section titled “power_reflection_coefficient”power_reflection_coefficient( incident_ir: Signal | NumericArrayLike, reflected_ir: Signal | NumericArrayLike, *, source_height_m: float = 1.25, microphone_height_m: float = 0.25, incidence_angle_rad: float = 0.0, n: int | np.integer[Any] | None = None,) -> NDArray[np.float64]Sound-power reflection factor QW(f) (ISO 13472-1, 4.1 / Annex C).
The direct energy route
(Kr,theta for oblique incidence). It equals
from
in_situ_reflection_factor but is formed from magnitudes only, so it is
independent of any reflected-path time offset.
Parameters
| Name | Description |
|---|---|
incident_ir |
Windowed incident impulse response hi(t), real. Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: what is read off the pair is the ratio of their transfer functions, so a factor the two share divides out. |
reflected_ir |
Windowed reflected impulse response hr(t), real. Same treatment as incident_ir; two Signals recorded at different rates are refused rather than arbitrated. |
source_height_m |
Source-to-plane distance ds, in metres. |
microphone_height_m |
Microphone-to-plane distance dm, in metres. |
incidence_angle_rad |
Incidence angle theta, in radians. |
n |
FFT length; defaults to the longer input. |
Returns: Sound-power reflection factor QW(f) (real).
Raises
| Exception | When |
|---|---|
| TypeError | if incident_ir or reflected_ir holds a text or a value that is not a real number, or n is not a whole number. |
reflected_path_delay
Section titled “reflected_path_delay”reflected_path_delay( microphone_height_m: float = 0.25, *, speed_of_sound: float = 340.0,) -> floatReflected-path arrival delay dtau (ISO 13472-1:2002, Annex C).
is the time difference between the direct
and the surface-reflected impulses for the normal-incidence geometry; it
is the delay undone by the phase-restoration term of
in_situ_reflection_factor.
Parameters
| Name | Description |
|---|---|
microphone_height_m |
Microphone-to-reference-plane distance dm, in metres. |
speed_of_sound |
Speed of sound c, in metres per second. |
Returns: Delay dtau, in seconds.
Raises
| Exception | When |
|---|---|
| ValueError | If dm or c is not positive. |
| TypeError | if microphone_height_m or speed_of_sound is not a single number. |
RoadAbsorptionWarning
Section titled “RoadAbsorptionWarning”Advisory for out-of-range in-situ road-absorption frequencies.
SPOT_FREQUENCY_RANGE_HZ
Section titled “SPOT_FREQUENCY_RANGE_HZ”Constant (tuple).
SPOT_FREQUENCY_RANGE_HZ = (250.0, 1600.0)spot_internal_loss_correction
Section titled “spot_internal_loss_correction”spot_internal_loss_correction( measured_absorption: float | np.floating[Any] | np.integer[Any], system_absorption: float | np.floating[Any] | np.integer[Any], *, clip_negative: bool = ...,) -> float
spot_internal_loss_correction( measured_absorption: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], system_absorption: NumericArrayLike, *, clip_negative: bool = ...,) -> NDArray[np.float64]
spot_internal_loss_correction( measured_absorption: float | np.floating[Any] | np.integer[Any], system_absorption: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, clip_negative: bool = ...,) -> NDArray[np.float64]
spot_internal_loss_correction( measured_absorption: NumericArrayLike, system_absorption: NumericArrayLike, *, clip_negative: bool = ...,) -> float | NDArray[np.float64]Internal-loss (system) correction (ISO 13472-2:2010, Annex A).
The tube reads all thermal/viscous losses between the microphones and the surface as absorption. For reflective surfaces this is removed by subtracting the reading on a totally reflecting reference plate:
Valid because both terms are small (measured < 0.15, internal < 0.03). This
is the subtractive Part-2 correction and must not be confused with the
Part-1 ratio correction (absorption_reference_corrected). Negative
one-third-octave results are set to zero when clip_negative is true
(Clause 6.6 step 5).
Parameters
| Name | Description |
|---|---|
measured_absorption |
Measured road absorption alpha_m(f). |
system_absorption |
Reference-plate (system) absorption alpha_system(f), same bands. |
clip_negative |
Set negative corrected values to zero (default True). |
Returns: Corrected absorption coefficient alpha(f). A float when measured_absorption and system_absorption are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | If the two inputs differ in shape. |
| TypeError | if measured_absorption or system_absorption holds a text or a value that is not a real number. |
spot_microphone_spacing_bounds
Section titled “spot_microphone_spacing_bounds”spot_microphone_spacing_bounds( *, speed_of_sound: float = 340.0, f_min: float = 220.0, f_max: float = 1800.0,) -> tuple[float, float]Microphone-spacing bounds (s_min, s_max) (ISO 13472-2:2010, 5.4.2).
avoids spacing approaching half a wavelength at the top frequency, and keeps the spacing above 5 % of a wavelength at the bottom frequency. For the narrow band 220-1800 Hz ( m/s) these give mm and mm, bracketing the nominal mm.
Parameters
| Name | Description |
|---|---|
speed_of_sound |
Speed of sound c0, in metres per second. |
f_min |
Lowest frequency of interest f_min, in hertz. |
f_max |
Highest frequency of interest f_max, in hertz. |
Returns: Tuple (s_min, s_max) of the lower and upper spacing limits, m.
Raises
| Exception | When |
|---|---|
| ValueError | On non-positive speed or frequency, or f_min >= f_max. |
| TypeError | if f_max, f_min or speed_of_sound is not a single number. |
SPOT_NARROW_BAND_RANGE_HZ
Section titled “SPOT_NARROW_BAND_RANGE_HZ”Constant (tuple).
SPOT_NARROW_BAND_RANGE_HZ = (220.0, 1800.0)spot_tube_upper_frequency
Section titled “spot_tube_upper_frequency”spot_tube_upper_frequency( diameter_m: float, *, speed_of_sound: float = 340.0,) -> floatUpper usable frequency of the spot tube (ISO 13472-2:2010, 5.4.1).
(circular tube), the highest frequency at which only plane waves propagate. A 100 mm tube at m/s gives Hz, comfortably above the 1800 Hz narrow-band top.
Parameters
| Name | Description |
|---|---|
diameter_m |
Tube diameter d, in metres. |
speed_of_sound |
Speed of sound c0, in metres per second. |
Returns: Upper usable frequency f_u, in hertz.
Raises
| Exception | When |
|---|---|
| ValueError | If d or c0 is not positive. |
| TypeError | if diameter_m or speed_of_sound is not a single number. |