Single module

Sources

Source bindings for PyMieSim.

This module exposes optical excitation sources used by the single scatterer simulation API. Plotting helpers use Matplotlib 3D axes through private _add_to_ax methods. Figure creation, styling, and public visualization APIs should remain controlled by the Python layer.

class Gaussian

Bases: BaseSource

Monochromatic Gaussian beam source.

This source models a diffraction limited Gaussian beam characterized by wavelength, polarization, numerical aperture, and optical power.

__init__(self: PyMieSim.single.source.Gaussian, wavelength: object, polarization: object, numerical_aperture: object, optical_power: object) → None

Construct a Gaussian beam source.

Parameters:

• wavelength (pint.Quantity) – Wavelength in vacuum. Must be convertible to meters.

• polarization (object) – Polarization specification. See PlaneWave for accepted formats.

• numerical_aperture (float) – Dimensionless numerical aperture.

• optical_power (pint.Quantity) – Optical power. Must be convertible to watts.

property area

Effective beam area.

Returns:

Area with units of square length.

Return type:

pint.Quantity

property numerical_aperture

Numerical aperture.

Returns:

Dimensionless numerical aperture.

Return type:

float

property optical_power

Optical power.

Returns:

Optical power with units of watts.

Return type:

pint.Quantity

property peak_intensity

Peak on axis intensity.

Returns:

Peak intensity with units of power per area.

Return type:

pint.Quantity

property waist

Beam waist radius.

Returns:

Waist radius with units of length.

Return type:

pint.Quantity

class PlaneWave

Bases: BaseSource

Monochromatic plane wave source.

This source models a spatially uniform incident field with a specified wavelength, polarization, and electric field amplitude.

__init__(self: PyMieSim.single.source.PlaneWave, wavelength: object, polarization: object, amplitude: object) → None

Construct a plane wave source.

Parameters:

• wavelength (pint.Quantity) – Wavelength in vacuum. Must be convertible to meters.

• polarization (object) – Polarization specification. Accepted inputs include bound C++ Jones vector objects, PyMieSim polarization objects, or any object accepted by the linear polarization constructor.

• amplitude (pint.Quantity) – Electric field amplitude. Must be convertible to V/m.

Scatterers

Lorenz-Mie Theory (LMT) C++ binding module for PyMieSim Python package.

This module provides C++ bindings for the PyMieSim Python package, which implements the Lorenz-Mie Theory (LMT) for light scattering by spherical particles and other scatterers.

class CoreShell

Bases: BaseScatterer

Core shell spherical scatterer for Lorenz Mie simulations.

The particle is defined by a spherical core, a concentric shell, their respective optical materials, and the surrounding medium. It exposes the Mie coefficients and geometric properties required by the PyMieSim scattering engine.

__init__(self: PyMieSim.single.scatterer.CoreShell, core_diameter: object, shell_thickness: object, core_material: object, shell_material: object, medium: object, max_order: SupportsInt | SupportsIndex = 0) → None

Construct a core shell spherical scatterer.

Parameters:

• core_diameter (pint.Quantity) – Diameter of the spherical core. The value is converted internally to meters.

• shell_thickness (pint.Quantity) – Thickness of the shell surrounding the core. The value is converted internally to meters.

• core_material (BaseMaterial or complex) – Core material model, or a constant complex refractive index.

• shell_material (BaseMaterial or complex) – Shell material model, or a constant complex refractive index.

• medium (BaseMedium or float) – Surrounding medium model, or a constant real refractive index.

• max_order (int, optional) – Maximum multipole order used in the Mie expansion. If zero, the implementation chooses an appropriate truncation order.

Notes

The external particle radius is core_diameter / 2 + shell_thickness. The plotting helper uses normalized display radii and does not draw the particle at its physical nanometer scale.

property an

Electric type external Mie coefficients (a_n).

Returns:

Zero copy complex array containing the external scattering coefficients (a_n).

