lsurf.materials.MaterialField

class lsurf.materials.MaterialField(name='Material', kernel=None, propagator=None)

Abstract base class for spatially-varying material properties.

All material properties are functions of position (x, y, z) and wavelength. Subclasses must implement methods that can be called from both CPU and GPU.

Parameters:

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

name

Material identifier.

Type:

str

Notes

Material properties modeled: - Refractive index n: Real part of complex refractive index - Absorption coefficient α: Controls intensity decay - Scattering coefficient μ_s: Controls scattering mean free path - Anisotropy factor g: Henyey-Greenstein scattering parameter

References

[1]

Born, M., & Wolf, E. (1999). Principles of Optics (7th ed.). Cambridge University Press.

__init__(name='Material', 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, kernel, propagator])	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)	Get absorption coefficient α at position (x, y, z).
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_refractive_index(x, y, z, wavelength)	Get refractive index at position (x, y, z) for given wavelength.
get_refractive_index_gradient(x, y, z, ...)	Get gradient of refractive index ∇n at position (x, y, z).
get_refractive_index_gradient_magnitude(x, ...)	Get magnitude of refractive index gradient |∇n|.
get_scattering_coefficient(x, y, z, wavelength)	Get scattering coefficient μ_s at position (x, y, z).
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

kernel_id	Return the kernel ID configured for this material instance.
propagator_id	Return the propagator ID configured for this material instance.

__init__(name='Material', 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 get_refractive_index(x, y, z, wavelength)

Get refractive index at position (x, y, z) for given wavelength.

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:

n – Real part of refractive index (dimensionless).

Return type:

float or ndarray

Notes

For absorbing materials, this returns only Re(n). Use get_absorption_coefficient() for the imaginary part.

abstractmethod get_refractive_index_gradient(x, y, z, wavelength)

Get gradient of refractive index ∇n at position (x, y, z).

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:

grad_n – (∂n/∂x, ∂n/∂y, ∂n/∂z) in units of m⁻¹.

Return type:

tuple of (float or ndarray)

Notes

For homogeneous materials, this returns (0, 0, 0). Gradient drives ray curvature via the eikonal equation: d²r/ds² = ∇n(r)/n(r)

References

[1]

Born & Wolf (1999), Section 3.1.

abstractmethod get_absorption_coefficient(x, y, z, wavelength)

Get absorption coefficient α at position (x, y, z).

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:

alpha – Absorption coefficient in m⁻¹.

Return type:

float or ndarray

Notes

Intensity decays as I(d) = I₀ exp(-αd) (Beer-Lambert law).

References

[1]

https://en.wikipedia.org/wiki/Beer%E2%80%93Lambert_law

abstractmethod get_scattering_coefficient(x, y, z, wavelength)

Get scattering coefficient μ_s at position (x, y, z).

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:

mu_s – Scattering coefficient in m⁻¹.

Return type:

float or ndarray

Notes

Mean free path between scattering events: ℓ_s = 1/μ_s.

get_extinction_coefficient(x, y, z, wavelength)

Get total extinction coefficient (absorption + scattering).

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:

mu_t – Total extinction coefficient in m⁻¹.

Return type:

float or ndarray

get_anisotropy_factor(x, y, z, wavelength)

Get scattering anisotropy factor g (Henyey-Greenstein parameter).

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:

g – Anisotropy factor, range [-1, 1]. - g = 0: isotropic scattering - g > 0: forward scattering - g < 0: backward scattering

Return type:

float or ndarray

Notes

Default implementation returns 0 (isotropic). Used in Henyey-Greenstein phase function: p(cos θ) = (1-g²) / (1 + g² - 2g cos θ)^(3/2)

References

[1]

Henyey & Greenstein (1941). Astrophysical Journal, 93, 70-83.

is_homogeneous()

Check if material has uniform properties (no spatial variation).

Returns:

True if material is homogeneous, False if inhomogeneous.

Return type:

bool

Notes

Homogeneous materials enable optimizations (straight-line propagation).

classmethod supported_kernels()

Return list of propagation kernels supported by this material type.

Returns:

List of kernel IDs this material supports.

Return type:

list[PropagationKernelID]

Examples

>>> from lsurf.materials import ExponentialAtmosphere
>>> ExponentialAtmosphere.supported_kernels()
[<PropagationKernelID.SIMPLE_EULER: ...>, <PropagationKernelID.SIMPLE_RK4: ...>]

classmethod default_kernel()

Return the default propagation kernel for this material type.

Returns:

The default kernel ID, or None if no GPU kernels are supported.

Return type:

PropagationKernelID or None

Examples

>>> from lsurf.materials import ExponentialAtmosphere
>>> ExponentialAtmosphere.default_kernel()
<PropagationKernelID.SIMPLE_RK4: ...>

classmethod supported_propagators()

Return list of propagators supported by this material type.

Returns:

List of propagator IDs this material supports.

Return type:

list[PropagatorID]

Examples

>>> from lsurf.materials import ExponentialAtmosphere
>>> ExponentialAtmosphere.supported_propagators()
[<PropagatorID.GPU_GRADIENT: ...>, <PropagatorID.CPU_GRADIENT: ...>]

classmethod default_propagator()

Return the default propagator for this material type.

Returns:

The default propagator ID, or None if not specified.

Return type:

PropagatorID or None

Examples

>>> from lsurf.materials import ExponentialAtmosphere
>>> ExponentialAtmosphere.default_propagator()
<PropagatorID.GPU_GRADIENT: ...>

property kernel_id: PropagationKernelID | None

Return the kernel ID configured for this material instance.

Returns:

The kernel ID selected for this instance, or None if not applicable.

Return type:

PropagationKernelID or None

property propagator_id: PropagatorID | None

Return the propagator ID configured for this material instance.

Returns:

The propagator ID selected for this instance, or None if not applicable.

Return type:

PropagatorID or None

get_refractive_index_gradient_magnitude(x, y, z, wavelength)

Get magnitude of refractive index gradient |∇n|.

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:

grad_mag – Magnitude of gradient |∇n| in m⁻¹.

Return type:

float or ndarray

compute_phase_velocity(x, y, z, wavelength)

Compute phase velocity v_p = c/n at position.

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:

v_p – Phase velocity in m/s.

Return type:

float or ndarray

__repr__()

Return string representation.