Detectors#

class Photodiode#

Bases: BASE_DETECTOR

Photodiode for Lorenz-Mie scattering simulations.

This class wraps a C++ Photodiode that samples the scattered field according to numerical aperture, orientation offsets, polarization filtering, and optional coherent or mean coupling strategies.

Parameters:

  • sampling (int) – Number of sample points on the detector’s angular mesh.

  • NA (float) – Numerical aperture of the detector; controls the angular acceptance.

  • cache_NA (float) – Cached NA threshold for fast lookup (set equal to NA to disable).

  • phi_offset (float) – Azimuthal angle offset (radians) for detector orientation.

  • gamma_offset (float) – Polar angle offset (radians) for detector orientation.

  • polarization_filter (float) – Degree or type of polarization filtering applied.

  • medium_refractive_index (float, optional) – Refractive index of the surrounding medium. Default is 1.0.

scalar_field#

The detected scalar field (intensity) sampled on the angular mesh.

Type:

numpy.ndarray

NA#

Numerical aperture exposed as a read-only property.

Type:

float[Dimensionless]

sampling#

Sampling count exposed as a read-only property.

Type:

int

phi_offset#

Azimuthal offset exposed as a read-only property.

Type:

float[Angle]

gamma_offset#

Polar offset exposed as a read-only property.

Type:

float[Angle]

polarization_filter#

Polarization filter setting exposed as a read-only property.

Type:

float[Angle]

mesh#

Underlying Fibonacci mesh of angles used by the detector.

Type:

numpy.ndarray

max_angle#

Maximum polar angle in the mesh (radians).

Type:

float[Angle]

min_angle#

Minimum polar angle in the mesh (radians); zero if no cache.

Type:

float[Angle]

property NA#

Numerical aperture of the detector.

Controls the angular extent of collected light.

property gamma_offset#

Polar offset angle for detector orientation.

get_coupling(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER) → object#

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:

