PyOptik 1.6.4.post0__tar.gz → 1.7.0.post0__tar.gz

{pyoptik-1.6.4.post0 → pyoptik-1.7.0.post0}/.github/workflows/deploy_anaconda.yml

@@ -31,4 +31,4 @@ jobs:
           ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }}  # Ensure the Anaconda token is set
         run: |
           conda install conda-build anaconda-client conda-verify -y
-          conda build .
+          conda build . -c martinpdes

{pyoptik-1.6.4.post0 → pyoptik-1.7.0.post0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyOptik
-Version: 1.6.4.post0
+Version: 1.7.0.post0
 Summary: A package for refractive index values.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -36,9 +36,9 @@ Classifier: Intended Audience :: Science/Research
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
+Requires-Dist: pint
 Requires-Dist: pydantic>=2.6.3
 Requires-Dist: numpy
-Requires-Dist: scipy
 Requires-Dist: pyyaml
 Requires-Dist: MPSPlots
 Requires-Dist: tabulate
@@ -69,7 +69,7 @@ PyOptik is a powerful Python tool designed to import refractive indexes and exti
    :header-rows: 1
 
    * - Testing
-     -
+     - |ci/cd|
      - |coverage|
      -
    * - Package
@@ -83,6 +83,7 @@ PyOptik is a powerful Python tool designed to import refractive indexes and exti
 
 Features
 ********
+
 - **Comprehensive Database Access**: Seamlessly import refractive index and extinction coefficient data for a wide range of materials.
 - **Simulation Ready**: Ideal for light-matter interaction simulations, particularly in optics and photonics.
 - **Simple API**: Easy-to-use API that integrates well with other Python libraries.
@@ -96,10 +97,10 @@ To install PyOptik, simply use `pip` or `conda`:
 .. code:: bash
 
    pip install PyOptik
-   conda install pyoptik
+   conda install --channels martinpdes pyoptik
 
-Usage
-*****
+Simple Usage
+************
 
 After installing PyOptik, you can easily access material properties:
 
@@ -199,6 +200,10 @@ As of 2024, PyOptik is still under development. If you would like to collaborate
    :target: https://martinpdes.github.io/PyOptik/
    :alt: Documentation Status
 
+.. |ci/cd| image:: https://github.com/martinpdes/pyoptik/actions/workflows/deploy_coverage.yml/badge.svg
+   :target: https://martinpdes.github.io/PyOptik/actions
+   :alt: Unittest Status
+
 .. |PyPi| image:: https://badge.fury.io/py/pyoptik.svg
    :target: https://badge.fury.io/py/pyoptik
 

{pyoptik-1.6.4.post0 → pyoptik-1.7.0.post0}/PyOptik/__init__.py

@@ -7,7 +7,8 @@ except ImportError:
 
 from .utils import build_default_library
 from .material import Material
-from .tabulated_class import TabulatedMaterial
-from .sellmeier_class import SellmeierMaterial
+from .material import TabulatedMaterial
+from .material import SellmeierMaterial
+from .material import base_class
 
 Material = Material()

{pyoptik-1.6.4.post0 → pyoptik-1.7.0.post0}/PyOptik/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.6.4.post0'
-__version_tuple__ = version_tuple = (1, 6, 4)
+__version__ = version = '1.7.0.post0'
+__version_tuple__ = version_tuple = (1, 7, 0)

pyoptik-1.7.0.post0/PyOptik/material/__init__.py

@@ -0,0 +1,4 @@
+from .base_class import BaseMaterial
+from .sellmeier_class import SellmeierMaterial
+from .tabulated_class import TabulatedMaterial
+from .material import Material

pyoptik-1.7.0.post0/PyOptik/material/base_class.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from PyOptik.units import Quantity, meter
+import numpy
+import warnings
+
+class BaseMaterial:
+    def __str__(self) -> str:
+        """
+        Provides an informal string representation of the Material object.
+
+        Returns
+        -------
+        str
+            Informal representation of the Material object.
+        """
+        return f"Material: {self.filename}"
+
+    def __repr__(self) -> str:
+        """
+        Provides a formal string representation of the Material object, including key attributes.
+
+        Returns
+        -------
+        str
+            Formal representation of the Material object.
+        """
+        return self.__str__()
+
+    def _check_wavelength(self, wavelength_range: Quantity) -> None:
+        """
+        Checks if a wavelength is within the material's allowable range and raises a warning if it is not.
+
+        Parameters
+        ----------
+        lambda_um : float
+            The wavelength to check, in micrometers.
+
+        Raises
+        ------
+        UserWarning
+            If the wavelength is outside the allowable range.
+        """
+        if self.wavelength_bound is not None:
+            min_value, max_value = self.wavelength_bound
+
+            if numpy.any((wavelength_range < min_value) | (wavelength_range > max_value)):
+                warnings.warn(
+                    f"Wavelength range goes from {wavelength_range.min().to_compact()} to {wavelength_range.max().to_compact()} "
+                    f"which is outside the allowable range of {min_value.to_compact()} to {max_value.to_compact()} µm. "
+                    f"[Material: {self.filename}]"
+                )
+
+    def ensure_units(func):
+        """
+        Decorator to ensure that the wavelength parameter has the correct units.
+
+        Parameters
+        ----------
+        func : callable
+            The function to wrap.
+
+        Returns
+        -------
+        callable
+            The wrapped function that ensures wavelength is a Quantity in meters.
+        """
+        def wrapper(self, wavelength: Quantity = None, *args, **kwargs):
+            if wavelength is None:
+                wavelength = numpy.linspace(self.wavelength_bound[0].magnitude, self.wavelength_bound[1].magnitude, 100) * self.wavelength_bound.units
+
+            if not isinstance(wavelength, Quantity):
+                wavelength = wavelength * meter
+            return func(self, wavelength, *args, **kwargs)
+        return wrapper

{pyoptik-1.6.4.post0/PyOptik → pyoptik-1.7.0.post0/PyOptik/material}/material.py

@@ -3,8 +3,8 @@
 
 from typing import Union
 from dataclasses import dataclass
-from PyOptik.sellmeier_class import SellmeierMaterial
-from PyOptik.tabulated_class import TabulatedMaterial
+from PyOptik.material.sellmeier_class import SellmeierMaterial
+from PyOptik.material.tabulated_class import TabulatedMaterial
 from PyOptik import data
 
 class staticproperty(property):
@@ -45,14 +45,20 @@ class Material:
         """
         Retrieve a material by name.
 
-        Args:
-            material_name (str): The name of the material to retrieve.
+        Parameters
+        ----------
+        material_name : str
+            The name of the material to retrieve.
 
-        Returns:
-            Union[SellmeierMaterial, TabulatedMaterial]: An instance of the material if found.
+        Returns
+        -------
+        Union[SellmeierMaterial, TabulatedMaterial]
+            An instance of the material if found.
 
-        Raises:
-            FileNotFoundError: If the material is not found in either the Sellmeier or Tabulated lists.
+        Raises
+        ------
+        FileNotFoundError
+            If the material is not found in either the Sellmeier or Tabulated lists.
         """
         if material_name in data.sellmeier.material_list:
             return SellmeierMaterial(material_name)

pyoptik-1.7.0.post0/PyOptik/material/sellmeier_class.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pydantic import Field, ConfigDict
+from pydantic.dataclasses import dataclass
+import matplotlib.pyplot as plt
+import numpy
+from typing import Tuple, Optional, Union
+import yaml
+from PyOptik.directories import sellmeier_data_path
+import itertools
+from PyOptik.material.base_class import BaseMaterial
+from MPSPlots.styles import mps
+from PyOptik.units import meter, micrometer, Quantity
+
+config_dict = ConfigDict(
+    arbitrary_types_allowed=True
+)
+
+@dataclass(config=config_dict, slots=True)
+class SellmeierMaterial(BaseMaterial):
+    """
+    Class representing a material with Sellmeier coefficients for refractive index computation.
+
+    Attributes
+    ----------
+    filename : str
+        The name of the YAML file containing material properties.
+    coefficients : numpy.ndarray
+        The Sellmeier coefficients used for calculating the refractive index.
+    wavelength_range : Optional[Tuple[float, float]]
+        The allowable wavelength range for the material in micrometers.
+    reference : Optional[str]
+        Reference information for the material data.
+    formula_type : int
+        The formula type to use for refractive index calculation.
+    """
+    filename: str
+    coefficients: Optional[numpy.ndarray] = Field(default=None)
+    wavelength_bound: Optional[Tuple[float, float]] = Field(default=None)
+    reference: Optional[str] = Field(default=None)
+    formula_type: Optional[int] = Field(default=None)
+
+    def __post_init__(self) -> None:
+        """
+        Post-initialization method to load coefficients, wavelength range, formula type, and reference from a YAML file.
+        """
+        self._load_coefficients()
+
+    def _load_coefficients(self) -> None:
+        """
+        Loads the Sellmeier coefficients, wavelength range, formula type, and reference from the specified YAML file.
+        """
+        file_path = sellmeier_data_path / f'{self.filename}'
+
+        if not file_path.with_suffix('.yml').exists():
+            raise FileNotFoundError(f"YAML file {file_path} not found.")
+
+        with file_path.with_suffix('.yml').open('r') as file:
+            parsed_yaml = yaml.safe_load(file)
+
+
+        # Extract the formula type
+        self.formula_type = int(parsed_yaml['DATA'][0]['type'].split()[-1])
+
+        # Extract coefficients and ensure the list has exactly 7 coefficients by padding with zeros if necessary
+        coefficients_str = parsed_yaml['DATA'][0]['coefficients']
+        coefficients = list(map(float, coefficients_str.split()))
+        if len(coefficients) < 7:
+            coefficients.extend([0.0] * (7 - len(coefficients)))
+        self.coefficients = numpy.array(coefficients)
+
+        # Extract wavelength range
+        if 'wavelength_range' in parsed_yaml['DATA'][0]:
+            data_str = parsed_yaml['DATA'][0]['wavelength_range'].split()
+            self.wavelength_bound = numpy.array([float(val) for val in data_str]) * micrometer
+
+        else:
+            self.wavelength_bound = None
+
+        # Extract reference
+        self.reference = parsed_yaml.get('REFERENCES', None)
+
+    @BaseMaterial.ensure_units
+    def compute_refractive_index(self, wavelength: Union[Quantity]) -> Union[float, numpy.ndarray]:
+        r"""
+        Computes the refractive index n(\u03bb) using the appropriate formula (either Formula 1, 2, 5, or 6).
+
+        Parameters
+        ----------
+        wavelength : Union[Quantity]
+            The wavelength \u03bb in meters, can be a single float or a numpy array.
+
+        Returns
+        -------
+        Union[Quantity]
+            The refractive index n(\u03bb) for the given wavelength or array of wavelengths.
+
+        Raises
+        ------
+        ValueError
+            If the wavelength is outside the specified range or if an unsupported formula type is encountered.
+        """
+        is_scalar = numpy.isscalar(wavelength)
+        wavelength = numpy.atleast_1d(wavelength)
+        self._check_wavelength(wavelength)
+
+        # Compute the refractive index based on the formula type
+        zipped_coefficients = itertools.zip_longest(*[iter(self.coefficients[1:])] * 2)
+
+        match self.formula_type:
+            case 1:  # Formula 1 computation (standard Sellmeier)
+                n_squared = self.coefficients[0]
+                for (B, C) in zipped_coefficients:
+                    n_squared += (B * wavelength.to(micrometer).magnitude**2) / (wavelength.to(micrometer).magnitude**2 - C**2)
+                n = numpy.sqrt(n_squared)
+
+            case 2:  # Formula 2 computation (extended Sellmeier)
+                n_squared = 1 + self.coefficients[0]
+                for (B, C) in zipped_coefficients:
+                    n_squared += (B * wavelength.to(micrometer).magnitude**2) / (wavelength.to(micrometer).magnitude**2 - C)
+                n = numpy.sqrt(n_squared)
+
+            case 5:  # Formula 5 computation (extended Sellmeier)
+                n = 1 + self.coefficients[0]
+                for (B, C) in zipped_coefficients:
+                    n = B * wavelength.to(micrometer).magnitude**C
+
+            case 6:
+                n = 1 + self.coefficients[0]
+                for (B, C) in zipped_coefficients:
+                    n = B / (C - wavelength.to(micrometer).magnitude**-2)
+
+            case _:
+                raise ValueError(f"Unsupported formula type: {self.formula_type}")
+
+        return n[0] if is_scalar else n
+
+    @BaseMaterial.ensure_units
+    def plot(self, wavelength: Optional[Quantity] = None) -> None:
+        """
+        Plots the refractive index as a function of wavelength over a specified range.
+
+        Parameters
+        ----------
+        wavelength : Optional[Quantity]
+            The range of wavelengths to plot, in meters. If not provided, the entire allowable wavelength range is used.
+
+        Raises
+        ------
+        ValueError
+            If the wavelength is not a 1D array or list of float values.
+        """
+        if wavelength.ndim != 1:
+            raise ValueError("wavelength must be a 1D array or list of float values.")
+
+        # Calculate the refractive index over the wavelength range
+        refractive_index = self.compute_refractive_index(wavelength)
+
+        with plt.style.context(mps):
+            fig, ax = plt.subplots()
+
+        ax.set(
+            ylabel='Refractive Index',
+            xlabel=r'Wavelength [$\mu$m]',
+            title=f"Refractive Index vs. Wavelength: [{self.filename}]"
+        )
+        ax.plot(wavelength.to(micrometer).magnitude, refractive_index.real, linewidth=2, label='Real Part')
+        ax.legend()
+
+        plt.show()
+
+    def print(self) -> str:
+        """
+        Provides a formal string representation of the Material object, including key attributes.
+
+        Returns
+        -------
+        str
+            Formal representation of the Material object.
+        """
+        return (
+            f"\nMaterial: '{self.filename}',\n"
+            f"coefficients: {self.coefficients},\n"
+            f"wavelength_range: {self.wavelength_bound},\n"
+            f"formula_type: {self.formula_type},\n"
+            f"reference: '{self.reference}')"
+        )

pyoptik-1.7.0.post0/PyOptik/material/tabulated_class.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+from pydantic.dataclasses import dataclass, Field
+from typing import Optional, Union
+import yaml
+import warnings
+from PyOptik.directories import tabulated_data_path
+from PyOptik.material.base_class import BaseMaterial
+from MPSPlots.styles import mps
+import matplotlib.pyplot as plt
+from PyOptik.units import Quantity, micrometer, meter
+
+
+@dataclass(config=dict(arbitrary_types_allowed=True))
+class TabulatedMaterial(BaseMaterial):
+    """
+    Class representing a material with tabulated refractive index (n) and absorption (k) values.
+
+    Attributes
+    ----------
+    filename : str
+        The name of the YAML file containing material properties.
+    wavelength : numpy.ndarray
+        Array of wavelengths in micrometers for which the refractive index and absorption values are tabulated.
+    n_values : numpy.ndarray
+        Array of tabulated refractive index values (n) corresponding to the wavelengths.
+    k_values : numpy.ndarray
+        Array of tabulated absorption values (k) corresponding to the wavelengths.
+    reference : Optional[str]
+        Reference information for the material data.
+    """
+    filename: str
+    wavelength: numpy.ndarray = Field(init=False)
+    n_values: numpy.ndarray = Field(init=False)
+    k_values: numpy.ndarray = Field(init=False)
+    reference: Optional[str] = Field(init=False)
+
+    def __post_init__(self) -> None:
+        """
+        Post-initialization method to load the tabulated data from the YAML file.
+        """
+        self._load_tabulated_data()
+
+    def _load_tabulated_data(self) -> None:
+        """
+        Loads the tabulated refractive index and absorption values from the specified YAML file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the specified YAML file does not exist.
+        ValueError
+            If the YAML data is malformed or missing required keys.
+        """
+        file_path = tabulated_data_path / f'{self.filename}'
+
+        if not file_path.with_suffix('.yml').exists():
+            raise FileNotFoundError(f"YAML file {file_path} not found.")
+
+        with file_path.with_suffix('.yml').open('r') as file:
+            parsed_yaml = yaml.safe_load(file)
+
+        try:
+            # Extract data points
+            data_points = parsed_yaml['DATA'][0]['data'].strip().split('\n')
+            data = numpy.array([[float(value) for value in point.split()] for point in data_points])
+
+            self.wavelength = data[:, 0] * micrometer
+            self.n_values = data[:, 1]
+            self.k_values = data[:, 2]
+        except (KeyError, IndexError, ValueError):
+            raise ValueError(f"Invalid or missing data in YAML file {file_path}")
+
+
+        self.wavelength_bound = [self.wavelength.min().magnitude, self.wavelength.max().magnitude] * micrometer
+
+        # Extract reference
+        self.reference = parsed_yaml.get('REFERENCES', None)
+
+    @BaseMaterial.ensure_units
+    def compute_refractive_index(self, wavelength: Union[float, Quantity]) -> numpy.ndarray:
+        """
+        Interpolates the refractive index (n) and absorption (k) values for the given wavelength(s).
+
+        Parameters
+        ----------
+        wavelength : Union[float, Quantity]
+            Wavelength(s) in micrometers for which to interpolate n and k.
+
+        Returns
+        -------
+        numpy.ndarray
+            Complex refractive index values (n + i*k) for the given wavelength(s).
+
+        Raises
+        ------
+        ValueError
+            If the wavelength is outside the tabulated range.
+        """
+        self._check_wavelength(wavelength)
+
+        n_interp = numpy.interp(wavelength.to(meter).magnitude, self.wavelength.to(meter).magnitude, self.n_values)
+        k_interp = numpy.interp(wavelength.to(meter).magnitude, self.wavelength.to(meter).magnitude, self.k_values)
+
+        return n_interp + 1j * k_interp
+
+    @BaseMaterial.ensure_units
+    def plot(self, wavelength: Optional[Quantity] = None) -> None:
+        """
+        Plots the tabulated refractive index (n) and absorption (k) as a function of wavelength.
+
+        Parameters
+        ----------
+        wavelength : Optional[Quantity]
+            The range of wavelengths to plot, in micrometers. If not provided, the entire tabulated wavelength range is used.
+        title : str, optional
+            Title of the plot.
+        grid : bool, optional
+            Whether to show grid lines on the plot.
+
+        Raises
+        ------
+        ValueError
+            If the wavelength is not a 1D array or list of float values.
+        """
+        n_values, k_values = self.compute_refractive_index(wavelength).real, self.compute_refractive_index(wavelength).imag
+
+        with plt.style.context(mps):
+            _, ax1 = plt.subplots()
+
+        ax1.set(
+            title=f"Refractive Index and Absorption vs. Wavelength [{self.filename}]",
+            xlabel='Wavelength [µm]',
+            ylabel='Refractive Index (n)',
+        )
+
+        ax1.plot(wavelength.to(micrometer).magnitude, n_values, 'o-', color='tab:blue', label='n')
+
+        ax2 = ax1.twinx()
+
+        ax2.set(
+            xlabel='Wavelength [µm]',
+            ylabel='Absorption (k)',
+        )
+
+        ax2.plot(wavelength.to(micrometer).magnitude, k_values, 'o-', color='tab:red', label='k')
+
+        plt.show()
+
+    def print(self) -> str:
+        """
+        Provides a formal string representation of the TabulatedMaterial object, including key attributes.
+
+        Returns
+        -------
+        str
+            Formal representation of the TabulatedMaterial object.
+        """
+        return (
+            f"\nTabulatedMaterial: '{self.filename}',\n"
+            f"wavelength_range: [{self.wavelength.min()} µm, {self.wavelength.max()} µm],\n"
+            f"reference: '{self.reference}')"
+        )

pyoptik-1.7.0.post0/PyOptik/units.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pint import UnitRegistry
+ureg = UnitRegistry()
+Quantity = ureg.Quantity
+micrometer = ureg.micrometer
+meter = ureg.meter
+nanometer = ureg.nanometer

{pyoptik-1.6.4.post0 → pyoptik-1.7.0.post0}/PyOptik/utils.py

@@ -10,11 +10,15 @@ def download_yml_file(url: str, filename: str, location: str) -> None:
     """
     Downloads a .yml file from a specified URL and saves it locally.
 
-    Args:
-        url (str): The URL of the .yml file to download.
-        save_path (str): The local path where the .yml file should be saved.
-
-    Raises:
+    Parameters
+    ----------
+    url : str
+        The URL of the .yml file to download.
+    save_path : str
+        The local path where the .yml file should be saved.
+
+    Raises
+    ------
         HTTPError: If the download fails due to an HTTP error.
     """
     file_path = location / f"{filename}.yml"
@@ -53,13 +57,19 @@ def remove_element(filename: str, location: str = 'any') -> None:
     """
     Remove a file associated with a given element name from the specified location.
 
-    Args:
-        filename (str): The name of the file to remove, without the '.yml' suffix.
-        location (str): The location to search for the file, either 'sellmeier', 'tabulated', or 'any' (default is 'any').
-
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
-        ValueError: If an invalid location is provided.
+    Parameters
+    ----------
+    filename : str
+        The name of the file to remove, without the '.yml' suffix.
+    location : str
+        The location to search for the file, either 'sellmeier', 'tabulated', or 'any' (default is 'any').
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    ValueError
+        If an invalid location is provided.
     """
     location = location.lower()
 
@@ -87,14 +97,22 @@ def create_sellmeier_file(
     """
     Creates a YAML file with custom Sellmeier coefficients in the correct format.
 
-    Args:
-        filename (str): The name of the file to create (without the extension).
-        formula_type (int): The type of Sellmeier formula.
-        coefficients (list[float]): A list of coefficients for the Sellmeier equation.
-        wavelength_range (Tuple[float, float]): The range of wavelengths, in micrometers.
-        reference (str): A reference for the material data.
-        comments (Optional[str]): Additional comments about the material.
-        specs (Optional[dict]): Additional specifications, such as temperature and whether the wavelength is in a vacuum.
+    Parameters
+    ----------
+    filename : str
+        The name of the file to create (without the extension).
+    formula_type : int
+        The type of Sellmeier formula.
+    coefficients :  list[float]
+        A list of coefficients for the Sellmeier equation.
+    wavelength_range : Tuple[float, float]
+        The range of wavelengths, in micrometers.
+    reference : str
+        A reference for the material data.
+    comments : Optional[str]
+        Additional comments about the material.
+    specs : Optional[dict]
+        Additional specifications, such as temperature and whether the wavelength is in a vacuum.
     """
     reference = 'None' if reference is None else reference
     wavelength_range = [None, None] if wavelength_range is None else wavelength_range
@@ -135,11 +153,16 @@ def create_tabulated_file(
     """
     Creates a YAML file with tabulated nk data in the correct format.
 
-    Args:
-        filename (str): The name of the file to create (without the extension).
-        data (List[Tuple[float, float, float]]): The tabulated nk data.
-        reference (Optional[str]): A reference for the material data.
-        comments (Optional[str]): Additional comments about the material.
+    Parameters
+    ----------
+    filename : str)
+        The name of the file to create (without the extension).
+    data : List[Tuple[float, float, float]])
+        The tabulated nk data.
+    reference : Optional[str])
+        A reference for the material data.
+    comments : Optional[str])
+        Additional comments about the material.
     """
     reference = 'None' if reference is None else reference