lsurf 1.0.0__py3-none-any.whl

lsurf/materials/__init__.py

@@ -0,0 +1,169 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Materials Module
+
+Provides optical material definitions with spatially-varying properties.
+Supports homogeneous materials with constant properties and dispersion models.
+
+Module Structure
+----------------
+- base/: Abstract base classes (MaterialField, HomogeneousMaterial, etc.)
+- implementations/: Concrete material implementations
+- utils/: Dispersion functions, factories, constants
+
+Note: GPU propagation kernels are in lsurf.propagation.kernels.propagation
+
+Classes
+-------
+MaterialField
+    Abstract base class for material property fields.
+HomogeneousMaterial
+    Uniform material with constant optical properties.
+SimpleInhomogeneousModel
+    Radially-symmetric inhomogeneous materials (GPU via LUT).
+GridInhomogeneousModel
+    3D grid-based inhomogeneous materials (GPU via trilinear interp).
+FullInhomogeneousModel
+    Arbitrary Python inhomogeneous materials (CPU-only).
+
+Constants
+---------
+VACUUM
+    Perfect vacuum with n = 1.0.
+AIR_STP
+    Air at standard temperature and pressure, n = 1.000293.
+WATER
+    Pure water with n = 1.333 and absorption.
+BK7_GLASS
+    Schott N-BK7 optical glass, n = 1.5168.
+
+Functions
+---------
+sellmeier_refractive_index
+    Compute n using Sellmeier equation.
+cauchy_refractive_index
+    Compute n using Cauchy equation.
+create_sellmeier_material
+    Factory for Sellmeier-dispersion materials.
+create_cauchy_material
+    Factory for Cauchy-dispersion materials.
+
+Examples
+--------
+>>> from lsurf.materials import VACUUM, WATER, HomogeneousMaterial
+>>>
+>>> # Use pre-defined material
+>>> n = WATER.get_refractive_index(0, 0, 0, 550e-9)
+>>>
+>>> # Create custom material
+>>> oil = HomogeneousMaterial("Oil", 1.47, absorption_coef=0.01)
+"""
+
+# Base classes
+from .base import (
+    MaterialField,
+    HomogeneousMaterial,
+    SimpleInhomogeneousModel,
+    GridInhomogeneousModel,
+    FullInhomogeneousModel,
+    EARTH_RADIUS,
+)
+
+# Standard material constants
+from .implementations import (
+    VACUUM,
+    AIR_STP,
+    WATER,
+    BK7_GLASS,
+)
+
+# Atmosphere implementations
+from .implementations import (
+    ExponentialAtmosphere,
+    STANDARD_ATMOSPHERE,
+    create_exponential_atmosphere,
+    DuctAtmosphere,
+    create_duct_atmosphere,
+)
+
+# Utilities
+from .utils import (
+    # Constants
+    N_SEA_LEVEL,
+    SCALE_HEIGHT_DEFAULT,
+    # Dispersion functions
+    sellmeier_refractive_index,
+    cauchy_refractive_index,
+    # Factory functions
+    create_sellmeier_material,
+    create_cauchy_material,
+    # GPU device functions
+    device_sellmeier_equation,
+    device_cauchy_equation,
+)
+
+__all__ = [
+    # Base classes
+    "MaterialField",
+    "HomogeneousMaterial",
+    # Inhomogeneous material base classes (template system)
+    "SimpleInhomogeneousModel",
+    "GridInhomogeneousModel",
+    "FullInhomogeneousModel",
+    # Standard materials
+    "VACUUM",
+    "AIR_STP",
+    "WATER",
+    "BK7_GLASS",
+    # Atmosphere materials
+    "ExponentialAtmosphere",
+    "STANDARD_ATMOSPHERE",
+    "create_exponential_atmosphere",
+    "DuctAtmosphere",
+    "create_duct_atmosphere",
+    # Atmosphere constants
+    "EARTH_RADIUS",
+    "N_SEA_LEVEL",
+    "SCALE_HEIGHT_DEFAULT",
+    # Dispersion functions
+    "sellmeier_refractive_index",
+    "cauchy_refractive_index",
+    # Factory functions
+    "create_sellmeier_material",
+    "create_cauchy_material",
+    # GPU device functions
+    "device_sellmeier_equation",
+    "device_cauchy_equation",
+]

lsurf/materials/base/__init__.py

@@ -0,0 +1,64 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Base Classes for Materials Module
+
+This submodule contains the abstract base classes and template classes
+for the materials system:
+
+- MaterialField: Abstract base class for all materials
+- HomogeneousMaterial: Uniform material with constant optical properties
+- SimpleInhomogeneousModel: Radially-symmetric 1D materials (GPU via LUT)
+- SpectralInhomogeneousModel: Radially-symmetric 2D materials with wavelength
+  dependence (GPU via 2D LUT)
+- GridInhomogeneousModel: 3D grid-based materials (GPU via trilinear interp)
+- FullInhomogeneousModel: Arbitrary Python materials (CPU-only)
+"""
+
+from .material_field import MaterialField
+from .homogeneous import HomogeneousMaterial
+from .simple_inhomogeneous import SimpleInhomogeneousModel, EARTH_RADIUS
+from .spectral_inhomogeneous import SpectralInhomogeneousModel
+from .grid_inhomogeneous import GridInhomogeneousModel
+from .full_inhomogeneous import FullInhomogeneousModel
+
+__all__ = [
+    "MaterialField",
+    "HomogeneousMaterial",
+    "SimpleInhomogeneousModel",
+    "SpectralInhomogeneousModel",
+    "GridInhomogeneousModel",
+    "FullInhomogeneousModel",
+    "EARTH_RADIUS",
+]

