PyMieSim 3.6.0__cp313-cp313-macosx_14_0_arm64.whl

PyMieSim/__init__.py

@@ -0,0 +1,16 @@
+"""PyMieSim package initialization.
+
+This module exposes the package version and sets up unit handling.  Importing
+``Quantity`` here ensures proper initialization on all platforms.  Removing this
+import causes unit tests to fail on macOS systems.
+"""
+
+from PyMieSim.units import Quantity  # required for unit registration on macOS
+
+try:
+    from ._version import version as __version__
+
+except ImportError:
+    __version__ = "0.0.0"
+
+debug_mode = False

PyMieSim/__main__.py

@@ -0,0 +1,9 @@
+
+"""Entry point for launching the experimental PyMieSim GUI."""
+
+from PyMieSim.gui.interface import OpticalSetupGUI
+
+
+if __name__ == '__main__':
+    _gui = OpticalSetupGUI()
+    _gui.run(host='127.0.0.1', port='8050', open_browser=True)

PyMieSim/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '3.6.0'
+__version_tuple__ = version_tuple = (3, 6, 0)

PyMieSim/directories.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pathlib import Path
+import PyMieSim
+
+__all__ = [
+    'root_path',
+    'validation_data_path',
+    'doc_path',
+    'logo_path',
+    'doc_css_path'
+]
+
+root_path = Path(PyMieSim.__path__[0])
+
+validation_data_path = root_path.joinpath('validation_data')
+
+doc_path = root_path.parents[0].joinpath('docs')
+
+logo_path = doc_path.joinpath('images/logo.png')
+
+doc_css_path = doc_path.joinpath('source/_static/default.css')
+
+if __name__ == '__main__':
+    for path_name in __all__:
+        path = locals()[path_name]
+        print(path)
+        assert path.exists(), f"Path {path_name} do not exists"
+
+# -

PyMieSim/experiment/__init__.py

@@ -0,0 +1 @@
+from .setup import Setup  # noqa: F401, W292

PyMieSim/experiment/dataframe_subclass.py

