PyMieSim 3.6.0__cp313-cp313-win_amd64.whl

PyMieSim/mesh.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+import numpy
+
+from PyMieSim.binary.interface_detector import FIBONACCIMESH
+from PyMieSim import units
+
+class FibonacciMesh(FIBONACCIMESH):
+    """
+    Represents an angular mesh using a Fibonacci sphere distribution, where each point
+    covers an equivalent solid angle. This type of mesh is useful for simulating angular
+    distributions in light scattering experiments.
+
+    The mesh is defined by a numerical aperture and a number of sampling points, with
+    additional control over the orientation and rotation of the mesh.
+
+    Parameters
+    ----------
+    max_angle : float
+        The maximum angle in radians, typically defined by the numerical aperture of the imaging system.
+    sampling : int
+        The number of points distributed across the mesh. Higher values result in finer resolution.
+    phi_offset : float
+        Angle offset in the azimuthal (parallel to incident light polarization) direction in degrees.
+    gamma_offset : float
+        Angle offset in the polar (perpendicular to incident light polarization) direction in degrees.
+    rotation_angle : Optional[float], default=0.0
+        Rotation of the entire mesh around its principal axis, in degrees.
+
+    Attributes
+    ----------
+    cartesian_coordinates : numpy.ndarray
+        Cartesian coordinates of the mesh points, calculated during initialization.
+    d_omega_radian : float
+        Differential solid angle element in radians for each point on the mesh.
+    d_omega_degree : float
+        Differential solid angle element in degrees for each point on the mesh.
+    omega_radian : float
+        Total solid angle covered by the mesh in radians.
+    omega_degree : float
+        Total solid angle covered by the mesh in degrees.
+
+    Methods
+    -------
+    projection_HV_vector() -> tuple:
+        Returns the parallel and perpendicular projections of the mesh on the horizontal and vertical base vectors as vectors.
+    projection_HV_scalar() -> tuple:
+        Returns the parallel and perpendicular projections of the mesh on the horizontal and vertical base vectors as scalar values.
+    projection_on_base_scalar(vector, base_vector) -> numpy.ndarray:
+        Computes the scalar projection of a given vector onto a base vector.
+    projection_on_base_vector(vector, base_vector) -> numpy.ndarray:
+        Computes the vector projection of a given vector onto a base vector.
+    get_axis_vector() -> numpy.ndarray:
+        Returns the axis vector corresponding to the phi and gamma offsets.
+    rotate_around_axis(rotation_angle) -> None:
+        Rotates the mesh around its principal axis by a specified angle.
+
+    """
+
+    # ---------------------- Validation Methods ----------------------
+    def _validate_angle_units(cls, value):
+        """
+        Ensures that diameter is Quantity objects with length units.
+        """
+        if not isinstance(value, units.Quantity) or not value.check(units.degree):
+            raise ValueError(f"{value} must be a Quantity with angle units [degree/radian].")
+
+        return value
+
+    def _validate_AU_units(cls, value):
+        """
+        Ensures that diameter is Quantity objects with length units.
+        """
+        if not isinstance(value, units.Quantity) or not value.check(units.AU):
+            raise ValueError(f"{value} must be a Quantity with arbitrary units [AU].")
+
+        return value
+
+    # ---------------------- Initialization Methods ----------------------
+    def __init__(self,
+        max_angle: units.Quantity,
+        sampling: int,
+        phi_offset: units.Quantity,
+        gamma_offset: units.Quantity,
+        min_angle: units.Quantity = 0 * units.degree,
+        rotation_angle: Optional[units.Quantity] = 0.0):
+        """
+        Initializes the FibonacciMesh with the specified parameters.
+
+        Parameters
+        ----------
+        max_angle : units.Quantity
+            The maximum angle in radians, typically defined by the numerical aperture of the imaging system.
+        sampling : int
+            The number of points distributed across the mesh. Higher values result in finer resolution.
+        phi_offset : units.Quantity
+            Angle offset in the azimuthal (parallel to incident light polarization) direction in degrees.
+        gamma_offset : units.Quantity
+            Angle offset in the polar (perpendicular to incident light polarization) direction in degrees.
+        rotation_angle : Optional[units.Quantity], default=0.0
+            Rotation of the entire mesh around its principal axis, in degrees.
+        """
+        self.sampling = sampling
+        self.max_angle = self._validate_angle_units(max_angle)
+        self.min_angle = self._validate_angle_units(min_angle)
+        phi_offset = self._validate_angle_units(phi_offset)
+        gamma_offset = self._validate_angle_units(gamma_offset)
+        rotation = self._validate_angle_units(rotation_angle)
+
+        super().__init__(
+            sampling=self.sampling,
+            max_angle=self.max_angle,
+            min_angle=self.min_angle,
+            rotation_angle=rotation,
+            phi_offset=numpy.deg2rad(phi_offset),
+            gamma_offset=numpy.deg2rad(gamma_offset),
+        )
+
+        self.compute_vector_field()
+
+    # ---------------------- Property Methods ----------------------
+    @property
+    def theta(self) -> units.Quantity:
+        """
+        Returns the polar angles (theta) of the mesh in radians.
+
+        Returns
+        -------
+        units.Quantity
+            The polar angles in radians.
+        """
+        return self.spherical.theta * units.radian
+
+    @property
+    def phi(self) -> units.Quantity:
+        """
+        Returns the azimuthal angles (phi) of the mesh in radians.
+
+        Returns
+        -------
+        units.Quantity
+            The azimuthal angles in radians.
+        """
+        return self.spherical.phi * units.radian
+
+    @property
+    def d_omega(self) -> units.Quantity:
+        """
+        Returns the solid angle (d_omega) of the mesh in steradians.
+
+        Returns
+        -------
+        units.Quantity
+            The solid angle in steradians.
+        """
+        return self.spherical._cpp_d_omega * units.steradian
+
+    @property
+    def omega(self) -> units.Quantity:
+        """
+        Returns the solid angle (omega) of the mesh in steradians.
+
+        Returns
+        -------
+        units.Quantity
+            The solid angle in steradians.
+        """
+        return self.spherical._cpp_omega * units.steradian
+
+    @property
+    def phi_offset(self) -> units.Quantity:
+        """
+        Returns the azimuthal angle offset (phi_offset) in radians.
+
+        Returns
+        -------
+        units.Quantity
+            The azimuthal angle offset in radians.
+        """
+        return self._cpp_phi_offset * units.radian
+
+    @property
+    def gamma_offset(self) -> units.Quantity:
+        """
+        Returns the polar angle offset (gamma_offset) in radians.
+
+        Returns
+        -------
+        units.Quantity
+            The polar angle offset in radians.
+        """
+        return self._cpp_gamma_offset * units.radian
+
+    @property
+    def rotation(self) -> units.Quantity:
+        """
+        Returns the rotation angle of the mesh around its principal axis in radians.
+
+        Returns
+        -------
+        units.Quantity
+            The rotation angle in radians.
+        """
+        return self._cpp_rotation * units.radian
+
+    # ---------------------- Additional Methods ----------------------
+    def get_axis_vector(self) -> numpy.ndarray:
+        """
+        Returns the axis vector corresponding to the phi and gamma offsets.
+
+        Returns
+        -------
+        numpy.ndarray
+            The axis vector normalized to unit length.
+        """
+        axis_vector = numpy.array([self.cartesian.x[0], self.cartesian.y[0], self.cartesian.z[0]])
+
+        norm = numpy.sqrt(numpy.square(axis_vector).sum())
+
+        return axis_vector / norm
+
+    def projection_HV_vector(self) -> tuple:
+        """
+        Projects the vertical and horizontal base vectors onto the parallel and perpendicular components
+        of the mesh, returning these projections as vectors.
+
+        The projections help visualize the relationship between the mesh's angular distribution and
+        the incident light polarization directions.
+
+        Returns
+        -------
+        tuple of numpy.ndarray
+            A tuple where the first element is the projection of the vertical and horizontal base vectors
+            onto the parallel vector field, and the second element is the projection onto the perpendicular
+            vector field.
+            Each of these projections is a 2D array of shape (2, 3), where:
+                - The first row corresponds to the projection onto the vertical base vector.
+                - The second row corresponds to the projection onto the horizontal base vector.
+        """
+        parallel_projection = [
+            self.projection_on_base_vector(
+                vector=self.parallel,
+                base_vector=X
+            ) for X in [self._cpp_vertical_base, self._cpp_horizontal_base]
+        ]
+
+        perpendicular_projection = [
+            self.projection_on_base_vector(
+                vector=self.perpendicular,
+                base_vector=X
+            ) for X in [self._cpp_vertical_base, self._cpp_horizontal_base]
+        ]
+
+        return numpy.array(parallel_projection), numpy.array(perpendicular_projection)
+
+    def projection_HV_scalar(self) -> tuple:
+        """
+        Projects the vertical and horizontal base vectors onto the parallel and perpendicular components
+        of the mesh, returning these projections as scalar values (dot products).
+
+        This method calculates the scalar projection, which represents the magnitude of the component
+        of the vector field along the base vectors.
+
+        Returns
+        -------
+        tuple of numpy.ndarray
+            A tuple where the first element is the scalar projection of the vertical and horizontal base vectors
+            onto the parallel vector field, and the second element is the scalar projection onto the perpendicular
+            vector field.
+            Each of these projections is a 1D array of length 2, where:
+                - The first element corresponds to the projection onto the vertical base vector.
+                - The second element corresponds to the projection onto the horizontal base vector.
+
+        """
+        parallel_projection = [
+            self.projection_on_base_scalar(
+                vector=self.parallel,
+                base_vector=X
+            ) for X in [self._cpp_vertical_base, self._cpp_horizontal_base]
+        ]
+
+        perpendicular_projection = [
+            self.projection_on_base_scalar(
+                vector=self.perpendicular,
+                base_vector=X
+            ) for X in [self._cpp_vertical_base, self._cpp_horizontal_base]
+        ]
+
+        return numpy.array(parallel_projection), numpy.array(perpendicular_projection)
+
+    def projection_on_base_scalar(self, vector: numpy.ndarray, base_vector: numpy.ndarray) -> numpy.ndarray:
+        r"""
+        Computes the scalar projection (dot product) of a given vector onto a base vector.
+
+        This method calculates the magnitude of the projection of `vector` along the direction
+        of `base_vector`. The scalar projection is useful for understanding how much of
+        `vector` is aligned with `base_vector`.
+
+        Parameters
+        ----------
+        vector : numpy.ndarray
+            The vector to be projected. It should be a 1D array representing the vector field component
+            (either parallel or perpendicular) of the mesh.
+        base_vector : numpy.ndarray
+            The base vector onto which the projection is made. It should be a 1D array, typically
+            representing the horizontal or vertical base direction.
+
+        Returns
+        -------
+        numpy.ndarray
+            The scalar projection of `vector` onto `base_vector`, which is a single numeric value.
+            This value represents the magnitude of the component of `vector` that is aligned with
+            `base_vector`.
+
+        Notes
+        -----
+        The scalar projection is calculated as the dot product of `vector` and `base_vector`:
+
+        .. math::
+            \text{scalar projection} = \vec{v} \cdot \vec{b}
+
+        where :math:`\vec{v}` is the input vector and :math:`\vec{b}` is the base vector.
+        """
+        return vector._cpp_get_scalar_product(base_vector)
+
+    def projection_on_base_vector(self, vector: numpy.ndarray, base_vector: numpy.ndarray) -> numpy.ndarray:
+        r"""
+        Computes the vector projection of a given vector onto a base vector.
+
+        This method calculates the projection of `vector` along the direction of `base_vector`
+        and returns a new vector that represents the component of `vector` aligned with
+        `base_vector`. This is useful for decomposing vectors in terms of directional components.
+
+        Parameters
+        ----------
+        vector : numpy.ndarray
+            The vector to be projected. It should be a 1D array representing the vector field component
+            (either parallel or perpendicular) of the mesh.
+        base_vector : numpy.ndarray
+            The base vector onto which the projection is made. It should be a 1D array, typically
+            representing the horizontal or vertical base direction.
+
+        Returns
+        -------
+        numpy.ndarray
+            The vector projection of `vector` onto `base_vector`, which is a vector in the direction
+            of `base_vector`. The resulting vector represents the part of `vector` that lies along
+            `base_vector`.
+
+        Notes
+        -----
+        The vector projection is calculated as:
+
+        .. math::
+            \text{vector projection} = \left( \frac{\vec{v} \cdot \vec{b}}{\vec{b} \cdot \vec{b}} \right) \vec{b}
+
+        where :math:`\vec{v}` is the input vector and :math:`\vec{b}` is the base vector. This formula gives the projection
+        of `vector` along the direction of `base_vector`.
+
+        The method first computes the scalar projection of `vector` onto `base_vector` using the dot product, and
+        then scales `base_vector` by this scalar to produce the projected vector.
+        """
+        projection = self.projection_on_base_scalar(vector, base_vector)
+        base_projection = numpy.outer(projection, base_vector.data)
+
+        return base_projection

