Command Line Interface (CLI)
============================

L-SURF provides a powerful command-line interface for building configurations and
running simulations. The CLI is the **recommended way** to run production simulations.

Overview
--------

The CLI provides three main commands:

- ``lsurf build`` - Create configuration files interactively or from templates
- ``lsurf run`` - Execute simulations from configuration files
- ``lsurf gui`` - Launch the graphical user interface

Getting Help
------------

.. code-block:: bash

   # General help
   lsurf --help

   # Command-specific help
   lsurf build --help
   lsurf run --help
   lsurf gui --help

Building Configurations
-----------------------

The ``lsurf build`` command creates YAML or TOML configuration files that define
your simulation parameters.

Interactive Mode
~~~~~~~~~~~~~~~~

The interactive wizard guides you through setting up a simulation:

.. code-block:: bash

   lsurf build -o my_simulation.yaml

This will prompt you to configure:

1. **Media** - Define the materials in your simulation (air, water, glass, etc.)
2. **Background** - Set the propagation medium (where rays travel)
3. **Surfaces** - Add optical surfaces that reflect/refract rays
4. **Detectors** - Add surfaces that record ray hits
5. **Source** - Configure the ray source (beam type, position, direction)
6. **Simulation** - Set parameters like step size and max bounces
7. **Output** - Configure where and how to save results

Using Templates
~~~~~~~~~~~~~~~

For common scenarios, use built-in templates:

.. code-block:: bash

   # List available templates
   lsurf build --list-templates -o dummy.yaml

   # Use a template
   lsurf build --template ocean -o ocean_sim.yaml

   # Modify template parameters
   lsurf build --template ocean --num-rays 100000 -o ocean_sim.yaml

Non-Interactive Mode
~~~~~~~~~~~~~~~~~~~~

For scripting and automation:

.. code-block:: bash

   lsurf build --non-interactive --template glass -o glass.toml

Running Simulations
-------------------

The ``lsurf run`` command executes simulations from configuration files.

Basic Usage
~~~~~~~~~~~

.. code-block:: bash

   # Run a simulation
   lsurf run simulation.yaml

   # Show progress during simulation
   lsurf run simulation.yaml --progress

   # Verbose output
   lsurf -v run simulation.yaml --progress

Validating Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~

Before running a full simulation, validate your configuration:

.. code-block:: bash

   # Dry run - validates without executing
   lsurf run simulation.yaml --dry-run

   # Verbose dry run shows configuration summary
   lsurf -v run simulation.yaml --dry-run

Overriding Parameters
~~~~~~~~~~~~~~~~~~~~~

Override configuration file settings from the command line:

.. code-block:: bash

   # Override number of rays
   lsurf run simulation.yaml --num-rays 1000000

   # Override output directory
   lsurf run simulation.yaml --output-dir ./custom_results

   # Combine options
   lsurf run simulation.yaml --num-rays 500000 --output-dir ./test --progress

Output Options
~~~~~~~~~~~~~~

.. code-block:: bash

   # Don't save results (useful for quick tests)
   lsurf run simulation.yaml --no-save

   # Suppress all output except errors
   lsurf run simulation.yaml --quiet

Configuration File Format
-------------------------

Configuration files can be written in YAML or TOML format. Here's a complete
example in YAML:

.. code-block:: yaml

   # simulation.yaml
   version: "1.0"

   # Define materials/media
   media:
     atmosphere:
       type: exponential_atmosphere
       params:
         n_sea_level: 1.000293
         scale_height: 8500.0
     ocean:
       type: water
       params: {}

   # Set the background propagation medium
   background: atmosphere

   # Define optical surfaces
   surfaces:
     - name: ocean_surface
       type: sphere
       role: optical
       front_medium: atmosphere
       back_medium: ocean
       params:
         center: [0.0, 0.0, -6371000.0]
         radius: 6371000.0

   # Define detector surfaces
   detectors:
     - name: sky_detector
       type: recording_sphere
       params:
         altitude: 35000.0
         earth_center: [0.0, 0.0, -6371000.0]
         earth_radius: 6371000.0

   # Configure the ray source
   source:
     type: diverging_beam
     params:
       origin: [0.0, 0.0, 1000.0]
       mean_direction: [0.17, 0.0, -0.98]
       divergence_angle: 0.1745  # ~10 degrees in radians
       num_rays: 10000
       wavelength: 532.0e-9

   # Simulation parameters
   simulation:
     step_size: 100.0
     min_step_size: 0.0003
     max_bounces: 5
     min_intensity: 1.0e-10
     adaptive_stepping: true
     use_gpu: true

   # Output configuration
   output:
     directory: ./results
     prefix: ocean_sim
     format: hdf5
     save_statistics: true

Media Types
~~~~~~~~~~~

Available media types:

- ``vacuum`` - Perfect vacuum (n = 1.0)
- ``air`` - Standard air at STP (n ≈ 1.000293)
- ``water`` - Pure water (n ≈ 1.33)
- ``glass`` - BK7 optical glass (n ≈ 1.52)
- ``homogeneous`` - Custom homogeneous material with specified refractive index
- ``exponential_atmosphere`` - Height-dependent refractive index
- ``duct_atmosphere`` - Atmospheric duct modeling

Surface Types
~~~~~~~~~~~~~

Available surface types:

- ``plane`` - Infinite flat plane
- ``bounded_plane`` - Rectangular flat plane
- ``annular_plane`` - Ring-shaped flat plane
- ``sphere`` - Spherical surface
- ``gerstner_wave`` - Single Gerstner wave
- ``curved_wave`` - Curved wave on spherical Earth
- ``multi_curved_wave`` - Multiple superimposed waves

Detector Types
~~~~~~~~~~~~~~

Available detector types:

- ``planar`` - Flat rectangular detector
- ``spherical`` - Spherical detector
- ``recording_sphere`` - Spherical shell at altitude (for atmospheric detection)
- ``local_recording_sphere`` - Local spherical detector
- ``directional`` - Directional detector

Source Types
~~~~~~~~~~~~

Available source types:

- ``point`` - Isotropic point source
- ``collimated_beam`` - Parallel beam of rays
- ``diverging_beam`` - Conical diverging beam
- ``gaussian_beam`` - Gaussian intensity profile beam

Output Formats
--------------

Results can be saved in three formats:

- ``hdf5`` - Hierarchical Data Format (recommended for large datasets)
- ``numpy`` - NumPy .npz archives
- ``csv`` - Comma-separated values (human-readable)

Output files include:

- ``{prefix}_statistics.{ext}`` - Simulation statistics
- ``{prefix}_detected.{ext}`` - Detected ray data (positions, directions, times)

Typical Workflow
----------------

A typical workflow for running simulations:

.. code-block:: bash

   # 1. Create configuration interactively
   lsurf build -o my_sim.yaml

   # 2. Validate the configuration
   lsurf -v run my_sim.yaml --dry-run

   # 3. Run a quick test with fewer rays
   lsurf run my_sim.yaml --num-rays 1000 --progress

   # 4. Run the full simulation
   lsurf run my_sim.yaml --progress

   # 5. View results (launch GUI to visualize)
   lsurf gui my_sim.yaml

Tips and Best Practices
-----------------------

1. **Start small** - Test with fewer rays before running large simulations
2. **Use templates** - Templates provide validated starting configurations
3. **Validate first** - Use ``--dry-run`` to catch configuration errors early
4. **Save configurations** - Keep configuration files for reproducibility
5. **Use GPU** - Enable ``use_gpu: true`` for significant speedup
6. **Output format** - Use HDF5 for large simulations, CSV for quick inspection