PyMieSim 3.6.0__cp313-cp313-win_amd64.whl

PyMieSim/single/detector/base.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import numpy
+from typing import Optional
+
+from PyMieSim.single.representations import Footprint
+from MPSPlots.colormaps import blue_black_red
+from PyMieSim.units import Quantity, watt, meter, second, farad, volt
+from PyMieSim import units
+from PyMieSim.single.scatterer.base import BaseScatterer
+import pyvista
+
+c = 299792458.0 * meter / second  #: Speed of light in vacuum (m/s).
+epsilon0 = 8.854187817620389e-12 * farad / meter  #: Vacuum permittivity (F/m).
+
+
+class BaseDetector(units.UnitsValidation):
+    medium_refractive_index: Optional[Quantity] = 1.0 * units.RIU
+
+    @property
+    def max_angle(self) -> Quantity:
+        """
+        Returns the maximum angle of the detector in radians.
+        This is used to determine the angular coverage of the detector.
+        """
+        return self._cpp_max_angle * units.radian
+
+    @property
+    def min_angle(self) -> Quantity:
+        """
+        Returns the minimum angle of the detector in radians.
+        This is used to determine the angular coverage of the detector.
+        """
+        return self._cpp_min_angle * units.radian
+
+    def _validate_angle_units(cls, value):
+        """
+        Ensures that gamma_offset, phi_offset, and rotation are Quantity objects with angle units.
+        Converts them to numpy arrays after validation.
+        """
+        if not isinstance(value, Quantity) or not value.check(units.degree):
+            raise ValueError(f"{value} must be a Quantity with angle units [degree or radian].")
+
+        return value
+
+    def get_coupling(self, scatterer: BaseScatterer) -> Quantity:
+        r"""
+        Compute the light coupling between the detector and a scatterer.
+
+        The coupling quantifies the interaction between the field captured by the detector and the scattered field produced by the scatterer. Mathematically, the coupling is calculated as:
+
+        .. math::
+            |\iint_{\Omega}  \Phi_{det} \, \Psi_{scat}^* \,  d \Omega|^2
+
+        Where:
+
+        - \( \Phi_{det} \): The capturing field of the detector, representing the sensitivity of the detector to the incoming scattered field.
+        - \( \Psi_{scat} \): The scattered field produced by the scatterer.
+        - \( \Omega \): The solid angle over which the integration is performed, typically covering the full \( 4\pi \) steradians around the scatterer.
+        - \( d\Omega \): The differential solid angle element.
+
+        This integral computes the overlap between the detector's sensitivity pattern and the scattered field, which is then squared to represent the power coupled into the detector.
+
+        Parameters
+        ----------
+        scatterer : BaseScatterer
+            The scatterer object that interacts with the incident light, producing the scattered field.
+
+        Returns
+        -------
+        Quantity
+            The power coupling between the detector and the scatterer, expressed in watts (W). This value represents the amount of scattered power that is captured by the detector.
+
+        Notes
+        -----
+        - The method internally invokes the appropriate binding method based on the type of scatterer (e.g., Sphere, Cylinder) to calculate the coupling.
+        - The coupling depends on both the geometry of the detector and the nature of the scattered field, making it essential for evaluating the efficiency of light collection in scattering experiments.
+
+        Example
+        -------
+        A common use case is to evaluate how much of the scattered light from a nanoparticle is captured by a photodiode or integrating sphere. The result can be used to estimate the efficiency of light collection for scattering measurements.
+
+        """
+        return self._cpp_get_coupling(scatterer) * units.watt
+
+    def get_footprint(self, scatterer: BaseScatterer) -> Footprint:
+        r"""
+        Generate the footprint of the scattered light coupling with the detector.
+
+        .. math::
+            \big| \mathscr{F}^{-1} \big\{ \tilde{ \psi } (\xi, \nu),\
+                   \tilde{ \phi}_{l,m}(\xi, \nu)  \big\}
+                   (\delta_x, \delta_y) \big|^2
+
+        | Where:
+        |   :math:`\Phi_{det}` is the capturing field of the detector and
+        |   :math:`\Psi_{scat}` is the scattered field.
+
+        Args:
+            scatterer (BaseScatterer): The scatterer object.
+
+        Returns:
+            Footprint: The scatterer footprint with this detector.
+        """
+        return Footprint(scatterer=scatterer, detector=self)
+
+    def _add_to_3d_ax(self, scene: pyvista.Plotter, colormap: str = blue_black_red) -> None:
+        """
+        Adds the scalar field and a directional cone to a 3D PyVista plotting scene.
+
+        This method adds points representing the real part of the scalar field to the given 3D scene,
+        along with a cone mesh to indicate directional information. It also includes a scalar bar
+        to display the values of the scalar field.
+
+        Parameters
+        ----------
+        scene : pyvista.Plotter
+            The PyVista plotting scene where the elements will be added.
+        colormap : str
+            The colormap to use for the scalar field visualization.
+
+        Returns:
+            None: This method does not return a value. It modifies the provided scene.
+        """
+        # Stack the mesh coordinates into a single array
+        coordinates = numpy.vstack((
+            self._cpp_mesh.cartesian.x,
+            self._cpp_mesh.cartesian.y,
+            self._cpp_mesh.cartesian.z
+        ))
+
+        # Wrap the coordinates for PyVista visualization
+        points = pyvista.wrap(coordinates.T)
+
+        scalar_field = numpy.asarray(self._cpp_scalar_field).real
+
+        abs_max = abs(scalar_field).max()
+
+        # Add the points to the scene, representing the real part of the scalar field
+        mapping = scene.add_points(
+            points,
+            scalars=scalar_field,
+            point_size=20,
+            render_points_as_spheres=True,
+            cmap=colormap,
+            show_scalar_bar=False,
+            clim=[-abs_max, abs_max]
+        )
+
+        # Create a cone mesh to indicate directional information
+        cone_mesh = pyvista.Cone(
+            center=coordinates.mean(axis=1) / 2,
+            direction=-coordinates.mean(axis=1),
+            height=numpy.cos(self.max_angle),
+            resolution=100,
+            angle=self.max_angle.to('degree').magnitude,
+        )
+
+        # Add the cone mesh to the scene with specified color and opacity
+        scene.add_mesh(cone_mesh, color='blue', opacity=0.6)
+
+        # Add a scalar bar to the scene for the real part of the field
+        scene.add_scalar_bar(mapper=mapping.mapper, title='Collecting Field Real Part')
+
+    def get_poynting_vector(self, scatterer: BaseScatterer, distance: Quantity = 1 * meter) -> float:
+        r"""
+        Compute the Poynting vector norm, representing the energy flux density of the electromagnetic field.
+
+        The Poynting vector describes the directional energy transfer per unit area for an electromagnetic wave. It is defined as:
+
+        .. math::
+            \vec{S} = \epsilon_0 c^2 \, \vec{E} \times \vec{B}
+
+        Where:
+
+        - \( \vec{S} \): Poynting vector (W/m²)
+        - \( \epsilon_0 \): Permittivity of free space (F/m)
+        - \( c \): Speed of light in vacuum (m/s)
+        - \( \vec{E} \): Electric field vector (V/m)
+        - \( \vec{B} \): Magnetic field vector (T)
+
+        The cross product of the electric and magnetic field vectors results in the Poynting vector, which represents the flow of electromagnetic energy in space.
+
+        Parameters
+        ----------
+        scatterer : BaseScatterer
+            The scatterer object that interacts with the incident electromagnetic wave, affecting the fields and energy flow.
+        distance : Quantity
+            The distance at which the Poynting vector is computed.
+
+        Returns
+        -------
+        Quantity
+            The norm of the Poynting vector, which gives the magnitude of the energy flux density in watts per square meter (W/m²).
+
+        Notes
+        -----
+        The Poynting vector is computed over a 3D mesh of voxels that cover the entire solid angle of \( 4\pi \) steradians. This method calculates the local energy flux at each voxel and returns the norm, which represents the magnitude of energy flow at each point in space around the scatterer.
+
+        The Poynting vector is fundamental in understanding how energy is transmitted through space in the form of electromagnetic waves.
+
+        Example
+        -------
+        This method is used to assess the distribution of energy around a scatterer. The total energy flow can be obtained by integrating the Poynting vector over the surface enclosing the scatterer.
+
+        """
+        Ephi, Etheta = scatterer.get_farfields_array(
+            phi=self._cpp_mesh.spherical.phi,
+            theta=self._cpp_mesh.spherical.theta,
+            r=distance
+        )
+
+        E_norm = numpy.sqrt(numpy.abs(Ephi)**2 + numpy.abs(Etheta)**2) * volt / meter
+
+        B_norm = (E_norm / c).to('tesla')
+
+        poynting = epsilon0 * c**2 * E_norm * B_norm
+
+        return poynting.to(watt/meter ** 2)
+
+    def get_energy_flow(self, scatterer: BaseScatterer, distance: Quantity = 1 * meter) -> Quantity:
+        r"""
+        Calculate the total energy flow (or radiated power) from the scatterer based on the Poynting vector.
+
+        The energy flow is computed using the following relationship between the scattered energy and the incident intensity:
+
+        .. math::
+            W_a &= \sigma_{sca} \cdot I_{inc} \\[10pt]
+            P &= \int_{A} I \, dA \\[10pt]
+            I &= \frac{c n \epsilon_0}{2} \, |E|^2
+
+        Where:
+
+        - \( W_a \): Energy flow (W)
+        - \( \sigma_{sca} \): Scattering cross section (m²)
+        - \( I_{inc} \): Incident intensity (W/m²)
+        - \( P \): Radiated power (W)
+        - \( I \): Energy density (W/m²)
+        - \( c \): Speed of light in vacuum (m/s)
+        - \( n \): Refractive index of the surrounding medium
+        - \( \epsilon_0 \): Permittivity of free space (F/m)
+        - \( E \): Electric field (V/m)
+
+        The total power is computed by integrating the intensity over the surface area of the scatterer.
+
+        Parameters
+        ----------
+        scatterer : BaseScatterer
+            The scatterer object, which contains information about the scattering properties of the particle, such as geometry and material.
+        distance : Quantity
+            The distance at which the Poynting vector is computed. It should change the computed total power.
+
+        Returns
+        -------
+        Quantity
+            The total energy flow (radiated power) from the scatterer, expressed in watts.
+
+        Notes
+        -----
+        This method computes the energy flow by calculating the Poynting vector (which represents the directional energy flux) and summing it over the surface mesh of the scatterer. The final result is the total radiated power.
+
+        """
+        poynting_vector = self.get_poynting_vector(scatterer=scatterer, distance=distance)
+
+        dA = self._cpp_mesh._cpp_d_omega * distance ** 2
+
+        total_power = 0.5 * numpy.trapezoid(y=poynting_vector, dx=dA)
+
+        return total_power
+