Return type:

numpy.ndarray

property bn

Magnetic type external Mie coefficients (b_n).

Returns:

Zero copy complex array containing the external scattering coefficients (b_n).

Return type:

numpy.ndarray

property cn

Electric type internal Mie coefficients (c_n).

Returns:

Zero copy complex array containing the internal coefficients (c_n).

Return type:

numpy.ndarray

property core_diameter

Diameter of the core.

Returns:

Core diameter expressed as a compact length unit.

Return type:

pint.Quantity

property core_material

Material model of the core.

property dn

Magnetic type internal Mie coefficients (d_n).

Returns:

Zero copy complex array containing the internal coefficients (d_n).

Return type:

numpy.ndarray

print_properties(self: PyMieSim.single.scatterer.CoreShell, arg0: SupportsInt | SupportsIndex) → None

Print the core shell scatterer properties to standard output.

property_names = ['size_parameter', 'cross_section', 'g', 'g_with_farfields', 'Qsca', 'Qext', 'Qabs', 'Qback', 'Qratio', 'Qforward', 'Qpr', 'Csca', 'Cext', 'Cabs', 'Cback', 'Cratio', 'Cforward', 'Cpr']

property radius

Outer radius of the core shell particle.

Returns:

Outer radius expressed as a compact length unit.

Return type:

pint.Quantity

property shell_material

Material model of the shell.

property shell_thickness

Thickness of the shell.

Returns:

Shell thickness expressed as a compact length unit.

Return type:

pint.Quantity

property volume

Shell volume excluding the core volume.

Returns:

Shell volume expressed as a compact cubic length unit.

Return type:

pint.Quantity

class InfiniteCylinder

Bases: BaseScatterer

Infinite cylindrical scatterer for Lorenz Mie simulations.

The cylinder is defined by its diameter, material, surrounding medium, and optional maximum expansion order. It exposes the cylindrical scattering coefficients and basic geometric properties used by the PyMieSim scattering engine.

__init__(self: PyMieSim.single.scatterer.InfiniteCylinder, diameter: object, material: object, medium: object, max_order: SupportsInt | SupportsIndex = 0) → None

Construct an infinite cylindrical scatterer.

Parameters:

• diameter (pint.Quantity) – Cylinder diameter. The value is converted internally to meters.

• material (BaseMaterial or complex) – Cylinder material model, or a constant complex refractive index.

• medium (BaseMedium or float) – Surrounding medium model, or a constant real refractive index.

• max_order (int, optional) – Maximum expansion order used in the cylindrical Mie calculation. If zero, the implementation chooses an appropriate truncation order.

Notes

The cylinder is infinite in the scattering model. The plotting helper draws a finite cylinder only as a normalized visual representation.

property a1n

Cylindrical scattering coefficients (a_{1n}).

Returns:

Zero copy complex array containing the (a_{1n}) coefficients.

Return type:

numpy.ndarray

property a2n

Cylindrical scattering coefficients (a_{2n}).

Returns:

Zero copy complex array containing the (a_{2n}) coefficients.

Return type:

numpy.ndarray

property b1n

Cylindrical scattering coefficients (b_{1n}).

Returns:

Zero copy complex array containing the (b_{1n}) coefficients.

Return type:

numpy.ndarray

property b2n

Cylindrical scattering coefficients (b_{2n}).

Returns:

Zero copy complex array containing the (b_{2n}) coefficients.

Return type:

numpy.ndarray

property diameter

Cylinder diameter.

Returns:

Diameter expressed as a compact length unit.

Return type:

pint.Quantity

property material

Material model of the cylinder.

property medium

Medium surrounding the cylinder.

print_properties(self: PyMieSim.single.scatterer.InfiniteCylinder, arg0: SupportsInt | SupportsIndex) → None

Print the cylinder properties to standard output.

property_names = ['size_parameter', 'cross_section', 'g_with_farfields', 'Qsca', 'Qext', 'Qabs', 'Csca', 'Cext', 'Cabs']

