lsurf 1.0.0__py3-none-any.whl

lsurf/cli/config_schema.py

@@ -0,0 +1,318 @@
+# 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.
+
+"""Pydantic models for L-SURF configuration file validation.
+
+This module defines the schema for YAML/TOML configuration files used
+to specify ray tracing simulations.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# Import SimulationConfig from the library - used directly in CLI config
+from ..simulation import SimulationConfig
+
+
+# =============================================================================
+# Media/Material Configuration
+# =============================================================================
+
+
+class MediaConfig(BaseModel):
+    """Configuration for a material/medium."""
+
+    type: Literal[
+        "vacuum",
+        "air",
+        "water",
+        "glass",
+        "homogeneous",
+        "exponential_atmosphere",
+        "duct_atmosphere",
+        "sellmeier",
+        "cauchy",
+    ]
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+# =============================================================================
+# Source Configuration
+# =============================================================================
+
+
+class SourceConfig(BaseModel):
+    """Configuration for a ray source."""
+
+    type: Literal[
+        "point",
+        "collimated_beam",
+        "diverging_beam",
+        "gaussian_beam",
+        "parallel_from_positions",
+        "custom",
+    ]
+    params: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("params")
+    @classmethod
+    def validate_source_params(cls, v: dict[str, Any], info) -> dict[str, Any]:
+        """Validate source parameters based on type."""
+        source_type = info.data.get("type")
+        required_params: dict[str, list[str]] = {
+            "point": ["position", "num_rays", "wavelength"],
+            "collimated_beam": [
+                "center",
+                "direction",
+                "beam_radius",
+                "num_rays",
+                "wavelength",
+            ],
+            "diverging_beam": [
+                "origin",
+                "mean_direction",
+                "divergence_angle",
+                "num_rays",
+                "wavelength",
+            ],
+            "gaussian_beam": [
+                "waist_position",
+                "direction",
+                "waist_radius",
+                "num_rays",
+                "wavelength",
+            ],
+            "parallel_from_positions": ["positions", "direction", "wavelength"],
+            "custom": ["positions", "directions", "wavelengths", "intensities"],
+        }
+        if source_type and source_type in required_params:
+            missing = [p for p in required_params[source_type] if p not in v]
+            if missing:
+                raise ValueError(
+                    f"Missing required parameters for {source_type}: {missing}"
+                )
+        return v
+
+
+# =============================================================================
+# Surface Configuration
+# =============================================================================
+
+
+class SurfaceConfig(BaseModel):
+    """Configuration for a surface."""
+
+    name: str
+    type: Literal[
+        "plane",
+        "bounded_plane",
+        "annular_plane",
+        "sphere",
+        "gerstner_wave",
+        "curved_wave",
+        "multi_curved_wave",
+    ]
+    role: Literal["optical", "detector", "absorber"]
+    front_medium: str | None = None
+    back_medium: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+# =============================================================================
+# Detector Configuration
+# =============================================================================
+
+
+class DetectorConfig(BaseModel):
+    """Configuration for a detector."""
+
+    name: str
+    type: Literal[
+        "spherical",
+        "planar",
+        "directional",
+        "recording_sphere",
+        "local_recording_sphere",
+    ]
+    params: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("params")
+    @classmethod
+    def validate_detector_params(cls, v: dict[str, Any], info) -> dict[str, Any]:
+        """Validate detector parameters based on type."""
+        detector_type = info.data.get("type")
+
+        # recording_sphere has flexible parameters:
+        # - Either 'altitude' alone (uses defaults for earth_center/earth_radius)
+        # - Or 'center' + 'radius' (radius can be altitude or total sphere radius)
+        # - Or 'altitude' + 'earth_center' + optional 'earth_radius'
+        if detector_type == "recording_sphere":
+            has_altitude = "altitude" in v
+            has_center_radius = "center" in v and "radius" in v
+            has_radius_only = "radius" in v and "center" not in v
+            if not (has_altitude or has_center_radius or has_radius_only):
+                raise ValueError(
+                    "recording_sphere requires either 'altitude', 'radius', "
+                    "or 'center' + 'radius'"
+                )
+            return v
+
+        required_params: dict[str, list[str]] = {
+            "spherical": ["center", "radius"],
+            "planar": ["center", "normal", "width", "height"],
+            "directional": ["position", "direction", "acceptance_angle", "radius"],
+            "local_recording_sphere": ["radius"],
+        }
+        if detector_type and detector_type in required_params:
+            missing = [p for p in required_params[detector_type] if p not in v]
+            if missing:
+                raise ValueError(
+                    f"Missing required parameters for {detector_type}: {missing}"
+                )
+        return v
+
+
+# =============================================================================
+# Output Configuration
+# =============================================================================
+
+
+class OutputConfig(BaseModel):
+    """Output configuration."""
+
+    directory: str = "./results"
+    format: Literal["hdf5", "numpy", "csv"] = "hdf5"
+    save_ray_paths: bool = False
+    save_statistics: bool = True
+    prefix: str = "simulation"
+
+
+# =============================================================================
+# Root Configuration
+# =============================================================================
+
+
+class LSURFConfig(BaseModel):
+    """Root configuration model for L-SURF simulations.
+
+    Example YAML:
+        version: "1.0"
+        media:
+          atmosphere:
+            type: exponential_atmosphere
+            params:
+              scale_height: 8500
+          ocean:
+            type: water
+        background: atmosphere
+        source:
+          type: collimated_beam
+          params:
+            center: [0, 0, 100000]
+            direction: [0, 0, -1]
+            beam_radius: 0.005
+            num_rays: 100000
+            wavelength: 532e-9
+        surfaces:
+          - name: ocean_surface
+            type: curved_wave
+            role: optical
+            front_medium: atmosphere
+            back_medium: ocean
+            params:
+              center: [0, 0, -6.371e6]
+              radius: 6.371e6
+        detectors:
+          - name: sky_detector
+            type: recording_sphere
+            params:
+              center: [0, 0, -6.371e6]
+              radius: 6.404e6
+        simulation:
+          step_size: 100.0
+          max_bounces: 1
+        output:
+          directory: ./results
+          format: hdf5
+    """
+
+    version: str = "1.0"
+    media: dict[str, MediaConfig] = Field(default_factory=dict)
+    background: str | None = None
+    source: SourceConfig
+    surfaces: list[SurfaceConfig] = Field(default_factory=list)
+    detectors: list[DetectorConfig] = Field(default_factory=list)
+    simulation: SimulationConfig = Field(default_factory=SimulationConfig)
+    output: OutputConfig = Field(default_factory=OutputConfig)
+
+    @field_validator("simulation", mode="before")
+    @classmethod
+    def parse_simulation_config(cls, v):
+        """Convert dict to SimulationConfig if needed."""
+        if isinstance(v, dict):
+            return SimulationConfig(**v)
+        return v
+
+    @model_validator(mode="after")
+    def validate_media_references(self) -> "LSURFConfig":
+        """Validate that all media references exist."""
+        defined_media = set(self.media.keys())
+
+        # Check background reference
+        if self.background and self.background not in defined_media:
+            raise ValueError(
+                f"Background medium '{self.background}' not defined in media section"
+            )
+
+        # Check surface media references
+        for surface in self.surfaces:
+            if surface.front_medium and surface.front_medium not in defined_media:
+                raise ValueError(
+                    f"Surface '{surface.name}' references undefined medium "
+                    f"'{surface.front_medium}'"
+                )
+            if surface.back_medium and surface.back_medium not in defined_media:
+                raise ValueError(
+                    f"Surface '{surface.name}' references undefined medium "
+                    f"'{surface.back_medium}'"
+                )
+
+        return self
+
+    @model_validator(mode="after")
+    def validate_has_geometry(self) -> "LSURFConfig":
+        """Validate that at least one surface or detector is defined."""
+        if not self.surfaces and not self.detectors:
+            raise ValueError("At least one surface or detector must be defined")
+        return self

lsurf/cli/gui_cmd.py

@@ -0,0 +1,76 @@
+# 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.
+
+"""GUI command for L-SURF CLI.
+
+Launches the interactive 3D visualization GUI.
+"""
+
+from pathlib import Path
+
+import click
+
+
+@click.command()
+@click.argument("config_file", required=False, type=click.Path(exists=True))
+@click.pass_context
+def gui(ctx: click.Context, config_file: str | None) -> None:
+    """Launch the interactive 3D visualization GUI.
+
+    Optionally load a configuration file (YAML or TOML) on startup.
+
+    \b
+    Examples:
+        # Launch empty GUI
+        lsurf gui
+
+        # Launch with a configuration file
+        lsurf gui simulation.yaml
+        lsurf gui ocean_config.toml
+    """
+    try:
+        from lsurf.gui import launch_gui
+    except ImportError as e:
+        raise click.ClickException(
+            f"GUI dependencies not installed. Install with: pip install 'lsurf[gui]'\n"
+            f"Error: {e}"
+        ) from e
+
+    config_path = Path(config_file) if config_file else None
+
+    if ctx.obj.get("verbose"):
+        click.echo("Launching L-SURF GUI...")
+        if config_path:
+            click.echo(f"Loading configuration: {config_path}")
+
+    launch_gui(config_path)