Ir al contenido

environment.propagation.refraction

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.

Atmospheric refraction: ray tracing and the parabolic equation (PE).

Sound propagation outdoors is bent by vertical gradients of the effective sound speed (the adiabatic sound speed plus the component of the wind in the propagation direction, Salomons Eq. (4.4)). This module predicts that refraction with two complementary models, clean-room from Salomons, Computational Atmospheric Acoustics (Springer, 2001) and Attenborough & Van Renterghem, Predicting Outdoor Sound (2e, CRC, 2021, Ch. 11), and it is the refracting-atmosphere counterpart of the range-independent ocean solvers in phonometry.underwater.propagation.numerical:

  • atmospheric_ray_paths: geometrical acoustics. Integrates Snell’s law for sound rays (Salomons Eq. (4.3)) with a fixed-step Runge-Kutta scheme, returning the curved ray paths, their turning points, travel times and ground reflections. It shares its ray core with the ocean ray_trace: the atmospheric version reflects at the ground () instead of the sea surface and marches an upward-open half space.
  • atmospheric_parabolic_equation: the Green’s Function Parabolic Equation (GFPE, Salomons Appendix H). Marches the one-way wave equation in range with the split-step Fourier algorithm (the same range-marching family as the ocean parabolic_equation), a Gaussian starter (Salomons Eq. (G.64)), an absorbing layer at the top of the grid (Salomons Sec. G.9) and a finite-impedance ground condition through the plane-wave reflection coefficient plus the surface-wave residue of its pole (Salomons Eqs. (H.28), (H.49)). It returns the relative sound level (dB re free field) over the range-height plane.

For a linear effective sound-speed profile the ray paths are exact circular arcs of radius ray_curvature_radius, and an upward-refracting linear profile has a closed-form shadow_zone_distance; both anchor the ray model. The PE is anchored against the exact spherical-wave ground effect (phonometry.environment.ground_effect) in the homogeneous limit (gradient zero), which it reproduces to a few tenths of a dB on the default grid (finer height_step_m converges it further).

The ground impedance is taken in the convention of Salomons (a passive ground has ), shared with phonometry.environment.propagation.ground_barriers. The porous models of phonometry.materials work in the opposite convention (), so an impedance derived from them (flow_resistivity_pa_s_m2= or a PorousMediumResult) is conjugated internally before entering the PE ground condition. Heights and ranges are in metres, sound speeds in m/s and frequencies in Hz.

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

atmospheric_parabolic_equation(
frequency_hz: float,
profile: EffectiveSoundSpeedProfile,
*,
source_height_m: float,
impedance: NumericArrayLike | PorousMediumResult | None = None,
flow_resistivity_pa_s_m2: float | None = None,
model: Literal['delany_bazley', 'miki'] = 'delany_bazley',
max_range: float = 1000.0,
max_height_m: float = 100.0,
range_step: float | None = None,
height_step_m: float | None = None,
fluid: Fluid = ...,
) -> AtmosphericPEResult

Relative-level field from the Green’s Function Parabolic Equation (GFPE).

Marches the split-step Fourier solution of the one-way wave equation (Salomons Appendix H) in range. Each step transforms the field to the vertical-wavenumber domain, applies the free-space propagator together with the ground reflection (Eq. (H.28)), transforms back, adds the surface-wave residue of the reflection pole at (the third term of Eq. (H.49), present for a passive ground, ) and applies the refraction phase screen (Eq. (H.58)). The source is a Gaussian starter with its ground image (Eqs. (G.64), (G.76)) and an absorbing layer at the top of the grid (Sec. G.9) suppresses top-boundary reflections. The reference wavenumber is taken at the ground.

The relative sound level re the free field is with the direct source-receiver distance (Salomons Eq. (3.6)); in a homogeneous atmosphere it reproduces the spherical-wave ground effect of ground_effect.

The ground surface impedance is either supplied through impedance (a normalized complex value/array, or a PorousMediumResult) or derived from an effective flow_resistivity_pa_s_m2 (Pa s/m2) via the model porous model. Exactly one of the two must be given. A plain impedance value is taken in the convention ( for a passive ground); a PorousMediumResult or flow_resistivity_pa_s_m2 is conjugated internally from the materials’ convention.

Parameters

Name Description
frequency_hz Source frequency, in Hz.
profile The effective sound-speed profile.
source_height_m Source height zs, in metres (> 0).
impedance Normalized ground impedance, or a PorousMediumResult.
flow_resistivity_pa_s_m2 Effective flow resistivity sigma (Pa s/m2), as an alternative to impedance.
model Porous model for flow_resistivity_pa_s_m2.
max_range Maximum range, in metres.
max_height_m Top of the output height grid, in metres (the receiver region of interest; an absorbing layer is added above it).
range_step Range marching step dr, in metres. Default (None): one wavelength.
height_step_m Vertical grid spacing dz, in metres. Default (None): a tenth of a wavelength (Salomons Sec. G.2).
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: An AtmosphericPEResult.

