PyMieSim 3.6.0__cp313-cp313-win_amd64.whl

PyMieSim/single/scatterer/sphere.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+import pyvista
+from PyOptik.material.base_class import BaseMaterial
+
+from PyMieSim import units
+from PyMieSim.single.scatterer.base import BaseScatterer
+from PyMieSim.binary.interface_scatterer import SPHERE
+from PyMieSim.single.source.base import BaseSource
+
+
+# @dataclass(config=config_dict, kw_only=True)
+class Sphere(SPHERE, BaseScatterer):
+    """
+    Class representing a homogeneous spherical scatterer.
+
+    Parameters
+    ----------
+    diameter : units.Quantity
+        Diameter of the cylindrical scatterer, given in meters.
+    property : units.Quantity or BaseMaterial
+        Defines either the refractive index (`Quantity`) or material (`BaseMaterial`) of the scatterer. Only one can be provided.
+
+    """
+    diameter: units.Quantity
+    property: units.Quantity | BaseMaterial
+    medium_property: units.Quantity | BaseMaterial
+    source: BaseSource
+
+    property_names = [
+        "size_parameter", "radius", "volume", "cross_section", "g",
+        "Qsca", "Qext", "Qabs", "Qback", "Qratio", "Qpr",
+        "Csca", "Cext", "Cabs", "Cback", "Cratio", "Cpr"
+    ]
+
+
+    def __init__(self, diameter: units.Quantity, property: units.Quantity | BaseMaterial, medium_property: units.Quantity | BaseMaterial, source: BaseSource):
+        """
+        Initialize the Sphere scatterer with its diameter and material properties.
+
+        Parameters
+        ----------
+        diameter : units.Quantity
+            Diameter of the sphere in meters.
+        property : units.Quantity or BaseMaterial
+            Refractive index or material of the sphere.
+        medium_property : units.Quantity
+            Refractive index of the surrounding medium.
+        source : Source
+            Source object associated with the scatterer.
+        """
+        self.diameter = self._validate_units(diameter, dimension='distance', units=units.meter)
+
+        self.property = self._validate_property(property)
+        self.medium_property = self._validate_property(medium_property)
+        self.source = source
+
+        self.index, self.material = self._assign_index_or_material(self.property)
+        self.medium_index, self.medium_material = self._assign_index_or_material(self.medium_property)
+
+        super().__init__(
+            diameter=diameter.to(units.meter).magnitude,
+            refractive_index=self.index.to(units.RIU).magnitude,
+            medium_refractive_index=self.medium_index.to(units.RIU).magnitude,
+            source=self.source
+        )
+
+    @property
+    def radius(self) -> units.Quantity:
+        """Return the radius of the sphere."""
+        return self.diameter / 2
+
+    @property
+    def volume(self) -> units.Quantity:
+        """Return the volume of the sphere."""
+        vol = (4/3) * numpy.pi * (self.radius ** 3)
+        return vol.to(units.meter ** 3)
+
+    def _add_to_3d_ax(self, scene: pyvista.Plotter, color: str = 'black', opacity: float = 1.0) -> None:
+        """
+        Adds a 3D cone representation to the given PyVista plotting scene.
+
+        The cone represents the acceptance angle determined by the numerical aperture (NA) of the system.
+        The cone is positioned at the origin and points downward along the z-axis.
+
+        Parameters
+        ----------
+        scene : pyvista.Plotter
+            The 3D plotting scene to which the cone will be added.
+        color : str
+            The color of the cone mesh. Default is 'red'.
+        opacity : float
+            The opacity of the cone mesh. Default is 0.8.
+
+        """
+        # Create the cone mesh
+        shape = pyvista.Sphere(
+            center=(0.0, 0.0, 0.0),
+            radius=0.1,
+            theta_resolution=100,
+            phi_resolution=100
+        )
+
+        # Add the cone mesh to the scene
+        scene.add_mesh(shape, color=color, opacity=opacity)
+

