environmental.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.environmental.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.

Ground effect (Weyl-Van der Pol)

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)):

p = e^{ikR1}/(4 pi R1) + Q e^{ikR2}/(4 pi R2)

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

Q  = Rp + (1 - Rp) F(w)
Rp = (Z cos(theta) - 1) / (Z cos(theta) + 1)        (Salomons Eq. (D.59))
F(w) = 1 + i sqrt(pi) w exp(-w^2) erfc(-i w)         (Salomons Eq. (D.60))
w  = sqrt(i k R2 / 2) (cos(theta) + 1/Z)             (Salomons Eq. (D.57))

Here Z is the normalized (by rho c) surface impedance of the ground, theta is the angle of incidence from the ground normal (cos(theta) = (hs + hr)/R2) and F(w) is the boundary-loss factor written through the scaled complementary error function exp(-w^2) erfc(-i w), i.e. the Faddeeva function scipy.special.wofz. The relative sound level (the “excess attenuation”, dB re free field) is (Salomons Eq. (3.4)):

dL = 20 lg| 1 + Q (R1/R2) exp(i k (R2 - R1)) |

Limits reproduced by the implementation: an acoustically hard ground (|Z| -> inf) gives Rp -> 1, so (1 - Rp) -> 0 and Q -> 1 regardless of the boundary loss (the ground wave vanishes), and dL reaches +6 dB in phase (Salomons Sec. 3.4); at grazing incidence (hs, hr -> 0, cos(theta) -> 0) Rp -> -1; and as the range grows (R2 -> inf) |w| -> inf and F -> 0. The ground impedance is taken in the e^{-i omega t} time convention of Salomons, in which a passive ground has Im(Z) > 0; 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 e^{+j omega t} convention (Im(Z) < 0 for a passive medium), so any impedance obtained from a porous model is conjugated internally before it enters the formulas above.

Barrier diffraction

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):

Delta = 5 + 20 lg( sqrt(2 pi N) / tanh(sqrt(2 pi N)) )

which tends to 5 dB at N -> 0 and stays within about 1.5 dB of Maekawa’s point-source curve for all N (a very good fit for N > 0.5);

• 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 N = (2/lambda)(A + B + e - d) (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

barrier_insertion_loss(
    frequencies: ArrayLike,
    source_height: float,
    barrier_distance: float,
    barrier_height: float,
    receiver_distance: float,
    receiver_height: float,
    *,
    method: Literal['kurze_anderson', 'exact'] = 'exact',
    thickness: float | None = None,
    ground_impedance: ArrayLike | PorousMediumResult | None = None,
    ground_flow_resistivity: float | None = None,
    ground_model: Literal['delany_bazley', 'miki'] = 'delany_bazley',
    speed_of_sound: float = 343.0,
    air_density: float = 1.205,
) -> 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 the double-edge Fresnel number N = (2/lambda)(A + B + e - d) 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), IL = 20 lg|p_free / p_diffracted|.
• method="exact" with a ground (ground_impedance or ground_flow_resistivity): 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	Source height, in metres.
barrier_distance	Horizontal source-to-barrier distance, in metres.
barrier_height	Barrier (edge) height, in metres.
receiver_distance	Horizontal source-to-receiver distance, in metres (> barrier_distance).
receiver_height	Receiver height, in metres.
method	"kurze_anderson" or "exact".
thickness	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 e^{-i omega t} convention (Im(Z) > 0 for a passive ground); a PorousMediumResult is conjugated internally from the materials’ e^{+j omega t} convention.
ground_flow_resistivity	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.
speed_of_sound	Speed of sound c, in m/s.
air_density	Air density rho, in kg/m3.

Returns: A BarrierInsertionLoss.

Raises

Exception	When
ValueError	On a non-positive/ordered geometry, or if a ground is requested with method="kurze_anderson".

BarrierInsertionLoss

BarrierInsertionLoss(
    frequencies: Real,
    insertion_loss: Real,
    fresnel_number: Real,
    method: str,
    ground: bool,
)

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

Attributes