Raises

Exception When
ValueError If the inputs are invalid or the impedance is unspecified.
TypeError if frequency_hz, height_step_m, max_height_m, max_range, range_step or source_height_m is not a single number, or model is not a text.
atmospheric_ray_paths(
profile: EffectiveSoundSpeedProfile,
*,
source_height_m: float,
launch_angles_deg: NumericArrayLike,
max_range: float = 1000.0,
n_steps: int | np.integer[Any] = 2000,
) -> AtmosphericRayResult

Trace sound rays through a refracting atmosphere over a ground surface.

Integrates Snell’s law for sound rays (Salomons Eq. (4.3), ) with a fixed-step fourth-order Runge-Kutta scheme, marching in range and reflecting specularly at the ground (). The state is the height z and the vertical slowness ; with the range-invariant the equations are and , the same ray core as the ocean ray_trace (with a ground reflection in place of the sea surface). The travel time is a third state of the same Runge-Kutta step, , so it is integrated with the very stages that place the ray rather than run over the finished path; a ground reflection is instantaneous and leaves it continuous.

Parameters

Name Description
profile The effective sound-speed profile (see linear_sound_speed_profile / log_linear_sound_speed_profile).
source_height_m Source height zs, in metres (>= 0).
launch_angles_deg Launch angles from the horizontal, in degrees (positive upward), within (-90, 90).
max_range Maximum horizontal range to trace, in metres.
n_steps Number of range steps per ray (>= 2).

Returns: An AtmosphericRayResult.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if max_range or source_height_m is not a single number, or n_steps is a flag, a text or an array where a count goes, or launch_angles_deg holds a text or a value that is not a real number.
AtmosphericPEResult(
frequency: float,
ranges: NDArray[np.float64],
heights_m: NDArray[np.float64],
relative_level: NDArray[np.float64],
source_height_m: float,
normalized_impedance: complex,
)

Parabolic-equation relative-level field in a refracting atmosphere.

Attributes

Name Description
frequency Source frequency, in Hz.
ranges Range grid, in metres.
heights_m Height grid of the output field, in metres.
relative_level Relative sound level (dB re free field), shape (n_heights, n_ranges).
source_height_m Source height, in metres.
normalized_impedance Normalized ground impedance used (complex).
AtmosphericPEResult.level_at_height(height_m: float) -> NDArray[np.float64]

Relative sound level versus range at the grid height nearest height_m.

Raises

Exception When
TypeError if height_m is not one real number.
AtmosphericPEResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the relative-level field over the range-height plane.

Parameters

Name Description
language The language of the labels: "en" or "es".
AtmosphericRayResult(
launch_angles_deg: NDArray[np.float64],
ranges: NDArray[np.float64],
heights_m: NDArray[np.float64],
travel_times: NDArray[np.float64],
turning_points: NDArray[np.int_],
ground_reflections: NDArray[np.int_],
source_height_m: float,
)

Ray-tracing solution through an effective sound-speed profile.

Attributes

Name Description
launch_angles_deg Launch angles from the horizontal, in degrees.
ranges Per-ray horizontal ranges, in metres, shape (n_rays, n_steps).
heights_m Per-ray heights, in metres, shape (n_rays, n_steps).
travel_times Per-ray cumulative travel times, in seconds, shape (n_rays, n_steps).
turning_points Number of turning points (height extrema) per ray.
ground_reflections Number of ground reflections per ray.
source_height_m Source height, in metres.
AtmosphericRayResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the curved ray paths (height on the vertical axis).

Parameters

Name Description
language The language of the labels: "en" or "es".
EffectiveSoundSpeedProfile(
*,
heights_m: NDArray[np.float64],
speeds_of_sound: NDArray[np.float64],
description: str = '',
)

Vertical profile of the effective sound speed c_eff(z).

The profile is sampled on a strictly increasing height grid starting at the ground (); intermediate heights are taken as piecewise linear, so a two-point profile represents an exact linear gradient.

Attributes

Name Description
heights_m Heights z above the ground, in metres (from ).
speeds_of_sound Effective sound speed at each height, in m/s.
description Short human-readable label (e.g. "linear, +0.1 s^-1").
EffectiveSoundSpeedProfile.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the effective sound-speed profile (height on the vertical axis).

Parameters

