PyMieSim 3.6.0__cp313-cp313-win_amd64.whl

PyMieSim/experiment/scatterer/base.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from PyOptik.material.base_class import BaseMaterial
+from pydantic import field_validator
+from PyMieSim.units import Quantity, meter, RIU
+from pint_pandas import PintArray
+from PyMieSim.binary.interface_sets import CppScattererProperties, CppMediumProperties
+import numpy
+
+
+class BaseScatterer():
+    """
+    Base class for scatterer objects.  This class handles the initialization and setup of
+    scatterer parameters for use in PyMieSim simulations.
+
+    """
+    mapping = None
+    binding_kwargs = None
+    binding = None
+
+    @field_validator('property', 'core_property', 'shell_property', 'medium_property', mode='plain')
+    def _validate_array(cls, value):
+        """Ensure that arrays are properly converted to numpy arrays."""
+        value = numpy.atleast_1d(value)
+
+        if isinstance(value, Quantity):
+            assert value.check(RIU), f"{value} must be a Quantity with refractive index units (RIU)."
+            return value
+
+        assert numpy.all([isinstance(p, BaseMaterial) for p in value]), f"{value} must be either a refractive index quantity (RIU) or BaseMaterial."
+
+        return value
+
+    @field_validator('diameter', 'core_diameter', 'shell_thickness', mode='plain')
+    def _validate_length_quantity(cls, value):
+        """
+        Ensures that diameter is Quantity objects with length units.
+        """
+        value = numpy.atleast_1d(value)
+
+        if not isinstance(value, Quantity) or not value.check(meter):
+            raise ValueError(f"{value} must be a Quantity with meters units.")
+
+        return value
+
+    def _add_properties(self, name: str, properties: Quantity | BaseMaterial) -> None:
+        """
+        Determines whether the provided property is a refractive index (Quantity) or a material (BaseMaterial),
+        and returns the corresponding values.
+
+        Parameters
+        ----------
+        property : Quantity or BaseMaterial
+            The core property to be assigned, which can either be a refractive index (Quantity) or a material (BaseMaterial).
+
+        Raises
+        ------
+        ValueError:
+            If the provided property is neither a Quantity (refractive index) nor a BaseMaterial.
+        """
+        CPPClass = CppMediumProperties if name == 'medium' else CppScattererProperties
+
+        if all(isinstance(item, Quantity) for item in properties):
+            instance = CPPClass(index_properties=properties.magnitude)
+            self.binding_kwargs[f'{name}_properties'] = instance
+
+            return instance
+
+        elif all(isinstance(item, BaseMaterial) for item in properties):
+            eval_index = numpy.asarray([m.compute_refractive_index(self.source.wavelength.to_base_units().magnitude) for m in properties])
+            instance = CPPClass(material_properties=eval_index)
+            self.binding_kwargs[f'{name}_properties'] = instance
+
+            return instance
+
+        else:
+            raise TypeError("All elements in the list must be of type 'Quantity' or 'BaseMaterial', not a mix of both.")
+
+    def _generate_mapping(self) -> None:
+        """
+        Constructs a table of the scatterer's properties formatted for data visualization.
+        This method populates the `mapping` dictionary with user-friendly descriptions and formats of the scatterer properties.
+
+        Returns
+        -------
+        list
+            A list of visual representations for each property in the `mapping` dictionary that has been populated.
+        """
+        for attr in self.attributes:
+            values = getattr(self, attr)
+            if values is None:
+                continue
+
+            if hasattr(values, 'magnitude'):
+                self.mapping["scatterer:" + attr] = PintArray(values.magnitude, dtype=values.units)
+            else:
+                self.mapping["scatterer:" + attr] = [repr(m) for m in values]

