lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/propagators/factory.py

@@ -0,0 +1,200 @@
+# 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.
+
+"""
+Propagator Factory
+
+Factory function for creating propagators with proper kernel/propagator
+selection based on material compatibility declarations.
+
+This module provides a unified interface for creating propagators,
+handling the selection of the appropriate propagator and kernel based on:
+1. Material's declared compatibility
+2. User overrides at propagator creation time
+3. Material instance preferences
+4. Class defaults
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..kernels.registry import PropagationKernelID, PropagatorID
+
+if TYPE_CHECKING:
+    from ...materials.base.material_field import MaterialField
+
+__all__ = ["create_propagator"]
+
+
+def create_propagator(
+    material: MaterialField,
+    propagator_id: PropagatorID | None = None,
+    kernel_id: PropagationKernelID | None = None,
+    method: str | None = None,
+    prefer_gpu: bool = True,
+    **kwargs: Any,
+) -> Any:
+    """
+    Create the appropriate propagator for a material.
+
+    Selection priority (highest to lowest):
+    1. If propagator_id/kernel_id passed here → use those (override)
+    2. Else use material's stored preference (material._propagator_id, material._kernel_id)
+    3. Else use material's class defaults
+
+    Parameters
+    ----------
+    material : MaterialField
+        The material to propagate through.
+    propagator_id : PropagatorID, optional
+        Override propagator selection. If None, uses material's preference.
+    kernel_id : PropagationKernelID, optional
+        Override kernel selection. If None, uses material's preference.
+        Note: Only used for GPU propagators.
+    method : str, optional
+        Integration method ("euler" or "rk4"). If None, determined from kernel_id.
+    prefer_gpu : bool, default True
+        If True and material supports GPU, use GPU propagator.
+        If False, force CPU propagator.
+    **kwargs
+        Additional propagator configuration (e.g., threads_per_block).
+
+    Returns
+    -------
+    Propagator
+        Configured propagator instance appropriate for the material.
+
+    Raises
+    ------
+    ValueError
+        If propagator_id or kernel_id is not supported by the material.
+
+    Examples
+    --------
+    >>> from lsurf.materials import ExponentialAtmosphere
+    >>> from lsurf.propagation.propagators import create_propagator
+    >>> from lsurf.propagation.kernels import PropagatorID, PropagationKernelID
+
+    >>> # Use defaults (RK4 kernel, GPU propagator)
+    >>> atmo = ExponentialAtmosphere(n_sea_level=1.000293)
+    >>> propagator = create_propagator(atmo)
+
+    >>> # Override kernel at propagator creation time
+    >>> propagator_euler = create_propagator(
+    ...     atmo,
+    ...     kernel_id=PropagationKernelID.SIMPLE_EULER
+    ... )
+
+    >>> # Force CPU propagator
+    >>> cpu_propagator = create_propagator(atmo, propagator_id=PropagatorID.CPU_GRADIENT)
+
+    >>> # Or use prefer_gpu=False
+    >>> cpu_propagator = create_propagator(atmo, prefer_gpu=False)
+    """
+    # Resolve propagator: override > prefer_gpu > material instance > class default
+    resolved_propagator_id = propagator_id
+    if resolved_propagator_id is None:
+        # If prefer_gpu is False, force CPU propagator
+        if not prefer_gpu:
+            resolved_propagator_id = PropagatorID.CPU_GRADIENT
+        else:
+            resolved_propagator_id = getattr(material, "_propagator_id", None)
+    if resolved_propagator_id is None:
+        resolved_propagator_id = material.default_propagator()
+
+    # Validate propagator is supported
+    supported_propagators = material.supported_propagators()
+    if supported_propagators and resolved_propagator_id not in supported_propagators:
+        raise ValueError(
+            f"{material.__class__.__name__} does not support {resolved_propagator_id}. "
+            f"Supported: {supported_propagators}"
+        )
+
+    # Resolve kernel: override > material instance > class default
+    resolved_kernel_id = kernel_id
+    if resolved_kernel_id is None:
+        resolved_kernel_id = getattr(material, "_kernel_id", None)
+    if resolved_kernel_id is None:
+        resolved_kernel_id = material.default_kernel()
+
+    # Validate kernel is supported (if applicable)
+    supported_kernels = material.supported_kernels()
+    if supported_kernels and resolved_kernel_id is not None:
+        if resolved_kernel_id not in supported_kernels:
+            raise ValueError(
+                f"{material.__class__.__name__} does not support {resolved_kernel_id}. "
+                f"Supported: {supported_kernels}"
+            )
+
+    # Resolve method: parameter > kernel_id > default
+    resolved_method = method
+    if resolved_method is None:
+        resolved_method = "rk4"  # Default
+        if resolved_kernel_id is not None:
+            # Map kernel ID to method string
+            if "EULER" in resolved_kernel_id.name:
+                resolved_method = "euler"
+            elif "RK4" in resolved_kernel_id.name:
+                resolved_method = "rk4"
+
+    # Create the appropriate propagator
+    if resolved_propagator_id == PropagatorID.CPU_GRADIENT:
+        from .gradient import GradientPropagator
+
+        return GradientPropagator(method=resolved_method, **kwargs)
+
+    elif resolved_propagator_id == PropagatorID.GPU_GRADIENT:
+        from .gpu_gradient import GPUGradientPropagator
+
+        return GPUGradientPropagator(
+            material=material, method=resolved_method, **kwargs
+        )
+
+    elif resolved_propagator_id == PropagatorID.GPU_SPECTRAL:
+        from .spectral_gpu_gradient import SpectralGPUGradientPropagator
+
+        return SpectralGPUGradientPropagator(
+            material=material, method=resolved_method, **kwargs
+        )
+
+    elif resolved_propagator_id == PropagatorID.GPU_SURFACE:
+        from .surface_propagator import SurfacePropagator
+
+        return SurfacePropagator(material=material, method=resolved_method, **kwargs)
+
+    else:
+        raise ValueError(
+            f"Unknown propagator ID: {resolved_propagator_id}. "
+            f"Available: {list(PropagatorID)}"
+        )

lsurf/propagation/propagators/fresnel_handler.py

@@ -0,0 +1,305 @@
+# 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.
+
+"""
+Fresnel Handler
+
+GPU memory management for Fresnel coefficient kernels.
+This module provides high-level interfaces that handle cuda.to_device(),
+copy_to_host(), and kernel launching for the Fresnel kernels.
+"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..kernels.fresnel import (
+    kernel_fresnel_standard,
+    kernel_fresnel_polarized,
+)
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    _HAS_CUDA = cuda.is_available()
+except ImportError:
+    _HAS_CUDA = False
+
+    class _FakeCuda:
+        @staticmethod
+        def is_available():
+            return False
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+
+
+def fresnel_coefficients_gpu(
+    cos_theta_i: NDArray[np.float32],
+    n1: NDArray[np.float32] | float,
+    n2: NDArray[np.float32] | float,
+    polarization: str | NDArray[np.int32] = "unpolarized",
+    threads_per_block: int = 256,
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """
+    GPU-accelerated Fresnel coefficient calculation.
+
+    Parameters
+    ----------
+    cos_theta_i : ndarray, shape (N,)
+        Cosine of incident angles
+    n1 : float or ndarray
+        Refractive index of incident medium
+    n2 : float or ndarray
+        Refractive index of transmitted medium
+    polarization : str or ndarray
+        Polarization state: 's', 'p', 'unpolarized', or per-ray int array
+        where 0=unpolarized, 1=s, 2=p
+    threads_per_block : int, optional
+        CUDA threads per block (default 256)
+
+    Returns
+    -------
+    reflectance : ndarray, shape (N,)
+        Reflection coefficient (0-1)
+    transmittance : ndarray, shape (N,)
+        Transmission coefficient (0-1)
+    """
+    num_rays = len(cos_theta_i)
+
+    # Handle scalar n1/n2
+    n1_is_scalar = not isinstance(n1, np.ndarray) or n1.ndim == 0
+    n2_is_scalar = not isinstance(n2, np.ndarray) or n2.ndim == 0
+
+    n1_arr = np.atleast_1d(np.float32(n1) if n1_is_scalar else n1.astype(np.float32))
+    n2_arr = np.atleast_1d(np.float32(n2) if n2_is_scalar else n2.astype(np.float32))
+
+    # Handle polarization
+    if isinstance(polarization, str):
+        if polarization == "s":
+            pol_arr = np.ones(num_rays, dtype=np.int32)
+        elif polarization == "p":
+            pol_arr = np.full(num_rays, 2, dtype=np.int32)
+        else:  # unpolarized
+            pol_arr = np.zeros(num_rays, dtype=np.int32)
+        use_polarized_kernel = polarization in ("s", "p")
+    else:
+        pol_arr = polarization.astype(np.int32)
+        use_polarized_kernel = True
+
+    if _HAS_CUDA:
+        # Allocate output arrays
+        reflectance = np.zeros(num_rays, dtype=np.float32)
+        transmittance = np.zeros(num_rays, dtype=np.float32)
+
+        # Transfer to GPU
+        d_cos_theta = cuda.to_device(cos_theta_i.astype(np.float32))
+        d_n1 = cuda.to_device(n1_arr)
+        d_n2 = cuda.to_device(n2_arr)
+        d_reflectance = cuda.to_device(reflectance)
+        d_transmittance = cuda.to_device(transmittance)
+
+        blocks = (num_rays + threads_per_block - 1) // threads_per_block
+
+        if use_polarized_kernel:
+            d_pol = cuda.to_device(pol_arr)
+            kernel_fresnel_polarized[blocks, threads_per_block](
+                d_cos_theta,
+                d_n1,
+                d_n2,
+                d_pol,
+                d_reflectance,
+                d_transmittance,
+                n1_is_scalar,
+                n2_is_scalar,
+            )
+        else:
+            kernel_fresnel_standard[blocks, threads_per_block](
+                d_cos_theta,
+                d_n1,
+                d_n2,
+                d_reflectance,
+                d_transmittance,
+                n1_is_scalar,
+                n2_is_scalar,
+            )
+
+        cuda.synchronize()
+        reflectance = d_reflectance.copy_to_host()
+        transmittance = d_transmittance.copy_to_host()
+    else:
+        reflectance, transmittance = _fresnel_coefficients_cpu(
+            cos_theta_i,
+            n1,
+            n2,
+            polarization if isinstance(polarization, str) else "unpolarized",
+        )
+
+    return reflectance, transmittance
+
+
+def compute_reflection_direction(
+    incident: NDArray[np.float32],
+    normal: NDArray[np.float32],
+) -> NDArray[np.float32]:
+    """
+    Compute reflected ray direction using law of reflection.
+
+    Parameters
+    ----------
+    incident : ndarray, shape (N, 3)
+        Incident ray directions (should be normalized)
+    normal : ndarray, shape (N, 3)
+        Surface normals (should be normalized, pointing toward incident side)
+
+    Returns
+    -------
+    reflected : ndarray, shape (N, 3)
+        Reflected ray directions (normalized)
+    """
+    dot_in = np.sum(incident * normal, axis=1, keepdims=True)
+    reflected = incident - 2.0 * dot_in * normal
+    norms = np.linalg.norm(reflected, axis=1, keepdims=True)
+    return (reflected / (norms + 1e-10)).astype(np.float32)
+
+
+def compute_refraction_direction(
+    incident: NDArray[np.float32],
+    normal: NDArray[np.float32],
+    n1: NDArray[np.float32] | float,
+    n2: NDArray[np.float32] | float,
+) -> tuple[NDArray[np.float32], NDArray[np.bool_]]:
+    """
+    Compute refracted ray direction using Snell's law.
+
+    Parameters
+    ----------
+    incident : ndarray, shape (N, 3)
+        Incident ray directions (should be normalized)
+    normal : ndarray, shape (N, 3)
+        Surface normals (should be normalized)
+    n1 : float or ndarray
+        Refractive index of incident medium
+    n2 : float or ndarray
+        Refractive index of transmitted medium
+
+    Returns
+    -------
+    refracted : ndarray, shape (N, 3)
+        Refracted ray directions (normalized, zero for TIR rays)
+    tir_mask : ndarray, shape (N,)
+        Boolean mask indicating total internal reflection
+    """
+    n1 = np.atleast_1d(n1).astype(np.float32)
+    n2 = np.atleast_1d(n2).astype(np.float32)
+
+    cos_theta_i = -np.sum(incident * normal, axis=1)
+    n_ratio = n1 / n2
+
+    sin_theta_t_sq = (n_ratio**2) * (1.0 - cos_theta_i**2)
+    tir_mask = sin_theta_t_sq > 1.0
+
+    cos_theta_t = np.sqrt(np.clip(1.0 - sin_theta_t_sq, 0, 1))
+
+    refracted = (
+        n_ratio[:, np.newaxis] * incident
+        + (n_ratio * cos_theta_i - cos_theta_t)[:, np.newaxis] * normal
+    )
+
+    refracted[tir_mask] = 0.0
+
+    norms = np.linalg.norm(refracted, axis=1, keepdims=True)
+    refracted = np.where(norms > 1e-10, refracted / norms, 0.0)
+
+    return refracted.astype(np.float32), tir_mask
+
+
+# =============================================================================
+# CPU Fallback Implementation
+# =============================================================================
+
+
+def _fresnel_coefficients_cpu(
+    cos_theta_i: NDArray[np.float32],
+    n1: NDArray[np.float32] | float,
+    n2: NDArray[np.float32] | float,
+    polarization: str = "unpolarized",
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """CPU implementation of Fresnel coefficient calculation."""
+    # Ensure arrays
+    cos_theta_i = np.atleast_1d(cos_theta_i).astype(np.float32)
+    n1 = np.atleast_1d(n1).astype(np.float32)
+    n2 = np.atleast_1d(n2).astype(np.float32)
+
+    n_ratio = n1 / n2
+    sin_theta_i_sq = 1.0 - cos_theta_i**2
+    sin_theta_t_sq = (n_ratio**2) * sin_theta_i_sq
+
+    # Check for TIR
+    tir_mask = sin_theta_t_sq > 1.0
+    cos_theta_t = np.sqrt(np.clip(1.0 - sin_theta_t_sq, 0, 1))
+
+    # Fresnel amplitude coefficients
+    r_s_num = n1 * cos_theta_i - n2 * cos_theta_t
+    r_s_den = n1 * cos_theta_i + n2 * cos_theta_t
+    r_s = r_s_num / (r_s_den + 1e-10)
+
+    r_p_num = n2 * cos_theta_i - n1 * cos_theta_t
+    r_p_den = n2 * cos_theta_i + n1 * cos_theta_t
+    r_p = r_p_num / (r_p_den + 1e-10)
+
+    # Intensity coefficients
+    R_s = r_s**2
+    R_p = r_p**2
+
+    # Handle TIR
+    R_s = np.where(tir_mask, 1.0, R_s)
+    R_p = np.where(tir_mask, 1.0, R_p)
+
+    # Select based on polarization
+    if polarization == "s":
+        R = R_s
+    elif polarization == "p":
+        R = R_p
+    else:
+        R = 0.5 * (R_s + R_p)
+
+    T = 1.0 - R
+
+    return R.astype(np.float32), T.astype(np.float32)
+
+
+__all__ = [
+    "fresnel_coefficients_gpu",
+    "compute_reflection_direction",
+    "compute_refraction_direction",
+]