PyMieSim/single/detector/coherent.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import logging
+from typing import Optional
+from PyMieSim import units
+from PyMieSim.binary.interface_detector import DETECTOR
+from PyMieSim.single.detector.base import BaseDetector
+
+
+class CoherentMode(DETECTOR, BaseDetector):
+    def __init__(self,
+            mode_number: str,
+            NA: units.Quantity,
+            gamma_offset: units.Quantity,
+            phi_offset: units.Quantity,
+            sampling: units.Quantity = 200,
+            polarization_filter: Optional[units.Quantity] = None,
+            cache_NA: Optional[units.Quantity] = 0 * units.AU,
+            mean_coupling: bool = False,
+            rotation: units.Quantity = 90 * units.degree,
+            medium_refractive_index: units.Quantity = 1.0 * units.RIU,
+        ):
+        """
+        Initialize the CoherentMode detector with its parameters.
+
+        Depending on the mode_number, this detector can represent different types of modes such as Hermite-Gauss (HG), Laguerre-Gauss (LG), or fiber linearly polarized (LP).
+        This class is designed to handle coherent light coupling mechanisms, meaning it depends on the phase of the impinging scattered light field.
+
+        Parameters
+        ----------
+        mode_number : str
+            String representing the mode to be initialized (e.g., 'LP01', 'HG11', 'LG22').
+        NA : units.Quantity
+            The numerical aperture of the detector, a dimensionless number that defines its light-gathering
+            ability. Higher NA values indicate a wider acceptance angle for capturing light.
+        gamma_offset : units.Quantity
+            The rotational offset in the gamma direction, controlling the angular positioning of the detector relative to the scatterer.
+        phi_offset : units.Quantity
+            The rotational offset in the phi direction, specifying the azimuthal angle of the detector's orientation.
+        sampling : units.Quantity
+            The sampling resolution of the detector, controlling how finely the detector's field is sampled
+            over the surface. A higher value increases precision but may require more computational resources. Default is 200.
+        polarization_filter : Optional[units.Quantity]
+            The polarization filter applied to the detected light. If specified, it allows the detector to
+            selectively capture light with a particular polarization. If set to `nan`, no filtering is applied.
+        cache_NA : Optional[units.Quantity]
+            Numerical aperture of the detector cache. Default is 0 AU.
+        mean_coupling : bool
+            A flag indicating whether the mean value of the coupling is used when calculating the light
+            interaction with the scatterer. This is typically set for cases where an average coupling is
+            needed over multiple angles or configurations.
+        rotation : units.Quantity
+            The rotational angle of the detector, defining its orientation relative to the incoming light or
+            scatterer. The default value rotates the detector by 90 degrees.
+        medium_refractive_index : units.Quantity
+            The refractive index of the medium in which the detector operates. This is important for
+            determining the acceptance cone of light.
+            Default is 1.0 (vacuum or air).
+        """
+
+        if NA > 0.3 * units.AU or NA < 0 * units.AU:
+            logging.warning(f"High values of NA: {NA} do not comply with the paraxial approximation. Values under 0.3 are preferred.")
+
+        self.mode_family = mode_number[:2]
+
+        if self.mode_family.lower() not in ['lp', 'lg', 'hg']:
+            raise ValueError(f'Invalid mode family: {self.mode_family}. Options are ["LP", "LG", "HG"]')
+
+        self.mode_number = mode_number
+        self.mean_coupling = mean_coupling
+
+        self.NA = self._validate_units(NA, dimension='arbitrary', units=units.AU)
+        self.cache_NA = self._validate_units(cache_NA, dimension='arbitrary', units=units.AU)
+        self.sampling = self._validate_units(sampling, dimension='arbitrary', units=units.AU)
+
+        self.gamma_offset = self._validate_units(gamma_offset, dimension='angle', units=units.degree)
+        self.phi_offset = self._validate_units(phi_offset, dimension='angle', units=units.degree)
+        self.rotation = self._validate_units(rotation, dimension='angle', units=units.degree)
+
+        self.medium_refractive_index = self._validate_units(medium_refractive_index, dimension='refractive index', units=units.RIU)
+
+        self.polarization_filter = self._validate_detector_polarization_units(polarization_filter)
+
+        super().__init__(
+            mode_number=self.mode_number,
+            sampling=self.sampling,
+            NA=self.NA.to(units.AU).magnitude,
+            cache_NA=self.cache_NA.to(units.AU).magnitude,
+            phi_offset=self.phi_offset.to(units.radian).magnitude,
+            gamma_offset=self.gamma_offset.to(units.radian).magnitude,
+            polarization_filter=self.polarization_filter.to(units.radian).magnitude,
+            rotation=self.rotation.to(units.radian).magnitude,
+            coherent=False,
+            mean_coupling=self.mean_coupling,
+            medium_refractive_index=self.medium_refractive_index.to(units.RIU).magnitude,
+        )
+
+# -

