lsurf.materials.GridInhomogeneousModel

class lsurf.materials.GridInhomogeneousModel(name='Grid Inhomogeneous', n_grid=None, bounds=None, gradient_grid=None, alpha_grid=None, kernel=None, propagator=None)

Base class for 3D inhomogeneous materials defined on a grid.

User provides a 3D array of refractive index values. The system provides: - Trilinear interpolation for arbitrary positions - Automatic gradient computation via finite differences - GPU support via 3D array interpolation

Parameters:

• name (str) – Name of the material model

• n_grid (ndarray (nx, ny, nz)) – Refractive index values on 3D grid

• bounds (tuple) – ((x_min, x_max), (y_min, y_max), (z_min, z_max))

• gradient_grid (ndarray (nx, ny, nz, 3), optional) – Pre-computed gradients. If None, computed via finite differences.

• alpha_grid (ndarray (nx, ny, nz), optional) – Absorption coefficient values on 3D grid. If None, defaults to zeros.

Example

>>> n_grid = np.ones((100, 100, 50)) * 1.000293
>>> n_grid += generate_turbulence(100, 100, 50)  # Add perturbations
>>> material = GridInhomogeneousModel(
...     name="Turbulent Field",
...     n_grid=n_grid,
...     bounds=((-5000, 5000), (-5000, 5000), (0, 25000))
... )

__init__(name='Grid Inhomogeneous', n_grid=None, bounds=None, gradient_grid=None, alpha_grid=None, 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, n_grid, bounds, ...])	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_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 via trilinear interpolation.
get_refractive_index_gradient(x, y, z, ...)	Get gradient via trilinear interpolation in gradient grid.
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	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='Grid Inhomogeneous', n_grid=None, bounds=None, gradient_grid=None, alpha_grid=None, 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.

get_refractive_index(x, y, z, wavelength)

Get refractive index via trilinear interpolation.

get_refractive_index_gradient(x, y, z, wavelength)

Get gradient via trilinear interpolation in gradient grid.

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.