property radius

Cylinder radius.

Returns:

Radius expressed as a compact length unit.

Return type:

pint.Quantity

class Sphere

Bases: BaseScatterer

Spherical scatterer for Lorenz Mie simulations.

The sphere is defined by its diameter, material, surrounding medium, and optional maximum multipole order. It exposes the Mie scattering coefficients and basic geometric properties used by the PyMieSim scattering engine.

__init__(self: PyMieSim.single.scatterer.Sphere, diameter: object, material: object, medium: object, max_order: SupportsInt | SupportsIndex = 0) → None

Construct a spherical scatterer.

Parameters:

• diameter (pint.Quantity) – Sphere diameter. The value is converted internally to meters.

• material (BaseMaterial or complex) – Sphere material model, or a constant complex refractive index.

• medium (BaseMedium or float) – Surrounding medium model, or a constant real refractive index.

• max_order (int, optional) – Maximum multipole order used in the Mie expansion. If zero, the implementation chooses an appropriate truncation order.

Notes

The material and medium may be dispersive objects or constant refractive indices, depending on the Python object passed to the constructor.

property an

Electric type external Mie coefficients (a_n).

Returns:

Zero copy complex array containing the external scattering coefficients (a_n).

Return type:

numpy.ndarray

property bn

Magnetic type external Mie coefficients (b_n).

Returns:

Zero copy complex array containing the external scattering coefficients (b_n).

Return type:

numpy.ndarray

property cn

Electric type internal Mie coefficients (c_n).

Returns:

Zero copy complex array containing the internal coefficients (c_n).

Return type:

numpy.ndarray

property diameter

Sphere diameter.

Returns:

Diameter expressed as a compact length unit.

Return type:

pint.Quantity

property dn

Magnetic type internal Mie coefficients (d_n).

Returns:

Zero copy complex array containing the internal coefficients (d_n).

Return type:

numpy.ndarray

property material

Material model of the sphere.

property medium

Medium surrounding the sphere.

print_properties(self: PyMieSim.single.scatterer.Sphere, arg0: SupportsInt | SupportsIndex) → None

Print the sphere properties to standard output.

property_names = ['size_parameter', 'cross_section', 'g', 'g_with_farfields', 'Qsca', 'Qext', 'Qabs', 'Qback', 'Qratio', 'Qforward', 'Qpr', 'Csca', 'Cext', 'Cabs', 'Cback', 'Cratio', 'Cforward', 'Cpr']

property radius

Sphere radius.

Returns:

Radius expressed as a compact length unit.

Return type:

pint.Quantity

property volume

Sphere volume.

Returns:

Volume expressed as a compact cubic length unit.

Return type:

pint.Quantity

Detectors

Detector bindings for PyMieSim.

This module exposes detector classes used to compute optical coupling between Lorenz Mie scatterers and detector geometries. It includes photodiode, coherent mode, and integrating sphere detectors.

The plotting helpers use Matplotlib axes directly through private _add_to_ax methods. Figure creation, styling, and public plotting APIs should remain controlled from the Python layer.

class CoherentMode

Bases: BaseDetector

Coherent mode detector for Lorenz Mie scattering simulations.

A coherent mode detector projects the scattered field onto a specified collecting mode and can account for orientation, rotation, numerical aperture, obscuration cache, and polarization filtering.

__init__(self: PyMieSim.single.detector.CoherentMode, mode_number: str, numerical_aperture: object, phi_offset: object, gamma_offset: object, rotation: object, medium: object = None, cache_numerical_aperture: object = 0.0, polarization_filter: object = <PolarizationState empty=True>, mean_coupling: object = False, sampling: typing.SupportsInt | typing.SupportsIndex = 200) → None

Construct a coherent mode detector.

Parameters:

• mode_number (str) – Mode identifier, for example "LP01" or "HG12".

