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, precision: SupportsInt | SupportsIndex = 4) → None

Print the core shell scatterer properties to standard output.

Parameters:

precision (int, optional) – Decimal places used in scientific notation (default: 4).

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 total_diameter

Outer diameter of the complete core-shell particle.

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, precision: SupportsInt | SupportsIndex = 4) → None

Print the cylinder properties to standard output.

Parameters:

precision (int, optional) – Decimal places used in scientific notation (default: 4).

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, precision: SupportsInt | SupportsIndex = 4) → None

Print the sphere properties to standard output.

Parameters:

precision (int, optional) – Decimal places used in scientific notation (default: 4).

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: SupportsInt | 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: SupportsInt | 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: SupportsInt | 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

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

Bases: AngularPlotMixin

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.

Parameters:

• setup (object)

• sampling (int)

• distance (Length)

add_phi_vector_to_3d_plot(ax, n_points=10, opacity=1.0, radius=1.0, length=0.08, color='black')

Add sparse unit vectors in the local :math:` phi ` direction.

This reproduces the previous PyVista call

transform_vectors_sph_to_cart(theta=theta, phi=phi, r=radius, u=0, v=1, w=0)

where theta is the azimuthal angle in degrees and phi is the polar angle in degrees.

Parameters:

• n_points (int)

• opacity (float)

• radius (float)

• length (float)

• color (str)

Return type:

None

add_theta_vector_to_3d_plot(ax, n_points=10, opacity=1.0, radius=1.0, length=0.08, color='black')

Add sparse unit vectors in the local :math:` theta ` direction.

This reproduces the previous PyVista call

transform_vectors_sph_to_cart(theta=theta, phi=phi, r=radius, u=1, v=0, w=0)

where theta is the azimuthal angle in degrees and phi is the polar angle in degrees.

Parameters:

• n_points (int)

• opacity (float)

• radius (float)

• length (float)

• color (str)

Return type:

None

plot(field='total_intensity', unit_size=(5.0, 5.0), background_color='white', colormap=None, opacity=1.0, show_edges=False, show_axis_label=False, show_colorbar=True, show_vector_field=False, vector_count=10, vector_radius=1.1, vector_length=0.08, vector_color='black', scale='log', percentile_clip=None, surface_linewidth=0.0, surface_antialiased=False, elevation=25.0, azimuth=35.0)

Plot one far-field quantity on a three-dimensional spherical surface.

Parameters:

• field (str, optional) –

  Quantity to plot. Supported values are:

  "total_intensity"

  Total intensity, computed as |E_phi|^2 + |E_theta|^2.

  "phi_intensity"

  Phi component intensity, computed as |E_phi|^2.

  "theta_intensity"

  Theta component intensity, computed as |E_theta|^2.

  "phi_real"

  Real part of \(E_\phi\).

  "phi_imag"

  Imaginary part of \(E_\phi\).

  "theta_real"

  Real part of \(E_\theta\).

  "theta_imag"

  Imaginary part of \(E_\theta\).

  "phi_phase"

  Phase of \(E_\phi\).

  "theta_phase"

  Phase of \(E_\theta\).

  "phase_difference"

  Wrapped phase difference arg(E_theta) - arg(E_phi).

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

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

• colormap (str or matplotlib.colors.Colormap, optional) – Colormap used for the selected field. If None, MPSPlots.colormaps.blue_black_red is used.

• opacity (float, optional) – Surface opacity.

• show_edges (bool, optional) – If True, draw surface mesh edges.

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

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

• show_vector_field (bool, optional) – If True, overlay sparse local basis vectors. Phi fields receive phi vectors, theta fields receive theta vectors, and total fields do not receive a vector overlay.

• vector_count (int, optional) – Number of angular samples per direction used for vector overlays.

• vector_radius (float, optional) – Radius at which direction vectors are drawn.

• vector_length (float, optional) – Display length of direction vectors.

• vector_color (str, optional) – Color of the direction vectors.

• scale (str, optional) – Scaling for intensity fields. Supported values are "linear" and "log". Ignored for signed and phase fields.

• percentile_clip (float, optional) – If provided, upper color limits are clipped to this percentile.

• surface_linewidth (float, optional) – Line width used for surface edges.

• 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 spherical far-field plot.

Return type:

matplotlib.figure.Figure

plot_heatmap(kind='intensity', unit_size=(4.2, 3.6), colormap=None, background_color='white', show_colorbar=True, scale='log', percentile_clip=None, interpolation='nearest')

Plot far-field quantities as two-dimensional angular heatmaps.

Parameters:

• kind (str, optional) – Plot type. Supported values are "intensity", "complex", and "phase".

• unit_size (Sequence[float], optional) – Size of each panel in inches, given as (width, height).

• colormap (str or matplotlib.colors.Colormap, optional) – Colormap used for the plotted values. If None, MPSPlots.colormaps.blue_black_red is used.

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

• show_colorbar (bool, optional) – If True, add one colorbar to each panel.

• scale (str, optional) – Scaling for intensity plots. Supported values are "linear" and "log". Ignored for "complex" and "phase".

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

• interpolation (str, optional) – Interpolation mode passed to imshow.

Returns:

Matplotlib figure containing the far-field heatmaps.

Return type:

matplotlib.figure.Figure

sampling: int

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

Bases: AngularPlotMixin

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.

Variables:

• setup (object) – Simulation setup used to compute the Stokes parameters.

• sampling (int) – Angular sampling used for the structured Stokes mesh.

• distance (pint.Quantity) – Observation distance.

• I (pint.Quantity) – Total scattered intensity.

• Q (pint.Quantity) – Linear polarization contrast between the x and y axes.

• U (pint.Quantity) – Linear polarization contrast between the +45 and -45 degree axes.

• V (pint.Quantity) – Circular polarization contrast.

• mesh (object) – Full spherical mesh returned by the backend.

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

sampling: int

class SPF(setup, sampling=200)

Bases: AngularPlotMixin

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.

Variables:

• setup (object) – Simulation setup used to compute the scattering phase function.

• sampling (int) – Angular sampling used for the structured SPF mesh.

• SPF (numpy.ndarray) – Scattering phase function sampled on the spherical mesh.

• mesh (object) – Full spherical mesh returned by the backend.

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

sampling: int

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.

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 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:

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

• sampling (int, optional) – Number of angular samples between \(-\pi\) and \(\pi\).

Variables:

• phi (pint.Quantity) – Sampled angular coordinates in radians.

• S2 (S1,) – Complex scattering amplitudes for the two polarization components.

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.

Examples

>>> 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 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.

Parameters:

setup (object)

compute(*field_components, type='scattered', sampling=200, plane_origin=None, plane_normal=None, u_range=None, v_range=None, extent_scale=2.5)

Compute near-field components on the configured sampling plane.

Parameters:

• field_components (Sequence[str]) – Components and reductions to evaluate, such as "Ex:real" or "E:abs".

• type (str) – Field family to evaluate: "total", "incident", or "scattered".

• sampling (int)

• plane_origin (Sequence[Length] | None)

• plane_normal (Sequence[float] | None)

• u_range (Tuple[Length, Length] | None)

• v_range (Tuple[Length, Length] | None)

• extent_scale (float)

Returns:

Requested fields keyed by their component notation. Arrays are arranged on the configured (u, v) sampling grid.

Return type:

dict[str, numpy.ndarray]

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.17/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