PyMieSim/polarization.py

@@ -0,0 +1,174 @@
+import numpy as np
+from pydantic.dataclasses import dataclass
+from PyMieSim.units import degree, Quantity
+from copy import copy
+
+config_dict = dict(
+    kw_only=False,
+    slots=True,
+    extra='forbid',
+    arbitrary_types_allowed=True
+)
+
+
+class BasePolarization:
+    """
+    Base class for polarization types.
+
+    This class serves as a parent class for different types of polarizations such as Jones vectors
+    and specific polarization states like right circular and left circular polarizations.
+
+    It provides a foundation for shared functionality across all polarization types.
+    """
+    pass
+
+
+@dataclass(config=config_dict, unsafe_hash=True)
+class JonesVector(BasePolarization):
+    """
+    Represents a general Jones vector for polarization.
+
+    A Jones vector is a two-dimensional complex vector used to describe the state of polarization
+    of electromagnetic waves. This class handles general forms of linear and circular polarization.
+
+    Parameters
+    ----------
+    element : list
+        A list representing the Jones vector. The list will be converted to a 2D NumPy array
+        of complex numbers upon initialization.
+
+    Attributes
+    ----------
+    element : numpy.ndarray
+        A 2D NumPy array of complex numbers representing the Jones vector.
+
+    Methods
+    -------
+    __post_init__():
+        Converts `element` to a 2D NumPy array with complex data type after initialization.
+
+    __iter__():
+        Returns an iterator over polarization angles if available, otherwise over the Jones vector elements.
+
+    __add__(other: BasePolarization) -> BasePolarization:
+        Combines two Jones vectors (or derived polarizations) by stacking their elements.
+
+    __repr__() -> str:
+        Returns a string representation of the polarization vector or angle.
+
+    __str__() -> str:
+        Converts the polarization vector or angle to a string format for easy display.
+    """
+    element: list
+
+    def __post_init__(self):
+        self.element = np.atleast_2d(self.element).astype(complex)
+
+    def __iter__(self):
+        if hasattr(self, 'angle'):
+            return iter(self.angle)
+        else:
+            return iter(self.element)
+
+    def __add__(self, other: BasePolarization) -> BasePolarization:
+        output = copy(self)
+
+        if hasattr(output, 'angle'):
+            del output.angle
+
+        output.element = np.vstack([self.element, other.element])
+
+        if hasattr(other, 'angle') and hasattr(self, 'angle'):
+            output.angle = np.hstack([self.angle, other.angle])
+
+        return output
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def __str__(self) -> str:
+        if hasattr(self, 'angle'):
+            return self.angle.__str__()
+
+        return self.element.__str__()
+
+
+class RightCircular(JonesVector):
+    """
+    Represents right circular polarization in the Jones formalism.
+
+    Right circular polarization is a specific form of circular polarization where the electric
+    field vector rotates in a right-handed sense around the direction of propagation.
+
+    Attributes
+    ----------
+    element : numpy.ndarray
+        A Jones vector corresponding to right circular polarization, set to `[1, 1j]`.
+
+    Methods
+    -------
+    __init__():
+        Initializes the Jones vector for right circular polarization.
+    """
+    def __init__(self) -> None:
+        super().__init__(element=[1, 1j])
+
+
+class LeftCircular(JonesVector):
+    """
+    Represents left circular polarization in the Jones formalism.
+
+    Left circular polarization is a specific form of circular polarization where the electric
+    field vector rotates in a left-handed sense around the direction of propagation.
+
+    Attributes
+    ----------
+    element : numpy.ndarray
+        A Jones vector corresponding to left circular polarization, set to `[1, -1j]`.
+
+    Methods
+    -------
+    __init__():
+        Initializes the Jones vector for left circular polarization.
+    """
+    def __init__(self) -> None:
+        super().__init__(element=[1, -1j])
+
+
+@dataclass(config=config_dict, unsafe_hash=True)
+class Linear(JonesVector):
+    """
+    Represents linear polarization for a given angle or set of angles.
+
+    Linear polarization occurs when the electric field vector oscillates in a straight line
+    along the propagation direction. This class allows for defining linear polarization at any angle
+    in the plane perpendicular to the propagation direction.
+
+    Parameters
+    ----------
+    element : Quantity
+        A `Quantity` object representing the angle(s) of linear polarization. This is converted into
+        a Jones vector based on the provided angle in degrees.
+
+    Attributes
+    ----------
+    element : numpy.ndarray
+        A 2D NumPy array representing the Jones vector for linear polarization.
+    angle : numpy.ndarray
+        Array of polarization angles in the appropriate units (degrees).
+
+    Methods
+    -------
+    __post_init__():
+        Converts the input `element` (polarization angle) to a Jones vector representation
+        and stores it in `element`. It also stores the polarization angle in degrees.
+    """
+    element: Quantity
+
+    def __post_init__(self):
+        self.angle = np.atleast_1d(self.element.magnitude) * self.element.units
+        angle = self.element.to(degree).magnitude
+
+        self.element = np.empty([len(self.angle), 2]).astype(complex)
+        self.element[:, 0] = np.cos(np.deg2rad(angle))
+        self.element[:, 1] = np.sin(np.deg2rad(angle))

