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

# 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:

lsurf build -o my_simulation.yaml

This will prompt you to configure:

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

Using Templates

For common scenarios, use built-in templates:

# 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:

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

Running Simulations

The lsurf run command executes simulations from configuration files.

Basic Usage

# 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:

# 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:

# 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

# 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:

# 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:

# 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

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