lsurf/materials/base/full_inhomogeneous.py

@@ -0,0 +1,208 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Full Inhomogeneous Model (CPU-only, Arbitrary Python)
+
+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.
+"""
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .material_field import MaterialField
+
+
+class FullInhomogeneousModel(MaterialField, ABC):
+    """
+    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
+    """
+
+    def __init__(self, name: str = "Full Inhomogeneous"):
+        super().__init__(name)
+        self._is_homogeneous = False
+
+    @abstractmethod
+    def get_refractive_index(
+        self,
+        x: float | NDArray[np.float64],
+        y: float | NDArray[np.float64],
+        z: float | NDArray[np.float64],
+        wavelength: float | NDArray[np.float64],
+    ) -> float | NDArray[np.float64]:
+        """
+        Get refractive index at position.
+
+        Any Python code is allowed here.
+
+        Parameters
+        ----------
+        x, y, z : float or ndarray
+            Position coordinates in meters
+        wavelength : float or ndarray
+            Wavelength in meters
+
+        Returns
+        -------
+        float or ndarray
+            Refractive index n >= 1.0
+        """
+        pass
+
+    def get_refractive_index_gradient(
+        self,
+        x: float | NDArray[np.float64],
+        y: float | NDArray[np.float64],
+        z: float | NDArray[np.float64],
+        wavelength: float | NDArray[np.float64],
+    ) -> tuple[
+        float | NDArray[np.float64],
+        float | NDArray[np.float64],
+        float | NDArray[np.float64],
+    ]:
+        """
+        Get gradient of n at position.
+
+        Default implementation uses numerical differentiation.
+        Override for analytical gradients.
+
+        Parameters
+        ----------
+        x, y, z : float or ndarray
+            Position coordinates in meters
+        wavelength : float or ndarray
+            Wavelength in meters
+
+        Returns
+        -------
+        tuple
+            (dn/dx, dn/dy, dn/dz) in m^-1
+        """
+        eps = 1.0  # 1 meter step
+
+        x = np.asarray(x)
+        y = np.asarray(y)
+        z = np.asarray(z)
+
+        n = self.get_refractive_index
+
+        grad_x = (n(x + eps, y, z, wavelength) - n(x - eps, y, z, wavelength)) / (
+            2 * eps
+        )
+        grad_y = (n(x, y + eps, z, wavelength) - n(x, y - eps, z, wavelength)) / (
+            2 * eps
+        )
+        grad_z = (n(x, y, z + eps, wavelength) - n(x, y, z - eps, wavelength)) / (
+            2 * eps
+        )
+
+        return grad_x, grad_y, grad_z
+
+    def get_absorption_coefficient(
+        self,
+        x: float | NDArray[np.float64],
+        y: float | NDArray[np.float64],
+        z: float | NDArray[np.float64],
+        wavelength: float | NDArray[np.float64],
+    ) -> float | NDArray[np.float64]:
+        """Return absorption coefficient (default: 0)."""
+        if isinstance(x, np.ndarray):
+            return np.zeros_like(x)
+        return 0.0
+
+    def get_scattering_coefficient(
+        self,
+        x: float | NDArray[np.float64],
+        y: float | NDArray[np.float64],
+        z: float | NDArray[np.float64],
+        wavelength: float | NDArray[np.float64],
+    ) -> float | NDArray[np.float64]:
+        """Return scattering coefficient (default: 0)."""
+        if isinstance(x, np.ndarray):
+            return np.zeros_like(x)
+        return 0.0
+
+    # =========================================================================
+    # GPU INTERFACE - NOT SUPPORTED
+    # =========================================================================
+
+    @property
+    def gpu_material_id(self) -> int:
+        """GPU is not supported for FullInhomogeneousModel."""
+        raise NotImplementedError(
+            "FullInhomogeneousModel does not support GPU acceleration. "
+            "Use GradientPropagator for CPU propagation, or consider using "
+            "SimpleInhomogeneousModel or GridInhomogeneousModel for GPU support."
+        )
+
+    def get_gpu_kernels(self) -> dict:
+        """GPU is not supported for FullInhomogeneousModel."""
+        raise NotImplementedError(
+            "FullInhomogeneousModel does not support GPU acceleration."
+        )
+
+    def get_gpu_parameters(self) -> tuple:
+        """GPU is not supported for FullInhomogeneousModel."""
+        raise NotImplementedError(
+            "FullInhomogeneousModel does not support GPU acceleration."
+        )