Skip to content

environment.propagation.ground_barriers

Spherical-wave ground effect and advanced barrier diffraction.

This module extends the tabulated ground and barrier terms of ISO 9613-2 (see phonometry.environment.propagation.outdoor_propagation) with the underlying wave acoustics: the spherical-wave reflection coefficient of a finite-impedance ground and the wave-theoretic diffraction of a screen, both in a homogeneous (non-refracting, non-turbulent) atmosphere.

The sound field of a point source above a locally reacting ground is the sum of a direct wave and a reflected wave weighted by the spherical-wave reflection coefficient Q (Attenborough & Van Renterghem, Predicting Outdoor Sound 2e, 2021, Eq. (2.40a); Salomons, Computational Atmospheric Acoustics, 2001, Eq. (3.2)):

with the source-receiver distance, the image-source distance and (Attenborough Eq. (2.40c) / Salomons Eq. (D.58)):

Here Z is the normalized (by rho c) surface impedance of the ground, theta is the angle of incidence from the ground normal () and is the boundary-loss factor written through the scaled complementary error function , i.e. the Faddeeva function scipy.special.wofz. The relative sound level (the “excess attenuation”, dB re free field) is:

Limits reproduced by the implementation: an acoustically hard ground () gives , so and regardless of the boundary loss (the ground wave vanishes), and reaches +6 dB in phase (Salomons Sec. 3.4); at grazing incidence (, ) ; and as the range grows () and . The ground impedance is taken in the time convention of Salomons, in which a passive ground has ; it may be supplied directly or derived from the porous models of phonometry.materials (delany_bazley / miki), which model a semi-infinite porous ground whose surface impedance equals the characteristic impedance of the medium. The materials domain works in the opposite convention ( for a passive medium), so any impedance obtained from a porous model is conjugated internally before it enters the formulas above.

Three levels of screening beyond the ISO 9613-2 Dz term are provided:

  • the Kurze-Anderson closed form in the Fresnel number N (Bies, Hansen & Howard, Engineering Noise Control 5e, 2017, Eq. (5.138); Kurze & Anderson, 1971), , which tends to 5 dB at and stays within about 1.5 dB of Maekawa’s point-source curve for all N (a very good fit for );

  • the wave-theoretic insertion loss of a rigid thin screen (half-plane), the flat-wedge limit of the MacDonald / Hadden & Pierce solution (Attenborough Eqs. (9.19)-(9.20)), obtained from the auxiliary Fresnel functions and correctly giving 6 dB at the shadow boundary (the field is halved);

  • the coherent barrier-on-ground model that combines the four source-image / receiver-image diffracted paths with the spherical-wave reflection coefficient Q above (Attenborough Ch. 9; Bies Sec. 5.3.5), which shows the ground-barrier interference structure a purely energetic sum cannot.

Thick barriers (or two parallel thin screens) are handled by the double-edge Fresnel number (Bies Eq. (5.157)).

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

barrier_insertion_loss(
frequencies: NumericArrayLike,
source_height_m: float,
barrier_distance: float,
barrier_height_m: float,
receiver_distance: float,
receiver_height_m: float,
*,
method: Literal['kurze_anderson', 'exact'] = 'exact',
thickness_m: float | None = None,
ground_impedance: NumericArrayLike | PorousMediumResult | None = None,
ground_flow_resistivity_pa_s_m2: float | None = None,
ground_model: Literal['delany_bazley', 'miki'] = 'delany_bazley',
fluid: Fluid = ...,
) -> BarrierInsertionLoss

Insertion loss of a thin, thick or ground-coupled barrier.

The 2-D geometry places the source at (0, source_height), the (near) diffraction edge at (barrier_distance, barrier_height) and the receiver at (receiver_distance, receiver_height). Three models are available:

  • method="kurze_anderson": the closed form kurze_anderson_attenuation of the Fresnel number fresnel_number (Bies Eqs. (5.134)/(5.138)); with thickness_m the double-edge Fresnel number of Bies Eq. (5.157) is used, e being the top width.
  • method="exact" without ground: the wave-theoretic insertion loss of the rigid thin screen (_screen_field, MacDonald / Hadden & Pierce), .
  • method="exact" with a ground (ground_impedance or ground_flow_resistivity_pa_s_m2): the coherent four-path model. The field with the barrier sums the four source-image / receiver-image diffracted paths, each ground reflection weighted by the spherical-wave coefficient Q (spherical_reflection_coefficient); the field without the barrier is the two-ray ground field. This exposes the ground-barrier interference structure (Attenborough Ch. 9; Bies Sec. 5.3.5). As a first-order simplification a single Q (evaluated over the overall source-receiver geometry) weights every bounce rather than a separate coefficient per image path; the model is coherent and reciprocal but not a full boundary-element solution.

