lsurf 1.0.0__py3-none-any.whl

lsurf/sources/gaussian.py

@@ -0,0 +1,272 @@
+# 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.
+
+"""
+Gaussian Beam Source Implementation
+
+Provides a Gaussian beam source following paraxial beam optics.
+Suitable for modeling focused laser beams.
+
+Examples
+--------
+>>> from surface_roughness.sources import GaussianBeam
+>>>
+>>> source = GaussianBeam(
+...     waist_position=(0, 0, 0),
+...     direction=(0, 0, 1),
+...     waist_radius=1e-3,  # 1 mm waist
+...     num_rays=5000,
+...     wavelength=1064e-9,  # Nd:YAG
+...     power=10e-3
+... )
+>>> rays = source.generate()
+
+References
+----------
+.. [1] Siegman, A. E. (1986). Lasers. University Science Books.
+"""
+
+import numpy as np
+
+from ..utilities.ray_data import RayBatch
+from .base import RaySource
+
+
+class GaussianBeam(RaySource):
+    """
+    Gaussian beam with specified waist and Rayleigh range.
+
+    Implements paraxial Gaussian beam using ray approximation.
+    Each ray represents a wavefront normal, with intensity weighted
+    according to the Gaussian profile.
+
+    Parameters
+    ----------
+    waist_position : tuple of float
+        Position of beam waist (x, y, z) in meters.
+    direction : tuple of float
+        Beam axis direction (dx, dy, dz), will be normalized.
+    waist_radius : float
+        Beam waist radius (w₀) in meters.
+    num_rays : int
+        Number of rays to generate.
+    wavelength : float
+        Wavelength in meters. Must be monochromatic for Gaussian beam.
+    power : float, optional
+        Total beam power in watts. Default is 1.0.
+
+    Attributes
+    ----------
+    waist_position : ndarray, shape (3,)
+        Beam waist position.
+    direction : ndarray, shape (3,)
+        Normalized beam direction.
+    waist_radius : float
+        Beam waist radius w₀.
+    rayleigh_range : float
+        Rayleigh range z_R = πw₀²/λ.
+
+    Notes
+    -----
+    The Gaussian beam has intensity profile:
+
+    I(r) = I₀ exp(-2r²/w²)
+
+    where w is the beam radius at distance z from the waist:
+
+    w(z) = w₀ √(1 + (z/z_R)²)
+
+    and z_R = πw₀²/λ is the Rayleigh range.
+
+    This implementation generates rays at the waist position with
+    parallel directions (plane wavefront at waist). Ray intensities
+    are weighted according to the Gaussian profile.
+
+    Examples
+    --------
+    >>> # 1 mm waist Nd:YAG laser
+    >>> source = GaussianBeam(
+    ...     waist_position=(0, 0, 0),
+    ...     direction=(0, 0, 1),
+    ...     waist_radius=1e-3,
+    ...     num_rays=5000,
+    ...     wavelength=1064e-9,
+    ...     power=10e-3
+    ... )
+    >>> print(f"Rayleigh range: {source.rayleigh_range:.3f} m")
+    """
+
+    def __init__(
+        self,
+        waist_position: tuple[float, float, float],
+        direction: tuple[float, float, float],
+        waist_radius: float,
+        num_rays: int,
+        wavelength: float,
+        power: float = 1.0,
+    ):
+        """
+        Initialize Gaussian beam.
+
+        Parameters
+        ----------
+        waist_position : tuple of float
+            Position of beam waist (x, y, z) in meters.
+        direction : tuple of float
+            Beam axis direction, will be normalized.
+        waist_radius : float
+            Beam waist radius w₀ in meters.
+        num_rays : int
+            Number of rays to generate.
+        wavelength : float
+            Wavelength in meters.
+        power : float, optional
+            Total beam power in watts. Default is 1.0.
+
+        Raises
+        ------
+        ValueError
+            If wavelength is a tuple (polychromatic not supported),
+            or if waist_radius <= 0.
+        """
+        if isinstance(wavelength, tuple):
+            raise ValueError("Gaussian beam requires monochromatic wavelength")
+
+        super().__init__(num_rays, wavelength, power)
+        self.waist_position = np.array(waist_position, dtype=np.float32)
+        self.waist_radius = waist_radius
+
+        # Normalize direction
+        direction_arr = np.array(direction, dtype=np.float32)
+        self.direction = direction_arr / np.linalg.norm(direction_arr)
+
+        # Compute Rayleigh range
+        self.rayleigh_range = np.pi * waist_radius**2 / wavelength
+
+        if waist_radius <= 0:
+            raise ValueError("waist_radius must be positive")
+
+    def generate(self) -> RayBatch:
+        """
+        Generate Gaussian beam.
+
+        Creates rays at the waist position with Gaussian-distributed
+        positions and parallel directions.
+
+        Returns
+        -------
+        RayBatch
+            Ray batch with Gaussian intensity distribution.
+
+        Notes
+        -----
+        Positions are sampled from a 2D Gaussian distribution with
+        σ = w₀/2. Intensities are weighted by the Gaussian profile
+        to accurately represent the beam's energy distribution.
+        """
+        rays = self._allocate_rays()
+
+        # Create perpendicular basis
+        v1, v2 = self._create_perpendicular_basis(self.direction)
+
+        # Generate positions at waist with Gaussian distribution
+        # Use w0/2 as sigma for sampling to get good coverage
+        sigma = self.waist_radius / 2
+        x_local = np.random.normal(0, sigma, self.num_rays)
+        y_local = np.random.normal(0, sigma, self.num_rays)
+
+        # Positions at waist
+        rays.positions[:] = (
+            self.waist_position
+            + x_local[:, np.newaxis] * v1
+            + y_local[:, np.newaxis] * v2
+        )
+
+        # At waist, rays are parallel to axis (plane wavefront)
+        rays.directions[:] = self.direction
+
+        # Adjust intensities according to Gaussian profile
+        # I(r) ∝ exp(-2r²/w₀²)
+        r_squared = x_local**2 + y_local**2
+        rays.intensities[:] *= np.exp(-2 * r_squared / self.waist_radius**2)
+
+        # Renormalize to conserve power
+        rays.intensities[:] *= self.power / np.sum(rays.intensities)
+
+        # Monochromatic wavelength
+        rays.wavelengths[:] = self.wavelength
+
+        return rays
+
+    def beam_radius_at(self, z: float) -> float:
+        """
+        Compute beam radius at distance z from waist.
+
+        Parameters
+        ----------
+        z : float
+            Distance from waist along beam axis in meters.
+
+        Returns
+        -------
+        float
+            Beam radius w(z) in meters.
+
+        Notes
+        -----
+        w(z) = w₀ √(1 + (z/z_R)²)
+        """
+        return self.waist_radius * np.sqrt(1 + (z / self.rayleigh_range) ** 2)
+
+    def divergence_angle(self) -> float:
+        """
+        Compute far-field divergence angle.
+
+        Returns
+        -------
+        float
+            Half-angle divergence in radians.
+
+        Notes
+        -----
+        θ = λ / (π w₀)
+        """
+        return self.wavelength / (np.pi * self.waist_radius)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"GaussianBeam(waist_position={self.waist_position.tolist()}, "
+            f"waist_radius={self.waist_radius:.2e}, "
+            f"rayleigh_range={self.rayleigh_range:.3f})"
+        )

