API Reference

Mathematical functions

ARTmie.besselj(v, z, es=False)

Calculates the Bessel function of the first kind

Parameters:

  • v (scalar, float) – order of the Bessel function

  • z (scalar or array-like, complex) – the argument/location, where the Bessel function has to be evaluated

  • es (scalar, bool) – optional, exponentially scales the result by \(\exp(\frac{2}{3} z^{1.5})\) if set to True, default: False

Returns:

result of the Bessel function of the first kind and order \(v\) at complex value \(z\), same shape as z

Return type:

scalar or array-like, complex

ARTmie.bessely(v, z, es=False)

Calculates the Bessel function of the second kind

Parameters:

  • v (scalar, float) – order of the Bessel function

  • z (scalar or array-like, complex) – the argument/location, where the Bessel function has to be evaluated

  • es (scalar, bool) – optional, exponentially scales the result by \(\exp(\frac{2}{3} z^{1.5})\) if set to True, default: False

Returns:

result of the Bessel function of the second kind and order \(v\) at complex value \(z\), same shape as z

Return type:

scalar or array-like, complex

ARTmie.hankel(v, z, m, es=False)

Calculates the Bessel function of the third kind Also known as Hankel function.

Parameters:

  • v (scalar, float) – order of the Bessel function

  • z (scalar, complex) – the argument/location, where the Hankel function has to be evaluated

  • m (scalar, int) – kind of the Hankel function, possible values: 1, 2

  • es (scalar, bool) – optional, exponentially scales the result by \(\exp(\frac{2}{3} z^{1.5})\) if set to True, default: False

Returns:

result of the Hankel function of kind \(m\) and order \(v\) at complex value \(z\)

Return type:

scalar, complex

Mie fields

ARTmie.Mie_ab(m, x)

Computes external field coefficients \(a_n\) and \(b_n\) based on the refractive index \(m\,=\,n+k\cdot{}i\) and the size parameter \(x\,=\,\pi\,d_p/\lambda\).

