Materials Module
================

.. automodule:: lsurf.materials
   :members:
   :undoc-members:
   :show-inheritance:

Material Classes
----------------

.. currentmodule:: lsurf.materials

.. autosummary::
   :toctree: _autosummary
   :recursive:

   MaterialField
   HomogeneousMaterial

Inhomogeneous Material Base Classes
-----------------------------------

.. autosummary::
   :toctree: _autosummary
   :recursive:

   SimpleInhomogeneousModel
   GridInhomogeneousModel
   FullInhomogeneousModel

Predefined Materials
--------------------

.. autosummary::
   :toctree: _autosummary

   VACUUM
   AIR_STP
   WATER
   BK7_GLASS

Atmosphere Implementations
--------------------------

.. autosummary::
   :toctree: _autosummary

   ExponentialAtmosphere
   DuctAtmosphere
   STANDARD_ATMOSPHERE

Dispersion Functions
--------------------

.. autosummary::
   :toctree: _autosummary

   sellmeier_refractive_index
   cauchy_refractive_index
   create_sellmeier_material
   create_cauchy_material

Material Classes
----------------

MaterialField
~~~~~~~~~~~~~

.. autoclass:: lsurf.materials.MaterialField
   :members:
   :special-members: __init__
   :undoc-members:
   :show-inheritance:

HomogeneousMaterial
~~~~~~~~~~~~~~~~~~~

.. autoclass:: lsurf.materials.HomogeneousMaterial
   :members:
   :special-members: __init__
   :undoc-members:
   :show-inheritance:

Pre-defined Materials
---------------------

.. data:: lsurf.materials.VACUUM

   Perfect vacuum with n = 1.0 (no dispersion).

.. data:: lsurf.materials.AIR_STP

   Air at standard temperature and pressure. Refractive index ~1.000293 at 589 nm.

.. data:: lsurf.materials.WATER

   Pure water with wavelength-dependent refractive index using empirical formula.
   n ≈ 1.333 at 589 nm.

.. data:: lsurf.materials.BK7_GLASS

   BK7 optical glass with Sellmeier dispersion formula. n ≈ 1.517 at 589 nm.

Dispersion Models
-----------------

sellmeier_refractive_index
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: lsurf.materials.sellmeier_refractive_index

cauchy_refractive_index
~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: lsurf.materials.cauchy_refractive_index

Factory Functions
-----------------

create_sellmeier_material
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: lsurf.materials.create_sellmeier_material

create_cauchy_material
~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: lsurf.materials.create_cauchy_material

Examples
--------

Using Pre-defined Materials
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from lsurf import AIR_STP, WATER, BK7_GLASS

   # Get refractive index at 532 nm
   n_air = AIR_STP.refractive_index(532e-9, (0, 0, 0))
   n_water = WATER.refractive_index(532e-9, (0, 0, 0))
   n_glass = BK7_GLASS.refractive_index(532e-9, (0, 0, 0))

   print(f"n_air = {n_air:.6f}")     # ~1.000293
   print(f"n_water = {n_water:.6f}") # ~1.333
   print(f"n_glass = {n_glass:.6f}") # ~1.519

Creating Custom Materials
~~~~~~~~~~~~~~~~~~~~~~~~~

Using Sellmeier formula:

.. code-block:: python

   from lsurf import create_sellmeier_material

   # Fused silica
   silica = create_sellmeier_material(
       name="Fused Silica",
       B1=0.6961663, C1=0.0684043,
       B2=0.4079426, C2=0.1162414,
       B3=0.8974794, C3=9.896161,
   )

Using Cauchy formula:

.. code-block:: python

   from lsurf import create_cauchy_material

   # Simple glass
   glass = create_cauchy_material(
       name="Simple Glass",
       A=1.5,  # Base refractive index
       B=0.01, # Dispersion coefficient
   )

Wavelength Dependence
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import numpy as np
   import matplotlib.pyplot as plt

   wavelengths = np.linspace(400e-9, 700e-9, 100)
   n_values = [WATER.refractive_index(wl, (0,0,0)) for wl in wavelengths]

   plt.plot(wavelengths * 1e9, n_values)
   plt.xlabel('Wavelength (nm)')
   plt.ylabel('Refractive Index')
   plt.title('Water Dispersion')
   plt.show()