PyMieSim/single/source/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseSource
+from .gaussian import Gaussian
+from .planewave import PlaneWave

PyMieSim/single/source/base.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from PyMieSim import units
+
+class BaseSource(units.UnitsValidation):
+    pass

PyMieSim/single/source/gaussian.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+import pyvista
+from PyMieSim import units
+from PyMieSim.polarization import BasePolarization
+from PyMieSim.binary.interface_source import GAUSSIAN
+from PyMieSim.single.source.base import BaseSource
+
+
+class Gaussian(GAUSSIAN, BaseSource):
+    amplitude: units.Quantity
+
+    def __init__(self,
+        wavelength: units.Quantity,
+        polarization: units.Quantity | BasePolarization,
+        optical_power: units.Quantity,
+        NA: units.Quantity) -> None:
+        """
+        Initializes a Gaussian light source for light scattering simulations, characterized by its optical power and numerical aperture.
+
+        Parameters
+        ----------
+
+        wavelength: units.Quantity
+            Wavelength of the light field in meters.
+        polarization : units.Quantity | BasePolarization
+            Polarization state of the light field, if float is given it is assumed Linear polarization of angle theta.
+        optical_power: units.Quantity
+            Optical power of the source in Watts.
+        NA: units.Quantity
+            Numerical aperture of the source.
+        """
+        self.wavelength = self._validate_units(wavelength, dimension="distance", units=units.meter)
+        self.optical_power = self._validate_units(optical_power, dimension="power", units=units.watt)
+        self.NA = self._validate_units(NA, dimension="arbitrary", units=units.AU)
+        self.polarization = self._validate_source_polarization(polarization)
+
+        self.wavenumber = 2 * numpy.pi / self.wavelength
+        self.waist = self.wavelength / (self.NA * numpy.pi)
+        self.peak_intensity = 2 * self.optical_power / (numpy.pi * self.waist**2)
+
+
+        super().__init__(
+            wavelength=self.wavelength.to(units.meter).magnitude,
+            jones_vector=self.polarization.element[0],
+            optical_power=self.optical_power.to(units.watt).magnitude,
+            NA=self.NA.to(units.AU).magnitude,
+        )
+
+    def numerical_aperture_to_angle(self, numerical_aperture: float) -> float:
+        """
+        Convert numerical aperture (NA) to angle in radians.
+
+        Parameters
+        ----------
+        NA : float
+            The numerical aperture.
+
+        Returns
+        -------
+        float
+            The angle in radians.
+        """
+        return numpy.arcsin(numerical_aperture) if numerical_aperture <= 1.0 else numpy.arcsin(numerical_aperture - 1) + numpy.pi / 2
+
+    def plot(self, color: str = 'red', opacity: float = 0.8, show_axis_label: bool = False) -> None:
+        """
+        Plots the 3D structure of the Gaussian source.
+
+        This method creates a 3D plot of the Gaussian source, adds the structure to the plot,
+        and optionally displays axis labels.
+
+        Parameters
+        ----------
+        color : str
+            The color of the structure in the plot. Default is 'red'.
+        opacity : float
+            The opacity of the structure. Default is 0.8.
+        show_axis_label : bool
+            If True, axis labels will be shown. Default is False.
+
+        """
+        # Create a 3D plotting scene
+        scene = pyvista.Plotter()
+
+        # Add the structure to the scene
+        self._add_to_3d_ax(scene=scene, color=color, opacity=opacity)
+
+        # Add axes at the origin, optionally showing axis labels
+        scene.add_axes_at_origin(labels_off=not show_axis_label)
+
+        # Add a translucent sphere to the scene
+        sphere = pyvista.Sphere(radius=1)
+        scene.add_mesh(sphere, opacity=0.3)
+
+        # Display the scene
+        scene.show()
+
+    def _add_to_3d_ax(self, scene: pyvista.Plotter, color: str = 'red', opacity: float = 0.8) -> None:
+        """
+        Adds a 3D cone representation to the given PyVista plotting scene.
+
+        The cone represents the acceptance angle determined by the numerical aperture (NA) of the system.
+        The cone is positioned at the origin and points downward along the z-axis.
+
+        Parameters
+        ----------
+        scene : pyvista.Plotter
+            The 3D plotting scene to which the cone will be added.
+        color : str
+            The color of the cone mesh. Default is 'red'.
+        opacity : float
+            The opacity of the cone mesh. Default is 0.8.
+
+        """
+        # Calculate the maximum angle from the numerical aperture (NA)
+
+        numerical_aperture = self.NA.magnitude
+
+        angle = self.numerical_aperture_to_angle(numerical_aperture)
+
+        max_angle = numpy.rad2deg(angle)
+
+        # Create the cone mesh
+        cone_mesh = pyvista.Cone(
+            center=(0.0, 0.0, -0.5),
+            direction=(0.0, 0.0, 1.0),
+            height=0.9,
+            resolution=100,
+            angle=max_angle
+        )
+
+        # Add the cone mesh to the scene
+        scene.add_mesh(cone_mesh, color=color, opacity=0.3)
+# -

