lsurf 1.0.0__py3-none-any.whl

lsurf/sources/base.py

@@ -0,0 +1,264 @@
+# 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.
+
+"""
+Ray Source Base Class
+
+Defines the abstract base class for all ray sources in the raytracing
+framework. Sources generate initial ray conditions for simulation.
+
+Design Notes
+------------
+- Follows Interface Segregation Principle: focused on ray generation
+- Derived classes implement specific spatial/angular distributions
+- Ray intensities are normalized to conserve total power
+"""
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..utilities.ray_data import RayBatch, create_ray_batch
+
+
+class RaySource(ABC):
+    """
+    Abstract base class for ray sources.
+
+    A ray source defines initial conditions for a ray batch, including
+    spatial distribution, angular distribution, wavelength spectrum,
+    and intensity distribution.
+
+    Parameters
+    ----------
+    num_rays : int
+        Number of rays to generate. Must be positive.
+    wavelength : float or tuple of float
+        Single wavelength in meters for monochromatic source, or
+        (min, max) tuple for polychromatic source.
+    power : float, optional
+        Total source power in watts. Default is 1.0.
+
+    Attributes
+    ----------
+    num_rays : int
+        Number of rays generated by this source.
+    wavelength : float or tuple
+        Wavelength specification.
+    power : float
+        Total source power.
+
+    Notes
+    -----
+    Derived classes must implement the `generate()` method which returns
+    a fully initialized RayBatch.
+
+    The ray intensities should sum to the total power (conservation of energy).
+    When generating rays, use `_allocate_rays()` to create the batch with
+    proper initialization and `_assign_wavelengths()` to set wavelengths.
+
+    Examples
+    --------
+    Creating a custom source:
+
+    >>> class MySource(RaySource):
+    ...     def __init__(self, position, num_rays, wavelength, power=1.0):
+    ...         super().__init__(num_rays, wavelength, power)
+    ...         self.position = np.array(position)
+    ...
+    ...     def generate(self):
+    ...         rays = self._allocate_rays()
+    ...         rays.positions[:] = self.position
+    ...         # Set directions...
+    ...         self._assign_wavelengths(rays)
+    ...         return rays
+    """
+
+    def __init__(
+        self,
+        num_rays: int,
+        wavelength: float | tuple[float, float],
+        power: float = 1.0,
+    ):
+        """
+        Initialize ray source.
+
+        Parameters
+        ----------
+        num_rays : int
+            Number of rays to generate. Must be positive.
+        wavelength : float or tuple of float
+            Single wavelength (m) or (min, max) range.
+        power : float, optional
+            Total source power in watts. Default is 1.0.
+
+        Raises
+        ------
+        ValueError
+            If num_rays <= 0, power <= 0, wavelength <= 0, or
+            wavelength range is invalid.
+        """
+        self.num_rays = num_rays
+        self.wavelength = wavelength
+        self.power = power
+
+        # Validate parameters
+        if num_rays <= 0:
+            raise ValueError("num_rays must be positive")
+        if power <= 0:
+            raise ValueError("power must be positive")
+
+        if isinstance(wavelength, tuple):
+            if len(wavelength) != 2:
+                raise ValueError("wavelength range must be (min, max)")
+            if wavelength[0] >= wavelength[1]:
+                raise ValueError("wavelength min must be less than max")
+            if wavelength[0] <= 0:
+                raise ValueError("wavelength values must be positive")
+        elif wavelength <= 0:
+            raise ValueError("wavelength must be positive")
+
+    @abstractmethod
+    def generate(self) -> RayBatch:
+        """
+        Generate ray batch with initial conditions.
+
+        Creates and initializes a RayBatch with positions, directions,
+        wavelengths, and intensities according to the source configuration.
+
+        Returns
+        -------
+        RayBatch
+            Initialized rays ready for propagation.
+
+        Notes
+        -----
+        Implementations should ensure:
+        - All rays are marked as active
+        - Directions are normalized
+        - Intensities sum to total power
+        - Wavelengths are set appropriately
+        """
+        pass
+
+    def _allocate_rays(self) -> RayBatch:
+        """
+        Allocate ray batch with uniform intensity distribution.
+
+        Creates a RayBatch with all rays active and intensities set
+        so they sum to the total power.
+
+        Returns
+        -------
+        RayBatch
+            Allocated ray batch with intensities initialized.
+
+        Notes
+        -----
+        Called by generate() implementations to create the ray batch.
+        """
+        rays = create_ray_batch(num_rays=self.num_rays)
+        rays.active[:] = True
+        rays.intensities[:] = self.power / self.num_rays
+        return rays
+
+    def _assign_wavelengths(self, rays: RayBatch) -> None:
+        """
+        Assign wavelengths to rays.
+
+        For monochromatic sources, sets all wavelengths to the single value.
+        For polychromatic sources, samples uniformly from the range.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Ray batch to assign wavelengths to.
+
+        Notes
+        -----
+        Called by generate() implementations after setting positions
+        and directions.
+        """
+        if isinstance(self.wavelength, tuple):
+            # Uniform distribution over range
+            rays.wavelengths[:] = np.random.uniform(
+                self.wavelength[0], self.wavelength[1], self.num_rays
+            ).astype(np.float32)
+        else:
+            # Monochromatic
+            rays.wavelengths[:] = self.wavelength
+
+    def _create_perpendicular_basis(
+        self, direction: NDArray[np.float32]
+    ) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+        """
+        Create two unit vectors perpendicular to a direction.
+
+        Parameters
+        ----------
+        direction : ndarray, shape (3,)
+            Direction vector (must be normalized).
+
+        Returns
+        -------
+        v1 : ndarray, shape (3,)
+            First perpendicular unit vector.
+        v2 : ndarray, shape (3,)
+            Second perpendicular unit vector (perpendicular to both
+            direction and v1).
+
+        Notes
+        -----
+        Used for generating positions/directions in a plane perpendicular
+        to the beam axis.
+        """
+        if abs(direction[2]) < 0.9:
+            v1 = np.cross(direction, np.array([0, 0, 1], dtype=np.float32))
+        else:
+            v1 = np.cross(direction, np.array([1, 0, 0], dtype=np.float32))
+        v1 = v1 / np.linalg.norm(v1)
+        v2 = np.cross(direction, v1)
+        return v1.astype(np.float32), v2.astype(np.float32)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        wl_str = (
+            f"({self.wavelength[0]:.2e}, {self.wavelength[1]:.2e})"
+            if isinstance(self.wavelength, tuple)
+            else f"{self.wavelength:.2e}"
+        )
+        return (
+            f"{self.__class__.__name__}(num_rays={self.num_rays}, "
+            f"wavelength={wl_str}, power={self.power})"
+        )