PyMieSim/experiment/scatterer/core_shell.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pydantic.dataclasses import dataclass
+from typing import List
+from PyMieSim.binary.interface_sets import CppCoreShellSet
+from PyOptik.material.base_class import BaseMaterial
+from PyMieSim.units import Quantity
+from PyMieSim.experiment.scatterer.base import BaseScatterer
+from PyMieSim.experiment.source.base import BaseSource
+from PyMieSim.experiment.utils import config_dict, Sequential
+
+
+@dataclass(config=config_dict, kw_only=True)
+class CoreShell(BaseScatterer, Sequential):
+    """
+    A data class representing a core-shell scatterer configuration used in PyMieSim simulations.
+
+    This class facilitates the setup and manipulation of core-shell scatterers by providing structured
+    attributes and methods that ensure the scatterers are configured correctly for simulations.
+    It extends the BaseScatterer class, adding specific attributes and methods relevant to core-shell geometries.
+
+    Parameters
+    ----------
+    source : PyMieSim.experiment.source.base.BaseSource
+        Light source configuration for the simulation.
+    core_diameter : Quantity
+        Diameters of the core components.
+    shell_thickness : Quantity
+        Thicknesses of the shell components.
+    core_property : List[BaseMaterial] | List[Quantity]
+        Refractive index or indices of the core.
+    shell_property : List[BaseMaterial] | List[Quantity]
+        Refractive index or indices of the shell.
+    medium_property : List[BaseMaterial] | List[Quantity]
+        BaseMaterial(s) defining the medium, used if `medium_index` is not provided.
+
+    """
+    source: BaseSource
+    core_diameter: Quantity
+    shell_thickness: Quantity
+    core_property: List[BaseMaterial] | List[Quantity]
+    shell_property: List[BaseMaterial] | List[Quantity]
+    medium_property: List[BaseMaterial] | List[Quantity]
+
+    available_measure_list = [
+        'Qsca', 'Qext', 'Qabs', 'Qratio', 'Qforward', 'Qback', 'Qpr',
+        'Csca', 'Cext', 'Cabs', 'Cratio', 'Cforward', 'Cback', 'Cpr', 'a1',
+        'a2', 'a3', 'b1', 'b2', 'b3', 'g', 'coupling',
+    ]
+
+    attributes = ['core_diameter', 'shell_thickness', 'core_property', 'shell_property', 'medium_property']
+
+    def _generate_binding(self) -> None:
+        """
+        Assembles the keyword arguments necessary for C++ binding, tailored for core-shell scatterers.
+        Prepares structured data from scatterer properties for efficient simulation integration.
+
+        This function populates `binding_kwargs` with values formatted appropriately for the C++ backend used in simulations.
+        """
+        self.mapping = {}
+
+        self.binding_kwargs = dict(
+            core_diameter=self.core_diameter,
+            shell_thickness=self.shell_thickness,
+            is_sequential=self.is_sequential
+        )
+
+        mediun_properties = self._add_properties(name='medium', properties=self.medium_property)
+
+        core_properties = self._add_properties(name='core', properties=self.core_property)
+
+        shell_properties = self._add_properties(name='shell', properties=self.shell_property)
+
+        self.binding = CppCoreShellSet(
+            core_diameter=self.core_diameter.to('meter').magnitude,
+            shell_thickness=self.shell_thickness.to('meter').magnitude,
+            core_properties=core_properties,
+            shell_properties=shell_properties,
+            medium_properties=mediun_properties,
+            is_sequential=self.is_sequential,
+        )

