Example 01: Basic Raytracing

Location: scripts/01_basic.py

This example demonstrates the fundamental workflow for raytracing in L-SURF.

Overview

This example shows:

Creating materials and surfaces
Generating rays from a source
Processing surface interactions
Basic Fresnel reflection/refraction

Key Concepts

Materials

L-SURF provides pre-defined materials with wavelength-dependent refractive indices:

import lsurf as sr

air = sr.AIR_STP    # n ≈ 1.000293
water = sr.WATER    # n ≈ 1.333 (at 589 nm)
glass = sr.BK7_GLASS  # n ≈ 1.517 (at 589 nm)

Surfaces

Create a planar water surface:

surface = sr.PlanarSurface(
    point=(0, 0, 0),           # Point on surface
    normal=(0, 0, 1),          # Surface normal (upward)
    material_front=sr.AIR_STP, # Material above (air)
    material_back=sr.WATER,    # Material below (water)
)

Ray Generation

Generate a collimated beam:

source = sr.CollimatedBeam(
    center=(0, 0, 0.1),          # 10 cm above surface
    direction=(0.707, 0, -0.707), # 45° incidence
    radius=0.01,                  # 1 cm beam
    num_rays=1000,
    wavelength=532e-9,            # 532 nm (green)
)
rays = source.generate()

Surface Interaction

Process Fresnel reflection and refraction:

reflected, refracted = sr.process_surface_interaction(
    rays, surface,
    wavelength=532e-9,
    generate_reflected=True,
    generate_refracted=True,
    polarization="unpolarized",
)

Expected Output

Console output:

======================================================================
Basic Raytracing Example
======================================================================

Surface: Water (air above, water below)
Source: Collimated beam, 1000 rays, 45.0° incidence
Wavelength: 532.0 nm

Refractive indices:
  n_air:   1.000293
  n_water: 1.333115

Processing surface interaction...
  Reflected rays: 1000
  Refracted rays: 1000

Fresnel reflectance (45°, unpolarized):
  Theoretical: 0.0898
  Measured:    0.0902
  Error:       0.39%

Physics Validation

The Fresnel equations predict the reflectance for unpolarized light:

\[R = \frac{1}{2}\left(R_s + R_p\right)\]

where:

\[ \begin{align}\begin{aligned}R_s = \left|\frac{n_1\cos\theta_i - n_2\cos\theta_t}{n_1\cos\theta_i + n_2\cos\theta_t}\right|^2\\R_p = \left|\frac{n_2\cos\theta_i - n_1\cos\theta_t}{n_2\cos\theta_i + n_1\cos\theta_t}\right|^2\end{aligned}\end{align} \]

For air-water at 45°, theory predicts R ≈ 0.090 (9.0% reflection).

Running the Example

From the scripts/ directory:

python 01_basic.py

This example runs quickly (< 1 second) and demonstrates the core API.

Exercises

Change the angle: Modify direction to test different incidence angles
Different materials: Replace WATER with BK7_GLASS
Wavelength effects: Try different wavelengths (400-700 nm)
More rays: Increase num_rays to 10,000 for better statistics