PyMieSim/single/__init__.py

@@ -0,0 +1,48 @@
+from .scatterer import Sphere, CoreShell, Cylinder  # noqa: F401
+from .source import PlaneWave, Gaussian  # noqa: F401
+from .detector import Photodiode, CoherentMode  # noqa: F401
+
+import pyvista
+from typing import NoReturn, Any
+from MPSPlots.colormaps import blue_black_red
+
+
+def plot_system(*objects: Any, data: Any = None, colormap: str = blue_black_red, show_axis_label: bool = True) -> NoReturn:
+    """
+    Plots a 3D visualization of a system of objects, each of which must have a `_add_to_3d_ax` method for adding itself to the scene.
+
+    This function creates a 3D plot of multiple objects, adding each one to a shared PyVista scene.
+    It ensures that each object has the required `_add_to_3d_ax` method for adding itself to the scene.
+    Additionally, it includes an optional translucent sphere and the option to display axis labels.
+
+    Args:
+        objects (Any): Objects to be plotted in the 3D scene. Each object must have a `_add_to_3d_ax` method.
+        show_axis_label (bool): If True, axis labels will be shown. Default is False.
+
+    Returns:
+        NoReturn: This function does not return a value. It displays the 3D visualization.
+    """
+    # Create a PyVista plotting scene
+    # scene = pyvista.Plotter(theme=pyvista.themes.DarkTheme())
+    scene = pyvista.Plotter()
+
+    # Add each object to the scene by calling its `_add_to_3d_ax` method
+    for obj in objects:
+        if not hasattr(obj, '_add_to_3d_ax'):
+            raise AttributeError(f'Object {obj} cannot be added to system plotting because it lacks a `_add_to_3d_ax` method.')
+        obj._add_to_3d_ax(scene=scene)
+
+    if data is not None:
+        if not hasattr(data, '_add_to_3d_ax'):
+            raise AttributeError(f'Data {obj} cannot be added to system plotting because it lacks a `_add_to_3d_ax` method.')
+        data._add_to_3d_ax(scene=scene, colormap=colormap)
+
+    # Add a translucent sphere to the scene to provide context or reference
+    sphere = pyvista.Sphere(radius=1)
+    scene.add_mesh(sphere, opacity=0.3)
+
+    # Optionally add axis labels to the scene
+    scene.add_axes_at_origin(zlabel='', xlabel='', ylabel='', labels_off=not show_axis_label)
+
+    # Display the scene
+    scene.show()

PyMieSim/single/detector/__init__.py

@@ -0,0 +1,2 @@
+from .coherent import CoherentMode
+from .uncoherent import Photodiode, IntegratingSphere