lsurf 1.0.0__py3-none-any.whl

lsurf/cli/run.py

@@ -0,0 +1,806 @@
+# 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 run command.
+
+This module implements the `lsurf run` command for executing simulations
+from configuration files.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+try:
+    import tomli
+except ImportError:
+    tomli = None
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+try:
+    from rich.console import Console
+    from rich.progress import (
+        Progress,
+        SpinnerColumn,
+        TextColumn,
+        BarColumn,
+        TaskProgressColumn,
+    )
+    from rich.table import Table
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+from .config_schema import LSURFConfig
+
+
+def read_config(path: Path) -> dict[str, Any]:
+    """Read a configuration file (YAML or TOML)."""
+    suffix = path.suffix.lower()
+
+    if suffix in (".yaml", ".yml"):
+        if yaml is None:
+            raise click.ClickException(
+                "PyYAML is required for YAML files. Install with: pip install pyyaml"
+            )
+        with open(path) as f:
+            return yaml.safe_load(f)
+
+    elif suffix == ".toml":
+        if tomli is None:
+            raise click.ClickException(
+                "tomli is required for TOML files. Install with: pip install tomli"
+            )
+        with open(path, "rb") as f:
+            return tomli.load(f)
+
+    else:
+        raise click.ClickException(
+            f"Unsupported config file format: {suffix}. Use .yaml, .yml, or .toml"
+        )
+
+
+def validate_config(config_dict: dict[str, Any]) -> LSURFConfig:
+    """Validate and parse a configuration dictionary."""
+    try:
+        return LSURFConfig(**config_dict)
+    except Exception as e:
+        raise click.ClickException(f"Configuration validation failed: {e}")
+
+
+def build_simulation(config: LSURFConfig, verbose: bool = False):
+    """Build simulation objects from configuration.
+
+    Returns:
+        Tuple of (geometry, rays, sim_config)
+    """
+    import lsurf as sr
+    from ..geometry import GeometryBuilder
+
+    console = Console() if RICH_AVAILABLE else None
+
+    if verbose and console:
+        console.print("[cyan]Building simulation from configuration...[/cyan]")
+
+    # Build media
+    media_objects: dict[str, Any] = {}
+    for name, media_cfg in config.media.items():
+        media_objects[name] = _create_medium(media_cfg.type, media_cfg.params)
+        if verbose and console:
+            console.print(f"  Created medium: [green]{name}[/green] ({media_cfg.type})")
+
+    # Build geometry
+    builder = GeometryBuilder()
+
+    # Register media
+    for name, medium in media_objects.items():
+        builder.register_medium(name, medium)
+
+    # Set background - default to vacuum if not specified
+    if config.background:
+        builder.set_background(config.background)
+    else:
+        # No background specified - use vacuum
+        import lsurf as sr
+
+        builder.register_medium("_vacuum", sr.VACUUM)
+        builder.set_background("_vacuum")
+        if verbose and console:
+            console.print("  [yellow]No background specified, using vacuum[/yellow]")
+
+    # Add surfaces
+    for surface_cfg in config.surfaces:
+        surface = _create_surface(surface_cfg, media_objects)
+        if surface_cfg.front_medium and surface_cfg.back_medium:
+            builder.add_surface(
+                surface,
+                front=surface_cfg.front_medium,
+                back=surface_cfg.back_medium,
+            )
+        else:
+            builder.add_detector(surface)
+        if verbose and console:
+            console.print(
+                f"  Added surface: [green]{surface_cfg.name}[/green] ({surface_cfg.type})"
+            )
+
+    # Add detectors
+    for detector_cfg in config.detectors:
+        detector_surface = _create_detector_surface(detector_cfg)
+        builder.add_detector(detector_surface)
+        if verbose and console:
+            console.print(
+                f"  Added detector: [green]{detector_cfg.name}[/green] ({detector_cfg.type})"
+            )
+
+    geometry = builder.build()
+
+    # Build source and generate rays
+    source = _create_source(config.source.type, config.source.params)
+    rays = source.generate()
+    if verbose and console:
+        console.print(
+            f"  Generated [green]{rays.num_rays}[/green] rays from {config.source.type}"
+        )
+
+    # config.simulation is already a SimulationConfig instance
+    return geometry, rays, config.simulation
+
+
+def _create_medium(media_type: str, params: dict[str, Any]):
+    """Create a medium object from type and parameters."""
+    import lsurf as sr
+    from ..materials.implementations.duct_atmosphere import DuctAtmosphere
+
+    if media_type == "vacuum":
+        return sr.VACUUM
+    elif media_type == "air":
+        return sr.AIR_STP
+    elif media_type == "water":
+        return sr.WATER
+    elif media_type == "glass":
+        n = params.get("refractive_index", 1.5168)
+        return sr.HomogeneousMaterial(name="glass", refractive_index=n)
+    elif media_type == "homogeneous":
+        return sr.HomogeneousMaterial(
+            name=params.get("name", "custom"),
+            refractive_index=params.get("refractive_index", 1.5),
+            absorption_coef=params.get("absorption_coef", 0.0),
+            scattering_coef=params.get("scattering_coef", 0.0),
+            anisotropy=params.get("anisotropy", 0.0),
+        )
+    elif media_type == "exponential_atmosphere":
+        return sr.ExponentialAtmosphere(
+            name=params.get("name", "Exponential Atmosphere"),
+            n_sea_level=params.get("n_sea_level", 1.000293),
+            scale_height=params.get("scale_height", 8500.0),
+            earth_radius=params.get("earth_radius", 6.371e6),
+            earth_center=tuple(params.get("earth_center", (0.0, 0.0, -6.371e6))),
+            absorption_coef=params.get("absorption_coef", 0.0),
+        )
+    elif media_type == "duct_atmosphere":
+        return DuctAtmosphere(**params)
+    else:
+        raise ValueError(f"Unknown medium type: {media_type}")
+
+
+def _create_source(source_type: str, params: dict[str, Any]):
+    """Create a source object from type and parameters."""
+    import lsurf as sr
+
+    # Helper to convert wavelength (may be string like "532e-9" from YAML)
+    def get_wavelength(p):
+        wl = p["wavelength"]
+        return float(wl) if isinstance(wl, str) else wl
+
+    if source_type == "point":
+        return sr.PointSource(
+            position=tuple(params["position"]),
+            num_rays=int(params["num_rays"]),
+            wavelength=get_wavelength(params),
+            power=float(params.get("power", 1.0)),
+        )
+    elif source_type == "collimated_beam":
+        return sr.CollimatedBeam(
+            center=tuple(params["center"]),
+            direction=tuple(params["direction"]),
+            radius=float(params.get("beam_radius", params.get("radius", 0.01))),
+            num_rays=int(params["num_rays"]),
+            wavelength=get_wavelength(params),
+            power=float(params.get("power", 1.0)),
+            profile=params.get("profile", "uniform"),
+        )
+    elif source_type == "diverging_beam":
+        return sr.DivergingBeam(
+            origin=tuple(params["origin"]),
+            mean_direction=tuple(params["mean_direction"]),
+            divergence_angle=float(params["divergence_angle"]),
+            num_rays=int(params["num_rays"]),
+            wavelength=get_wavelength(params),
+            power=float(params.get("power", 1.0)),
+        )
+    elif source_type == "gaussian_beam":
+        return sr.GaussianBeam(
+            waist_position=tuple(params["waist_position"]),
+            direction=tuple(params["direction"]),
+            waist_radius=float(params["waist_radius"]),
+            num_rays=int(params["num_rays"]),
+            wavelength=get_wavelength(params),
+            power=float(params.get("power", 1.0)),
+        )
+    elif source_type == "parallel_from_positions":
+        import numpy as np
+
+        return sr.ParallelBeamFromPositions(
+            positions=np.array(params["positions"]),
+            direction=tuple(params["direction"]),
+            wavelength=params["wavelength"],
+            power=params.get("power", 1.0),
+        )
+    elif source_type == "custom":
+        import numpy as np
+
+        return sr.CustomRaySource(
+            positions=np.array(params["positions"]),
+            directions=np.array(params["directions"]),
+            wavelengths=np.array(params["wavelengths"]),
+            intensities=np.array(params["intensities"]),
+        )
+    else:
+        raise ValueError(f"Unknown source type: {source_type}")
+
+
+def _create_surface(surface_cfg, media_objects: dict[str, Any]):
+    """Create a surface object from configuration."""
+    import lsurf as sr
+    from ..surfaces import (
+        SurfaceRole,
+        BoundedPlaneSurface,
+        AnnularPlaneSurface,
+        GPUGerstnerWaveSurface,
+        GPUCurvedWaveSurface,
+        GPUMultiCurvedWaveSurface,
+    )
+
+    params = surface_cfg.params
+
+    # Map role string to enum
+    role_map = {
+        "optical": SurfaceRole.OPTICAL,
+        "detector": SurfaceRole.DETECTOR,
+        "absorber": SurfaceRole.ABSORBER,
+    }
+    role = role_map.get(surface_cfg.role, SurfaceRole.OPTICAL)
+
+    surface_type = surface_cfg.type
+
+    if surface_type == "plane":
+        return sr.PlaneSurface(
+            point=tuple(params["point"]),
+            normal=tuple(params["normal"]),
+            role=role,
+            name=surface_cfg.name,
+        )
+    elif surface_type == "bounded_plane":
+        return BoundedPlaneSurface(
+            point=tuple(params["point"]),
+            normal=tuple(params["normal"]),
+            width=params["width"],
+            height=params["height"],
+            role=role,
+            name=surface_cfg.name,
+        )
+    elif surface_type == "annular_plane":
+        return AnnularPlaneSurface(
+            point=tuple(params["point"]),
+            normal=tuple(params["normal"]),
+            inner_radius=params["inner_radius"],
+            outer_radius=params["outer_radius"],
+            role=role,
+            name=surface_cfg.name,
+        )
+    elif surface_type == "sphere":
+        return sr.SphereSurface(
+            center=tuple(params["center"]),
+            radius=params["radius"],
+            role=role,
+            name=surface_cfg.name,
+        )
+    elif surface_type == "gerstner_wave":
+        return GPUGerstnerWaveSurface(
+            amplitude=params["amplitude"],
+            wavelength=params["wavelength"],
+            direction=tuple(params["direction"]),
+            reference_z=params.get("reference_z", 0.0),
+            role=role,
+            name=surface_cfg.name,
+            phase=params.get("phase", 0.0),
+            time=params.get("time", 0.0),
+        )
+    elif surface_type == "curved_wave":
+        return GPUCurvedWaveSurface(
+            amplitude=params["amplitude"],
+            wavelength=params["wavelength"],
+            direction=tuple(params["direction"]),
+            earth_center=tuple(params.get("earth_center", (0.0, 0.0, -6.371e6))),
+            earth_radius=params.get("earth_radius", 6.371e6),
+            role=role,
+            name=surface_cfg.name,
+            time=params.get("time", 0.0),
+        )
+    elif surface_type == "multi_curved_wave":
+        from ..surfaces import GerstnerWaveParams
+
+        # Convert wave_params from dicts to GerstnerWaveParams objects
+        wave_params = []
+        for wp in params["wave_params"]:
+            if isinstance(wp, dict):
+                wave_params.append(
+                    GerstnerWaveParams(
+                        amplitude=wp["amplitude"],
+                        wavelength=wp["wavelength"],
+                        direction=tuple(wp["direction"]),
+                        phase=wp.get("phase", 0.0),
+                        steepness=wp.get("steepness", 0.5),
+                    )
+                )
+            else:
+                wave_params.append(wp)
+
+        return GPUMultiCurvedWaveSurface(
+            wave_params=wave_params,
+            earth_center=tuple(params.get("earth_center", (0.0, 0.0, -6.371e6))),
+            earth_radius=params.get("earth_radius", 6.371e6),
+            time=params.get("time", 0.0),
+            role=role,
+            name=surface_cfg.name,
+        )
+    else:
+        raise ValueError(f"Unknown surface type: {surface_type}")
+
+
+def _create_detector_surface(detector_cfg):
+    """Create a detector surface from configuration."""
+    import lsurf as sr
+    from ..surfaces import SurfaceRole, BoundedPlaneSurface
+
+    params = detector_cfg.params
+    detector_type = detector_cfg.type
+
+    if detector_type == "spherical":
+        # Small spherical detector - use SphereSurface with DETECTOR role
+        return sr.SphereSurface(
+            center=tuple(params["center"]),
+            radius=params["radius"],
+            role=SurfaceRole.DETECTOR,
+            name=detector_cfg.name,
+        )
+    elif detector_type == "planar":
+        # Planar detector - use BoundedPlaneSurface with DETECTOR role
+        return BoundedPlaneSurface(
+            point=tuple(params["center"]),
+            normal=tuple(params["normal"]),
+            width=params["width"],
+            height=params["height"],
+            role=SurfaceRole.DETECTOR,
+            name=detector_cfg.name,
+        )
+    elif detector_type == "directional":
+        # Directional detector - approximate with bounded plane
+        return BoundedPlaneSurface(
+            point=tuple(params["position"]),
+            normal=tuple(params["direction"]),
+            width=params["radius"] * 2,
+            height=params["radius"] * 2,
+            role=SurfaceRole.DETECTOR,
+            name=detector_cfg.name,
+        )
+    elif detector_type == "recording_sphere":
+        # RecordingSphereSurface uses altitude, earth_center, earth_radius
+        # Config can specify either:
+        #   - altitude directly
+        #   - center + radius (where radius is either total sphere radius or altitude)
+        earth_radius = float(params.get("earth_radius", 6.371e6))
+        earth_center = tuple(
+            params.get("earth_center", params.get("center", (0.0, 0.0, -6.371e6)))
+        )
+
+        if "altitude" in params:
+            # Altitude specified directly
+            altitude = float(params["altitude"])
+        elif "radius" in params:
+            radius = float(params["radius"])
+            # Heuristic: if radius > earth_radius, it's the total sphere radius
+            # Otherwise, radius IS the altitude
+            if radius > earth_radius:
+                altitude = radius - earth_radius
+            else:
+                altitude = radius
+        else:
+            altitude = 33000.0  # Default 33km
+
+        return sr.RecordingSphereSurface(
+            altitude=altitude,
+            earth_center=earth_center,
+            earth_radius=earth_radius,
+            name=detector_cfg.name,
+        )
+    elif detector_type == "local_recording_sphere":
+        return sr.LocalRecordingSphereSurface(
+            radius=params["radius"],
+            center=tuple(params.get("center", (0.0, 0.0, 0.0))),
+            name=detector_cfg.name,
+        )
+    else:
+        raise ValueError(f"Unknown detector type: {detector_type}")
+
+
+def run_simulation(
+    geometry, rays, sim_config, progress: bool = False, verbose: bool = False
+):
+    """Run the simulation and return results."""
+    from ..simulation import Simulation
+
+    console = Console() if RICH_AVAILABLE else None
+
+    sim = Simulation(geometry, sim_config)
+
+    if progress and RICH_AVAILABLE:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            console=console,
+        ) as progress_bar:
+            task = progress_bar.add_task("[cyan]Running simulation...", total=None)
+            result = sim.run(rays)
+            progress_bar.update(task, completed=True)
+    else:
+        if verbose:
+            click.echo("Running simulation...")
+        result = sim.run(rays)
+
+    return result
+
+
+def save_results(result, config: LSURFConfig, verbose: bool = False):
+    """Save simulation results to files."""
+    import numpy as np
+    from pathlib import Path
+
+    output_cfg = config.output
+    output_dir = Path(output_cfg.directory)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    prefix = output_cfg.prefix
+    fmt = output_cfg.format
+
+    console = Console() if RICH_AVAILABLE else None
+
+    if verbose and console:
+        console.print(f"[cyan]Saving results to {output_dir}...[/cyan]")
+
+    # Save statistics
+    if output_cfg.save_statistics:
+        stats = result.statistics
+        stats_data = {
+            "total_rays_initial": int(stats.total_rays_initial),
+            "total_rays_created": int(stats.total_rays_created),
+            "rays_detected": int(stats.rays_detected),
+            "rays_absorbed": int(stats.rays_absorbed),
+            "rays_terminated_bounds": int(stats.rays_terminated_bounds),
+            "rays_terminated_intensity": int(stats.rays_terminated_intensity),
+            "rays_terminated_max_bounces": int(stats.rays_terminated_max_bounces),
+            "bounces_completed": int(stats.bounces_completed),
+        }
+
+        if fmt == "hdf5":
+            try:
+                import h5py
+
+                with h5py.File(output_dir / f"{prefix}_statistics.h5", "w") as f:
+                    for key, value in stats_data.items():
+                        f.create_dataset(key, data=value)
+            except ImportError:
+                # Fallback to numpy
+                np.savez(output_dir / f"{prefix}_statistics.npz", **stats_data)
+        elif fmt == "numpy":
+            np.savez(output_dir / f"{prefix}_statistics.npz", **stats_data)
+        elif fmt == "csv":
+            import csv
+
+            with open(output_dir / f"{prefix}_statistics.csv", "w", newline="") as f:
+                writer = csv.writer(f)
+                writer.writerow(["metric", "value"])
+                for key, value in stats_data.items():
+                    writer.writerow([key, value])
+
+    # Save detected rays
+    if hasattr(result, "detected") and result.detected is not None:
+        detected = result.detected
+        if hasattr(detected, "positions") and detected.positions is not None:
+            positions = np.asarray(detected.positions)
+            directions = (
+                np.asarray(detected.directions)
+                if hasattr(detected, "directions") and detected.directions is not None
+                else None
+            )
+            intensities = (
+                np.asarray(detected.intensities)
+                if hasattr(detected, "intensities") and detected.intensities is not None
+                else None
+            )
+            times = (
+                np.asarray(detected.times)
+                if hasattr(detected, "times") and detected.times is not None
+                else None
+            )
+            wavelengths = (
+                np.asarray(detected.wavelengths)
+                if hasattr(detected, "wavelengths") and detected.wavelengths is not None
+                else None
+            )
+
+            if fmt == "hdf5":
+                try:
+                    import h5py
+
+                    with h5py.File(output_dir / f"{prefix}_detected.h5", "w") as f:
+                        f.create_dataset("positions", data=positions)
+                        if directions is not None:
+                            f.create_dataset("directions", data=directions)
+                        if intensities is not None:
+                            f.create_dataset("intensities", data=intensities)
+                        if times is not None:
+                            f.create_dataset("times", data=times)
+                        if wavelengths is not None:
+                            f.create_dataset("wavelengths", data=wavelengths)
+                except ImportError:
+                    np.savez(
+                        output_dir / f"{prefix}_detected.npz",
+                        positions=positions,
+                        directions=directions if directions is not None else [],
+                        intensities=intensities if intensities is not None else [],
+                        times=times if times is not None else [],
+                        wavelengths=wavelengths if wavelengths is not None else [],
+                    )
+            elif fmt == "numpy":
+                np.savez(
+                    output_dir / f"{prefix}_detected.npz",
+                    positions=positions,
+                    directions=directions if directions is not None else [],
+                    intensities=intensities if intensities is not None else [],
+                    times=times if times is not None else [],
+                    wavelengths=wavelengths if wavelengths is not None else [],
+                )
+            elif fmt == "csv":
+                # Save positions as CSV
+                np.savetxt(
+                    output_dir / f"{prefix}_detected_positions.csv",
+                    positions,
+                    delimiter=",",
+                    header="x,y,z",
+                    comments="",
+                )
+
+    if verbose and console:
+        console.print(f"[green]Results saved to {output_dir}[/green]")
+
+    return output_dir
+
+
+def print_summary(result, verbose: bool = False):
+    """Print a summary of simulation results."""
+    stats = result.statistics
+
+    # Compute derived values
+    rays_initial = stats.total_rays_initial
+    rays_escaped = stats.rays_terminated_bounds
+    rays_terminated = (
+        stats.rays_terminated_intensity + stats.rays_terminated_max_bounces
+    )
+
+    if RICH_AVAILABLE:
+        console = Console()
+        table = Table(title="Simulation Results")
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", style="green", justify="right")
+
+        table.add_row("Rays Initial", f"{rays_initial:,}")
+        table.add_row("Rays Created (with splits)", f"{stats.total_rays_created:,}")
+        table.add_row("Rays Detected", f"{stats.rays_detected:,}")
+        table.add_row("Rays Absorbed", f"{stats.rays_absorbed:,}")
+        table.add_row("Rays Escaped (bounds)", f"{rays_escaped:,}")
+        table.add_row("Rays Terminated", f"{rays_terminated:,}")
+        table.add_row("Bounces Completed", f"{stats.bounces_completed:,}")
+
+        if rays_initial > 0:
+            detection_rate = stats.rays_detected / rays_initial * 100
+            table.add_row("Detection Rate", f"{detection_rate:.2f}%")
+
+        console.print(table)
+    else:
+        click.echo("\n=== Simulation Results ===")
+        click.echo(f"  Rays Initial:    {rays_initial:,}")
+        click.echo(f"  Rays Created:    {stats.total_rays_created:,}")
+        click.echo(f"  Rays Detected:   {stats.rays_detected:,}")
+        click.echo(f"  Rays Absorbed:   {stats.rays_absorbed:,}")
+        click.echo(f"  Rays Escaped:    {rays_escaped:,}")
+        click.echo(f"  Rays Terminated: {rays_terminated:,}")
+        click.echo(f"  Bounces:         {stats.bounces_completed:,}")
+
+        if rays_initial > 0:
+            detection_rate = stats.rays_detected / rays_initial * 100
+            click.echo(f"  Detection Rate:  {detection_rate:.2f}%")
+
+
+@click.command()
+@click.argument(
+    "config_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--num-rays",
+    type=int,
+    help="Override the number of rays in the source",
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Override the output directory",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Validate configuration without running simulation",
+)
+@click.option(
+    "--progress",
+    is_flag=True,
+    help="Show progress display during simulation",
+)
+@click.option(
+    "--quiet",
+    is_flag=True,
+    help="Suppress all output except errors",
+)
+@click.option(
+    "--no-save",
+    is_flag=True,
+    help="Don't save results to files",
+)
+@click.pass_context
+def run(
+    ctx: click.Context,
+    config_file: Path,
+    num_rays: int | None,
+    output_dir: Path | None,
+    dry_run: bool,
+    progress: bool,
+    quiet: bool,
+    no_save: bool,
+) -> None:
+    """Run a simulation from a configuration file.
+
+    \b
+    CONFIG_FILE: Path to a .yaml or .toml configuration file
+
+    \b
+    Examples:
+        # Basic run
+        lsurf run simulation.yaml
+
+        # With progress display
+        lsurf run simulation.yaml --progress
+
+        # Validate only (dry run)
+        lsurf run simulation.yaml --dry-run
+
+        # Override output directory
+        lsurf run simulation.yaml --output-dir ./my_results
+
+        # Override number of rays
+        lsurf run simulation.yaml --num-rays 1000000
+    """
+    verbose = ctx.obj.get("verbose", False) and not quiet
+
+    # Read configuration
+    if not quiet:
+        click.echo(f"Reading configuration from: {config_file}")
+
+    config_dict = read_config(config_file)
+
+    # Apply overrides
+    if num_rays is not None:
+        config_dict["source"]["params"]["num_rays"] = num_rays
+        if verbose:
+            click.echo(f"  Overriding num_rays: {num_rays}")
+
+    if output_dir is not None:
+        config_dict["output"]["directory"] = str(output_dir)
+        if verbose:
+            click.echo(f"  Overriding output_dir: {output_dir}")
+
+    # Validate configuration
+    config = validate_config(config_dict)
+
+    if not quiet:
+        click.echo("Configuration validated successfully.")
+
+    if dry_run:
+        click.echo("\n[Dry run] Configuration is valid. No simulation was run.")
+
+        if verbose:
+            click.echo("\nConfiguration summary:")
+            click.echo(f"  Media: {list(config.media.keys())}")
+            click.echo(f"  Background: {config.background}")
+            click.echo(f"  Source: {config.source.type}")
+            click.echo(f"  Surfaces: {len(config.surfaces)}")
+            click.echo(f"  Detectors: {len(config.detectors)}")
+            click.echo(f"  Max bounces: {config.simulation.max_bounces}")
+            click.echo(f"  GPU: {config.simulation.use_gpu}")
+        return
+
+    # Build simulation
+    try:
+        geometry, rays, sim_config = build_simulation(config, verbose=verbose)
+    except Exception as e:
+        raise click.ClickException(f"Failed to build simulation: {e}")
+
+    # Run simulation
+    try:
+        result = run_simulation(
+            geometry, rays, sim_config, progress=progress, verbose=verbose
+        )
+    except Exception as e:
+        raise click.ClickException(f"Simulation failed: {e}")
+
+    # Print summary
+    if not quiet:
+        print_summary(result, verbose=verbose)
+
+    # Save results
+    if not no_save:
+        try:
+            output_path = save_results(result, config, verbose=verbose)
+            if not quiet:
+                click.echo(f"\nResults saved to: {output_path}")
+        except Exception as e:
+            raise click.ClickException(f"Failed to save results: {e}")