lsurf.materials.DuctAtmosphere

class lsurf.materials.DuctAtmosphere(name='Duct Atmosphere', n_sea_level=1.000293, scale_height=8500.0, earth_radius=6371000.0, earth_center=(0.0, 0.0, 0.0), duct_center=0.0, duct_width=100.0, duct_intensity=0.0, duct_sharpness=0.5)

Exponential atmosphere with a refractive index duct layer.

Models an atmosphere where air density decreases exponentially with altitude, modified by a duct (inversion layer) at a specified altitude. The duct creates a localized region where the refractive index gradient is modified, which can trap or guide electromagnetic waves.

The duct is modeled using hyperbolic tangent functions to create smooth transitions at the duct boundaries.

Parameters:

• name (str, optional) – Descriptive name for this material. Default is “Duct Atmosphere”.

• n_sea_level (float, optional) – Refractive index at sea level. Default is 1.000293.

• scale_height (float, optional) – Atmospheric scale height H in meters. Default is 8500.0 m.

• earth_radius (float, optional) – Radius of Earth in meters. Default is 6,371,000 m.

• earth_center (tuple of float, optional) – Position of Earth’s center in meters. Default is (0, 0, 0).

• duct_center (float, optional) – Center altitude of the duct layer in meters. Default is 0.0.

• duct_width (float, optional) – Width of the duct layer in meters. Default is 100.0.

• duct_intensity (float, optional) – Intensity of the duct effect (0 = no duct, 1 = full strength). Default is 0.0.

• duct_sharpness (float, optional) – Sharpness of duct boundaries (0 = gradual, 1 = sharp). Default is 0.5.

Examples

>>> # Surface duct at 100m altitude
>>> atmosphere = DuctAtmosphere(
...     duct_center=100.0,
...     duct_width=50.0,
...     duct_intensity=0.5,
...     duct_sharpness=0.8,
... )

>>> # Elevated duct for radio propagation study
>>> atmosphere = DuctAtmosphere(
...     duct_center=1000.0,
...     duct_width=200.0,
...     duct_intensity=0.8,
...     duct_sharpness=0.9,
...     earth_center=(0.0, 0.0, -EARTH_RADIUS),
... )

__init__(name='Duct Atmosphere', n_sea_level=1.000293, scale_height=8500.0, earth_radius=6371000.0, earth_center=(0.0, 0.0, 0.0), duct_center=0.0, duct_width=100.0, duct_intensity=0.0, duct_sharpness=0.5)

Initialize material field.

Parameters:

• name (str, optional) – Descriptive name for this material. Default is “Material”.

• kernel (PropagationKernelID, optional) – Override the default propagation kernel. Must be in supported_kernels(). If None, uses the class default.

• propagator (PropagatorID, optional) – Override the default propagator. Must be in supported_propagators(). If None, uses the class default.

Raises:

ValueError – If kernel or propagator is not supported by this material type.

Methods

__init__([name, n_sea_level, scale_height, ...])	Initialize material field.
alpha_at_altitude(altitude[, wavelength])	Return absorption coefficient at given altitude.
compute_phase_velocity(x, y, z, wavelength)	Compute phase velocity v_p = c/n at position.
default_kernel()	Return the default propagation kernel for this material type.
default_propagator()	Return the default propagator for this material type.
dn_dh_at_altitude(altitude[, wavelength])	Return analytical dn/dh at given altitude.
get_absorption_coefficient(x, y, z, wavelength)	Return absorption coefficient (default: 0).
get_anisotropy_factor(x, y, z, wavelength)	Get scattering anisotropy factor g (Henyey-Greenstein parameter).
get_duct_gpu_parameters()	Return scalar parameters for analytical duct GPU kernels.
get_extinction_coefficient(x, y, z, wavelength)	Get total extinction coefficient (absorption + scattering).
get_gpu_arrays()	Return device arrays for GPU kernel (none needed for analytical).
get_gpu_kernels()	Return GPU kernels for propagation (analytical, no LUT).
get_gpu_parameters()	Return scalar parameters for GPU kernel.
get_refractive_index(x, y, z, wavelength)	Get refractive index at position (auto-generated from n_at_altitude).
get_refractive_index_gradient(x, y, z, ...)	Get gradient of n at position (auto-generated).
get_refractive_index_gradient_magnitude(x, ...)	Get magnitude of refractive index gradient |∇n|.
get_scattering_coefficient(x, y, z, wavelength)	Return scattering coefficient (default: 0).
is_homogeneous()	Check if material has uniform properties (no spatial variation).
n_at_altitude(altitude[, wavelength])	Return refractive index at given altitude.
supported_kernels()	Return list of propagation kernels supported by this material type.
supported_propagators()	Return list of propagators supported by this material type.

Attributes

gpu_material_id	Return GPU material ID for analytical duct kernels.
kernel_id	Return the kernel ID configured for this material instance.
propagator_id	Return the propagator ID configured for this material instance.

__init__(name='Duct Atmosphere', n_sea_level=1.000293, scale_height=8500.0, earth_radius=6371000.0, earth_center=(0.0, 0.0, 0.0), duct_center=0.0, duct_width=100.0, duct_intensity=0.0, duct_sharpness=0.5)

Initialize material field.

Parameters:

• name (str, optional) – Descriptive name for this material. Default is “Material”.

• kernel (PropagationKernelID, optional) – Override the default propagation kernel. Must be in supported_kernels(). If None, uses the class default.

• propagator (PropagatorID, optional) – Override the default propagator. Must be in supported_propagators(). If None, uses the class default.

Raises:

ValueError – If kernel or propagator is not supported by this material type.

n_at_altitude(altitude, wavelength=None)

Return refractive index at given altitude.

Implements the exponential profile with duct modification:

n(h) = 1 + delta_n * exp(-h / H) * D(h)

Parameters:

• altitude (float) – Altitude above Earth’s surface in meters (clamped to >= 0).

• wavelength (float, optional) – Wavelength in meters (not used - no dispersion).

Returns:

Refractive index at altitude.

Return type:

float

dn_dh_at_altitude(altitude, wavelength=None)

Return analytical dn/dh at given altitude.

Uses the product rule for the derivative:

dn/dh = delta_n * [exp’ * D + exp * D’]

Parameters:

• altitude (float) – Altitude above Earth’s surface in meters.

• wavelength (float, optional) – Wavelength in meters (not used).

Returns:

Derivative dn/dh in m^-1.

Return type:

float

property gpu_material_id: int

Return GPU material ID for analytical duct kernels.

get_gpu_kernels()

Return GPU kernels for propagation (analytical, no LUT).

get_gpu_parameters()

Return scalar parameters for GPU kernel.

get_duct_gpu_parameters()

Return scalar parameters for analytical duct GPU kernels.

Equivalent to get_gpu_parameters() for DuctAtmosphere, but provides a consistent interface for propagators to detect analytical duct kernels.

get_gpu_arrays()

Return device arrays for GPU kernel (none needed for analytical).

__repr__()

Return string representation.