Parameters

Name Description
frequencies Frequencies, in hertz.
source_height_m Source height, in metres.
barrier_distance Horizontal source-to-barrier distance, in metres.
barrier_height_m Barrier (edge) height, in metres.
receiver_distance Horizontal source-to-receiver distance, in metres (> barrier_distance).
receiver_height_m Receiver height, in metres.
method "kurze_anderson" or "exact".
thickness_m Top width e of a thick barrier (double diffraction), in metres; None for a thin screen.
ground_impedance Normalized ground impedance for the coherent ground model ("exact" only), in the convention ( for a passive ground); a PorousMediumResult is conjugated internally from the materials’ convention.
ground_flow_resistivity_pa_s_m2 Effective flow resistivity sigma (Pa s/m2) for the ground model, as an alternative to ground_impedance.
ground_model Porous model for ground_flow_resistivity_pa_s_m2.
fluid The medium, a Fluid (Default: ABSORBER_AIR, dry air at 20 degC at textbook values). Pass a computed one, such as fluids.air(temperature_c=30.0, relative_humidity_percent=70.0), to work in the air of the room.

Returns: A BarrierInsertionLoss.

Raises

Exception When
ValueError On a non-positive/ordered geometry, a method other than the two listed, or if a ground is requested with method="kurze_anderson".
TypeError if barrier_distance, barrier_height_m, receiver_distance or thickness_m is not a single number, frequencies holds a text or a value that is not a real number, or method is not a text, or ground_model is not a text. receiver_height_m or source_height_m are refused the same way when any is not one real number.
BarrierInsertionLoss(
frequencies: NDArray[np.float64],
insertion_loss: NDArray[np.float64],
fresnel_number: NDArray[np.float64],
method: Literal['kurze_anderson', 'exact'],
*,
ground: bool,
source_height_m: float,
barrier_distance: float,
barrier_height_m: float,
receiver_distance: float,
receiver_height_m: float,
thickness_m: float | None = None,
)

Per-frequency barrier insertion loss (IL vs frequency).

Attributes

