lsurf 1.0.0__py3-none-any.whl

lsurf/geometry/geometry.py

@@ -0,0 +1,222 @@
+# 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.
+
+"""
+Immutable Geometry Container
+
+Holds the result of a GeometryBuilder.build() call.
+Provides convenient accessors for surfaces, detectors, and materials.
+"""
+
+from dataclasses import dataclass
+
+from ..surfaces import Surface
+from ..materials import MaterialField
+
+
+@dataclass(frozen=True)
+class Geometry:
+    """
+    Immutable container for simulation geometry.
+
+    Created by GeometryBuilder.build(). Provides access to surfaces,
+    detectors, and named media by name or index.
+
+    Parameters
+    ----------
+    surfaces : tuple of Surface
+        All optical/absorber surfaces in the geometry.
+    detectors : tuple of Surface
+        All detector surfaces in the geometry.
+    background_material : MaterialField
+        The background/ambient material (from set_background() medium).
+    media : dict
+        Mapping from medium name to MaterialField.
+    surface_names : dict
+        Mapping from surface name to index in surfaces tuple.
+    detector_names : dict
+        Mapping from detector name to index in detectors tuple.
+
+    Examples
+    --------
+    >>> geometry = builder.build()
+    >>> ocean = geometry.get_surface("ocean")
+    >>> detector = geometry.get_detector("detector_35km")
+    >>> atmosphere_material = geometry.get_medium("atmosphere")
+    """
+
+    surfaces: tuple[Surface, ...]
+    detectors: tuple[Surface, ...]
+    background_material: MaterialField
+    media: dict[str, MaterialField]
+    surface_names: dict[str, int]
+    detector_names: dict[str, int]
+
+    def get_medium(self, name: str) -> MaterialField:
+        """
+        Get the material for a named medium.
+
+        Parameters
+        ----------
+        name : str
+            The name of the medium.
+
+        Returns
+        -------
+        MaterialField
+            The material for the medium.
+
+        Raises
+        ------
+        KeyError
+            If no medium with the given name exists.
+        """
+        if name not in self.media:
+            available = ", ".join(sorted(self.media.keys()))
+            raise KeyError(f"No medium named '{name}'. Available: {available}")
+        return self.media[name]
+
+    def get_surface(self, name: str) -> Surface:
+        """
+        Get a surface by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the surface.
+
+        Returns
+        -------
+        Surface
+            The surface with the given name.
+
+        Raises
+        ------
+        KeyError
+            If no surface with the given name exists.
+        """
+        if name not in self.surface_names:
+            available = ", ".join(sorted(self.surface_names.keys()))
+            raise KeyError(f"No surface named '{name}'. Available: {available}")
+        return self.surfaces[self.surface_names[name]]
+
+    def get_surface_index(self, name: str) -> int:
+        """
+        Get the index of a surface by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the surface.
+
+        Returns
+        -------
+        int
+            The index of the surface in the surfaces tuple.
+
+        Raises
+        ------
+        KeyError
+            If no surface with the given name exists.
+        """
+        if name not in self.surface_names:
+            available = ", ".join(sorted(self.surface_names.keys()))
+            raise KeyError(f"No surface named '{name}'. Available: {available}")
+        return self.surface_names[name]
+
+    def get_detector(self, name: str) -> Surface:
+        """
+        Get a detector by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the detector.
+
+        Returns
+        -------
+        Surface
+            The detector with the given name.
+
+        Raises
+        ------
+        KeyError
+            If no detector with the given name exists.
+        """
+        if name not in self.detector_names:
+            available = ", ".join(sorted(self.detector_names.keys()))
+            raise KeyError(f"No detector named '{name}'. Available: {available}")
+        return self.detectors[self.detector_names[name]]
+
+    def get_detector_index(self, name: str) -> int:
+        """
+        Get the index of a detector by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the detector.
+
+        Returns
+        -------
+        int
+            The index of the detector in the detectors tuple.
+
+        Raises
+        ------
+        KeyError
+            If no detector with the given name exists.
+        """
+        if name not in self.detector_names:
+            available = ", ".join(sorted(self.detector_names.keys()))
+            raise KeyError(f"No detector named '{name}'. Available: {available}")
+        return self.detector_names[name]
+
+    def to_surface_list(self) -> list[Surface]:
+        """
+        Convert all surfaces and detectors to a list for SurfacePropagator.
+
+        Returns
+        -------
+        list of Surface
+            All surfaces and detectors as a mutable list.
+        """
+        return list(self.surfaces) + list(self.detectors)
+
+    def __len__(self) -> int:
+        """Return the total number of surfaces and detectors."""
+        return len(self.surfaces) + len(self.detectors)
+
+    def __iter__(self):
+        """Iterate over all surfaces and detectors."""
+        return iter(self.surfaces + self.detectors)