@@ -0,0 +1,220 @@
+from MPSPlots.styles import mps
+import matplotlib.pyplot as plt
+import pandas as pd
+import numpy as np
+from typing import Optional
+
+class PyMieSimDataFrame(pd.DataFrame):
+    """
+    A subclass of pandas DataFrame with custom plot methods tailored for
+    multi-indexed data containing pint-quantified values.
+    """
+
+    @property
+    def _constructor(self):
+        """
+        Ensures that operations returning DataFrames return instances of PyMieSimDataFrame.
+        """
+        return PyMieSimDataFrame
+
+    def _validate_axis(self, axis: str) -> None:
+        # Validate that 'x' is a valid index level.
+        if axis not in self.index.names:
+            available = ", ".join(self.index.names)
+            raise ValueError(f"x parameter '{axis}' is not in the DataFrame index. Available index levels: {available}")
+
+    def _get_complementary_axis(self, *axis) -> tuple:
+        return [level for level in self.index.names if level not in axis]
+
+    def plot(self,
+        x: str,
+        std: Optional[str] = None,
+        alpha: float = 0.4,
+        ax: Optional[plt.Axes] = None,
+        show: bool = True,
+        xscale: bool = 'linear',
+        yscale: bool = 'linear',
+        **kwargs) -> plt.Axes:
+        """
+        Plots the DataFrame using a specified MultiIndex level for the x-axis.
+        Optionally, if a standard deviation level is provided, it will also
+        plot the mean ± std.
+
+        Parameters
+        ----------
+        x : str
+            The MultiIndex level to use for the x-axis.
+        alpha : float, optional
+            The transparency level for the shaded standard deviation region.
+        std : Optional[str], optional
+            The MultiIndex level used for standard deviation calculation.
+        ax : Optional[plt.Axes], optional
+            The matplotlib Axes on which to plot. If None, a new Axes is created.
+        show : bool, optional
+            If True, displays the plot.
+        **kwargs : dict
+            Additional keyword arguments passed to the underlying plotting functions.
+
+        Returns
+        -------
+        plt.Axes
+            The matplotlib Axes with the plot.
+        """
+        self._validate_axis(axis=x)
+
+        if std is not None:
+            self._validate_axis(axis=std)
+
+
+        with plt.style.context(mps):
+            if ax is None:
+                _, ax = plt.subplots()
+
+            ax.set(xscale=xscale, yscale=yscale)
+
+            if std is not None:
+                self._plot_with_std(ax=ax, x=x, std=std, alpha=alpha, **kwargs)
+            else:
+                self._plot_without_std(ax=ax, x=x, **kwargs)
+
+            self._format_legend(ax)
+
+            if show:
+                plt.show()
+
+            return ax
+
+    def _plot_with_std(self, ax: plt.Axes, x: str, std: str, alpha: float = 0.5, **kwargs) -> None:
+        """
+        Plot the mean with standard deviation shading.
+        Expects the DataFrame to have a MultiIndex and a 'pint' attribute.
+
+        Parameters
+        ----------
+        ax : plt.Axes
+            The matplotlib Axes to plot on.
+        x : str
+            The MultiIndex level to use for the x-axis.
+        std : str
+            The MultiIndex level used for standard deviation calculation.
+        alpha : float, optional
+            Transparency for the std shading.
+        show : bool, optional
+            Whether to call plt.show() after plotting.
+        **kwargs : dict
+            Additional keyword arguments for line styling.
+        """
+
+        # Determine levels to unstack
+        no_std_levels = self._get_complementary_axis(std)
+        no_x_levels = self._get_complementary_axis(x, std)
+
+        # Calculate standard deviation and mean, preserving pint units
+        std_df = (
+            self.pint.dequantify()
+            .unstack(no_std_levels)
+            .apply(np.std)
+            .to_frame(name="std")
+            .unstack("unit")
+            .pint.quantify()
+        )
+        mean_df = (
+            self.pint.dequantify()
+            .unstack(no_std_levels)
+            .apply(np.mean)
+            .to_frame(name="mean")
+            .unstack("unit")
+            .pint.quantify()
+        )
+
+        combined_df = pd.concat([mean_df, std_df], axis=1)
+        groupby_levels = self.columns.names + no_x_levels
+
+        for name, group in combined_df.groupby(groupby_levels):
+            group = group.droplevel(groupby_levels)
+
+            label = [item for pair in zip(groupby_levels, name) for item in pair]
+
+            label = " : ".join(map(str, label))
+
+            ax.plot(group.index, group['mean'], linewidth=1, linestyle='--', **kwargs)
+            ax.fill_between(
+                x=group.index,
+                y1=group['mean'] + group['std'],
+                y2=group['mean'] - group['std'],
+                alpha=alpha,
+                edgecolor="black",
+                label=label
+            )
+
+        ax.legend()
+
+    def _format_legend(self, ax: plt.Axes) -> None:
+        leg = ax.get_legend()  # Get the existing legend from the axes
+        for text in leg.get_texts():
+            original_label = text.get_text()
+            new_label = original_label.replace(')', '').replace('(', '').replace(', ', ' | ')
+            text.set_text(new_label)
+
+    def _plot_without_std(self, ax: plt.Axes, x: str, **kwargs) -> None:
+        """
+        Plots the data without standard deviation shading.
+        Handles both real and imaginary parts for complex data.
+
+        Parameters
+        ----------
+        ax : plt.Axes
+            The matplotlib Axes on which to plot.
+        x : str
+            The index level to use for the x-axis.
+        y : Optional[str], optional
+            The column to use for the y-axis. If None, the first available column is used.
+        show : bool, optional
+            Whether to display the plot.
+        log_scale_x : bool, optional
+            If True, sets a logarithmic scale for the x-axis.
+        log_scale_y : bool, optional
+            If True, sets a logarithmic scale for the y-axis.
+        **kwargs : dict
+            Additional keyword arguments for the plot.
+
+        Returns
+        -------
+        None
+        """
+        df = self.copy()
+
+        groupby_levels = df._get_complementary_axis(x)
+
+        df = df.unstack(groupby_levels)
+
+        if isinstance(df.index, pd.MultiIndex) and df.index.nlevels == 1:
+            df.index = df.index.get_level_values(0)
+
+        super(PyMieSimDataFrame, df).plot(ax=ax, **kwargs)
+
+        legend = ax.legend()
+
+        legend.set_title(' | '.join(df.columns.names))
+
+    def add_weight(self, weight_index: str, weight: np.ndarray) -> "PyMieSimDataFrame":
+
+        self._validate_axis(axis=weight_index)
+
+        stacking_index = self._get_complementary_axis(weight_index)
+
+        return (
+            self
+            .unstack(stacking_index)
+            .multiply(weight.squeeze(), axis='index')
+            .stack(stacking_index)
+        )
+
+    def sum_over(self, axis: str) -> "PyMieSimDataFrame":
+
+        self._validate_axis(axis=axis)
+
+        stacking_index = [name for name in self.index.names if name != axis]
+
+        return self.groupby(stacking_index).sum()#.to_frame().T
+