• numerical_aperture (float) – Numerical aperture defining the angular collection region.

• phi_offset (pint.Quantity) – Azimuthal orientation offset.

• gamma_offset (pint.Quantity) – Polar orientation offset.

• rotation (pint.Quantity) – Rotation of the detector mode field.

• medium (BaseMedium or float, optional) – Surrounding medium. If None, a constant refractive index of 1.0 is used.

• cache_numerical_aperture (float, optional) – Numerical aperture of the central obscuration cache.

• polarization_filter (PolarizationState, optional) – Polarization filter applied before coherent projection.

• mean_coupling (bool, optional) – If True, use mean coupling behavior where supported by the detector implementation.

• sampling (int, optional) – Number of angular samples on the detector mesh.

print_properties(self: PyMieSim.single.detector.CoherentMode, precision: SupportsInt | SupportsIndex = 4) → None

Print coherent mode detector properties.

Parameters:

precision (int, optional) – Number of decimal places used for floating point values.

property rotation

Rotation angle of the coherent mode field.

Returns:

Rotation angle in radians.

Return type:

pint.Quantity

class IntegratingSphere

Bases: BaseDetector

Integrating sphere detector for Lorenz Mie scattering simulations.

The integrating sphere represents full angular collection over the detector mesh, optionally with polarization filtering.

__init__(self: PyMieSim.single.detector.IntegratingSphere, polarization_filter: object = <PolarizationState empty=True>, sampling: typing.SupportsInt | typing.SupportsIndex = 400) → None

Construct an integrating sphere detector.

Parameters:

• polarization_filter (PolarizationState, optional) – Polarization filter applied before detection.

• sampling (int, optional) – Number of angular samples on the detector mesh.

print_properties(self: PyMieSim.single.detector.IntegratingSphere, precision: SupportsInt | SupportsIndex = 4) → None

Print integrating sphere detector properties.

Parameters:

precision (int, optional) – Number of decimal places used for floating point values.

class Photodiode

Bases: BaseDetector

Photodiode detector for Lorenz Mie scattering simulations.

A photodiode integrates the scattered power over an angular collection aperture defined by its numerical aperture, orientation, optional obscuration cache, and polarization filter.

__init__(self: PyMieSim.single.detector.Photodiode, numerical_aperture: object, phi_offset: object, gamma_offset: object, medium: object = None, polarization_filter: object = <PolarizationState empty=True>, cache_numerical_aperture: object = 0.0, sampling: typing.SupportsInt | typing.SupportsIndex = 200) → None

Construct a photodiode detector.

Parameters:

• numerical_aperture (float) – Numerical aperture defining the detector collection angle.

• phi_offset (pint.Quantity) – Azimuthal orientation offset.

• gamma_offset (pint.Quantity) – Polar orientation offset.

• medium (BaseMedium or float, optional) – Surrounding medium. If None, a constant refractive index of 1.0 is used.

• polarization_filter (PolarizationState, optional) – Polarization filter applied before detection.

• cache_numerical_aperture (float, optional) – Numerical aperture of the central obscuration cache.

• sampling (int, optional) – Number of angular samples on the detector mesh.

print_properties(self: PyMieSim.single.detector.Photodiode, precision: SupportsInt | SupportsIndex = 4) → None

Print photodiode properties.

Parameters:

precision (int, optional) – Number of decimal places used for floating point values.

Representations

Far-field scattering representation.

This class computes and visualizes the complex far-field electric-field components returned by a single-scatterer setup.

The far-field components are evaluated on a spherical angular mesh and are returned as the transverse components (E_phi) and (E_theta).

The default visualization is a single three-dimensional spherical plot. A single field is shown at a time to keep rendering responsive and to make the figure easier to interpret.

class Stokes(setup, sampling=200, distance=<Quantity(1.0, 'meter')>)

Bases: object

Stokes parameter representation.

The Stokes parameters describe the polarization state of the scattered light.