PyMieSim/single/source/planewave.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+import pyvista
+from PyMieSim import units
+from PyMieSim.polarization import BasePolarization
+from PyMieSim.binary.interface_source import PLANEWAVE
+from PyMieSim.single.source.base import BaseSource
+
+
+class PlaneWave(PLANEWAVE, BaseSource):
+    def __init__(self,
+            wavelength: units.Quantity,
+            polarization: units.Quantity | BasePolarization,
+            amplitude: units.Quantity) -> None:
+        """
+        Initializes a plane wave light source for light scattering simulations.
+
+        Parameters
+        ----------
+        wavelength : units.Quantity
+            Wavelength of the light field in meters.
+        polarization : BasePolarization | units.Quantity
+            Polarization state of the light field, if float is given it is assumed Linear polarization of angle theta.
+        amplitude : units.Quantity
+            Amplitude of the electric field.
+        """
+        self.wavelength = self._validate_units(wavelength, dimension="distance", units=units.meter)
+        self.polarization = self._validate_source_polarization(polarization)
+        self.amplitude = self._validate_units(amplitude, dimension="amplitude", units=units.volt/units.meter)
+
+        self.wavenumber = 2 * numpy.pi / self.wavelength
+
+        super().__init__(
+            wavelength=self.wavelength.to(units.meter).magnitude,
+            jones_vector=self.polarization.element[0],
+            amplitude=self.amplitude.to(units.volt / units.meter).magnitude,
+        )
+
+    def plot(self, color: str = 'red', opacity: float = 0.8, show_axis_label: bool = False) -> None:
+        """
+        Plots the 3D structure of the Gaussian source.
+
+        This method creates a 3D plot of the Gaussian source, adds the structure to the plot,
+        and optionally displays axis labels.
+
+        Parameters
+        ----------
+        color : str
+            The color of the structure in the plot. Default is 'red'.
+        opacity : float
+            The opacity of the structure. Default is 0.8.
+        show_axis_label : bool
+            If True, axis labels will be shown. Default is False.
+
+        """
+        # Create a 3D plotting scene
+        scene = pyvista.Plotter()
+
+        # Add the structure to the scene
+        self._add_to_3d_ax(scene=scene, color=color, opacity=opacity)
+
+        # Add axes at the origin, optionally showing axis labels
+        scene.add_axes_at_origin(labels_off=not show_axis_label)
+
+        # Display the scene
+        scene.show()
+
+    def _add_to_3d_ax(self, scene: pyvista.Plotter, color: str = 'red', opacity: float = 0.8) -> None:
+        """
+        Adds a 3D cone representation to the given PyVista plotting scene.
+
+        The cylinder represents the acceptance angle determined by the numerical aperture (NA) of the system.
+        The cylinder is positioned at the origin and points downward along the z-axis.
+
+        Parameters
+        ----------
+        scene : pyvista.Plotter
+            The 3D plotting scene to which the cone will be added.
+        color : str
+            The color of the cone mesh. Default is 'red'.
+        opacity : float
+            The opacity of the cone mesh. Default is 0.8.
+
+        """
+        # Define the cylinder parameters
+        cylinder_mesh = pyvista.Cylinder(
+            center=(0.0, 0.0, 0.5),
+            direction=(0.0, 0.0, -1.0),
+            radius=0.2,
+            height=1.0,
+            resolution=100
+        )
+
+        # Add the cone mesh to the scene
+        scene.add_mesh(cylinder_mesh, color='blue', opacity=0.3)