PyMieSim/experiment/detector/__init__.py

@@ -0,0 +1,2 @@
+from .photodiode import Photodiode
+from .coherent_mode import CoherentMode

PyMieSim/experiment/detector/base.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+import numpy
+from pint_pandas import PintArray
+from pydantic import field_validator
+from PyMieSim.binary.interface_sets import CppDetectorSet
+from PyMieSim.units import Quantity, radian, degree
+
+
+class BaseDetector:
+    """
+    A base class for defining detectors in Mie scattering simulations.
+
+    This class provides the foundational structure for defining detectors that interface with C++ backends to perform
+    high-performance scattering calculations. It is designed to handle common parameters such as numerical aperture (NA),
+    angular offsets, rotation, and polarization. Subclasses should extend this base class to create specific detector types.
+
+    Attributes
+    ----------
+    mode_number : str
+        The mode number used in the detection process, identifying the angular momentum mode involved.
+    NA : Quantity
+        The numerical aperture of the detector, typically a float-like value wrapped in a physical unit (e.g., steradian).
+    gamma_offset : Quantity
+        The angular offset in the gamma direction (in degrees).
+    phi_offset : Quantity
+        The angular offset in the phi direction (in degrees).
+    rotation : Quantity
+        The rotational angle of the detector (in degrees).
+    mean_coupling : bool
+        Specifies whether the mean coupling of detected modes is to be considered (default is False).
+    coherent : bool
+        Specifies whether the detection process is coherent (default is True).
+    sampling : Optional[Quantity]
+        The sampling rate of the detector. If not specified, defaults to 200.
+    polarization_filter : Optional[Quantity]
+        The polarization filter angle (in degrees). Defaults to NaN if not provided.
+
+    Methods
+    -------
+    validate_polarization_filter(cls, value)
+        Ensures that the polarization filter is either None or a Quantity with angle units (degree or radian).
+    validate_angle_quantity(cls, value)
+        Validates that angles like gamma_offset, phi_offset, and rotation are Quantities with angle units.
+    validate_au_quantity(cls, value)
+        Ensures that numerical values are correctly cast as NumPy arrays.
+    __post_init__()
+        Initializes the internal detector mapping and binds the detector to the C++ backend.
+    _initialize_binding()
+        Sets up the C++ bindings required for efficient simulation by passing detector parameters.
+    _generate_mapping()
+        Generates a mapping of scatterer properties to be used for visualization purposes.
+    """
+    @field_validator('mode_number', mode='plain')
+    def _validate_mode_number(cls, mode_number):
+        """Ensure mode numbers are valid and belong to supported families."""
+        mode_number = numpy.atleast_1d(mode_number).astype(str)
+        for mode in mode_number:
+            if mode[:2] not in ['LP', 'HG', 'LG', 'NC']:
+                raise ValueError(f'Invalid mode family {mode[:2]}. Must be one of: LP, HG, LG, NC')
+        return mode_number
+
+    @field_validator('polarization_filter', mode='plain')
+    def validate_polarization(cls, value):
+        """
+        Validates the polarization filter. If not provided, defaults to NaN degrees.
+        Ensures the value has angular units (degree or radian).
+
+        Parameters
+        ----------
+        value : Any
+            The input value for polarization filter.
+
+        Returns
+        -------
+        numpy.ndarray
+            A NumPy array containing the validated and converted polarization filter value.
+        """
+        if value is None:
+            value = numpy.nan * degree
+
+        if not isinstance(value, Quantity) or not value.check(degree):
+            raise ValueError(f"{value} must have angle units (degree or radian).")
+
+        return numpy.atleast_1d(value).astype(float)
+
+    @field_validator('gamma_offset', 'phi_offset', 'rotation', mode='plain')
+    def validate_angle_quantity(cls, value):
+        """
+        Ensures that angular quantities (gamma_offset, phi_offset, rotation) are correctly formatted as Quantities with angle units.
+
+        Parameters
+        ----------
+        value : Any
+            The input value for the angle.
+
+        Returns
+        -------
+        numpy.ndarray
+            A NumPy array containing the validated and converted angle value.
+        """
+        if not isinstance(value, Quantity) or not value.check(degree):
+            raise ValueError(f"{value} must be a Quantity with angle units [degree or radian].")
+
+        return numpy.atleast_1d(value)
+
+    @field_validator('NA', 'cache_NA', 'sampling', mode='plain')
+    def validate_au_quantity(cls, value):
+        """
+        Ensures that numerical values such as numerical aperture (NA) and sampling rate are correctly cast into NumPy arrays.
+
+        Parameters
+        ----------
+        value : Any
+            The input value to be validated.
+
+        Returns
+        -------
+        numpy.ndarray
+            A NumPy array representing the validated input value.
+        """
+        if not isinstance(value, Quantity) or not value.check(degree):
+            raise ValueError(f"{value} must be a Quantity with arbitrary units [AU].")
+
+        if not isinstance(value, numpy.ndarray):
+            value = numpy.atleast_1d(value)
+
+        return value
+
+    def _generate_binding(self) -> None:
+        """
+        Initializes the C++ binding for the detector using the given simulation parameters. This ensures that the
+        detector is correctly linked to the backend, enabling high-performance Mie scattering calculations.
+
+        Sets up parameters such as mode number, sampling rate, NA, and various offsets for the simulation.
+        """
+        self.binding_kwargs = {
+            "mode_number": self.mode_number,
+            "sampling": self.sampling,
+            "NA": self.NA,
+            "cache_NA": self.cache_NA,
+            "polarization_filter": self.polarization_filter.to(radian).magnitude if self.polarization_filter is not None else numpy.nan,
+            "phi_offset": self.phi_offset.to(radian).magnitude,
+            "gamma_offset": self.gamma_offset.to(radian).magnitude,
+            "rotation": self.rotation.to(radian).magnitude,
+            "is_sequential": self.is_sequential
+        }
+
+        # Ensure all values are at least 1D arrays for compatibility
+        self.binding_kwargs = {k: numpy.atleast_1d(v) for k, v in self.binding_kwargs.items()}
+
+        # Additional detector settings
+        self.binding_kwargs["mean_coupling"] = self.mean_coupling
+        self.binding_kwargs["coherent"] = self.coherent
+
+        self.binding = CppDetectorSet(**self.binding_kwargs)
+
+    def _generate_mapping(self) -> None:
+        """
+        Updates the internal mapping of the detector with current parameter values, allowing for visual representation
+        of the detector's properties in a tabular format (useful for debugging and visualization).
+
+        Attributes like mode number, NA, offsets, and sampling are included in this mapping.
+        """
+        self.mapping = {}
+        self.mapping.update({'detector:mode_number': self.mode_number})
+
+        for attr in ['NA', 'sampling', 'cache_NA', 'phi_offset', 'gamma_offset', 'rotation', 'polarization_filter']:
+            self.mapping["detector:" + attr] = PintArray(getattr(self, attr), dtype=getattr(self, attr).units)