Name	Description
frequencies	Frequencies, in hertz.
insertion_loss	Insertion loss IL = 20 lg|p_without / p_with|, 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 ("kurze_anderson" or "exact").
ground	Whether the coherent four-path ground model was applied.

BarrierInsertionLoss.plot()

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

Plot the insertion loss versus frequency.

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

BarrierInsertionLoss.report()

BarrierInsertionLoss.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = '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 (pip install "phonometry[report,plot]").

fresnel_number

fresnel_number(
    source_to_edge: float,
    edge_to_receiver: float,
    direct_distance: float,
    frequencies: ArrayLike,
    speed_of_sound: float = 343.0,
) -> Real

Fresnel number N = (2/lambda)(A + B - d) (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 (A + B > d) 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.

Raises

Exception	When
ValueError	If a distance is not positive.

ground_effect

ground_effect(
    frequencies: ArrayLike,
    source_height: float,
    receiver_height: float,
    distance: float,
    *,
    impedance: ArrayLike | PorousMediumResult | None = None,
    flow_resistivity: float | None = None,
    model: Literal['delany_bazley', 'miki'] = 'delany_bazley',
    speed_of_sound: float = 343.0,
    air_density: float = 1.205,
) -> SphericalGroundResult

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

Assembles the two-ray field p = e^{ikR1}/(4 pi R1) + Q e^{ikR2}/(4 pi R2) with the spherical-wave reflection coefficient Q of spherical_reflection_coefficient and reports the relative sound level dL = 20 lg| 1 + Q (R1/R2) exp(i k (R2 - R1)) | (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 (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	Source height hs, in metres.
receiver_height	Receiver height hr, in metres.
distance	Horizontal source-receiver distance, in metres.
impedance	Normalized ground impedance (e^{-i omega t} convention, Im(Z) > 0 for a passive ground), or a PorousMediumResult (which is conjugated internally from the materials’ e^{+j omega t} convention).
flow_resistivity	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 0.01 < rho f / sigma < 1 (it still extrapolates a value there).
model	Porous model for flow_resistivity ("delany_bazley" or "miki").
speed_of_sound	Speed of sound c, in m/s.
air_density	Air density rho, in kg/m3.

Returns: A SphericalGroundResult.

Raises

Exception	When
ValueError	If neither or both of impedance/flow_resistivity are given, a height is negative, or the distance is not positive.

kurze_anderson_attenuation

kurze_anderson_attenuation(fresnel_number: ArrayLike) -> Real

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

Delta = 5 + 20 lg( sqrt(2 pi N) / tanh(sqrt(2 pi N)) )   dB

For N -> 0 the ratio tends to 1 and Delta -> 5 dB; for N < 0 (bright zone) the square root is imaginary and tanh becomes tan, so the expression continues smoothly until, below N = -0.2 (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 N > 0.5). 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.

spherical_reflection_coefficient

spherical_reflection_coefficient(
    frequencies: ArrayLike,
    normalized_impedance: ArrayLike,
    source_height: float,
    receiver_height: float,
    distance: float,
    speed_of_sound: float = 343.0,
) -> Complex

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

Implements Q = Rp + (1 - Rp) F(w) (Attenborough Eq. (2.40c); Salomons Eq. (D.58)) with the plane-wave coefficient Rp (Eq. (D.59)), the boundary-loss factor F(w) = 1 + i sqrt(pi) w exp(-w^2) erfc(-i w) (Eq. (D.60), evaluated through scipy.special.wofz) and the numerical distance w = sqrt(i k R2 / 2) (cos(theta) + 1/Z) (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 e^{-i omega t} time convention (a passive ground has Im(Z) > 0).
source_height	Source height hs above the ground, in metres.
receiver_height	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.

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.

SphericalGroundResult

SphericalGroundResult(
    frequencies: Real,
    excess_attenuation: Real,
    reflection_coefficient: Complex,
    plane_reflection_coefficient: Complex,
    boundary_loss: Complex,
    normalized_impedance: Complex,
    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 dL (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()

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

Plot the excess attenuation dL versus frequency.

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