PyMieSim/special_functions.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+
+
+def cartesian_to_spherical(x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray) -> tuple:
+    """
+    Convert Cartesian coordinates to spherical coordinates.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        The x coordinates.
+    y : numpy.ndarray
+        The y coordinates.
+    z : numpy.ndarray
+        The z coordinates.
+
+    Returns
+    -------
+    numpy.ndarray
+        The spherical coordinates (r, phi, theta).
+    """
+    r = numpy.sqrt(x**2 + y**2 + z**2)
+    phi = numpy.arcsin(z / r)
+    theta = numpy.arctan2(y, x)
+    return r, phi, theta
+
+
+def spherical_to_cartesian(phi: numpy.ndarray, theta: numpy.ndarray, r: numpy.ndarray = None) -> tuple:
+    """
+    Convert spherical coordinates to Cartesian coordinates.
+
+    Parameters
+    ----------
+    phi : numpy.ndarray
+        The phi angles.
+    theta : numpy.ndarray
+        The theta angles.
+    r : numpy.ndarray
+        The radial distances; defaults to unit radius if None.
+
+    Returns
+    -------
+    numpy.ndarray
+        The Cartesian coordinates (x, y, z).
+    """
+    if r is None:
+        r = numpy.ones_like(phi)
+
+    x = r * numpy.cos(phi) * numpy.cos(theta)
+    y = r * numpy.cos(phi) * numpy.sin(theta)
+    z = r * numpy.sin(phi)
+    return x, y, z
+
+
+def rotate_on_x(phi: numpy.ndarray, theta: numpy.ndarray, angle: float) -> tuple:
+    """Rotate spherical coordinates around the X-axis.
+
+    Parameters
+    ----------
+    phi : numpy.ndarray
+        Azimuthal angles in radians.
+    theta : numpy.ndarray
+        Polar angles in radians.
+    angle : float
+        Rotation angle about the X-axis, in radians.
+
+    Returns
+    -------
+    tuple
+        The rotated spherical coordinates ``(r, phi, theta)``.
+    """
+    # Convert to Cartesian for rotation
+    x, y, z = spherical_to_cartesian(phi, theta)
+    # Apply rotation around the X-axis
+    yp = y * numpy.cos(angle) - z * numpy.sin(angle)
+    zp = y * numpy.sin(angle) + z * numpy.cos(angle)
+    # Convert back to spherical coordinates
+    return cartesian_to_spherical(x, yp, zp)

PyMieSim/units.py