Name Description
frequencies Frequencies, in hertz.
insertion_loss Insertion loss , in decibels, per frequency.
fresnel_number Fresnel number N per frequency (single-edge geometry; the double-edge N for a thick barrier).
method Diffraction model used, and the tag the fiche and the plot name it by: "kurze_anderson" or "exact", the two models the library implements. Any other tag is refused at construction.
ground Whether the coherent four-path ground model was applied.
source_height_m Source height the loss was computed for, in metres, kept (with the other geometry fields) so plot_geometry can draw the section.
barrier_distance Source-to-barrier horizontal distance, in metres.
barrier_height_m Barrier height, in metres.
receiver_distance Source-to-receiver horizontal distance, in metres.
receiver_height_m Receiver height, in metres.
thickness_m Thick-barrier top width, in metres, or None.
BarrierInsertionLoss.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the insertion loss versus frequency.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
BarrierInsertionLoss.plot_geometry(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the source-barrier-receiver section to scale.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
BarrierInsertionLoss.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render a one-page barrier insertion-loss prediction fiche to a PDF.

Writes a prediction sheet (clearly labelled a prediction, not a measurement) laid out like an outdoor-noise barrier calculation: the standard-basis line naming the diffraction model used (the wave-theoretic rigid-screen model for method="exact" or the Kurze-Anderson closed form for method="kurze_anderson", a wave-acoustics complement to the ISO 9613-2 screening term), an optional metadata header (source/situation, client, receiver position, date), a per-band table of the insertion loss IL (and, in verbose mode, the Fresnel number N), the insertion-loss spectrum plot, a boxed mean insertion loss over the octave bands, an optional PASS/FAIL verdict against a declared minimum required insertion loss (a higher insertion loss is better) and a footer identity/disclaimer block.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata supplying the header identity (specimen the source/situation, client, test_room the receiver position) and the footer identity. A supplied requirement is read as the minimum required mean insertion loss in dB.
engine Rendering back end; only "reportlab" is supported.
verbose When True, the per-band table adds the Fresnel number N column.
language Fiche language: "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab" or language is unknown.
ImportError If reportlab or matplotlib is not installed (the [report] and [plot] extras).
fresnel_number(
source_to_edge: float,
edge_to_receiver: float,
direct_distance: float,
frequencies: float | np.floating[Any] | np.integer[Any],
*,
speed_of_sound: float = ...,
) -> float
fresnel_number(
source_to_edge: float,
edge_to_receiver: float,
direct_distance: float,
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
fresnel_number(
source_to_edge: float,
edge_to_receiver: float,
direct_distance: float,
frequencies: NumericArrayLike,
*,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Fresnel number (Bies Eq. (5.134)).

A and B are the two segments of the shortest source-edge-receiver path and d is the straight source-receiver distance. N is positive when the receiver is in the shadow zone () and negative in the bright zone.

Parameters

Name Description
source_to_edge Path segment A from source to edge, in metres.
edge_to_receiver Path segment B from edge to receiver, in metres.
direct_distance Straight source-receiver distance d, in metres.
frequencies Frequencies, in hertz.
speed_of_sound Speed of sound c, in m/s.

Returns: Fresnel number N per frequency. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a distance is not positive.
TypeError if speed_of_sound is not a single number, or frequencies holds a text or a value that is not a real number, or direct_distance, edge_to_receiver or source_to_edge is not a single number.
ground_effect(
frequencies: NumericArrayLike,
source_height_m: float,
receiver_height_m: float,
distance: float,
*,
impedance: NumericArrayLike | PorousMediumResult,
model: Literal['delany_bazley', 'miki'] = ...,
fluid: Fluid = ...,
) -> SphericalGroundResult
ground_effect(
frequencies: NumericArrayLike,
source_height_m: float,
receiver_height_m: float,
distance: float,
*,
flow_resistivity_pa_s_m2: float,
model: Literal['delany_bazley', 'miki'] = ...,
fluid: Fluid = ...,
) -> SphericalGroundResult

Spherical-wave ground effect above a finite-impedance ground.

Assembles the two-ray field with the spherical-wave reflection coefficient Q of spherical_reflection_coefficient and reports the relative sound level (Salomons Eq. (3.4)), i.e. the level re the free field.

The ground surface impedance is either supplied through impedance (a normalized complex array/scalar, or a PorousMediumResult) or derived from an effective flow_resistivity_pa_s_m2 (in Pa s/m2) via the model porous model of the materials domain. Exactly one of the two must be given.

Parameters

Name Description
frequencies Frequencies, in hertz.
source_height_m Source height hs, in metres.
receiver_height_m Receiver height hr, in metres.
distance Horizontal source-receiver distance, in metres.
impedance Normalized ground impedance ( convention, for a passive ground), or a PorousMediumResult (which is conjugated internally from the materials’ convention).
flow_resistivity_pa_s_m2 Effective flow resistivity sigma (Pa s/m2); grassland is about 2e5 (Salomons Sec. 3.1). The porous model raises a PorousAbsorberWarning when the lowest bands fall below its published fit range (it still extrapolates a value there).
model Porous model for flow_resistivity_pa_s_m2 ("delany_bazley" or "miki").
fluid The medium, a Fluid (Default: ABSORBER_AIR, dry air at 20 degC at textbook values). Pass a computed one, such as fluids.air(temperature_c=30.0, relative_humidity_percent=70.0), to work in the air of the room.

Returns: A SphericalGroundResult.

Raises

Exception When
ValueError If neither or both of impedance/flow_resistivity_pa_s_m2 are given, a height is negative, or the distance is not positive.
TypeError if distance, flow_resistivity_pa_s_m2, receiver_height_m or source_height_m is not a single number, or frequencies holds a text or a value that is not a real number, or model is not a text, or impedance holds a text or a value that is not a number.
kurze_anderson_attenuation(
fresnel_number: float | np.floating[Any] | np.integer[Any],
) -> float
kurze_anderson_attenuation(
fresnel_number: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
kurze_anderson_attenuation(
fresnel_number: NumericArrayLike,
) -> float | NDArray[np.float64]

Kurze-Anderson barrier attenuation (Bies Eq. (5.138); Kurze & Anderson, 1971).

For the ratio tends to 1 and dB; for (bright zone) the square root is imaginary and tanh becomes tan, so the expression continues smoothly until, below (the illuminated-zone limit of Maekawa’s curve), the diffraction is taken as negligible (0 dB) rather than let the closed form oscillate through the tangent poles. It stays within about 1.5 dB of Maekawa’s point-source curve for all N (a very good fit for ). The result is clamped at 0 dB (a barrier never amplifies).

Parameters

Name Description
fresnel_number Fresnel number N (scalar or array).

Returns: Attenuation Delta, in decibels (>= 0), matching the input shape. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError for a fresnel_number that is text, complex or otherwise not a number.
ValueError for a non-finite or ragged fresnel_number.
plot_barrier_geometry(
*,
ax: Axes | None = None,
source_height_m: float,
barrier_distance: float,
barrier_height_m: float,
receiver_distance: float,
receiver_height_m: float,
thickness_m: float | None = None,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the source-barrier-receiver section to scale.

Ground line, thin (or thick) screen, the direct path cut by the screen and the diffracted path over the top edge(s), with the path-length difference annotated. Distances follow barrier_insertion_loss: receiver_distance is horizontal from the source.

Parameters

Name Description
ax Existing axes, or None to create a figure.
source_height_m Source height above ground, in metres.
barrier_distance Source-to-barrier horizontal distance, in metres.
barrier_height_m Barrier height, in metres.
receiver_distance Source-to-receiver horizontal distance, in metres (> barrier_distance).
receiver_height_m Receiver height above ground, in metres.
thickness_m Barrier top width, in metres; None draws a thin screen.
language Label language, "en" (default) or "es".
kwargs Forwarded to the barrier rectangle.

Returns: The axes.

Raises

Exception When
ValueError for a height that is not finite and non-negative, a distance that is not finite and positive, a receiver no further than the barrier, or a non-positive thickness.
TypeError if barrier_distance, barrier_height_m, receiver_distance, receiver_height_m, source_height_m or thickness_m is not a single number.
spherical_reflection_coefficient(
normalized_impedance: NumericArrayLike,
source_height_m: float,
receiver_height_m: float,
distance: float,
*,
frequencies: float | np.floating[Any] | np.integer[Any],
speed_of_sound: float = ...,
) -> complex
spherical_reflection_coefficient(
normalized_impedance: NumericArrayLike,
source_height_m: float,
receiver_height_m: float,
distance: float,
*,
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
speed_of_sound: float = ...,
) -> NDArray[np.complex128]
spherical_reflection_coefficient(
normalized_impedance: NumericArrayLike,
source_height_m: float,
receiver_height_m: float,
distance: float,
*,
frequencies: NumericArrayLike,
speed_of_sound: float = ...,
) -> complex | NDArray[np.complex128]

Spherical-wave reflection coefficient Q (Weyl-Van der Pol).

Implements (Attenborough Eq. (2.40c); Salomons Eq. (D.58)) with the plane-wave coefficient Rp (Eq. (D.59)), the boundary-loss factor (Eq. (D.60), evaluated through scipy.special.wofz) and the numerical distance (Eq. (D.57)).

Parameters

Name Description
frequencies Frequencies, in hertz.
normalized_impedance Ground surface impedance normalized by rho c (complex, per frequency or scalar), in the time convention (a passive ground has ).
source_height_m Source height hs above the ground, in metres.
receiver_height_m Receiver height hr above the ground, in metres.
distance Horizontal source-receiver distance, in metres.
speed_of_sound Speed of sound c, in m/s.

Returns: Complex Q per frequency. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a height is negative, the distance is not positive, the impedance is zero, or its shape does not match the frequencies.
TypeError if distance, receiver_height_m, source_height_m or speed_of_sound is not a single number, or frequencies holds a text or a value that is not a real number, or normalized_impedance holds a text or a value that is not a number.
SphericalGroundResult(
frequencies: NDArray[np.float64],
excess_attenuation: NDArray[np.float64],
reflection_coefficient: NDArray[np.complex128],
plane_reflection_coefficient: NDArray[np.complex128],
boundary_loss: NDArray[np.complex128],
normalized_impedance: NDArray[np.complex128],
r_direct: float,
r_reflected: float,
)

Spherical-wave ground-effect result (Weyl-Van der Pol).

Every array is aligned with frequencies.

Attributes

Name Description
frequencies Frequencies, in hertz.
excess_attenuation Relative sound level (dB re free field, Salomons Eq. (3.4)); positive is enhancement (up to +6 dB over hard ground), negative is the ground-effect dip.
reflection_coefficient Spherical-wave reflection coefficient Q (complex, Attenborough Eq. (2.40c)).
plane_reflection_coefficient Plane-wave reflection coefficient Rp (complex, Salomons Eq. (D.59)).
boundary_loss Boundary-loss factor F(w) (complex, Eq. (D.60)).
normalized_impedance Normalized surface impedance Z used.
r_direct Direct source-receiver distance R1, in metres.
r_reflected Image-source distance R2, in metres.
SphericalGroundResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the excess attenuation versus frequency.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

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