\[\begin{split}I &= |E_x|^2 + |E_y|^2 \\ Q &= |E_x|^2 - |E_y|^2 \\ U &= 2 \operatorname{Re}\{E_x E_y^*\} \\ V &= 2 \operatorname{Im}\{E_x E_y^*\}\end{split}\]

Parameters:

• setup (object) – Single-scatterer setup object exposing get_stokes.

• sampling (int, optional) – Number of angular samples used in each spherical mesh direction.

• distance (pint.Quantity, optional) – Observation distance at which the Stokes parameters are evaluated.

setup

Simulation setup used to compute the Stokes parameters.

Type:

object

sampling

Angular sampling used for the structured Stokes mesh.

Type:

int

distance

Observation distance.

Type:

pint.Quantity

I

Total scattered intensity.

Type:

pint.Quantity

Q

Linear polarization contrast between the x and y axes.

Type:

pint.Quantity

U

Linear polarization contrast between the +45 and -45 degree axes.

Type:

pint.Quantity

V

Circular polarization contrast.

Type:

pint.Quantity

mesh

Full spherical mesh returned by the backend.

Type:

object

plot(field='I', unit_size=(5.0, 5.0), background_color='white', show_edges=False, edge_color='black', colormap=<matplotlib.colors.LinearSegmentedColormap object>, opacity=1.0, show_axis_label=False, show_colorbar=True, percentile_clip=None, surface_linewidth=0.0, surface_antialiased=False, elevation=25.0, azimuth=35.0)

Plot one Stokes parameter on a Matplotlib 3D spherical surface.

Examples

stokes.plot("I")
stokes.plot("Q")
stokes.plot("U")
stokes.plot("V")

Parameters:

• field (str, optional) – Stokes parameter to plot. Supported values are "I", "Q", "U", and "V".

• unit_size (Sequence[float], optional) – Figure size in inches, given as (width, height).

• background_color (str, optional) – Figure and axis background color.

• show_edges (bool, optional) – If True, draw surface mesh edges. Edges are also drawn automatically when surface_linewidth is greater than zero.

• edge_color (str, optional) – Color used for surface mesh edges.

• colormap (str or matplotlib.colors.Colormap, optional) – Colormap used for the Stokes parameter values.

• opacity (float, optional) – Surface opacity.

• show_axis_label (bool, optional) – If True, display Cartesian axis labels, ticks, and panes. If False, hide the axis frame.

• show_colorbar (bool, optional) – If True, add a colorbar.

• percentile_clip (float, optional) – If provided, symmetric color limits are clipped to this percentile of the finite absolute values.

• surface_linewidth (float, optional) – Line width used for surface edges. Values greater than zero enable mesh edges even if show_edges is False.

• surface_antialiased (bool, optional) – Matplotlib antialiasing flag for surfaces.

• elevation (float, optional) – Matplotlib 3D view elevation angle in degrees.

• azimuth (float, optional) – Matplotlib 3D view azimuth angle in degrees.

Returns:

Matplotlib figure containing the selected Stokes parameter.

Return type:

matplotlib.figure.Figure

class SPF(setup, sampling=200)

Bases: object

Scattering phase function representation.

The scattering phase function describes how the scattered intensity varies as a function of the scattering direction around the particle.

The SPF is sampled on the backend spherical mesh and can be rendered either as a normalized radial surface or as an intensity map on a unit sphere.

Parameters:

• setup (object) – Single scatterer setup object exposing get_spf.

• sampling (int, optional) – Number of angular samples used in each spherical mesh direction.

setup

Simulation setup used to compute the scattering phase function.

Type:

object

sampling

Angular sampling used for the structured SPF mesh.

Type:

int

SPF

Scattering phase function sampled on the spherical mesh.

Type:

numpy.ndarray

mesh

Full spherical mesh returned by the backend.

Type:

object