lsurf/sources/parallel_from_positions.py

@@ -0,0 +1,197 @@
+# 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.
+
+"""
+Parallel Beam from Explicit Position Array
+
+Provides a source where ray positions are explicitly specified and all rays
+share a common direction. Useful for atmospheric propagation studies where
+rays are launched from specific impact parameters or grid points.
+
+Examples
+--------
+>>> from lsurf.sources import ParallelBeamFromPositions
+>>> import numpy as np
+>>>
+>>> # Create rays at different altitudes, all traveling horizontally
+>>> positions = np.array([
+...     [-1000, 0, 100],
+...     [-1000, 0, 200],
+...     [-1000, 0, 300],
+... ])
+>>> source = ParallelBeamFromPositions(
+...     positions=positions,
+...     direction=(1, 0, 0),
+...     wavelength=532e-9,
+... )
+>>> rays = source.generate()
+"""
+
+import numpy as np
+import numpy.typing as npt
+
+from ..utilities.ray_data import RayBatch
+from .base import RaySource
+
+
+class ParallelBeamFromPositions(RaySource):
+    """
+    Parallel rays from explicitly specified positions.
+
+    All rays share the same direction, making this ideal for:
+    - Atmospheric refraction studies with specific impact parameters
+    - Plane wave propagation through inhomogeneous media
+    - Grid-based ray launching for wavefront analysis
+
+    Unlike CollimatedBeam which generates positions in a disk, this source
+    accepts arbitrary position arrays, enabling custom spatial distributions.
+
+    Parameters
+    ----------
+    positions : array_like, shape (N, 3)
+        Starting positions for each ray in meters.
+    direction : tuple of float
+        Direction vector for all rays (will be normalized).
+    wavelength : float or tuple of float, optional
+        Single wavelength (m) or (min, max) range. Default is 532 nm.
+    power : float, optional
+        Total source power in watts. Default is 1.0.
+
+    Attributes
+    ----------
+    positions : ndarray, shape (N, 3)
+        Ray starting positions.
+    direction : ndarray, shape (3,)
+        Normalized ray direction.
+
+    Examples
+    --------
+    >>> # Rays at different impact parameters for atmospheric study
+    >>> impact_params = np.linspace(0, 10000, 100)
+    >>> positions = np.column_stack([
+    ...     -np.sqrt((R + 100e3)**2 - (R + impact_params)**2),  # x
+    ...     np.zeros_like(impact_params),                       # y
+    ...     impact_params                                       # z
+    ... ])
+    >>> source = ParallelBeamFromPositions(positions, direction=(1, 0, 0))
+    >>> rays = source.generate()
+    >>> propagator.propagate(rays, total_distance=500e3, step_size=100)
+
+    >>> # Regular grid of rays
+    >>> x, y = np.meshgrid(np.linspace(-1, 1, 10), np.linspace(-1, 1, 10))
+    >>> positions = np.column_stack([x.ravel(), y.ravel(), np.zeros(100)])
+    >>> source = ParallelBeamFromPositions(positions, direction=(0, 0, 1))
+    """
+
+    def __init__(
+        self,
+        positions: npt.ArrayLike,
+        direction: tuple[float, float, float],
+        wavelength: float | tuple[float, float] = 532e-9,
+        power: float = 1.0,
+    ):
+        """
+        Initialize parallel ray source.
+
+        Parameters
+        ----------
+        positions : array_like, shape (N, 3)
+            Starting positions for each ray in meters.
+        direction : tuple of float
+            Direction vector for all rays (will be normalized).
+        wavelength : float or tuple of float, optional
+            Wavelength in meters or (min, max) range. Default is 532 nm.
+        power : float, optional
+            Total source power in watts. Default is 1.0.
+
+        Raises
+        ------
+        ValueError
+            If positions shape is invalid or direction is zero vector.
+        """
+        # Convert and validate positions
+        self._positions = np.asarray(positions, dtype=np.float32)
+        if self._positions.ndim == 1:
+            self._positions = self._positions.reshape(1, 3)
+        if self._positions.ndim != 2 or self._positions.shape[1] != 3:
+            raise ValueError(
+                f"positions must have shape (N, 3), got {self._positions.shape}"
+            )
+
+        num_rays = self._positions.shape[0]
+
+        # Initialize base class
+        super().__init__(num_rays, wavelength, power)
+
+        # Normalize direction
+        direction_arr = np.array(direction, dtype=np.float32)
+        norm = np.linalg.norm(direction_arr)
+        if norm < 1e-10:
+            raise ValueError("direction cannot be zero vector")
+        self.direction = direction_arr / norm
+
+    @property
+    def positions(self) -> npt.NDArray[np.float32]:
+        """Ray starting positions, shape (N, 3)."""
+        return self._positions
+
+    def generate(self) -> RayBatch:
+        """
+        Generate parallel ray batch.
+
+        Creates rays at the specified positions, all with the same direction.
+
+        Returns
+        -------
+        RayBatch
+            Ray batch with parallel rays ready for propagation.
+        """
+        rays = self._allocate_rays()
+
+        # Set positions from input array
+        rays.positions[:] = self._positions
+
+        # All rays have same direction
+        rays.directions[:] = self.direction
+
+        # Assign wavelengths
+        self._assign_wavelengths(rays)
+
+        return rays
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"ParallelBeamFromPositions(num_rays={self.num_rays}, "
+            f"direction={self.direction.tolist()})"
+        )

