# holopy.scattering package¶

## Module contents¶

Scattering calculations

The scattering package provides objects and methods to define scatterer geometries, and theories to compute scattering from specified geometries. Scattering depends on holopy.core, and certain scattering theories may require external scattering codes.

The HoloPy scattering module is used to:

1. Describe geometry as a scatterer object
2. Define the result you want as a Schema object
3. Calculate scattering quantities with an theory appropriate for your scatterer -> Marray object

## holopy.scattering.calculations module¶

Base class for scattering theories. Implements python-based calc_intensity and calc_holo, based on subclass’s calc_field

calc_cross_sections(scatterer, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto')

Calculate scattering, absorption, and extinction cross sections, and asymmetry parameter <cos heta>.

Parameters: scatterer (scatterer object) – (possibly composite) scatterer for which to compute scattering medium_index (float or complex) – Refractive index of the medium in which the scatter is imbedded illum_wavelen (float or ndarray(float)) – Wavelength of illumination light. If illum_wavelen is an array result will add a dimension and have all wavelengths theory (theory object (optional)) – Scattering theory object to use for the calculation. This is optional if there is a clear choice of theory for your scatterer. If there is not a clear choice, calc_intensity will error out and ask you to specify a theory cross_sections – Dimensional scattering, absorption, and extinction cross sections, and array (4)
calc_field(schema, scatterer, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto')

Calculate hologram formed by interference between scattered fields and a reference wave

Parameters: scatterer (scatterer object) – (possibly composite) scatterer for which to compute scattering medium_index (float or complex) – Refractive index of the medium in which the scatter is imbedded illum_wavelen (float or ndarray(float)) – Wavelength of illumination light. If illum_wavelen is an array result will add a dimension and have all wavelengths theory (theory object (optional)) – Scattering theory object to use for the calculation. This is optional if there is a clear choice of theory for your scatterer. If there is not a clear choice, calc_intensity will error out and ask you to specify a theory e_field – Calculated hologram from the given distribution of spheres Vector object
calc_holo(schema, scatterer, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto', scaling=1.0)

Calculate hologram formed by interference between scattered fields and a reference wave

Parameters: scatterer (scatterer object) – (possibly composite) scatterer for which to compute scattering medium_index (float or complex) – Refractive index of the medium in which the scatter is imbedded illum_wavelen (float or ndarray(float)) – Wavelength of illumination light. If illum_wavelen is an array result will add a dimension and have all wavelengths theory (theory object (optional)) – Scattering theory object to use for the calculation. This is optional if there is a clear choice of theory for your scatterer. If there is not a clear choice, calc_intensity will error out and ask you to specify a theory scaling (scaling value (alpha) for amplitude of reference wave) – holo – Calculated hologram from the given distribution of spheres Image object
calc_intensity(schema, scatterer, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto')

Calculate intensity at a location or set of locations

Parameters: scatterer (scatterer object) – (possibly composite) scatterer for which to compute scattering medium_index (float or complex) – Refractive index of the medium in which the scatter is imbedded illum_wavelen (float or ndarray(float)) – Wavelength of illumination light. If illum_wavelen is an array result will add a dimension and have all wavelengths theory (theory object (optional)) – Scattering theory object to use for the calculation. This is optional if there is a clear choice of theory for your scatterer. If there is not a clear choice, calc_intensity will error out and ask you to specify a theory inten – scattered intensity Image
calc_scat_matrix(schema, scatterer, medium_index=None, illum_wavelen=None, theory='auto')

Compute farfield scattering matrices for scatterer

Parameters: scatterer (holopy.scattering.scatterer object) – (possibly composite) scatterer for which to compute scattering medium_index (float or complex) – Refractive index of the medium in which the scatter is imbedded illum_wavelen (float or ndarray(float)) – Wavelength of illumination light. If illum_wavelen is an array result will add a dimension and have all wavelengths theory (theory object (optional)) – Scattering theory object to use for the calculation. This is optional if there is a clear choice of theory for your scatterer. If there is not a clear choice, calc_intensity will error out and ask you to specify a theory scat_matr – Scattering matrices at specified positions Marray
check_schema(schema, pol=True)
determine_theory(scatterer)
finalize(schema, result)
interpret_theory(scatterer, theory='auto')
prep_schema(schema, medium_index, illum_wavelen, illum_polarization)
scattered_field_to_hologram(scat, ref, normals)

Calculate a hologram from an E-field

Parameters: scat (VectorGrid) – The scattered (object) field ref (xarray[vector]]) – The reference field detector_normal ((float, float, float)) – Vector normal to the detector the hologram should be measured at (defaults to z hat, a detector in the x, y plane)

## holopy.scattering.geometry module¶

Routines for common calculations and transformations of groups of spheres.

This code is in need of significant refactoring and simplification, refactoring which may break code that depends on it.

angles(cluster, degrees=True)

calculate the angles between one particle and every pair of other particles

Parameters: cluster (holopy.scattering.scatterer.Scatterer) – A sphere cluster to determine the interparticle distances of. degrees (bool) – Whether to return angles in degrees (True) or in radians (False).

Notes

Angle abc is the acute angle formed by edges conecting points ab and bc. If a, b, and c are locations of particles (vertices), the returned 3D array has non-zero values for angles abc, zeros for angles aba, and NAN’s for “angles” aab.

distances(cluster, gaponly=False)

calculate the distances between each sphere in a cluster and each of the others

Parameters: cluster (holopy.scattering.scatterer.Scatterer) – A sphere cluster to determine the interparticle distances of. gaponly (bool) – Whether to calculate the distances between particle centers or between particle surfaces (gap distances).

Notes

The returned array of distances includes redundant information. The identical distances between sphere 1 and sphere 2 and between sphere 2 and sphere 1 are both in the returned array. Calculating and returning the full array makes it easy for the user to access all the interparticle distances starting from any sphere of interest.

make_cubecluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of eight particles forming a cube centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate
make_octacluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of six particles forming an octahedron centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate
make_polytetracluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of six particles forming a polytetrahedron centered on a given center of mass of the middle tetrahedron.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass of the middle tetrahedron x-coordinate ycom – Center of mass of the middle tetrahedron x-coordinate zcom – Center of mass of the middle tetrahedron x-coordinate
make_sqcluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of four particles forming a square centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate
make_tetracluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of four particles forming a tetrahedron centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate
make_tribipyrcluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of five particles forming a triagonal bipyramid centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate
make_tricluster(index, radius, gap, xcom=0, ycom=0, zcom=0)

Returns a sphere cluster of three particles forming an equilateral triangle centered on a given center of mass.

Parameters: index – Index of refraction of particles. radius – Radius if particles. gap – Space to add between the particles. xcom – Center of mass x-coordinate ycom – Center of mass y-coordinate zcom – Center of mass z-coordinate