plot(unit_size=(5.0, 5.0), background_color='white', show_edges=False, edge_color='black', colormap='viridis', opacity=1.0, set_surface=True, show_axis_label=False, scale='linear', percentile_clip=None, surface_linewidth=0.1, surface_antialiased=False, elevation=25.0, azimuth=35.0)

Plot the scattering phase function on a Matplotlib 3D surface.

Parameters:

• unit_size (Sequence[float], optional) – Figure size in inches, given as (width, height).

• background_color (str, optional) – Figure and axis background color.

• show_edges (bool, optional) – If True, draw surface mesh edges. Edges are also drawn automatically when surface_linewidth is greater than zero.

• edge_color (str, optional) – Color used for surface mesh edges.

• colormap (str or matplotlib.colors.Colormap, optional) – Colormap used for the SPF intensity values.

• opacity (float, optional) – Surface opacity.

• set_surface (bool, optional) – If True, the surface radius is proportional to the normalized SPF intensity. If False, the SPF intensity is drawn on a unit sphere.

• show_axis_label (bool, optional) – If True, display Cartesian axis labels, ticks, and panes. If False, hide the axis frame.

• scale (str, optional) – Color scaling. Supported values are "linear" and "log".

• percentile_clip (float, optional) – If provided, the upper color limit is clipped to this percentile of the finite positive values.

• surface_linewidth (float, optional) – Line width used for surface edges. Values greater than zero enable mesh edges even if show_edges is False.

• surface_antialiased (bool, optional) – Matplotlib antialiasing flag for surfaces.

• elevation (float, optional) – Matplotlib 3D view elevation angle in degrees.

• azimuth (float, optional) – Matplotlib 3D view azimuth angle in degrees.

Returns:

Matplotlib figure containing the SPF visualization.

Return type:

matplotlib.figure.Figure

class S1S2(setup, sampling=200)

Bases: object

Compute the S1 and S2 scattering amplitude functions for a spherical scatterer.

The S1 and S2 parameters represent the scattering amplitudes for perpendicular and parallel polarizations of light, respectively. These parameters are fundamental in Mie theory, which describes the scattering of electromagnetic waves by spherical particles.

The formulas for ( S_1 ) and ( S_2 ) are:

\[\begin{split}S_1 = \sum\limits_{n=1}^{n_{\text{max}}} \frac{2n+1}{n(n+1)} \left( a_n \pi_n + b_n \tau_n \right) \\ S_2 = \sum\limits_{n=1}^{n_{\text{max}}} \frac{2n+1}{n(n+1)} \left( a_n \tau_n + b_n \pi_n \right)\end{split}\]

Where:

• \(a_n\) and \(b_n\): Mie coefficients, which depend on the size, shape, and refractive index of the scatterer.

