lsurf.materials.FullInhomogeneousModel

class lsurf.materials.FullInhomogeneousModel(name='Full Inhomogeneous')

Base class for arbitrary 3D inhomogeneous materials (CPU-only).

Use this when you need maximum flexibility and cannot express your model using the other tiers. Any Python code is allowed, including external libraries, database lookups, or complex computations.

GPU acceleration is not available for this tier. Use GradientPropagator for CPU propagation.

User must implement: - get_refractive_index(x, y, z, wavelength)

User may optionally implement: - get_refractive_index_gradient(x, y, z, wavelength) (default: numerical)

Example

>>> class WeatherModel(FullInhomogeneousModel):
...     def __init__(self, weather_file):
...         super().__init__(name="Weather Model")
...         self._data = load_weather_data(weather_file)
...
...     def get_refractive_index(self, x, y, z, wavelength):
...         return self._data.interpolate(x, y, z)
...
>>> model = WeatherModel("weather.nc")
>>> propagator = GradientPropagator()  # CPU only

__init__(name='Full Inhomogeneous')

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])	Initialize material field.
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.
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_kernels()	GPU is not supported for FullInhomogeneousModel.
get_gpu_parameters()	GPU is not supported for FullInhomogeneousModel.
get_refractive_index(x, y, z, wavelength)	Get refractive index at position.
get_refractive_index_gradient(x, y, z, ...)	Get gradient of n at position.
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).
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	GPU is not supported for FullInhomogeneousModel.
kernel_id	Return the kernel ID configured for this material instance.
propagator_id	Return the propagator ID configured for this material instance.

__init__(name='Full Inhomogeneous')

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 get_refractive_index(x, y, z, wavelength)

Get refractive index at position.

Any Python code is allowed here.

Parameters:

• x (float or ndarray) – Position coordinates in meters

• y (float or ndarray) – Position coordinates in meters

• z (float or ndarray) – Position coordinates in meters

• wavelength (float or ndarray) – Wavelength in meters

Returns:

Refractive index n >= 1.0

Return type:

float or ndarray

get_refractive_index_gradient(x, y, z, wavelength)

Get gradient of n at position.

Default implementation uses numerical differentiation. Override for analytical gradients.

Parameters:

• x (float or ndarray) – Position coordinates in meters

• y (float or ndarray) – Position coordinates in meters

• z (float or ndarray) – Position coordinates in meters

• wavelength (float or ndarray) – Wavelength in meters

Returns:

(dn/dx, dn/dy, dn/dz) in m^-1

Return type:

tuple

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

GPU is not supported for FullInhomogeneousModel.

get_gpu_kernels()

GPU is not supported for FullInhomogeneousModel.

get_gpu_parameters()

GPU is not supported for FullInhomogeneousModel.