@@ -0,0 +1,130 @@
+from typing import Optional
+from PyOptik.units import ureg
+import pint as _pint
+import pint_pandas as pint
+
+_pint.set_application_registry(ureg)
+
+
+# Define a list of base units to scale
+BASE_UNITS = [
+    'watt', 'volt', 'meter', 'second', 'liter', 'hertz', 'ohm', 'ampere'
+]
+
+# Define prefixes for scaling units
+SCALES = ['nano', 'micro', 'milli', '', 'kilo', 'mega']
+
+
+def initialize_registry(ureg: Optional[object] = None):
+    """
+    Initialize and set up a unit registry. This function also leaks
+    the units into the global namespace for easy access throughout
+    the module.
+
+    Parameters
+    ----------
+    ureg: Optional[pint.UnitRegistry]
+        A UnitRegistry object to use. If None, the default PintType.ureg will be used.
+    """
+
+    # If no unit registry is provided, use the default
+    ureg = ureg or pint.PintType.ureg
+
+    # Set up matplotlib integration and unit formatting
+    ureg.setup_matplotlib()
+    ureg.formatter.default_format = '~P'  # Compact format without units like 'meter'
+
+    # Leak scaled units into the global namespace
+    for unit in BASE_UNITS:
+        for scale in SCALES:
+            scaled_unit_name = scale + unit
+            globals()[scaled_unit_name] = getattr(ureg, scaled_unit_name)
+
+    # Leak commonly used specific units into the global namespace
+    common_units = {
+        'farad': ureg.farad,
+        'joule': ureg.joule,
+        'coulomb': ureg.coulomb,
+        'power': ureg.watt.dimensionality,
+        'kelvin': ureg.kelvin,
+        'celsius': ureg.celsius,
+        'particle': ureg.particle,
+        'RIU': ureg.refractive_index_unit,
+        'refractive_index_unit': ureg.refractive_index_unit,
+        'degree': ureg.degree,
+        'radian': ureg.radian,
+        'steradian': ureg.steradian,
+        'AU': ureg.dimensionless,
+        'distance': ureg.meter.dimensionality,
+        'time': ureg.second.dimensionality,
+        'volume': ureg.liter.dimensionality,
+        'frequency': ureg.hertz.dimensionality,
+        'Quantity': ureg.Quantity
+    }
+
+    # Leak the common units into the global namespace
+    globals().update(common_units)
+
+    globals()['ureg'] = ureg
+
+
+initialize_registry()
+
+
+class UnitsValidation():
+    def _validate_units(cls, value, dimension: str, units: str):
+        """
+        Ensures that diameter is Quantity objects with power units.
+        """
+
+        if not isinstance(value, ureg.Quantity):
+            if units == ureg.dimensionless:
+                return value * ureg.dimensionless
+
+            raise ValueError(f"{value} must be a Quantity instance, use PyMieSim.units module.")
+
+        if not value.check(units):
+            raise ValueError(f"{value} must be a Quantity with {dimension} units [{units}] but has {value.units}.")
+
+        return value
+
+    def _validate_source_polarization(cls, value):
+        """
+        Ensures that polarization is well defined.
+        """
+        from PyMieSim.polarization import BasePolarization, Linear
+
+        if isinstance(value, BasePolarization):
+            return value
+
+        if isinstance(value, ureg.Quantity):
+            value = cls._validate_units(value, dimension='angle', units=ureg.degree)
+            return Linear(value)
+
+        raise ValueError(f"{value} must be a Linear or a Quantity with degree units.")
+
+    def _validate_property(cls, value):
+        """
+        Ensures that diameter is Quantity objects with RIU units.
+        """
+        from PyOptik.material.base_class import BaseMaterial
+
+        if not isinstance(value, ureg.Quantity | BaseMaterial):
+            raise ValueError(f"{value} must be a Quantity (RIU units) or a material (BaseMaterial from PyOptik).")
+
+        return value
+
+    def _validate_detector_polarization_units(cls, value):
+        """
+        Ensures that medium_refractive_index, and rotation are Quantity objects with angle units.
+        Converts them to numpy arrays after validation.
+        """
+        import numpy
+
+        if value is None:
+            value = numpy.nan * ureg.degree
+
+        if not isinstance(value, ureg.Quantity) or not value.check(ureg.refractive_index_unit):
+            raise ValueError(f"{value} must be a Quantity with refractive index units [RIU].")
+
+        return value