API Reference

Complete API documentation for all modules in L-SURF.

Module Overview

Simulation Framework

Geometry Module: GeometryBuilder for constructing simulation geometries with named media.
Simulation Module: Simulation class and SimulationConfig for running ray tracing simulations.
Propagation Module: Ray propagation engines including GPU-accelerated gradient propagators.

Core Modules

Materials Module: Material property definitions including refractive indices, dispersion models, and atmospheric profiles.
Sources Module: Ray generation from various source types (point, collimated, diverging, gaussian).
Surfaces Module: Surface geometry and ray-surface intersection (planar, spherical, wave surfaces).
Detectors Module: Detection and analysis of rays at specified locations.
Interactions Module: High-level functions for processing ray-surface interactions.
Visualization Module: Plotting and visualization tools for ray paths, detections, and distributions.
Utilities Module: Supporting utilities for ray data structures and Fresnel calculations.

Quick Reference

Setting Up a Simulation

import lsurf as sr
from lsurf.geometry import GeometryBuilder
from lsurf.simulation import Simulation, SimulationConfig
from lsurf.surfaces import SphereSurface, PlaneSurface, SurfaceRole

# Build geometry
geometry = (
    GeometryBuilder()
    .register_medium("air", sr.AIR_STP)
    .register_medium("water", sr.WATER)
    .set_background("air")
    .add_surface(ocean_surface, front="air", back="water")
    .add_detector(detector_plane)
    .build()
)

# Configure and run
config = SimulationConfig(step_size=100.0, max_bounces=5)
sim = Simulation(geometry, config)
result = sim.run(rays)

Creating Objects

import lsurf as sr
from lsurf.surfaces import SurfaceRole

# Materials
material = sr.WATER
atmosphere = sr.ExponentialAtmosphere(n_sea_level=1.000293)
custom = sr.create_sellmeier_material(B1=1.03961212, ...)

# Sources
source = sr.CollimatedBeam(center=(0,0,1), direction=(0,0,-1), ...)

# Surfaces (with roles)
surface = sr.PlaneSurface(
    point=(0,0,0), normal=(0,0,1),
    role=SurfaceRole.OPTICAL, name="surface"
)

# Detectors
detector = sr.PlaneSurface(
    point=(0,0,10), normal=(0,0,1),
    role=SurfaceRole.DETECTOR, name="detector"
)

Processing Results

result = sim.run(rays)

# Access detected rays
detected = result.detected
print(f"Detected: {detected.num_rays}")
print(f"Times: {detected.times}")
print(f"Positions: {detected.positions}")

# Statistics
stats = result.statistics
print(f"Rays detected: {stats.rays_detected}")
print(f"Rays absorbed: {stats.rays_absorbed}")
print(f"Bounces completed: {stats.bounces_completed}")

# Per-detector breakdown
for name, count in result.detections_per_surface.items():
    print(f"  {name}: {count}")

Simple Surface Interaction

For quick tests without full simulation:

# Direct surface interaction
reflected, refracted = sr.process_surface_interaction(
    rays, surface, wavelength=532e-9
)

Visualization

from lsurf.visualization import (
    plot_ray_paths_projection,
    plot_detection_counts,
    create_detector_scan_figure,
)

fig = plot_ray_paths_projection(
    rays=initial_rays,
    reflected_rays=reflected,
    surface=surface,
)

Logging

import lsurf as sr

sr.configure_logging("INFO")   # Simulation summaries
sr.configure_logging("DEBUG")  # Per-bounce details