lsurf/geometry/surface_analysis.py

@@ -0,0 +1,375 @@
+# 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.
+
+"""
+Surface Relationship Analysis
+
+Tools for analyzing geometric relationships between surfaces to detect
+potential material assignment conflicts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from ..surfaces import Surface
+
+
+class SurfaceRelationship(Enum):
+    """Classification of the geometric relationship between two surfaces."""
+
+    DISJOINT = auto()  # Surfaces don't overlap in the domain of interest
+    PARALLEL = auto()  # Surfaces are parallel (planes) or concentric (spheres)
+    NESTED = auto()  # One surface completely contains the other
+    INTERSECTING = auto()  # Surfaces intersect, creating multiple regions
+
+
+@dataclass
+class SurfaceAnalysisResult:
+    """
+    Result of analyzing the relationship between two surfaces.
+
+    Attributes
+    ----------
+    relationship : SurfaceRelationship
+        The geometric relationship between the surfaces.
+    details : str
+        Human-readable explanation of the analysis.
+    materials_consistent : bool
+        Whether material assignments are consistent for this relationship.
+    """
+
+    relationship: SurfaceRelationship
+    details: str
+    materials_consistent: bool
+
+
+# Tolerance for parallel detection (cosine of angle between normals)
+PARALLEL_TOLERANCE = 1e-6
+
+
+def are_planes_parallel(
+    normal1: NDArray[np.float64],
+    normal2: NDArray[np.float64],
+    tolerance: float = PARALLEL_TOLERANCE,
+) -> bool:
+    """
+    Check if two planes are parallel based on their normals.
+
+    Parameters
+    ----------
+    normal1 : ndarray, shape (3,)
+        Normal vector of the first plane.
+    normal2 : ndarray, shape (3,)
+        Normal vector of the second plane.
+    tolerance : float, optional
+        Tolerance for parallel detection. Default is 1e-6.
+        Planes are considered parallel if |dot(n1, n2)| > 1 - tolerance.
+
+    Returns
+    -------
+    bool
+        True if the planes are parallel (or anti-parallel).
+    """
+    # Normalize vectors
+    n1 = np.asarray(normal1, dtype=np.float64)
+    n2 = np.asarray(normal2, dtype=np.float64)
+
+    n1 = n1 / np.linalg.norm(n1)
+    n2 = n2 / np.linalg.norm(n2)
+
+    # Check if parallel (dot product magnitude close to 1)
+    dot = np.abs(np.dot(n1, n2))
+    return dot > (1.0 - tolerance)
+
+
+def are_spheres_concentric(
+    center1: NDArray[np.float64],
+    center2: NDArray[np.float64],
+    tolerance: float = 1e-6,
+) -> bool:
+    """
+    Check if two spheres are concentric (same center).
+
+    Parameters
+    ----------
+    center1 : ndarray, shape (3,)
+        Center of the first sphere.
+    center2 : ndarray, shape (3,)
+        Center of the second sphere.
+    tolerance : float, optional
+        Distance tolerance for considering centers equal.
+
+    Returns
+    -------
+    bool
+        True if the spheres share the same center.
+    """
+    c1 = np.asarray(center1, dtype=np.float64)
+    c2 = np.asarray(center2, dtype=np.float64)
+    return np.linalg.norm(c1 - c2) < tolerance
+
+
+def _get_plane_normal(surface: Surface) -> NDArray[np.float64] | None:
+    """Extract normal from a plane surface, or None if not a plane."""
+    # Check for PlaneSurface or BoundedPlaneSurface by looking for normal attribute
+    if hasattr(surface, "normal"):
+        return np.asarray(surface.normal, dtype=np.float64)
+    return None
+
+
+def _get_sphere_center(surface: Surface) -> NDArray[np.float64] | None:
+    """Extract center from a sphere surface, or None if not a sphere."""
+    if hasattr(surface, "center"):
+        return np.asarray(surface.center, dtype=np.float64)
+    return None
+
+
+def analyze_surface_pair(
+    surface1: Surface,
+    surface2: Surface,
+) -> SurfaceAnalysisResult:
+    """
+    Analyze the geometric relationship between two surfaces.
+
+    Determines if surfaces are parallel, concentric, nested, or intersecting,
+    and checks whether material assignments are consistent.
+
+    Parameters
+    ----------
+    surface1 : Surface
+        First surface to analyze.
+    surface2 : Surface
+        Second surface to analyze.
+
+    Returns
+    -------
+    SurfaceAnalysisResult
+        Analysis result including relationship type and material consistency.
+
+    Notes
+    -----
+    For intersecting surfaces with different materials, the front/back model
+    cannot consistently assign materials to all regions. This function detects
+    such conflicts.
+    """
+    from ..surfaces import SurfaceRole
+
+    # Skip non-optical surfaces - they don't define materials
+    if surface1.role != SurfaceRole.OPTICAL or surface2.role != SurfaceRole.OPTICAL:
+        return SurfaceAnalysisResult(
+            relationship=SurfaceRelationship.DISJOINT,
+            details="Non-optical surfaces do not define material regions.",
+            materials_consistent=True,
+        )
+
+    # Check for plane-plane relationship
+    normal1 = _get_plane_normal(surface1)
+    normal2 = _get_plane_normal(surface2)
+
+    if normal1 is not None and normal2 is not None:
+        return _analyze_plane_pair(surface1, surface2, normal1, normal2)
+
+    # Check for sphere-sphere relationship
+    center1 = _get_sphere_center(surface1)
+    center2 = _get_sphere_center(surface2)
+
+    if center1 is not None and center2 is not None:
+        return _analyze_sphere_pair(surface1, surface2, center1, center2)
+
+    # Check for plane-sphere relationship
+    if normal1 is not None and center2 is not None:
+        return _analyze_plane_sphere(surface1, surface2)
+
+    if center1 is not None and normal2 is not None:
+        return _analyze_plane_sphere(surface2, surface1)
+
+    # Unknown surface types - assume potentially intersecting
+    # Check if materials are the same (consistent even if intersecting)
+    consistent = _check_material_consistency(surface1, surface2)
+    return SurfaceAnalysisResult(
+        relationship=SurfaceRelationship.INTERSECTING,
+        details=(
+            f"Cannot determine geometric relationship for surface types "
+            f"{type(surface1).__name__} and {type(surface2).__name__}. "
+            f"Assuming potentially intersecting."
+        ),
+        materials_consistent=consistent,
+    )
+
+
+def _analyze_plane_pair(
+    surface1: Surface,
+    surface2: Surface,
+    normal1: NDArray[np.float64],
+    normal2: NDArray[np.float64],
+) -> SurfaceAnalysisResult:
+    """Analyze relationship between two planes."""
+    if are_planes_parallel(normal1, normal2):
+        return SurfaceAnalysisResult(
+            relationship=SurfaceRelationship.PARALLEL,
+            details="Planes are parallel - no intersection.",
+            materials_consistent=True,
+        )
+
+    # Non-parallel planes always intersect
+    consistent = _check_material_consistency(surface1, surface2)
+    angle_rad = np.arccos(np.clip(np.abs(np.dot(normal1, normal2)), 0, 1))
+    angle_deg = np.degrees(angle_rad)
+
+    details = (
+        f"Planes intersect at {angle_deg:.1f}° creating 4 quadrants. "
+        f"Surface '{surface1.name}' has front={_material_name(surface1.material_front)}, "
+        f"back={_material_name(surface1.material_back)}. "
+        f"Surface '{surface2.name}' has front={_material_name(surface2.material_front)}, "
+        f"back={_material_name(surface2.material_back)}."
+    )
+
+    if not consistent:
+        details += (
+            " Materials conflict: each quadrant must satisfy constraints from "
+            "both surfaces, but the assigned materials are incompatible."
+        )
+
+    return SurfaceAnalysisResult(
+        relationship=SurfaceRelationship.INTERSECTING,
+        details=details,
+        materials_consistent=consistent,
+    )
+
+
+def _analyze_sphere_pair(
+    surface1: Surface,
+    surface2: Surface,
+    center1: NDArray[np.float64],
+    center2: NDArray[np.float64],
+) -> SurfaceAnalysisResult:
+    """Analyze relationship between two spheres."""
+    if are_spheres_concentric(center1, center2):
+        # Concentric spheres create nested regions (like onion layers)
+        return SurfaceAnalysisResult(
+            relationship=SurfaceRelationship.NESTED,
+            details="Spheres are concentric - creates nested regions.",
+            materials_consistent=True,
+        )
+
+    # Non-concentric spheres may or may not intersect depending on radii
+    # For simplicity, we check material consistency
+    consistent = _check_material_consistency(surface1, surface2)
+
+    return SurfaceAnalysisResult(
+        relationship=SurfaceRelationship.INTERSECTING,
+        details="Spheres have different centers - may intersect.",
+        materials_consistent=consistent,
+    )
+
+
+def _analyze_plane_sphere(
+    plane: Surface,
+    sphere: Surface,
+) -> SurfaceAnalysisResult:
+    """Analyze relationship between a plane and sphere."""
+    # A plane always intersects a sphere (unless the sphere is entirely on one side,
+    # but we can't easily determine that without bounds)
+    consistent = _check_material_consistency(plane, sphere)
+
+    return SurfaceAnalysisResult(
+        relationship=SurfaceRelationship.INTERSECTING,
+        details=(
+            f"Plane '{plane.name}' and sphere '{sphere.name}' may intersect. "
+            f"Material consistency check required."
+        ),
+        materials_consistent=consistent,
+    )
+
+
+def _check_material_consistency(
+    surface1: Surface,
+    surface2: Surface,
+) -> bool:
+    """
+    Check if two surfaces have consistent material assignments for intersection.
+
+    For intersecting surfaces, the front/back model is only consistent if
+    all materials are the same OR if the surfaces share materials in a
+    compatible way.
+
+    The simplest consistent case is when both surfaces use the same material
+    on both sides (e.g., both are "air" everywhere).
+    """
+    mat1_front = surface1.material_front
+    mat1_back = surface1.material_back
+    mat2_front = surface2.material_front
+    mat2_back = surface2.material_back
+
+    # If any material is None, we can't validate
+    if any(m is None for m in [mat1_front, mat1_back, mat2_front, mat2_back]):
+        return True
+
+    # Consistent if all four materials are the same
+    if mat1_front is mat1_back is mat2_front is mat2_back:
+        return True
+
+    # Consistent if each surface has the same material on both sides
+    # (even if different between surfaces - this means no refraction at that surface)
+    if mat1_front is mat1_back and mat2_front is mat2_back:
+        return True
+
+    # For intersecting surfaces with different front/back materials on both,
+    # we have a conflict: the 4 quadrants can't all be assigned consistently
+    #
+    # Quadrant analysis:
+    # Q1 (front₁ ∩ front₂): must be mat1_front AND mat2_front
+    # Q2 (back₁ ∩ front₂): must be mat1_back AND mat2_front
+    # Q3 (front₁ ∩ back₂): must be mat1_front AND mat2_back
+    # Q4 (back₁ ∩ back₂): must be mat1_back AND mat2_back
+    #
+    # This is only satisfiable if the materials form a compatible pattern
+
+    return False
+
+
+def _material_name(material) -> str:
+    """Get a display name for a material."""
+    if material is None:
+        return "None"
+    if hasattr(material, "name"):
+        return str(material.name)
+    return type(material).__name__

lsurf/geometry/validation.py

@@ -0,0 +1,91 @@
+# 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.
+
+"""
+Geometry Validation Exceptions
+
+Exception classes for geometry validation errors.
+"""
+
+
+class GeometryValidationError(Exception):
+    """Base exception for geometry validation errors."""
+
+    pass
+
+
+class IntersectingSurfacesError(GeometryValidationError):
+    """
+    Raised when non-parallel surfaces have inconsistent material assignments.
+
+    Two non-parallel surfaces divide space into 4 quadrants. With the simple
+    front/back material model, all 4 quadrants would need to have the same
+    material on each side of both surfaces, which is over-constrained when
+    the surfaces have different materials.
+
+    To resolve this error, either:
+    1. Use parallel surfaces that don't create conflicting regions
+    2. Assign the same material to both sides where conflicts occur
+    3. Use the cell-based API (add_surface_only + add_cell) for explicit
+       region-by-region material assignment
+
+    Attributes
+    ----------
+    surface1_name : str
+        Name of the first conflicting surface.
+    surface2_name : str
+        Name of the second conflicting surface.
+    details : str
+        Detailed explanation of the conflict.
+    """
+
+    def __init__(
+        self,
+        surface1_name: str,
+        surface2_name: str,
+        details: str = "",
+    ):
+        self.surface1_name = surface1_name
+        self.surface2_name = surface2_name
+        self.details = details
+
+        message = (
+            f"Surfaces '{surface1_name}' and '{surface2_name}' intersect "
+            f"with inconsistent material assignments.\n"
+            f"{details}\n\n"
+            f"To resolve this, either:\n"
+            f"  1. Use parallel surfaces\n"
+            f"  2. Assign the same material to conflicting sides\n"
+            f"  3. Use the cell-based API: add_surface_only() + add_cell()"
+        )
+        super().__init__(message)