PyMieSim/experiment/scatterer/cylinder.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import List
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+from PyMieSim.binary.interface_sets import CppCylinderSet
+from PyOptik.material.base_class import BaseMaterial
+from PyMieSim.experiment.scatterer.base import BaseScatterer
+from PyMieSim.experiment.source.base import BaseSource
+from PyMieSim.experiment.utils import config_dict, Sequential
+
+
+@dataclass(config=config_dict, kw_only=True)
+class Cylinder(BaseScatterer, Sequential):
+    """
+    Represents a cylindrical scatterer configuration for PyMieSim simulations.
+
+    Parameters
+    ----------
+    source : PyMieSim.experiment.source.base.BaseSource
+        Light source configuration for the simulation.
+    diameter : Quantity
+        Diameter(s) of the cylinder in meters.
+    property : List[BaseMaterial] | List[Quantity]
+        Refractive index or indices of the spherical scatterers themselves.
+    medium_property : List[BaseMaterial] | List[Quantity]
+        BaseMaterial(s) defining the medium, used if `medium_index` is not provided.
+    """
+    source: BaseSource
+    diameter: Quantity
+    property: List[BaseMaterial] | List[Quantity]
+    medium_property: List[BaseMaterial] | List[Quantity]
+
+    available_measure_list = [
+        'Qsca', 'Qext', 'Qabs', 'Csca', 'Cext', 'Cabs', 'a11',
+        'a21', 'a12', 'a22', 'a13', 'a23', 'b11', 'b21', 'b12',
+        'b22', 'b13', 'b23', 'coupling',
+    ]
+
+    attributes = ['diameter', 'property', 'medium_property']
+
+    def _generate_binding(self) -> None:
+        """
+        Constructs the keyword arguments necessary for the C++ binding interface, specifically tailored for spherical scatterers.
+        This includes processing material indices and organizing them into a structured dictionary for simulation interaction.
+
+        This method automatically configures the `binding_kwargs` attribute with appropriately formatted values.
+        """
+        self.mapping = {}
+
+        self.binding_kwargs = dict(diameter=self.diameter, is_sequential=self.is_sequential)
+
+        mediun_properties = self._add_properties(name='medium', properties=self.medium_property)
+
+        scatterer_properties = self._add_properties(name='scatterer', properties=self.property)
+
+        self.binding = CppCylinderSet(
+            diameter=self.diameter.to('meter').magnitude,
+            scatterer_properties=scatterer_properties,
+            medium_properties=mediun_properties,
+            is_sequential=self.is_sequential,
+        )

PyMieSim/experiment/scatterer/sphere.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from typing import List
+from pydantic.dataclasses import dataclass
+from PyMieSim.binary.interface_sets import CppSphereSet
+from PyOptik.material.base_class import BaseMaterial
+from PyMieSim.units import Quantity
+from PyMieSim.experiment.scatterer.base import BaseScatterer
+from PyMieSim.experiment.source.base import BaseSource
+from PyMieSim.experiment.utils import config_dict, Sequential
+
+
+@dataclass(config=config_dict, kw_only=True)
+class Sphere(BaseScatterer, Sequential):
+    """
+    A data class that represents a spherical scatterer configuration used in PyMieSim simulations.
+
+    This class provides specific implementations for setting up and binding spherical scatterers
+    with their properties to a simulation environment. It extends the `BaseScatterer` class by
+    adding spherical-specific attributes and methods for handling simulation setups.
+
+    Parameters
+    ----------
+    source : PyMieSim.experiment.source.base.BaseSource
+        Light source configuration for the simulation.
+    diameter : Quantity
+        Diameter(s) of the spherical scatterers in meters.
+    property : List[BaseMaterial] | List[Quantity]
+        Refractive index or indices of the spherical scatterers themselves.
+    medium_property : List, optional
+        BaseMaterial(s) defining the medium, used if `medium_index` is not provided.
+    """
+    source: BaseSource
+    diameter: Quantity
+    property: List[BaseMaterial] | List[Quantity]
+    medium_property: List[BaseMaterial] | List[Quantity]
+
+    available_measure_list = [
+        'Qsca', 'Qext', 'Qabs', 'Qratio', 'Qforward', 'Qback', 'Qpr',
+        'Csca', 'Cext', 'Cabs', 'Cratio', 'Cforward', 'Cback', 'Cpr', 'a1',
+        'a2', 'a3', 'b1', 'b2', 'b3', 'g', 'coupling',
+    ]
+
+    attributes = ['diameter', 'property', 'medium_property']
+
+    def _generate_binding(self):
+        """
+        Constructs the keyword arguments necessary for the C++ binding interface, specifically tailored for spherical scatterers.
+        This includes processing material indices and organizing them into a structured dictionary for simulation interaction.
+
+        This method automatically configures the `binding_kwargs` attribute with appropriately formatted values.
+        """
+        self.mapping = {}
+
+        self.binding_kwargs = dict(diameter=self.diameter, is_sequential=self.is_sequential)
+
+        mediun_properties = self._add_properties(name='medium', properties=self.medium_property)
+
+        scatterer_properties = self._add_properties(name='scatterer', properties=self.property)
+
+        self.binding = CppSphereSet(
+            diameter=self.diameter.to('meter').magnitude,
+            scatterer_properties=scatterer_properties,
+            medium_properties=mediun_properties,
+            is_sequential=self.is_sequential,
+        )