• \(\pi_n\) and \(\tau_n\) )`: Angular functions related to the angular components of the incident and scattered fields.

• \(n_{\text{max}}\): Maximum number of terms in the series, determined by the size parameter of the scatterer.

These scattering amplitude functions are essential for calculating properties such as scattering phase functions, efficiencies, and angular distribution of scattered light.

Parameters:

• sampling (int) – The number of angular points used to sample the S1 and S2 functions. Higher sampling improves the resolution of the scattering pattern but increases computation time.

• distance (Length, optional) – The distance from the scatterer at which the S1 and S2 parameters are evaluated. This is typically set to 1 meter by default, but can be adjusted for specific setups.

Returns:

An object containing the computed S1 and S2 parameters, representing the scattering amplitudes for the two polarization components.

Return type:

representations.S1S2

Notes

• The S1 and S2 parameters are central to Mie scattering theory and are used to derive many important scattering properties, such as intensity distributions and polarization effects.

• The sampling parameter controls how finely the angular distribution is resolved. A higher value of sampling provides more detailed scattering information, which can be critical for accurately modeling the far-field pattern.

Example

You can use this method to compute the scattering properties of spherical particles, particularly in experiments where the polarization and scattering pattern of the light are important.

Example usage:

>>> s1s2 = scatterer.get_s1s2(sampling=500)
>>> print(s1s2.S1, s1s2.S2)

plot(figure_size=(12, 5), titles=('S$_1$ parameter', 'S$_2$ parameter'), tight_layout=True, save_as=None, show=True, ylim=None, style=None)

Plot the S1 and S2 scattering amplitudes on polar subplots.

Parameters:

• figure_size (Tuple[float, float]) – Figure size passed to plt.subplots.

• titles (Sequence[str]) – Two subplot titles applied to the S1 and S2 panels.

• tight_layout (bool) – If True, call figure.tight_layout() before returning.

• save_as (str | None) – Optional output path used to save the figure.

• show (bool) – If True, display the figure with plt.show().

• ylim (Tuple[float, float] | None) – Optional radial limits applied to both polar subplots.

• style – Matplotlib style applied while creating the figure. If omitted, the runtime-loaded MPSPlots.styles.scientific style is used.

Returns:

Figure containing the two polar amplitude plots.

Return type:

plt.Figure

class Footprint(setup, sampling=200, padding_factor=20)

Bases: object

Compute the footprint of the scattered light coupling with the detector.

The footprint represents the spatial distribution of the scattered light as it couples with the detector. This is important for understanding how the scattered light interacts with the detector’s field of view and is influenced by both the scatterer’s properties and the detector configuration.

The footprint is computed using an inverse Fourier transform:

\[\big| \mathscr{F}^{-1} \big\{ \tilde{ \psi } (\xi, \nu),\ \tilde{ \phi}_{l,m}(\xi, \nu) \big\} (\delta_x, \delta_y) \big|^2\]

Where:

• \(\tilde{ \psi } (\xi, \nu)\): The Fourier transform of the scattered field.

• \(\tilde{ \phi}_{l,m} (\xi, \nu)\): The Fourier transform of the detector’s capturing field.

• \(\mathscr{F}^{-1}\): The inverse Fourier transform operator.

• \((\delta_x, \delta_y)\): Spatial coordinates describing the footprint in the detector plane.

The inverse Fourier transform yields the spatial pattern of the scattered light’s interaction with the detector, which is then squared to compute the intensity of the footprint.

Parameters:

• detector (GenericDetector) – The detector object that defines the capturing field and geometry. This object provides information about the detector’s configuration, including its numerical aperture, position, and sensitivity.

• setup (object)

• sampling (int)

• padding_factor (int)

Returns:

An object containing the computed scatterer footprint, representing the spatial distribution of the scattered light on the detector plane.

Return type:

representations.Footprint

Notes

• The footprint provides valuable information about the coupling efficiency between the scattered light and the detector. This is useful in designing experiments where precise control of light detection is important, such as in microscopy, remote sensing, or optical measurements.

• The interaction between the scattered field and the detector is influenced by factors such as the size, shape, and refractive index of the scatterer, as well as the detector’s aperture and positioning.

Example

You can use this method to compute the footprint of the scattered light on a detector, helping to visualize how light from the scatterer is spatially distributed on the detector.

Example usage:

>>> footprint = scatterer.get_footprint(detector=my_detector)
>>> print(footprint)

compute_footprint()

Computes the footprint of the scatterer as detected by the specified detector.

The footprint is calculated based on the far-field scattering patterns and the characteristics of the detector, using a Fourier transform to project the far-field onto the detector plane.

The computed footprint and the corresponding spatial coordinates are stored as attributes of the instance.

Warning: this function do not currently take account of the cache block on the detector.

get_fourier_component(scalar)

Computes the Fourier component of a given scalar field.

This method performs a two-dimensional inverse Fourier transform on the input scalar field, which represents a projection (either parallel or perpendicular) of the far-field pattern. It then extracts a central portion of the result, effectively applying a padding factor to increase the resolution of the Fourier transform.

Parameters:

scalar (-) – A two-dimensional numpy array representing the scalar field of which the Fourier component is to be computed. This field could represent either the parallel or perpendicular projection of the far-field pattern onto the detector plane.

Returns:

• numpy.ndarray – A two-dimensional numpy array representing the computed Fourier component. This array is a square section, extracted from the center of the full Fourier transform, with dimensions determined by the original sampling rate and the padding factor of the instance. The values in the array represent the intensity distribution of the light in the detector plane, providing insights into the spatial characteristics of the scattering pattern.

• The method uses numpy’s fft module to perform the Fourier transform, applying a padding factor to the input to

• achieve a higher resolution in the Fourier domain. The resulting Fourier transform is then squared and fftshifted

• to center the zero-frequency component, and a central portion is extracted to match the intended output size.

Return type:

ndarray

plot(colormap='gray')

Plots the scatterer footprint using a 2D colormap.

The method generates a plot representing the footprint of the scatterer, with the X and Y axes showing offset distances in micrometers, and the colormap depicting the mapping values.

Parameters:

colormap (str) – The colormap to use for the plot. Default is ‘gray’.

Return type:

None

class NearFields(setup)

Bases: object

Near field visualization for a scatterer.

This class samples fields over an arbitrary plane defined by an origin and a normal. All coordinates are kept as unit aware objects because the C++ wrapper accepts units.

Important concept

The plot is parameterized by two in plane coordinates (u, v):

r(u, v) = r0 + u * u_hat + v * v_hat

The ranges u_range and v_range define the sampled extent in that plane. These replace the old idea of x_range and y_range, because the plane is not necessarily a z slice.

param scatterer:

Object exposing compute_total_nearfields, compute_incident_nearfields, compute_scattered_nearfields.

plot(*field_components, type='scattered', sampling=200, plane_origin=None, plane_normal=None, u_range=None, v_range=None, extent_scale=2.5, colormap=<matplotlib.colors.LinearSegmentedColormap object>, figure_size=(6, 6), tight_layout=True, save_as=None, show=True, xscale=None, yscale=None, xlim=None, ylim=None, style=PosixPath('/opt/hostedtoolcache/Python/3.11.15/x64/lib/python3.11/site-packages/MPSPlots/styles/scientific.mplstyle'))

Plot near fields over a specified plane.

Parameters:

• field_components (str) – List of field components to plot, for example Ex:real, |E|:abs.

• type (str) – Type of field to compute: total, incident, or scattered.

• sampling (int) – Number of points along each in plane direction (u and v).

• plane_origin (Sequence[Length] | None) – Origin of the sampling plane in 3D space. If None, defaults to (0, 0, z).

• plane_normal (Sequence[float] | None) – Normal vector of the sampling plane. If None, defaults to (0, 0, 1).

• u_range (Tuple[Length, Length] | None) – Range of plane coordinate u along u_hat. If None, inferred from scatterer diameter and extent_scale.

• v_range (Tuple[Length, Length] | None) – Range of plane coordinate v along v_hat. If None, inferred from scatterer diameter and extent_scale.

• extent_scale (float) – Scaling factor applied to the default extent derived from the scatterer radius.

• colormap (str) – Colormap to use for plotting.

• figure_size (tuple) – Size of the matplotlib figure.

• tight_layout (bool) – If True, call figure.tight_layout() before returning.

• save_as (str | None) – Optional output path used to save the figure.

• show (bool) – If True, display the figure with plt.show().

• xscale (str | None) – Optional x-axis scale applied to every subplot.

• yscale (str | None) – Optional y-axis scale applied to every subplot.

• xlim (Tuple[float, float] | None) – Optional x-axis limits applied to every subplot.

• ylim (Tuple[float, float] | None) – Optional y-axis limits applied to every subplot.

• style – Matplotlib style applied while constructing the figure.

Returns:

Figure containing the requested near-field plots.

Return type:

plt.Figure

Parameters:

setup (object)