lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/absorption/grid.py

@@ -0,0 +1,240 @@
+# 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.
+
+"""
+Absorption Kernel for GridInhomogeneousModel
+
+GPU kernel for applying Beer-Lambert absorption using 3D grid-based LUT.
+"""
+
+import math
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = True
+except ImportError:
+
+    class _FakeCuda:
+        """Fake cuda module for when numba is not installed."""
+
+        class devicearray:
+            """Fake devicearray submodule."""
+
+            DeviceNDArray = object
+
+        @staticmethod
+        def jit(*args, **kwargs):
+            """Return a no-op decorator."""
+
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+@cuda.jit(device=True)
+def _device_trilinear_interpolate(
+    x: float,
+    y: float,
+    z: float,
+    grid,
+    x_min: float,
+    y_min: float,
+    z_min: float,
+    dx: float,
+    dy: float,
+    dz: float,
+    nx: int,
+    ny: int,
+    nz: int,
+) -> float:
+    """Trilinear interpolation in 3D grid."""
+    xn = (x - x_min) / dx
+    yn = (y - y_min) / dy
+    zn = (z - z_min) / dz
+
+    xn = max(0.0, min(xn, nx - 1.001))
+    yn = max(0.0, min(yn, ny - 1.001))
+    zn = max(0.0, min(zn, nz - 1.001))
+
+    x0 = int(xn)
+    y0 = int(yn)
+    z0 = int(zn)
+
+    x1 = min(x0 + 1, nx - 1)
+    y1 = min(y0 + 1, ny - 1)
+    z1 = min(z0 + 1, nz - 1)
+
+    xd = xn - x0
+    yd = yn - y0
+    zd = zn - z0
+
+    c000 = grid[x0, y0, z0]
+    c001 = grid[x0, y0, z1]
+    c010 = grid[x0, y1, z0]
+    c011 = grid[x0, y1, z1]
+    c100 = grid[x1, y0, z0]
+    c101 = grid[x1, y0, z1]
+    c110 = grid[x1, y1, z0]
+    c111 = grid[x1, y1, z1]
+
+    c00 = c000 * (1 - xd) + c100 * xd
+    c01 = c001 * (1 - xd) + c101 * xd
+    c10 = c010 * (1 - xd) + c110 * xd
+    c11 = c011 * (1 - xd) + c111 * xd
+
+    c0 = c00 * (1 - yd) + c10 * yd
+    c1 = c01 * (1 - yd) + c11 * yd
+
+    return c0 * (1 - zd) + c1 * zd
+
+
+@cuda.jit
+def _kernel_absorption_grid(
+    positions,
+    directions,
+    active,
+    intensities,
+    optical_depth,
+    step_size: float,
+    num_steps: int,
+    x_min: float,
+    y_min: float,
+    z_min: float,
+    grid_dx: float,
+    grid_dy: float,
+    grid_dz: float,
+    nx: int,
+    ny: int,
+    nz: int,
+    alpha_grid,
+):
+    """
+    Apply Beer-Lambert absorption for GridInhomogeneousModel.
+
+    Integrates absorption along the ray path using trilinear interpolation
+    in 3D absorption grid.
+
+    Parameters
+    ----------
+    positions : device array, shape (N, 3)
+        Ray positions (after propagation)
+    directions : device array, shape (N, 3)
+        Ray directions (unit vectors)
+    active : device array, shape (N,)
+        Boolean mask for active rays
+    intensities : device array, shape (N,)
+        Ray intensities (modified in-place)
+    optical_depth : device array, shape (N,)
+        Accumulated optical depth (modified in-place)
+    step_size : float
+        Integration step size in meters
+    num_steps : int
+        Number of steps taken in propagation
+    x_min, y_min, z_min : float
+        Grid origin
+    grid_dx, grid_dy, grid_dz : float
+        Grid spacing in each dimension
+    nx, ny, nz : int
+        Grid dimensions
+    alpha_grid : device array, shape (nx, ny, nz)
+        3D absorption coefficient grid
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+    if not active[idx]:
+        return
+
+    # Get current position and direction
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+    dx_dir = directions[idx, 0]
+    dy_dir = directions[idx, 1]
+    dz_dir = directions[idx, 2]
+
+    # Integrate absorption along path by stepping backwards
+    delta_tau = 0.0
+
+    for step in range(num_steps):
+        # Position at this step (walking backwards from current)
+        back_dist = step * step_size
+        px = x - dx_dir * back_dist
+        py = y - dy_dir * back_dist
+        pz = z - dz_dir * back_dist
+
+        # Look up absorption coefficient (trilinear interpolation)
+        alpha = _device_trilinear_interpolate(
+            px,
+            py,
+            pz,
+            alpha_grid,
+            x_min,
+            y_min,
+            z_min,
+            grid_dx,
+            grid_dy,
+            grid_dz,
+            nx,
+            ny,
+            nz,
+        )
+
+        # Accumulate optical depth for this step
+        delta_tau += alpha * step_size
+
+    # Apply Beer-Lambert decay: I = I₀ * exp(-τ)
+    intensities[idx] *= math.exp(-delta_tau)
+
+    # Accumulate optical depth
+    optical_depth[idx] += delta_tau

lsurf/propagation/kernels/absorption/simple.py

@@ -0,0 +1,232 @@
+# 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.
+
+"""
+Absorption Kernel for SimpleInhomogeneousModel
+
+GPU kernel for applying Beer-Lambert absorption using 1D altitude-based LUT.
+Called separately after propagation to update ray intensities.
+"""
+
+import math
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = True
+except ImportError:
+
+    class _FakeCuda:
+        """Fake cuda module for when numba is not installed."""
+
+        class devicearray:
+            """Fake devicearray submodule."""
+
+            DeviceNDArray = object
+
+        @staticmethod
+        def jit(*args, **kwargs):
+            """Return a no-op decorator."""
+
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+@cuda.jit(device=True)
+def _device_lut_interpolate(
+    value: float,
+    lut: cuda.devicearray.DeviceNDArray,
+    min_val: float,
+    delta: float,
+    lut_size: int,
+) -> float:
+    """
+    Linear interpolation in 1D lookup table.
+
+    Parameters
+    ----------
+    value : float
+        Value to interpolate at
+    lut : device array
+        1D lookup table
+    min_val : float
+        Minimum value in table
+    delta : float
+        Spacing between table entries
+    lut_size : int
+        Number of entries in table
+
+    Returns
+    -------
+    float
+        Interpolated value
+    """
+    idx_float = (value - min_val) / delta
+
+    if idx_float <= 0.0:
+        return lut[0]
+    if idx_float >= lut_size - 1:
+        return lut[lut_size - 1]
+
+    idx = int(idx_float)
+    frac = idx_float - idx
+
+    return lut[idx] + frac * (lut[idx + 1] - lut[idx])
+
+
+@cuda.jit
+def _kernel_absorption_simple(
+    positions,
+    directions,
+    active,
+    intensities,
+    optical_depth,
+    step_size: float,
+    num_steps: int,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    ref_radius: float,
+    min_alt: float,
+    delta_h: float,
+    lut_size: int,
+    lut_alpha,
+):
+    """
+    Apply Beer-Lambert absorption for SimpleInhomogeneousModel.
+
+    This kernel applies absorption decay to ray intensities based on
+    the distance traveled through the medium. It integrates α along
+    the ray path by stepping backwards from the current position and
+    sampling α at each step.
+
+    The kernel computes:
+        τ = ∫ α(s) ds  (integrated along path)
+        I_new = I_old * exp(-τ)
+
+    Parameters
+    ----------
+    positions : device array, shape (N, 3)
+        Ray positions (after propagation)
+    directions : device array, shape (N, 3)
+        Ray directions (unit vectors)
+    active : device array, shape (N,)
+        Boolean mask for active rays
+    intensities : device array, shape (N,)
+        Ray intensities (modified in-place)
+    optical_depth : device array, shape (N,)
+        Accumulated optical depth (modified in-place)
+    step_size : float
+        Integration step size in meters
+    num_steps : int
+        Number of steps taken in propagation
+    center_x, center_y, center_z : float
+        Center of spherical symmetry
+    ref_radius : float
+        Reference radius (e.g., Earth radius)
+    min_alt : float
+        Minimum altitude in LUT
+    delta_h : float
+        Altitude spacing in LUT
+    lut_size : int
+        Number of entries in LUT
+    lut_alpha : device array
+        1D lookup table for absorption coefficient α(altitude)
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+    if not active[idx]:
+        return
+
+    # Get current position and direction
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+    dx_dir = directions[idx, 0]
+    dy_dir = directions[idx, 1]
+    dz_dir = directions[idx, 2]
+
+    # Integrate absorption along path by stepping backwards
+    # Start at current position, step back along -direction
+    delta_tau = 0.0
+
+    for step in range(num_steps):
+        # Position at this step (walking backwards from current)
+        # At step=0, we're at the current position
+        # At step=num_steps-1, we're at the starting position
+        back_dist = step * step_size
+        px = x - dx_dir * back_dist
+        py = y - dy_dir * back_dist
+        pz = z - dz_dir * back_dist
+
+        # Compute altitude
+        rx = px - center_x
+        ry = py - center_y
+        rz = pz - center_z
+        r = math.sqrt(rx * rx + ry * ry + rz * rz)
+        altitude = r - ref_radius
+        if altitude < 0.0:
+            altitude = 0.0
+
+        # Look up absorption coefficient at this position
+        alpha = _device_lut_interpolate(altitude, lut_alpha, min_alt, delta_h, lut_size)
+
+        # Accumulate optical depth for this step
+        delta_tau += alpha * step_size
+
+    # Apply Beer-Lambert decay: I = I₀ * exp(-τ)
+    intensities[idx] *= math.exp(-delta_tau)
+
+    # Accumulate optical depth
+    optical_depth[idx] += delta_tau