Parameters:

  • m (scalar, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • x (scalar, float) – size parameter of the particle

Returns:

  • an (array-like, 1dimensional, complex) – external field coefficients \(a_n\)

  • bn (array-like, 1dimensional, complex) – external field coefficients \(b_n\)

ARTmie.MieCoated_ab(m_core, x_core, m_shell, x_shell)

Computes external field coefficients \(a_n\) and \(b_n\) based on the parameters of the particle’s core: refractive index \(x_\text{core}\,=\,n_{core}+k_{core}\cdot{}i\), size parameter \(x_\text{core}\,=\,\pi\,d_{p,core}/\lambda\) and the particle’s shell: refractive index \(x_\text{shell}\,=\,n_{shell}+k_{shell}\cdot{}i\), size parameter \(x_\text{shell}\,=\,\pi\,d_{p,shell}/\lambda\).

Parameters:

  • m_core (scalar, complex) – refractive index of the particle’s core reduced by the refractive index of the surrounding medium

  • x_core (scalar, float) – size parameter of the particle’s core

  • m_shell (scalar, complex) – refractive index of the particle’s shell (coating) reduced by the refractive index of the surrounding medium

  • x_shell (scalar, float) – size parameter of the particle’s shell (coating), e.g. based on the diameter of the whole particle

Returns:

  • an (array-like, 1dimensional, complex) – external field coefficients \(a_n\)

  • bn (array-like, 1dimensional, complex) – external field coefficients \(b_n\)

ARTmie.Mie_cd(m, x)

Computes internal field coefficients \(c_n\) and \(d_n\) based on the refractive index \(m\,=\,n+k\cdot{}i\) and the size parameter \(x\,=\,\pi\,d_p/\lambda\).

Parameters:

  • m (scalar, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • x (scalar, float) – size parameter of the particle

Returns:

  • cn (array-like, 1dimensional, complex) – internal field coefficients \(c_n\)

  • dn (array-like, 1dimensional, complex) – internal field coefficients \(d_n\)

ARTmie.Mie_pitau(theta, nmax)

Calculates angular functions \(\pi_n\) and \(\tau_n\).

Parameters:

  • theta (scalar, float or array-like, 1dimensional, floats) – the scattering angle(s) \(\theta\)

  • nmax (scalar, int) – the maximum number of coefficients to compute. Typically, \(\left\lfloor {2+x+4x^{1/3}} \right\rfloor\)

Returns:

  • pin (arry-like, floats) – coefficient series \(\pi_n\)

  • taun (arry-like, floats) – coefficient series \(\tau_n\)

Single particle Mie functions

ARTmie.ab2mie(an, bn, wavelength, diameter, /, asCrossSection=False, asDict=False)

Helper function to calculate Mie efficiencies from the wavelength of the incident light, the particle’s diameter and the external fields \(a_n\) and \(b_n\)

Parameters:

  • an (array-like, 1dimensional, complex) – external field coefficients \(a_n\)

  • bn (array-like, 1dimensional, complex) – external field coefficients \(b_n\)

  • wavelength (scalar, float) – the wavelength of the incident light, in nm

  • diameter (scalar, float) – the diameter of the particle, in nm

  • asCrossSection (scalar, bool) – optional, if specified and set to True, returns the results as optical cross-sections with units of \(\text{nm}^2\)

  • asDict (scalar, bool) – optional, if specified and set to True, returns the results as a dictionary

Returns:

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies as described in MieQ()

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies as optical cross sections, if asCrossSection set to True

  • q (dict) – dictionary of the Mie efficiencies, if asDict is set to True

  • c (dict) – dictionary of Mie efficiencies as optical cross sections, if asDict and asCrossSection are both set to True

ARTmie.MieQ(m, diam, wavelength, /, nMedium=1.0, asCrossSection=False, asDict=False)

Computes extinction, scattering, backscattering and absorption efficiencies, radiation pressure and asymmetry parameternn

Parameters:

  • m (scalar or array-like, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • diam (scalar, float) – the diameter of the particle, in nm

  • wavelength (scalar or array-like, float) – the wavelength of the incident light, in nm, same shape as m

  • nMedium (scalar, float) – optional, refractive index of the surrounding medium without the extinction k (only real part)

  • asCrossSection (scalar, bool) – optional, if specified and set to True, returns the results as optical cross-sections with units of \(\text{nm}^2\)

  • asDict (scalar, bool) – optional, if specified and set to True, returns the results as a dictionary

Returns:

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies: extinction, scattering, absorption, backscattering, and backscatter-ratio, radiation pressure and asymmetry parameter

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies as optical cross sections, if asCrossSection set to True

  • q (dict) – dictionary of the Mie efficiencies, if asDict is set to True

  • c (dict) – dictionary of Mie efficiencies as optical cross sections, if asDict and asCrossSection are both set to True

ARTmie.MieCoatedQ(m_core, diam_core, m_shell, diam_shell, wavelength, /, nMedium=1.0, asCrossSection=False, asDict=False)

As MieQ() but for coated particles.

Parameters:

  • m_core (scalar or array-like, complex) – refractive index of the particle’s core reduced by the refractive index of the surrounding medium

  • diam_core (scalar, float) – the diameter of the particle’s core, in nm

  • m_shell (scalar or array-like, complex) – refractive index of the particle’s shell (coating) reduced by the refractive index of the surrounding medium, same shape as m_core

  • diam_shell (scalar, float) – the diameter of the particle’s shell aka the diameter of the whole particle, in nm

  • wavelength (scalar or array-like, float) – the wavelength of the incident light, in nm, same shape as m_core

  • nMedium (scalar, float) – optional, refractive index of the surrounding medium without the extinction k (only real part)

  • asCrossSection (scalar, bool) – optional, if specified and set to True, returns the results as optical cross-sections with units of \(\text{nm}^2\)

  • asDict (scalar, bool) – optional, if specified and set to True, returns the results as a dictionary

Returns:

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies as described in MieQ()

  • qext,qsca,qabs,qback,qratio,qpr,g (scalars, floats) – Mie efficiencies as optical cross sections, if asCrossSection set to True

  • q (dict) – dictionary of the Mie efficiencies, if asDict is set to True

  • c (dict) – dictionary of Mie efficiencies as optical cross sections, if asDict and asCrossSection are both set to True

ARTmie.ScatteringFunction(m, diam, wavelength, theta, /, m_shell=m, fcoat=0.0)

Calculates the angle-dependent scattering intensities for parallel, perpendicular polarized and unpolarized light.

Parameters:

  • m (scalar, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • diam (scalar, float) – the diameter of the particle, in nm

  • wavelength (scalar, float) – the wavelength of the incident light, in nm

  • theta (array-like, 1dimensional, floats) – the scattering angles \(\theta\), in degrees

  • m_shell (scalar, complex) – optional, refractive index of the particle’s shell (coating) reduced by the refractive index of the surrounding medium, default m

  • fcoat (scalar, float) – optional, coating fraction aka the fraction increase of the particle’s diameter from the core’s diameter, default 0.0

Returns:

  • sl (array-like, 1dimensional, floats) – scattering intensities of perpendicular polarized light

  • sr (array-like, 1dimensional, floats) – scattering intensities of parallel polarized light

  • su (array-like, 1dimensional, floats) – scattering intensities of unpolarized light

Mie functions for Particle size distribubtions

Note

Currently only hardcoded log-normal distributions are supported

ARTmie.createLogNormalDistribution(mean_diam, stdev_diam, /, fcoat=0.0, res=0.0, norm2core=False, norm2volume=True)

Calculates the parameters regarding the log-normal particle size distribution needed internally by Size_Distribution_Optics() and Size_Distribution_Phase_Function()

Parameters:

  • mean_diam (scalar, float) – the median count diameter of the particles, in nm

  • stdev_diam (scalar, float) – the geometric standard deviation of the particle size distribution,

  • fcoat (scalar, float) – optional, the coating fraction, default 0.0

  • res (scalar, float) – optional, resolution of the particle size distribtion, default 1.0

  • dens (scalar, float) – optional, the density, default 1.0

  • norm2core (scalar, bool) – optional, normalize the pdf to the particle’s core, default False

  • norm2volume (scalar, bool) – optional, normalize the pdf to the particle’s volume, default True

Returns:

  • x_range (array-like, 1dimensional, floats) – sample core diameters of the particles of the particle size distribution

  • y_range (array-like, 1dimensional, floats) – sample shell diameters of the particles of the particle size distribution

  • pdf (array-like, 1dimensional, floats) – probability density function of the particle diameters

  • crossArea (array-like, 1dimensional, floats) – scaled particle cross section areas

  • normWeight (scalar, float) – normalization weight

ARTmie.calcBackscattering(x, an, bn, theta, dtheta, scatwts, pin, taun)

Calculates the scattering angle weighted Mie backscattering efficiency.

Note

this is not the same backscattering efficiency as calculated by MieQ() or ab2mie()

Parameters:

  • x (scalar, float) – size parameter of the particle

  • an (array-like, 1dimensional, complex) – external field coefficients \(a_n\)

  • bn (array-like, 1dimensional, complex) – external field coefficients \(b_n\)

  • theta (array-like, 1dimensional, floats) – the scattering angles \(\theta\), in degrees

  • dtheta (array-like, 1dimensional, floats) – bin widths of each scattering angle \(\theta\), in degrees

  • scatwgts – the scattering weights for each scattering angle \(\theta\), typically \(\sin(\theta)\) if \(\theta>90^\circ\)

  • pin (array-like, 2dimensional, floats) – angular function, coefficient series \(\pi_n\)

  • taun (array-like, 2dimensional, floats) – angular function, coefficient series \(\tau_n\)

Returns:

scattering angle weighted backscatter coefficient

Return type:

scalar, float

ARTmie.calcBackscatteringFromPhFunc(x, theta, phfunc, dtheta, scatwts)

Calculates the scattering angle weighted backscattering coefficient.

Note

this is not the same backscattering coefficient as calculated by MieQ() or ab2mie()

the result is the same as calcBackscattering() but calculated from the phase function instead of the Mie coefficients, so it can be used for non-Mie scattering as well

Parameters:

  • x (scalar, float) – size parameter of the particle

  • theta (array-like, 1dimensional, floats) – the scattering angles \(\theta\), in degrees

  • phfunc (array-like, 1dimensional, floats) – the phase function values at the scattering angles

Returns:

scattering angle weighted backscatter coefficient

Return type:

scalar, float

ARTmie.Size_Distribution_Optics(mp, sizepar1, sizepar2, wavelength, /, nMedium=1.0, fcoat=0.0, mc=mp, density=1.0, resolution=10, effcore=True, normalized=True)

Calculates the Mie efficiencies as in MieQ() but for a particle size distribution.

Note

The size distribution is currently hardcoded to be log-normal. Other distributions may follow in future versions.

Note

1dimensional arguments for sizepar1 and sizepar2 are not implemented yet, they will come in version 0.2.0

Parameters:

  • m (scalar, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • sizepar1 (scalar, float or array-like, 1dimensional, floats) – mean count diameter (if scalar) or particle sizes \(d\) (if array-like), in nm

  • sizepar2 (scalar, float or array-like, 1dimensional, floats) – geometric std. dev. (if scalar) or \(\text{d}N/\text{d}\log{}D\) in \(\text{cm}^{-3}\) (if array-like)

  • wavelength (scalar, float) – the wavelength of the incident light, in nm

  • nMedium (scalar, float) – optional, refractive index of the surrounding medium without the extinction \(k\) (only real part)

  • fcoat (scalar, float) – optional, the coating fraction, default 0.0

  • mc (scalar, complex) – optional, refractive index of the particle’s shell, default m

  • density (scalar, float) – optional, the density of the particles, in \(\text{g/cm}^3\), default 1.0

  • resolution (scalar, float) – optional, number of bins per power of magnitude within the particle size distribution, default 10.0, ignored when sizepar1 & sizepar2 array-like

  • effcore (scalar, bool) – optional, calculates cross-section as \(\text{nm}^2\)/(g of core), default False

  • normalize (scalar, bool) – optional, normalized to \(\text{nm}^2\)/g particles, default True, setting to False works only with \(d\) & \(\text{d}N/\text{d}\log{}D\) (array-like sizeparX)

Returns:

mie_tots (dict) – dictionary of the Mie efficiencies with scattering angle weighted backscatter efficiency instead of the phase function at \(180^\circ\)

ARTmie.Size_Distribution_Phase_Function(mp, sizepar1, sizepar2, wavelength, /, nMedium=1.0, fcoat=0.0, mc=mp, density=1.0, resolution=10, effcore=True, normalized=False)

Computes the scattering phase function for a particle size distribution.nn

Note

The size distribution is currently hardcoded to be log-normal. Other distributions may follow in future versions.

Note

1dimensional arguments for sizepar1 and sizepar2 are not implemented yet, they will come in version 0.2.0

Parameters:

  • m (scalar, complex) – refractive index of the particle reduced by the refractive index of the surrounding medium

  • sizepar1 (scalar, float or array-like, 1dimensional, floats) – mean count diameter (if scalar) or particle sizes \(d\) (if array-like), in nm

  • sizepar2 (scalar, float or array-like, 1dimensional, floats) – geometric std. dev. (if scalar) or \(\text{d}N/\text{d}\log{}D\) in \(\text{cm}^{-3}\) (if array-like)

  • wavelength (scalar, float) – the wavelength of the incident light, in nm

  • nMedium (scalar, float) – optional, refractive index of the surrounding medium without the extinction \(k\) (only real part)

  • fcoat (scalar, float) – optional, the coating fraction, default 0.0

  • mc (scalar, complex) – optional, refractive index of the particle’s shell, default m

  • density (scalar, float) – optional, the density of the particles, in \(\text{g/cm}^3\), default 1.0

  • resolution (scalar, float) – optional, number of bins per power of magnitude within the particle size distribution, default 10.0, ignored when sizepar1 & sizepar2 array-like

  • effcore (scalar, bool) – optional, calculates cross-section as \(\text{nm}^2\)/(g of core), default False

  • normalize (scalar, bool) – optional, normalized to \(\text{nm}^2\)/g particles, default True, setting to False works only with \(d\) & \(\text{d}N/\text{d}\log{}D\) (array-like sizeparX)

Returns:

  • sl (array-like, 1dimensional, floats) – scattering intensities of perpendicular polarized light

  • sr (array-like, 1dimensional, floats) – scattering intensities of parallel polarized light

  • su (array-like, 1dimensional, floats) – scattering intensities of unpolarized light