lsurf 1.0.0__py3-none-any.whl

lsurf/cli/__init__.py

@@ -0,0 +1,48 @@
+# 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.
+
+"""L-SURF Command Line Interface.
+
+This module provides a Click-based CLI for building geometry configurations
+and running ray tracing simulations.
+
+Commands:
+    lsurf build - Interactive/CLI geometry builder that generates config files
+    lsurf run - Execute simulations from config files
+"""
+
+__version__ = "1.0.0"
+
+from .main import cli
+
+__all__ = ["cli", "__version__"]

lsurf/cli/build.py

@@ -0,0 +1,398 @@
+# 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.
+
+"""L-SURF CLI build command.
+
+This module implements the `lsurf build` command for creating geometry
+configuration files interactively or from templates.
+"""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+try:
+    import tomli_w
+except ImportError:
+    tomli_w = None
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+from .config_schema import (
+    LSURFConfig,
+)
+from .interactive import (
+    get_template,
+    get_template_description,
+    get_template_names,
+    run_interactive_wizard,
+)
+
+
+def config_to_dict(config: LSURFConfig) -> dict[str, Any]:
+    """Convert a Pydantic config to a serializable dict."""
+    return config.model_dump(exclude_none=True, exclude_defaults=False)
+
+
+def write_yaml(config: dict[str, Any], path: Path) -> None:
+    """Write configuration to a YAML file."""
+    if yaml is None:
+        raise click.ClickException(
+            "PyYAML is required for YAML output. Install with: pip install pyyaml"
+        )
+
+    with open(path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+
+def write_toml(config: dict[str, Any], path: Path) -> None:
+    """Write configuration to a TOML file."""
+    if tomli_w is None:
+        raise click.ClickException(
+            "tomli-w is required for TOML output. Install with: pip install tomli-w"
+        )
+
+    with open(path, "wb") as f:
+        tomli_w.dump(config, f)
+
+
+@click.command()
+@click.option(
+    "-o",
+    "--output",
+    "output_path",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    required=True,
+    help="Output config file path (.yaml or .toml)",
+)
+@click.option(
+    "--template",
+    "template_name",
+    type=click.Choice(get_template_names()),
+    help="Use a pre-built template configuration",
+)
+@click.option(
+    "--non-interactive",
+    is_flag=True,
+    help="Disable interactive prompts (requires --template)",
+)
+@click.option(
+    "--source",
+    "source_type",
+    type=click.Choice(["collimated", "point", "diverging", "gaussian"]),
+    help="Source type (non-interactive mode)",
+)
+@click.option(
+    "--num-rays",
+    type=int,
+    default=10000,
+    help="Number of rays (non-interactive mode)",
+)
+@click.option(
+    "--surface",
+    "surface_type",
+    type=click.Choice(["plane", "sphere", "ocean"]),
+    help="Surface type (non-interactive mode)",
+)
+@click.option(
+    "--detector",
+    "detector_type",
+    type=click.Choice(["sphere", "plane", "recording_sphere"]),
+    help="Detector type (non-interactive mode)",
+)
+@click.option(
+    "--list-templates",
+    is_flag=True,
+    help="List available templates and exit",
+)
+@click.pass_context
+def build(
+    ctx: click.Context,
+    output_path: Path,
+    template_name: str | None,
+    non_interactive: bool,
+    source_type: str | None,
+    num_rays: int,
+    surface_type: str | None,
+    detector_type: str | None,
+    list_templates: bool,
+) -> None:
+    """Build a geometry configuration file.
+
+    \b
+    Creates a configuration file for L-SURF simulations. Can run
+    interactively (default), from a template, or with CLI flags.
+
+    \b
+    Examples:
+        # Interactive mode
+        lsurf build -o simulation.yaml
+
+        # From template
+        lsurf build --template ocean -o ocean_sim.yaml
+
+        # Non-interactive with template
+        lsurf build --non-interactive --template glass -o glass.toml
+
+        # List available templates
+        lsurf build --list-templates -o dummy.yaml
+    """
+    verbose = ctx.obj.get("verbose", False)
+
+    # Handle --list-templates
+    if list_templates:
+        click.echo("\nAvailable templates:\n")
+        for name in get_template_names():
+            desc = get_template_description(name)
+            click.echo(f"  {name:15} - {desc}")
+        click.echo()
+        return
+
+    # Determine output format from extension
+    suffix = output_path.suffix.lower()
+    if suffix not in (".yaml", ".yml", ".toml"):
+        raise click.ClickException(
+            f"Output file must have .yaml, .yml, or .toml extension, got: {suffix}"
+        )
+
+    is_yaml = suffix in (".yaml", ".yml")
+
+    # Build configuration
+    config_dict: dict[str, Any]
+
+    if template_name:
+        # Use template
+        config_dict = get_template(template_name)
+        if config_dict is None:
+            raise click.ClickException(f"Unknown template: {template_name}")
+
+        # Apply any overrides from CLI flags
+        if num_rays != 10000:
+            config_dict["source"]["params"]["num_rays"] = num_rays
+
+        if verbose:
+            click.echo(f"Using template: {template_name}")
+            click.echo(f"Description: {get_template_description(template_name)}")
+
+    elif non_interactive:
+        # Non-interactive without template requires source/surface/detector
+        if not source_type:
+            raise click.ClickException(
+                "--non-interactive requires --template or explicit configuration flags"
+            )
+
+        config_dict = _build_from_flags(
+            source_type=source_type,
+            num_rays=num_rays,
+            surface_type=surface_type,
+            detector_type=detector_type,
+        )
+
+    else:
+        # Interactive mode
+        try:
+            config = run_interactive_wizard()
+            config_dict = config_to_dict(config)
+        except KeyboardInterrupt:
+            click.echo("\nConfiguration cancelled.")
+            sys.exit(1)
+
+    # Validate configuration
+    try:
+        LSURFConfig(**config_dict)
+    except Exception as e:
+        raise click.ClickException(f"Invalid configuration: {e}")
+
+    # Write output
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if is_yaml:
+        write_yaml(config_dict, output_path)
+    else:
+        write_toml(config_dict, output_path)
+
+    click.echo(f"\nConfiguration written to: {output_path}")
+
+    if verbose:
+        click.echo("\nConfiguration summary:")
+        click.echo(f"  Media: {list(config_dict.get('media', {}).keys())}")
+        click.echo(f"  Source: {config_dict.get('source', {}).get('type')}")
+        click.echo(f"  Surfaces: {len(config_dict.get('surfaces', []))}")
+        click.echo(f"  Detectors: {len(config_dict.get('detectors', []))}")
+
+
+def _build_from_flags(
+    source_type: str | None,
+    num_rays: int,
+    surface_type: str | None,
+    detector_type: str | None,
+) -> dict[str, Any]:
+    """Build a minimal configuration from CLI flags."""
+    config: dict[str, Any] = {
+        "version": "1.0",
+        "media": {
+            "air": {"type": "air", "params": {}},
+        },
+        "background": "air",
+        "surfaces": [],
+        "detectors": [],
+        "simulation": {"step_size": 100.0, "max_bounces": 5, "use_gpu": True},
+        "output": {"directory": "./results", "format": "hdf5"},
+    }
+
+    # Source configuration
+    source_configs = {
+        "collimated": {
+            "type": "collimated_beam",
+            "params": {
+                "center": [0.0, 0.0, 0.0],
+                "direction": [0.0, 0.0, 1.0],
+                "beam_radius": 0.01,
+                "num_rays": num_rays,
+                "wavelength": 532e-9,
+            },
+        },
+        "point": {
+            "type": "point",
+            "params": {
+                "position": [0.0, 0.0, 0.0],
+                "num_rays": num_rays,
+                "wavelength": 532e-9,
+            },
+        },
+        "diverging": {
+            "type": "diverging_beam",
+            "params": {
+                "origin": [0.0, 0.0, 0.0],
+                "mean_direction": [0.0, 0.0, 1.0],
+                "divergence_angle": 0.1,
+                "num_rays": num_rays,
+                "wavelength": 532e-9,
+            },
+        },
+        "gaussian": {
+            "type": "gaussian_beam",
+            "params": {
+                "waist_position": [0.0, 0.0, 0.0],
+                "direction": [0.0, 0.0, 1.0],
+                "waist_radius": 0.001,
+                "num_rays": num_rays,
+                "wavelength": 532e-9,
+            },
+        },
+    }
+
+    config["source"] = source_configs.get(source_type, source_configs["collimated"])
+
+    # Surface configuration
+    if surface_type:
+        surface_configs = {
+            "plane": {
+                "name": "plane_surface",
+                "type": "plane",
+                "role": "optical",
+                "front_medium": "air",
+                "back_medium": "air",
+                "params": {"point": [0.0, 0.0, 1.0], "normal": [0.0, 0.0, -1.0]},
+            },
+            "sphere": {
+                "name": "sphere_surface",
+                "type": "sphere",
+                "role": "optical",
+                "front_medium": "air",
+                "back_medium": "air",
+                "params": {"center": [0.0, 0.0, 1.0], "radius": 0.5},
+            },
+            "ocean": {
+                "name": "ocean_surface",
+                "type": "curved_wave",
+                "role": "optical",
+                "front_medium": "air",
+                "back_medium": "air",
+                "params": {
+                    "amplitude": 0.5,
+                    "wavelength": 100.0,
+                    "direction": [1.0, 0.0],
+                    "earth_center": [0.0, 0.0, -6.371e6],
+                    "earth_radius": 6.371e6,
+                },
+            },
+        }
+        config["surfaces"].append(surface_configs[surface_type])
+
+    # Detector configuration
+    if detector_type:
+        detector_configs = {
+            "sphere": {
+                "name": "sphere_detector",
+                "type": "spherical",
+                "params": {"center": [0.0, 0.0, 2.0], "radius": 0.1},
+            },
+            "plane": {
+                "name": "plane_detector",
+                "type": "planar",
+                "params": {
+                    "center": [0.0, 0.0, 2.0],
+                    "normal": [0.0, 0.0, -1.0],
+                    "width": 0.2,
+                    "height": 0.2,
+                },
+            },
+            "recording_sphere": {
+                "name": "recording_sphere_detector",
+                "type": "recording_sphere",
+                "params": {"center": [0.0, 0.0, -6.371e6], "radius": 6.371e6 + 35000},
+            },
+        }
+        config["detectors"].append(detector_configs[detector_type])
+    else:
+        # Add a default detector if none specified
+        config["detectors"].append(
+            {
+                "name": "default_detector",
+                "type": "planar",
+                "params": {
+                    "center": [0.0, 0.0, 2.0],
+                    "normal": [0.0, 0.0, -1.0],
+                    "width": 0.5,
+                    "height": 0.5,
+                },
+            }
+        )
+
+    return config