lsurf/sources/point.py

@@ -0,0 +1,172 @@
+# 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.
+
+"""
+Point Source Implementation
+
+Provides an isotropic point source that emits rays uniformly in all
+directions from a single point.
+
+Examples
+--------
+>>> from surface_roughness.sources import PointSource
+>>>
+>>> source = PointSource(
+...     position=(0, 0, 0),
+...     num_rays=10000,
+...     wavelength=532e-9,  # Green laser
+...     power=1e-3
+... )
+>>> rays = source.generate()
+"""
+
+import numpy as np
+
+from ..utilities.ray_data import RayBatch
+from .base import RaySource
+
+
+class PointSource(RaySource):
+    """
+    Isotropic point source emitting in all directions.
+
+    Generates rays from a single point with directions uniformly
+    distributed over the unit sphere.
+
+    Parameters
+    ----------
+    position : tuple of float
+        Source position (x, y, z) 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 source power in watts. Default is 1.0.
+
+    Attributes
+    ----------
+    position : ndarray, shape (3,)
+        Source position in meters.
+
+    Notes
+    -----
+    The angular distribution is uniform over the full 4π steradians.
+    Each ray carries equal intensity (power / num_rays).
+
+    Examples
+    --------
+    >>> # Monochromatic point source
+    >>> source = PointSource(
+    ...     position=(0, 0, 0),
+    ...     num_rays=10000,
+    ...     wavelength=532e-9,
+    ...     power=1e-3
+    ... )
+    >>> rays = source.generate()
+
+    >>> # Polychromatic source (white light LED)
+    >>> source = PointSource(
+    ...     position=(0, 0.1, 0),
+    ...     num_rays=5000,
+    ...     wavelength=(400e-9, 700e-9),
+    ...     power=0.5
+    ... )
+    """
+
+    def __init__(
+        self,
+        position: tuple[float, float, float],
+        num_rays: int,
+        wavelength: float | tuple[float, float],
+        power: float = 1.0,
+    ):
+        """
+        Initialize point source.
+
+        Parameters
+        ----------
+        position : tuple of float
+            Source position (x, y, z) 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 source power in watts. Default is 1.0.
+        """
+        super().__init__(num_rays, wavelength, power)
+        self.position = np.array(position, dtype=np.float32)
+
+    def generate(self) -> RayBatch:
+        """
+        Generate isotropic ray distribution.
+
+        Creates rays emanating from the source position with directions
+        uniformly distributed over the unit sphere.
+
+        Returns
+        -------
+        RayBatch
+            Ray batch with isotropic direction distribution.
+
+        Notes
+        -----
+        Uses the standard method for uniform sphere sampling:
+        - θ uniformly distributed in [0, 2π)
+        - cos(φ) uniformly distributed in [-1, 1]
+        """
+        rays = self._allocate_rays()
+
+        # All rays start at same position
+        rays.positions[:] = self.position
+
+        # Generate uniform distribution on sphere
+        theta = np.random.uniform(0, 2 * np.pi, self.num_rays)
+        cos_phi = np.random.uniform(-1, 1, self.num_rays)
+        sin_phi = np.sqrt(1 - cos_phi**2)
+
+        rays.directions[:, 0] = sin_phi * np.cos(theta)
+        rays.directions[:, 1] = sin_phi * np.sin(theta)
+        rays.directions[:, 2] = cos_phi
+
+        self._assign_wavelengths(rays)
+
+        return rays
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"PointSource(position={self.position.tolist()}, "
+            f"num_rays={self.num_rays})"
+        )