Name Description
language The language of the labels: "en" or "es".
EffectiveSoundSpeedProfile.speed_at(
height_m: float | np.floating[Any] | np.integer[Any],
) -> float
EffectiveSoundSpeedProfile.speed_at(
height_m: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
EffectiveSoundSpeedProfile.speed_at(
height_m: NumericArrayLike,
) -> float | NDArray[np.float64]

Piecewise-linear effective sound speed at one or more heights.

Parameters

Name Description
height_m Height above the ground, in metres.

Returns: The effective sound speed at each height, in metres per second. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if height_m holds a text or a value that is not a real number.
linear_sound_speed_profile(
gradient_per_s: float,
*,
ground_speed_of_sound: float = 343.0,
max_height_m: float = 100.0,
) -> EffectiveSoundSpeedProfile

Linear effective sound-speed profile (constant vertical gradient).

The profile is . A positive gradient_per_s (sound speed increasing with height) refracts sound downward (favourable propagation); a negative gradient refracts it upward and creates an acoustic shadow near the ground (Salomons Sec. 4.2).

Parameters

Name Description
gradient_per_s Vertical gradient dc/dz, in s^-1 (m/s per m).
ground_speed_of_sound Sound speed c0 at the ground, in m/s.
max_height_m Top of the sampled profile, in metres.

Returns: A two-point EffectiveSoundSpeedProfile.

Raises

Exception When
ValueError If max_height_m or ground_speed_of_sound is not positive, or the profile turns non-positive within [0, max_height_m].
TypeError if gradient_per_s, ground_speed_of_sound or max_height_m is not a single number.
log_linear_sound_speed_profile(
b: float,
*,
ground_speed_of_sound: float = 340.0,
roughness_length: float = 0.1,
max_height_m: float = 100.0,
n_points: int | np.integer[Any] = 128,
) -> EffectiveSoundSpeedProfile

Logarithmic effective sound-speed profile (surface layer).

The profile is , the realistic surface-layer profile of Salomons Eq. (4.5): b is the strength of the gradient (+1 m/s for a typical downward-refracting atmosphere, -1 m/s for an upward-refracting one) and z0 is the aerodynamic roughness length (about 0.1 m for grassland). The steep gradient near the ground is resolved by sampling the height grid logarithmically.

Parameters

Name Description
b Profile strength b, in m/s (positive: downward refraction).
ground_speed_of_sound Sound speed c0 at the ground, in m/s.
roughness_length Aerodynamic roughness length z0, in metres.
max_height_m Top of the sampled profile, in metres.
n_points Number of samples of the height grid (>= 2).

Returns: An EffectiveSoundSpeedProfile.

Raises

Exception When
ValueError On non-positive c0, z0 or max_height_m, fewer than two points, or a profile that turns non-positive.
TypeError if b, ground_speed_of_sound, max_height_m or roughness_length is not a single number, or n_points is a flag, a text or an array where a count goes.
ray_curvature_radius(
gradient_per_s: float,
*,
ground_speed_of_sound: float = 343.0,
launch_angle_deg: float = 0.0,
) -> float

Radius of curvature of a sound ray in a linear sound-speed gradient.

In a linear effective sound-speed profile a sound ray is an exact circular arc of radius with the Snell invariant , evaluated at the launch height (Salomons Sec. 4.4; Attenborough Ch. 11). For a ray launched from the height where the speed is ground_speed_of_sound (), .

Parameters

Name Description
gradient_per_s Vertical gradient dc/dz, in s^-1 (must be non-zero).
ground_speed_of_sound Sound speed at the launch height, in m/s.
launch_angle_deg Launch angle from the horizontal, in degrees.

Returns: The radius of curvature Rc, in metres (always positive).

Raises

Exception When
ValueError If the gradient is zero (a straight ray) or the launch angle is not within (-90, 90) degrees.
TypeError if gradient_per_s, ground_speed_of_sound or launch_angle_deg is not a single number.
shadow_zone_distance(
gradient_per_s: float,
source_height_m: float,
receiver_height_m: float,
*,
ground_speed_of_sound: float = 343.0,
) -> float

Distance to the acoustic shadow boundary, upward-refracting profile.

For a linear upward-refracting profile (gradient < 0) the ground-level ray that just grazes the surface bounds a region beyond which no direct or once-reflected ray arrives (Salomons Sec. 4.4; Attenborough Ch. 11). With a ray radius the limiting horizontal distance is the closed form:

valid for source and receiver heights , small compared with .

Parameters

Name Description
gradient_per_s Vertical gradient dc/dz, in s^-1 (must be negative for a shadow zone to exist).
source_height_m Source height hs, in metres (>= 0).
receiver_height_m Receiver height hr, in metres (>= 0).
ground_speed_of_sound Sound speed c0 at the ground, in m/s.

Returns: The horizontal shadow-boundary distance, in metres.

Raises

Exception When
ValueError If the gradient is not negative, or a height is negative.
TypeError if gradient_per_s, ground_speed_of_sound, receiver_height_m or source_height_m is not a single number.