Geometry Module
===============

The geometry module provides the ``GeometryBuilder`` for constructing simulation
geometries and the ``Geometry`` container for the built result.

.. module:: lsurf.geometry

Overview
--------

The geometry system uses a builder pattern to construct immutable simulation
geometries:

1. **GeometryBuilder** - Fluent interface for building geometries
2. **Geometry** - Immutable container holding the built geometry

GeometryBuilder
---------------

.. autoclass:: lsurf.geometry.GeometryBuilder
   :members:
   :undoc-members:

Geometry
--------

.. autoclass:: lsurf.geometry.Geometry
   :members:
   :undoc-members:

Usage Example
-------------

.. code-block:: python

   from lsurf.geometry import GeometryBuilder
   from lsurf.materials import ExponentialAtmosphere, WATER
   from lsurf.surfaces import SphereSurface, PlaneSurface, SurfaceRole

   EARTH_RADIUS = 6.371e6

   # Create materials
   atmosphere = ExponentialAtmosphere(n_sea_level=1.000293)

   # Create surfaces
   ocean = SphereSurface(
       center=(0, 0, -EARTH_RADIUS),
       radius=EARTH_RADIUS,
       role=SurfaceRole.OPTICAL,
       name="ocean",
   )

   detector = PlaneSurface(
       point=(0, 0, 35000),
       normal=(0, 0, 1),
       role=SurfaceRole.DETECTOR,
       name="detector_35km",
   )

   # Build geometry
   geometry = (
       GeometryBuilder()
       .register_medium("atmosphere", atmosphere)
       .register_medium("ocean", WATER)
       .set_background("atmosphere")
       .add_surface(ocean, front="atmosphere", back="ocean")
       .add_detector(detector)
       .build()
   )

   # Access geometry components
   ocean_surface = geometry.get_surface("ocean")
   detector_surface = geometry.get_detector("detector_35km")
   atmo_material = geometry.get_medium("atmosphere")

Builder Methods
---------------

The ``GeometryBuilder`` provides a fluent interface:

register_medium(name, material)
   Register a named medium with its material. Multiple surfaces can reference
   the same medium by name, ensuring material consistency.

set_background(medium_name)
   Set the background propagation medium. This is the material through which
   rays propagate between surfaces.

add_surface(surface, front, back)
   Add an optical or absorber surface. The ``front`` and ``back`` parameters
   specify which registered media are on each side of the surface.

add_detector(detector)
   Add a detector surface. Detectors don't need front/back materials since
   they simply record rays that hit them.

build()
   Finalize and return the immutable ``Geometry`` object.

Geometry Accessors
------------------

The ``Geometry`` object provides accessors for its components:

get_surface(name)
   Get a surface by name.

get_detector(name)
   Get a detector by name.

get_medium(name)
   Get a material by medium name.

to_surface_list()
   Get all surfaces and detectors as a list (for propagators).

Surface Roles
-------------

Surfaces must have a role that determines their behavior:

.. code-block:: python

   from lsurf.surfaces import SurfaceRole

   # OPTICAL: Reflects and/or refracts rays (Fresnel coefficients)
   ocean = SphereSurface(..., role=SurfaceRole.OPTICAL)

   # DETECTOR: Records rays and terminates them
   detector = PlaneSurface(..., role=SurfaceRole.DETECTOR)

   # ABSORBER: Terminates rays without recording
   boundary = SphereSurface(..., role=SurfaceRole.ABSORBER)