PyMieSim/single/detector/uncoherent.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+from PyMieSim.binary.interface_detector import DETECTOR
+from PyMieSim import units
+from PyMieSim.single.detector.base import BaseDetector
+
+
+class Photodiode(DETECTOR, BaseDetector):
+    """
+    Detector class representing a photodiode with a non-coherent light coupling mechanism.
+    This means it is independent of the phase of the impinging scattered light field.
+
+    """
+    def __init__(self,
+            NA: units.Quantity,
+            gamma_offset: units.Quantity,
+            phi_offset: units.Quantity,
+            sampling: units.Quantity = 200,
+            polarization_filter: Optional[units.Quantity] = None,
+            cache_NA: Optional[units.Quantity] = 0 * units.AU,
+            mean_coupling: bool = False,
+            medium_refractive_index: units.Quantity = 1.0 * units.RIU):
+        """
+        Initialize the Photodiode detector with its parameters.
+
+        Parameters
+        ----------
+
+        NA : units.Quantity
+            Numerical aperture of the imaging system.
+        gamma_offset : units.Quantity
+            Angle [Degree] offset of the detector in the direction perpendicular to polarization.
+        phi_offset : units.Quantity
+            Angle [Degree] offset of the detector in the direction parallel to polarization.
+        sampling : units.Quantity
+            Sampling rate of the far-field distribution. Default is 200.
+        polarization_filter : Optional[units.Quantity]
+            Angle [Degree] of the polarization filter in front of the detector.
+        cache_NA : Optional[units.Quantity]
+            Numerical aperture of the detector cache. Default is 0 AU.
+        mean_coupling : bool
+            Indicates if the coupling mechanism is point-wise (True) or mean-wise (False). Default is False.
+        medium_refractive_index : units.Quantity
+            The refractive index of the medium in which the detector operates. This is important for
+            determining the acceptance cone of light.
+            Default is 1.0 (vacuum or air).
+        """
+        self.mean_coupling = mean_coupling
+
+        self.NA = self._validate_units(NA, dimension='arbitrary', units=units.AU)
+        self.cache_NA = self._validate_units(cache_NA, dimension='arbitrary', units=units.AU)
+        self.sampling = self._validate_units(sampling, dimension='arbitrary', units=units.AU)
+
+        self.gamma_offset = self._validate_units(gamma_offset, dimension='angle', units=units.degree)
+        self.phi_offset = self._validate_units(phi_offset, dimension='angle', units=units.degree)
+
+        self.medium_refractive_index = self._validate_units(medium_refractive_index, dimension='refractive index', units=units.RIU)
+
+        self.polarization_filter = self._validate_detector_polarization_units(polarization_filter)
+
+        super().__init__(
+            mode_number="NC00",
+            NA=self.NA.to(units.AU).magnitude,
+            cache_NA=self.cache_NA.to(units.AU).magnitude,
+            gamma_offset=self.gamma_offset.to(units.radian).magnitude,
+            phi_offset=self.phi_offset.to(units.radian).magnitude,
+            sampling=self.sampling,
+            polarization_filter=self.polarization_filter.to(units.radian).magnitude,
+            mean_coupling=self.mean_coupling,
+            rotation=0,
+            coherent=False,
+            medium_refractive_index=self.medium_refractive_index.to(units.RIU).magnitude
+        )
+
+
+class IntegratingSphere(Photodiode):
+    def __init__(self, sampling: units.Quantity, polarization_filter: Optional[units.Quantity] = None, mean_coupling: bool = False):
+        """
+        Detector class representing a photodiode with a non-coherent light coupling mechanism.
+        This implies independence from the phase of the impinging scattered light field.
+
+        Parameters
+        ----------
+
+        sampling : units.Quantity
+            Sampling rate of the far-field distribution. Default is 200.
+        polarization_filter : Optional[units.Quantity]
+            Angle [Degree] of the polarization filter in front of the detector.
+        cache_NA : Optional[units.Quantity]
+            Numerical aperture of the detector cache. Default is 0 AU.
+        mean_coupling : bool
+            Indicates if the coupling mechanism is point-wise (True) or mean-wise (False). Default is False.
+        """
+
+        super().__init__(
+            sampling=sampling,
+            polarization_filter=polarization_filter,
+            mean_coupling=mean_coupling,
+            NA=2.0 * units.AU,  # Fixed NA for IntegratingSphere
+            gamma_offset=0 * units.degree,  # Fixed gamma offset for IntegratingSphere
+            phi_offset=0 * units.degree,  # Fixed phi offset for IntegratingSphere
+            cache_NA=0 * units.AU,  # Fixed cache NA for IntegratingSphere
+        )