PyMieSim/experiment/detector/coherent_mode.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+from pydantic.dataclasses import dataclass
+from typing import List, Union, Optional
+from PyMieSim.experiment.detector.base import BaseDetector
+from PyMieSim.units import Quantity, degree, AU
+from PyMieSim.experiment.utils import config_dict, Sequential
+
+@dataclass(config=config_dict)
+class CoherentMode(BaseDetector, Sequential):
+    """
+    Coherent mode detector for Mie scattering simulations, handling coherent detection modes.
+
+    This detector is designed specifically for coherent modes, such as LP, HG, LG, and NC modes, which require specific handling
+    in Mie scattering experiments.
+
+    Parameters
+    ----------
+    mode_number : Union[List[str], str]
+        Mode number(s) involved in the detection.
+    NA : Union[List[float], float]
+        Numerical aperture(s) of the detector.
+    gamma_offset : Quantity
+        Gamma angular offset (in degrees).
+    phi_offset : Quantity
+        Phi angular offset (in degrees).
+    rotation : Quantity
+        Rotation angle of the detector.
+    sampling : Union[List[int], int]
+        Sampling rate(s) for the detector.
+    polarization_filter : Optional[Quantity]
+        Polarization filter angle (in degrees).
+    mean_coupling : Optional[bool]
+        Whether mean coupling is used. Defaults to False.
+    coherent : bool
+        Specifies if the detection is coherent. Defaults to True.
+    """
+    mode_number: Union[List[str], str]
+    NA: Quantity
+    gamma_offset: Quantity
+    phi_offset: Quantity
+    rotation: Quantity
+    mean_coupling: bool
+    coherent: bool = True
+    mean_coupling: Optional[bool] = False
+    cache_NA: Quantity = (0.,) * AU
+    sampling: Optional[Quantity] = (200,) * AU
+    polarization_filter: Optional[Quantity | None] = (numpy.nan, ) * degree