lsurf/sources/collimated.py

@@ -0,0 +1,252 @@
+# 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.
+
+"""
+Collimated Beam Source Implementation
+
+Provides a collimated (parallel) beam source with optional spatial intensity
+profiles. Useful for modeling laser beams and plane wave illumination.
+
+Examples
+--------
+>>> from surface_roughness.sources import CollimatedBeam
+>>>
+>>> source = CollimatedBeam(
+...     center=(0, 0, -10),
+...     direction=(0, 0, 1),
+...     radius=0.001,  # 1 mm
+...     num_rays=5000,
+...     wavelength=633e-9,  # HeNe laser
+...     power=5e-3
+... )
+>>> rays = source.generate()
+"""
+
+from typing import Literal
+
+import numpy as np
+
+from ..utilities.ray_data import RayBatch
+from .base import RaySource
+
+
+class CollimatedBeam(RaySource):
+    """
+    Collimated beam with parallel rays.
+
+    Generates rays with identical directions and positions distributed
+    in a circular cross-section. Supports uniform and Gaussian intensity
+    profiles.
+
+    Parameters
+    ----------
+    center : tuple of float
+        Beam center position (x, y, z) in meters.
+    direction : tuple of float
+        Beam propagation direction (dx, dy, dz), will be normalized.
+    radius : float
+        Beam radius in meters.
+    num_rays : int
+        Number of rays to generate.
+    wavelength : float or tuple of float
+        Single wavelength (m) or (min, max) range.
+    power : float, optional
+        Total beam power in watts. Default is 1.0.
+    profile : {'uniform', 'gaussian'}, optional
+        Spatial intensity profile. Default is 'uniform'.
+
+    Attributes
+    ----------
+    center : ndarray, shape (3,)
+        Beam center position.
+    direction : ndarray, shape (3,)
+        Normalized beam direction.
+    radius : float
+        Beam radius.
+    profile : str
+        Intensity profile type.
+
+    Notes
+    -----
+    For Gaussian profile, the radius corresponds to 2σ (where σ is the
+    standard deviation of the Gaussian). Ray intensities are weighted
+    according to the Gaussian distribution.
+
+    Ray timing is initialized so that all rays cross the reference plane
+    (at center) at time=0. This ensures coherent phase fronts.
+
+    Examples
+    --------
+    >>> # Uniform circular beam
+    >>> source = CollimatedBeam(
+    ...     center=(0, 0, 0),
+    ...     direction=(0, 0, 1),
+    ...     radius=1e-3,
+    ...     num_rays=5000,
+    ...     wavelength=633e-9,
+    ...     power=5e-3
+    ... )
+
+    >>> # Gaussian beam profile
+    >>> source = CollimatedBeam(
+    ...     center=(0, 0, 0),
+    ...     direction=(0, 0, 1),
+    ...     radius=2e-3,
+    ...     num_rays=10000,
+    ...     wavelength=1064e-9,
+    ...     power=1.0,
+    ...     profile='gaussian'
+    ... )
+    """
+
+    def __init__(
+        self,
+        center: tuple[float, float, float],
+        direction: tuple[float, float, float],
+        radius: float,
+        num_rays: int,
+        wavelength: float | tuple[float, float],
+        power: float = 1.0,
+        profile: Literal["uniform", "gaussian"] = "uniform",
+    ):
+        """
+        Initialize collimated beam.
+
+        Parameters
+        ----------
+        center : tuple of float
+            Beam center position (x, y, z) in meters.
+        direction : tuple of float
+            Beam propagation direction, will be normalized.
+        radius : float
+            Beam radius in meters.
+        num_rays : int
+            Number of rays to generate.
+        wavelength : float or tuple of float
+            Wavelength in meters or (min, max) range.
+        power : float, optional
+            Total beam power in watts. Default is 1.0.
+        profile : {'uniform', 'gaussian'}, optional
+            Spatial intensity profile. Default is 'uniform'.
+
+        Raises
+        ------
+        ValueError
+            If radius <= 0 or profile not in {'uniform', 'gaussian'}.
+        """
+        super().__init__(num_rays, wavelength, power)
+        self.center = np.array(center, dtype=np.float32)
+        self.radius = radius
+        self.profile = profile
+
+        # Normalize direction
+        direction_arr = np.array(direction, dtype=np.float32)
+        self.direction = direction_arr / np.linalg.norm(direction_arr)
+
+        if radius <= 0:
+            raise ValueError("radius must be positive")
+        if profile not in ("uniform", "gaussian"):
+            raise ValueError("profile must be 'uniform' or 'gaussian'")
+
+    def generate(self) -> RayBatch:
+        """
+        Generate collimated beam.
+
+        Creates rays with parallel directions and positions sampled
+        in a disk perpendicular to the beam direction.
+
+        Returns
+        -------
+        RayBatch
+            Ray batch with collimated ray directions.
+
+        Notes
+        -----
+        For uniform profile, positions are uniformly distributed in a disk.
+        For Gaussian profile, positions follow a 2D Gaussian distribution
+        and intensities are weighted accordingly.
+        """
+        rays = self._allocate_rays()
+
+        # All rays have same direction
+        rays.directions[:] = self.direction
+
+        # Create perpendicular basis
+        v1, v2 = self._create_perpendicular_basis(self.direction)
+
+        if self.profile == "uniform":
+            # Uniform disk sampling
+            r = self.radius * np.sqrt(np.random.uniform(0, 1, self.num_rays))
+            theta = np.random.uniform(0, 2 * np.pi, self.num_rays)
+
+            x_local = r * np.cos(theta)
+            y_local = r * np.sin(theta)
+        else:  # gaussian
+            # Gaussian profile (radius = 2*sigma)
+            sigma = self.radius / 2
+            x_local = np.random.normal(0, sigma, self.num_rays)
+            y_local = np.random.normal(0, sigma, self.num_rays)
+
+            # Adjust intensities for Gaussian profile
+            r_squared = x_local**2 + y_local**2
+            rays.intensities[:] *= np.exp(-r_squared / (2 * sigma**2))
+            # Renormalize to conserve power
+            rays.intensities[:] *= self.power / np.sum(rays.intensities)
+
+        # Convert to 3D positions
+        rays.positions[:] = (
+            self.center + x_local[:, np.newaxis] * v1 + y_local[:, np.newaxis] * v2
+        )
+
+        # Initialize accumulated_time for coherent phase front
+        # All rays should cross the reference plane (at center) at t=0
+        c = 299792458.0  # Speed of light in vacuum
+        n = 1.0  # Assume initial medium is air/vacuum
+
+        # Distance along beam direction from center to each ray position
+        offset_along_beam = np.sum(
+            (rays.positions - self.center) * self.direction, axis=1
+        )
+        # Time offset: negative for rays ahead, positive for rays behind
+        rays.accumulated_time[:] = -offset_along_beam * n / c
+
+        self._assign_wavelengths(rays)
+
+        return rays
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"CollimatedBeam(center={self.center.tolist()}, "
+            f"radius={self.radius}, profile='{self.profile}')"
+        )