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:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. math::

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

where:

.. math::

   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

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

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

See Also
--------

* :doc:`02_sources` - Explore different ray source types
* :doc:`04_glass_reflection` - Detailed Fresnel analysis
* :py:class:`lsurf.surfaces.PlanarSurface` - API documentation