lsurf.materials.SimpleInhomogeneousModel

class lsurf.materials.SimpleInhomogeneousModel(name='Simple Inhomogeneous', center=(0.0, 0.0, 0.0), reference_radius=6371000.0, altitude_range=(0.0, 200000.0), lut_resolution=10000, kernel=None, propagator=None)

Base class for radially-symmetric inhomogeneous materials.

User implements only n_at_altitude() - a simple 1D function that returns the refractive index at a given altitude. The system automatically provides: - get_refractive_index(x, y, z, wavelength) via altitude computation - get_refractive_index_gradient(x, y, z, wavelength) via radial direction - GPU support via precomputed lookup tables

Parameters:

• name (str) – Name of the material model

• center (tuple) – Center of spherical symmetry (x, y, z). Default: (0, 0, 0)

• reference_radius (float) – Radius at which altitude = 0 (e.g., Earth radius). Default: 6,371,000 m

• altitude_range (tuple) – (min_altitude, max_altitude) for lookup table. Default: (0, 200,000)

• lut_resolution (int) – Number of samples in lookup table. Default: 10,000

• kernel (PropagationKernelID, optional) – Override the default kernel. Supported: SIMPLE_EULER, SIMPLE_RK4

• propagator (PropagatorID, optional) – Override the default propagator. Supported: GPU_GRADIENT, CPU_GRADIENT

Example

>>> class MyAtmosphere(SimpleInhomogeneousModel):
...     def n_at_altitude(self, altitude, wavelength=None):
...         return 1.0 + 0.000293 * math.exp(-altitude / 8500)
...
>>> atm = MyAtmosphere(name="My Atmosphere")
>>> propagator = GPUGradientPropagator(atm)  # Auto GPU support

__init__(name='Simple Inhomogeneous', center=(0.0, 0.0, 0.0), reference_radius=6371000.0, altitude_range=(0.0, 200000.0), lut_resolution=10000, kernel=None, propagator=None)

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, center, reference_radius, ...])	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 dn/d(altitude) 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_extinction_coefficient(x, y, z, wavelength)	Get total extinction coefficient (absorption + scattering).
get_gpu_arrays()	Return device arrays for GPU kernel.
get_gpu_kernels()	Return GPU kernels for propagation.
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 kernel dispatch.
kernel_id	Return the kernel ID configured for this material instance.
propagator_id	Return the propagator ID configured for this material instance.

__init__(name='Simple Inhomogeneous', center=(0.0, 0.0, 0.0), reference_radius=6371000.0, altitude_range=(0.0, 200000.0), lut_resolution=10000, kernel=None, propagator=None)

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.

abstractmethod n_at_altitude(altitude, wavelength=None)

Return refractive index at given altitude.

This is the only method users must implement.

Parameters:

• altitude (float) – Altitude above reference surface in meters (altitude >= 0)

• wavelength (float, optional) – Wavelength in meters (for dispersion models)

Returns:

Refractive index n >= 1.0

Return type:

float

dn_dh_at_altitude(altitude, wavelength=None)

Return dn/d(altitude) at given altitude.

Default implementation uses numerical differentiation. Override for analytical derivatives (more accurate).

Parameters:

• altitude (float) – Altitude above reference surface in meters

• wavelength (float, optional) – Wavelength in meters

Returns:

Derivative dn/dh in m^-1

Return type:

float

alpha_at_altitude(altitude, wavelength=None)

Return absorption coefficient at given altitude.

Default implementation returns 0 (no absorption). Override in subclasses that model absorbing media.

Parameters:

• altitude (float) – Altitude above reference surface in meters

• wavelength (float, optional) – Wavelength in meters

Returns:

Absorption coefficient α in m^-1 (for Beer-Lambert: I = I₀·exp(-α·s))

Return type:

float

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, wavelength)

Get gradient of n at position (auto-generated).

get_absorption_coefficient(x, y, z, wavelength)

Return absorption coefficient (default: 0).

get_scattering_coefficient(x, y, z, wavelength)

Return scattering coefficient (default: 0).

property gpu_material_id: int

Return GPU material ID for kernel dispatch.

get_gpu_kernels()

Return GPU kernels for propagation.

get_gpu_parameters()

Return scalar parameters for GPU kernel.

get_gpu_arrays()

Return device arrays for GPU kernel.