PyMieSim/experiment/detector/photodiode.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from typing import Optional
+import numpy
+from dataclasses import field
+from pydantic.dataclasses import dataclass
+from PyMieSim.units import Quantity, degree, AU
+from typing import Tuple
+from PyMieSim.experiment.detector.base import BaseDetector
+from PyMieSim.experiment.utils import config_dict, Sequential
+
+
+@dataclass(config=config_dict)
+class Photodiode(BaseDetector, Sequential):
+    """
+    Photodiode detector tailored for Mie scattering simulations, extending BaseDetector with specific features.
+
+    Parameters
+    ----------
+    NA : Union[List[float], float]
+        Numerical aperture(s) of the detector.
+    gamma_offset : Quantity
+        Gamma angular offset (in degrees).
+    phi_offset : Quantity
+        Phi angular offset (in degrees).
+    polarization_filter : Optional[Quantity]
+        Polarization filter angle (in degrees).
+    sampling : Union[List[int], int]
+        Sampling rate(s) for the detector.
+    mean_coupling : bool
+        Whether mean coupling is used. Defaults to True.
+    rotation : Quantity
+        Rotation angle of the detector. Defaults to 0 degrees.
+    coherent : bool
+        Indicates if the detection is coherent. Defaults to False.
+    mode_number : str
+        Mode number of the detector. Defaults to 'NC00'.
+    """
+    NA: Quantity
+    gamma_offset: Quantity
+    phi_offset: Quantity
+    mean_coupling: bool
+    coherent: bool
+    cache_NA: Quantity = (0.,) * AU
+    sampling: Optional[Quantity] = (200,) * AU
+    polarization_filter: Optional[Quantity | None] = (numpy.nan, ) * degree
+    mode_number: Tuple[str] = field(default_factory=lambda: ['NC00'], init=True)
+    rotation: Quantity = field(default=(0,) * degree, init=True)
+
+    coherent: bool = field(default=False, init=False)
+    mean_coupling: bool = field(default=False, init=False)
+

PyMieSim/experiment/scatterer/__init__.py

@@ -0,0 +1,4 @@
+from .sphere import Sphere
+from .cylinder import Cylinder
+from .core_shell import CoreShell
+from .base import BaseScatterer