PyMieSim/experiment/setup.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+import pandas as pd
+from pydantic.dataclasses import dataclass
+from PyMieSim.binary.interface_experiment import EXPERIMENT
+from PyMieSim.units import AU, meter, watt
+from typing import Union, Optional, List
+from PyMieSim.experiment.scatterer import Sphere, Cylinder, CoreShell
+from PyMieSim.experiment.detector import Photodiode, CoherentMode
+from PyMieSim.experiment.source import Gaussian, PlaneWave
+from PyMieSim.experiment.dataframe_subclass import PyMieSimDataFrame
+import PyMieSim
+from PyMieSim.binary.interface_sets import CppDetectorSet
+
+
+class EmptyDetector:
+    def __init__(self):
+        self.binding = CppDetectorSet()
+        self.mapping = {}
+
+    def _generate_binding(self, *args, **kwargs):
+        pass
+
+    def _generate_mapping(self, *args, **kwargs):
+        pass
+
+@dataclass
+class Setup:
+    """
+    Orchestrates the setup and execution of light scattering experiments using PyMieSim.
+
+    Attributes:
+        scatterer (Union[Sphere, Cylinder, CoreShell]): Configuration for the scatterer in the experiment.
+            Defines the physical properties of the particle being studied.
+        source (Union[Gaussian, PlaneWave]): Configuration for the light source. Specifies the characteristics
+            of the light (e.g., wavelength, polarization) illuminating the scatterer.
+        detector (Union[Photodiode, CoherentMode, None], optional): Configuration for the detector, if any. Details the
+            method of detection for scattered light, including positional and analytical parameters. Defaults to None.
+
+    Methods provide functionality for initializing bindings, generating parameter tables for visualization,
+    and executing the simulation to compute and retrieve specified measures.
+    """
+    scatterer: Union[Sphere, Cylinder, CoreShell]
+    source: Union[Gaussian, PlaneWave]
+    detector: Optional[Union[Photodiode, CoherentMode]] = EmptyDetector()
+
+    def __post_init__(self):
+        """
+        Initializes the experiment by setting the source for the scatterer and establishing bindings
+        between the components and the simulation environment.
+        """
+        self.scatterer._generate_binding()
+
+        self.source._generate_binding()
+
+        self.detector._generate_binding()
+
+        self.scatterer.source = self.source
+
+        self.binding = EXPERIMENT(debug_mode=PyMieSim.debug_mode)
+
+    def _generate_mapping(self) -> None:
+        self.source._generate_mapping()
+        self.scatterer._generate_mapping()
+        self.detector._generate_mapping()
+
+    def get_sequential(self, measure: str) -> numpy.ndarray:
+        """
+        Executes the simulation to compute and retrieve the specified measures in a sequential manner contrary to the standard get function.
+        This means that ranges are not iterated in a structured fashion into a dataframe but are only run once.
+        This methods was developed for specific aims, for the best suited vizualization tools go for the .get() method.
+
+        Parameters
+        ----------
+        measures : str
+            The measure to be computed in the simulation, provided as arguments by the user.
+        Returns
+        -------
+        numpy.ndarray
+            An array containing the computed measures.
+        """
+        method_name = f'get_{measure}_sequential'
+
+        # Compute the values using the binding method
+        return getattr(self.binding, method_name)(
+            scatterer_set=self.scatterer.binding,
+            source_set=self.source.binding,
+            detector_set=self.detector.binding
+        )
+
+    def get(self, *measures, scale_unit: bool = False, drop_unique_level: bool = True, add_units: bool = True, as_numpy: bool = False) -> pd.DataFrame:
+        """
+        Run the simulation to compute specified measures and return the results.
+
+        Parameters
+        ----------
+        measures : tuple
+            Variable-length tuple of measure names to compute, specified by the user.
+        scale_unit : bool, optional
+            If True, scales the units in the output DataFrame to the most appropriate units. Defaults to False.
+        drop_unique_level : bool, optional
+            If True, removes levels from the DataFrame's MultiIndex where only one unique value exists, simplifying the DataFrame. Defaults to True.
+        add_units : bool, optional
+            If True, includes units in the output DataFrame using pint quantities. If False, the output will contain raw numeric values only. Defaults to True.
+        as_numpy : bool, optional
+            If True, returns the result as a NumPy array instead of a DataFrame. Defaults to False.
+
+        Returns
+        -------
+        pd.DataFrame or np.ndarray
+            A DataFrame containing the computed measures with optional units and simplified MultiIndex, or a NumPy array if `as_numpy` is set to True.
+        """
+        measures = set(numpy.atleast_1d(measures))
+
+        if 'coupling' in measures:
+            assert self.detector is not None, "To compute the coupling power the detector has to be provided to Setup class"
+
+        if as_numpy:
+            return self._get_measure_array(measures)
+
+        is_complex = self._is_complex_measure(measures)
+
+        df = self.generate_dataframe(
+            measure=list(measures),
+            is_complex=is_complex,
+            drop_unique_level=drop_unique_level
+        )
+
+        df = self._get_measure_dataframe(df, measures, is_complex, add_units)
+
+        # Optionally scale the units in the DataFrame
+        if scale_unit:
+            df = self.scale_dataframe_units(df)
+
+        return df
+
+    def _is_complex_measure(self, measures: set) -> bool:
+        """
+        Determines if the measures involve complex values based on measure names.
+        No complex value are computed now, as the a & b parameters a return as absolute values for convienience.
+
+        Parameters
+        ----------
+        measures : set
+            A set of measures requested for computation.
+
+        Returns
+        -------
+        bool
+            True if any measure involves complex values, False otherwise.
+        """
+        return False
+
+    def _get_measure_array(self, measures: List[str]) -> pd.DataFrame:
+        """
+        Retrieve data for specified measures and return them as a NumPy array.
+
+        Parameters
+        ----------
+        measures : List[str]
+            List of measure names to compute.
+
+        Returns
+        -------
+        np.ndarray
+            A NumPy array containing computed values for the specified measures.
+        """
+        output_array = []
+
+        for measure in measures:
+            method_name = f'get_{measure}'
+
+            method = getattr(self.binding, method_name)
+
+            array = method(
+                scatterer_set=self.scatterer.binding,
+                source_set=self.source.binding,
+                detector_set=self.detector.binding
+            )
+
+            output_array.append(array)
+
+        return numpy.asarray(output_array).squeeze()
+
+    def _get_measure_dataframe(self, df: pd.DataFrame, measures: List[str], is_complex: bool, add_units: bool) -> pd.DataFrame:
+        """
+        Populate a DataFrame with computed values for specified measures.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            DataFrame in which to store computed values for the specified measures.
+        measures : List[str]
+            List of measure names to compute and add to the DataFrame.
+        is_complex : bool
+            Indicates whether any of the measures involve complex values.
+        add_units : bool
+            If True, adds units to the computed values in the DataFrame.
+
+        Returns
+        -------
+        pd.DataFrame
+            Updated DataFrame with computed values for the specified measures, with optional units if `add_units` is True.
+        """
+        for measure in measures:
+
+            method_name = f'get_{measure}'
+
+            # Compute the values using the binding method
+            array = getattr(self.binding, method_name)(
+                scatterer_set=self.scatterer.binding,
+                source_set=self.source.binding,
+                detector_set=self.detector.binding
+            )
+
+            # Determine the unit based on the measure type
+            dtype = self._determine_dtype(measure)
+
+            # Set the data in the DataFrame
+            df = self._set_data(
+                measure=measure,
+                dataframe=df,
+                array=array,
+                dtype=dtype,
+                is_complex=is_complex,
+                add_units=add_units
+            )
+
+        return df
+
+    def _determine_dtype(self, measure: str):
+        """
+        Determine the appropriate unit (dtype) based on the measure's first character.
+
+        Parameters
+        ----------
+        measure : str
+            The measure type to determine the unit for.
+
+        Returns
+        -------
+        pint.Quantity
+            The appropriate unit for the measure.
+        """
+        match measure[0]:
+            case 'C':
+                return meter**2  # Cross-section measure
+            case 'c':
+                assert self.detector is not None, "Detector needs to be defined in order to measure coupling"
+                return watt  # Power measure
+            case _:
+                return AU  # Arbitrary units for other measures
+
+    def _set_data(self, measure: str, dataframe: pd.DataFrame, array: numpy.ndarray, dtype: type, is_complex: bool, add_units: bool) -> None:
+        """
+        Sets the real and imaginary parts of a NumPy array as separate 'real' and 'imag' levels
+        in the 'type' index of a pandas DataFrame.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The target DataFrame with a MultiIndex that includes a 'type' level (with possible values 'real' and 'imag').
+        array : np.ndarray
+            A complex NumPy array whose real and imaginary parts will be assigned to the DataFrame.
+        dtype : type
+            The data type to cast the real and imaginary parts into, using PintArrays.
+        is_complex : bool
+            A flag that indicates whether the input array is complex. If False, the 'type' level is not saved, and the array is treated as purely real.
+        """
+        dtype = f'pint[{dtype}]' if add_units else float
+
+        if is_complex:
+            dataframe[(measure, 'real')] = pd.Series(array.ravel().real, dtype=dtype, index=dataframe.index)
+            dataframe[(measure, 'imag')] = pd.Series(array.ravel().imag, dtype=dtype, index=dataframe.index)
+
+        else:
+            dataframe[measure] = pd.Series(array.ravel(), dtype=dtype, index=dataframe.index)
+
+        return dataframe
+
+    def scale_dataframe_units(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """
+        Scales the units of all columns in a pandas DataFrame to the most compact unit
+        based on the maximum value in each column.
+
+        This method iterates over each column in the DataFrame, retrieves the maximum value's
+        unit, and converts the entire column to that unit using pint's unit system.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame where each column contains PintArray elements with units.
+
+        Returns
+        -------
+        pd.DataFrame
+            The updated DataFrame with all columns scaled to the most compact unit based on the maximum value in each column.
+        """
+        max_value_unit = dataframe.max().max().to_compact().units
+
+        for name, col in dataframe.items():
+            dataframe[name] = col.pint.to(max_value_unit)
+
+        return dataframe
+
+    def generate_dataframe(self, measure, is_complex: bool = False, drop_unique_level: bool = True):
+        """
+        Generates a pandas DataFrame with a MultiIndex based on the mapping
+        of 'source' and 'scatterer' from an experiment object.
+
+        Parameters
+        ----------
+        experiment :
+            The experiment object containing 'source' and 'scatterer' mappings.
+
+        Returns
+        -------
+        pd.DataFrame
+            A DataFrame with a MultiIndex created from the experiment mappings.
+        """
+        self._generate_mapping()
+
+        iterables = dict()
+
+        iterables.update(self.source.mapping)
+
+        iterables.update(self.scatterer.mapping)
+
+        if self.detector is not None:
+            iterables.update(self.detector.mapping)
+
+        if drop_unique_level:
+            _iterables = {
+                k: v for k, v in iterables.items() if len(v) > 1
+            }
+
+            if len(_iterables) != 0:
+                iterables = _iterables
+
+        # Create a MultiIndex from the iterables
+        row_index = pd.MultiIndex.from_product(
+            iterables.values(), names=iterables.keys()
+        )
+
+        if is_complex:
+            columns = pd.MultiIndex.from_product(
+                [measure, ['real', 'imag']],
+                names=['data', 'type']
+            )
+        else:
+            columns = pd.MultiIndex.from_product([measure], names=['data'])
+
+        # Return an empty DataFrame with the generated MultiIndex
+        return PyMieSimDataFrame(columns=columns, index=row_index)

PyMieSim/experiment/source/__init__.py

@@ -0,0 +1,2 @@
+from .gaussian import Gaussian
+from .planewave import PlaneWave