\[|\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 ( 4pi ) steradians around the scatterer.

  • ( dOmega ): 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:

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.

Return type:

Quantity

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.

get_energy_flow(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER) → object#

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:

\[\begin{split}W_a &= \sigma_{sca} \cdot I_{inc} \\[10pt] P &= \int_{A} I \, dA \\[10pt] I &= \frac{c n \epsilon_0}{2} \, |E|^2\end{split}\]

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.

Returns:

The total energy flow (radiated power) from the scatterer, expressed in watts.

Return type:

Quantity

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.

get_poynting_field(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER, distance: object = 1.0) → object#

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:

\[\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) – An instance of a PyMieSim scatterer (e.g., SPHERE or CYLINDER).

  • distance (float, optional) – Distance from the scatterer to the detector (default is 1).

Returns:

A 2D array of shape (sampling, sampling) containing the Poynting vector magnitudes.

Return type:

numpy.ndarray

Notes

The Poynting vector is computed over a 3D mesh of voxels that cover the entire solid angle of ( 4pi ) 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.

get_structured_scalarfield(self: PyMieSim.binary.interface_single.BASE_DETECTOR, sampling: SupportsInt) → numpy.typing.NDArray[numpy.complex128]#

NumPy array of shape (sampling, 2) with columns [gamma, phi].

property is_coherent#

CoherentMode detection mode flag.

True if the detector is in coherent mode; false for incoherent.

property max_angle#

Returns the maximum angle of the detector in radians. This is used to determine the angular coverage of the detector.

property min_angle#

Returns the minimum angle of the detector in radians. This is used to determine the angular coverage of the detector.

property mode_field#

ModeField instance representing the detector’s mode. Contains methods for field computation and projections.

property mode_id#

ModeID instance representing the detector’s mode identifier. Contains family and number information for the mode.

property phi_offset#

Azimuthal offset angle for detector orientation.

property polarization_filter#

Polarization filter setting. Specifies any linear or circular filter applied to the signal.

print_properties(self: PyMieSim.binary.interface_single.Photodiode, arg0: SupportsInt) → None#

Print the properties of the Photodiode detector.

property sampling#

Number of samples per full angular sweep.

Determines resolution of the detected field.

property scalar_field#

Complex far field samples as numpy.complex128, shape (N,) Getter returns a zero copy view tied to the detector lifetime Setter accepts any 1D array castable to complex128

class CoherentMode#

Bases: BASE_DETECTOR

Photodiode for Lorenz-Mie scattering simulations.

This class wraps a C++ Photodiode that samples the scattered field according to numerical aperture, orientation offsets, polarization filtering, and optional coherent or mean coupling strategies.

Parameters:

  • mode_number (str) – Identifier for the detector mode (e.g. ‘0’, ‘1’, …).

  • sampling (int) – Number of sample points on the detector’s angular mesh.

  • NA (float) – Numerical aperture of the detector; controls the angular acceptance.

  • cache_NA (float) – Cached NA threshold for fast lookup (set equal to NA to disable).

  • phi_offset (float) – Azimuthal angle offset (radians) for detector orientation.

  • gamma_offset (float) – Polar angle offset (radians) for detector orientation.

  • polarization_filter (float) – Degree or type of polarization filtering applied.

  • rotation (float) – Rotation angle (radians) of the detector’s field-of-view.

  • mean_coupling (bool) – If true, uses mean coupling; if false, uses point coupling.

  • medium_refractive_index (float, optional) – Refractive index of the surrounding medium. Default is 1.0.

scalar_field#

The detected scalar field (intensity) sampled on the angular mesh.

Type:

numpy.ndarray

NA#

Numerical aperture exposed as a read-only property.

Type:

float[Dimensionless]

sampling#

Sampling count exposed as a read-only property.

Type:

int

phi_offset#

Azimuthal offset exposed as a read-only property.

Type:

float[Angle]

gamma_offset#

Polar offset exposed as a read-only property.

Type:

float[Angle]

polarization_filter#

Polarization filter setting exposed as a read-only property.

Type:

float[Angle]

rotation#

Rotation angle exposed as a read-only property.

Type:

float[Angle]

mesh#

Underlying Fibonacci mesh of angles used by the detector.

Type:

numpy.ndarray

max_angle#

Maximum polar angle in the mesh (radians).

Type:

float[Angle]

min_angle#

Minimum polar angle in the mesh (radians); zero if no cache.

Type:

float[Angle]

property NA#

Numerical aperture of the detector.

Controls the angular extent of collected light.

property gamma_offset#

Polar offset angle for detector orientation.

get_coupling(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER) → object#

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:

\[|\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 ( 4pi ) steradians around the scatterer.

  • ( dOmega ): 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:

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.

Return type:

Quantity

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.

get_energy_flow(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER) → object#

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:

\[\begin{split}W_a &= \sigma_{sca} \cdot I_{inc} \\[10pt] P &= \int_{A} I \, dA \\[10pt] I &= \frac{c n \epsilon_0}{2} \, |E|^2\end{split}\]

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.

Returns:

The total energy flow (radiated power) from the scatterer, expressed in watts.

Return type:

Quantity

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.

get_poynting_field(self: PyMieSim.binary.interface_single.BASE_DETECTOR, scatterer: PyMieSim.binary.interface_single.BASESCATTERER, distance: object = 1.0) → object#

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:

\[\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) – An instance of a PyMieSim scatterer (e.g., SPHERE or CYLINDER).

  • distance (float, optional) – Distance from the scatterer to the detector (default is 1).

Returns:

A 2D array of shape (sampling, sampling) containing the Poynting vector magnitudes.

Return type:

numpy.ndarray

Notes

The Poynting vector is computed over a 3D mesh of voxels that cover the entire solid angle of ( 4pi ) 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.

get_structured_scalarfield(self: PyMieSim.binary.interface_single.BASE_DETECTOR, sampling: SupportsInt) → numpy.typing.NDArray[numpy.complex128]#

NumPy array of shape (sampling, 2) with columns [gamma, phi].

property is_coherent#

CoherentMode detection mode flag.

True if the detector is in coherent mode; false for incoherent.

property max_angle#

Returns the maximum angle of the detector in radians. This is used to determine the angular coverage of the detector.

property min_angle#

Returns the minimum angle of the detector in radians. This is used to determine the angular coverage of the detector.

property mode_field#

ModeField instance representing the detector’s mode. Contains methods for field computation and projections.

property mode_id#

ModeID instance representing the detector’s mode identifier. Contains family and number information for the mode.

property phi_offset#

Azimuthal offset angle for detector orientation.

property polarization_filter#

Polarization filter setting. Specifies any linear or circular filter applied to the signal.

print_properties(self: PyMieSim.binary.interface_single.CoherentMode, arg0: SupportsInt) → None#

Print the properties of the CoherentMode detector.

property rotation#

Rotation angle of the detector’s field-of-view.

property sampling#

Number of samples per full angular sweep.

Determines resolution of the detected field.

property scalar_field#

Complex far field samples as numpy.complex128, shape (N,) Getter returns a zero copy view tied to the detector lifetime Setter accepts any 1D array castable to complex128