miepython 3.2.0__py3-none-any.whl → 3.3.1__py3-none-any.whl

miepython/__init__.py

@@ -42,6 +42,29 @@ The scattering matrix
 
     mie.phase_matrix(m, x, mu)
 
+Submodules
+----------
+
+``miepython.rayleigh`` is imported with the package and needs nothing beyond NumPy.
+It mirrors the API above using the small-sphere limit, which is handy for checking
+the full solution as x goes to zero::
+
+    mie.rayleigh.efficiencies_mx(1.5, 0.01)
+
+``miepython.vsh`` holds the vector spherical harmonics as a direct transcription of
+the textbook formulas.  It is a reference for development and cross-checking rather
+than a fast path, it requires the optional ``scipy`` dependency, and so it is bound
+only when scipy is installed::
+
+    mie.vsh.M_odd(1, k, d_sphere, r, theta, phi)
+
+``miepython.monte_carlo`` samples scattering angles from the Mie phase function.  It
+imports this package, so importing it from here would be circular; ask for it
+explicitly instead::
+
+    import miepython.monte_carlo as mc
+    mu, cdf = mc.mu_with_uniform_cdf(m, x, 100)
+
 Near-field calculations are provided by the ``miepython.field`` module::
 
     from miepython.field import e_near, h_near, eh_near
@@ -68,6 +91,8 @@ from ._backend import single_sphere, small_conducting_sphere, small_sphere
 from .core import efficiencies, intensities, i_par, i_per, i_unpolarized
 from .core import efficiencies_mx, S1_S2, phase_matrix, coefficients
 
+from . import rayleigh
+
 _FIELD_IMPORT_ERROR = None
 
 
@@ -93,10 +118,14 @@ def _missing_field_function(name):
 
 try:
     from . import field as _field
+    from . import vsh  # noqa: F401  reachable as miepython.vsh; needs scipy, so guarded here
 except ModuleNotFoundError as exc:
     missing_module = str(getattr(exc, "name", "") or "")
     if missing_module.startswith("scipy"):
         _FIELD_IMPORT_ERROR = exc
+        # ``miepython.vsh`` is left unbound rather than stubbed out.  It is a
+        # reference implementation used for development and cross-checking, not part
+        # of the public surface, and every one of its functions needs scipy.
         e_far = _missing_field_function("e_far")
         e_near = _missing_field_function("e_near")
         h_near = _missing_field_function("h_near")
@@ -115,8 +144,10 @@ else:
     h_near_cartesian = _field.h_near_cartesian
     eh_near_cartesian = _field.eh_near_cartesian
 
-# functions exposed to the user
+# Names exposed to the user.  ``vsh`` is deliberately absent: it is bound only when
+# scipy is installed, and a star-import must not depend on that.
 __all__ = (
+    "rayleigh",
     "intensities",
     "i_par",
     "i_per",
@@ -147,7 +178,7 @@ __all__ = (
     "_D_downwards",
 )
 
-__version__ = "3.2.0"
+__version__ = "3.3.1"
 __author__ = "Scott Prahl"
 __email__ = "scott.prahl@oit.edu"
 __copyright__ = "2017-2026, Scott Prahl"

miepython/core.py

@@ -47,9 +47,77 @@ __all__ = (
     "S1_S2",
     "phase_matrix",
     "coefficients",
+    "wiscombe_terms",
+    "normalization_factor",
 )
 
 
+def wiscombe_terms(x):
+    """
+    Return the number of Mie series terms from Wiscombe's criterion.
+
+    The series is truncated after this many orders so that the summed scattering
+    quantities are accurate to about 1e-6.  The low-level ``an_bn`` and ``cn_dn``
+    kernels repeat this expression because numba cannot call back into Python.
+
+    Args:
+        x: the size parameter of the sphere
+
+    Returns:
+        number of terms, so orders 1 through the returned value
+    """
+    return int(x + 4.05 * x**0.33333 + 2.0)
+
+
+def _check_m_x(m, x):
+    """
+    Reject an index or size parameter that the kernels would silently misread.
+
+    The kernels treat any index whose real part fails ``m.real > 0`` as a perfect
+    conductor, so a NaN or negative real part gave the answer for a metal sphere
+    instead of an error.  A NaN or infinite x failed differently on each backend.
+
+    Args:
+        m: refractive index of the sphere, scalar or array
+        x: size parameter of the sphere, scalar or array
+
+    Raises:
+        ValueError: if m or x is not finite, x is negative, or m.real is negative
+    """
+    m = np.asarray(m)
+    x = np.asarray(x)
+    if not np.all(np.isfinite(m)):
+        raise ValueError(f"refractive index must be finite, got m={m}")
+    if np.any(m.real < 0):
+        raise ValueError(
+            f"real part of the refractive index must not be negative, got m={m}; "
+            "use m.real == 0 for a perfect conductor"
+        )
+    if not np.all(np.isfinite(x)):
+        raise ValueError(f"size parameter must be finite, got x={x}")
+    if np.any(x < 0):
+        raise ValueError(f"size parameter must not be negative, got x={x}")
+
+
+def _check_one_sphere(m, x):
+    """
+    Reject arrays of m or x in functions that describe a single sphere.
+
+    The angular functions vectorize over mu, so an array of spheres has no
+    unambiguous shape to return.  Without this check numpy raised "truth value of
+    an array is ambiguous" from deep inside.
+
+    Args:
+        m: refractive index of the sphere
+        x: size parameter of the sphere
+
+    Raises:
+        ValueError: if m or x is not a scalar
+    """
+    if np.ndim(m) > 0 or np.ndim(x) > 0:
+        raise ValueError("this function takes one sphere, so m and x must be scalars; loop over spheres for more")
+
+
 def coefficients(m, x, n_pole=0, internal=False):
     """
     Computes the Mie coefficients for a sphere.
@@ -73,31 +141,42 @@ def coefficients(m, x, n_pole=0, internal=False):
             calculate fields inside the sphere.
 
     Returns:
-        tuple:
-            - a (complex or array-like): The computed Mie coefficient A_n or an array of A_n values.
-            - b (complex or array-like): The computed Mie coefficient B_n or an array of B_n values.
+        ndarray: ``[a, b]``, or ``[a, b, c, d]`` when ``internal`` is True.  For
+            scalar ``m`` and ``x`` each entry is a 1-D array of coefficients, so
+            the result has shape ``(2, n_terms)`` or ``(4, n_terms)``.  For array
+            input each entry gains a leading axis over the spheres, giving
+            ``(2, n_spheres, n_pole)`` or ``(4, n_spheres, n_pole)``.
 
     Notes:
         - If the imaginary part of the refractive index is positive, it is
           automatically corrected to its conjugate value to ensure a valid input.
+        - Every returned coefficient is a real term; the arrays carry no padding.
+
+    Raises:
+        ValueError: if m or x is not finite, x is negative, or the real part of
+            m is negative.  A perfect conductor is m.real == 0, not m.real < 0.
 
     Examples:
         Compute coefficients for a single sphere:
-        >>> m = 1.5 - 0.1j
-        >>> x = 0.1
-        >>> mie_coefficients(m, x)
-        (array([3.33370015e-05+1.97363100e-04j, 1.77504613e-08+1.11834113e-07j,
-        4.60529820e-12+2.97368373e-11j, 1.58460985e-28+1.25881287e-14j]),
-        array([6.67296256e-08+2.75469444e-07j, 1.90474848e-11+7.86835968e-11j,
-        3.02615454e-15+1.24937186e-14j, 1.58460985e-28+1.25881287e-14j]))
-
-        Compute first multipoles for multiple spheres:
-        >>> m = [1.5 + 0.1j, 1.4 + 0.05j]
-        >>> x = [2.0, 1.8]
-        >>> mie_coefficients(m, x, 1)
-        (array([0.44794644+0.38665192j, 0.27813728+0.38495241j]),
-        array([0.5621083 +0.25504616j, 0.20206531+0.29589842j]))
+
+        >>> import miepython as mie
+        >>> a, b = mie.coefficients(1.5 - 0.1j, 0.1)
+        >>> len(a), len(b)
+        (3, 3)
+        >>> print(f"{a[0]:.6e}")
+        3.333700e-05-1.973631e-04j
+        >>> print(f"{b[0]:.6e}")
+        6.672963e-08-2.754694e-07j
+
+        Keep only the dipole term for each of several spheres:
+
+        >>> a, b = mie.coefficients([1.5 - 0.1j, 1.4 - 0.05j], [2.0, 1.8], n_pole=1)
+        >>> a.shape
+        (2, 1)
+        >>> print(f"{a[0, 0]:.6f}")
+        0.447946-0.386652j
     """
+    _check_m_x(m, x)
     mlen = np.size(m) if np.ndim(m) > 0 else 0
     xlen = np.size(x) if np.ndim(x) > 0 else 0
 
@@ -155,8 +234,11 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
             - If 0 (default), computes contributions from all multipoles.
             - If non-zero, computes contributions from the specified multipole order.
         e_field (boolean):
-            If n_pole>0, then True value returns the electric
-            multipole contribution otherwise the Magnetic field contribution
+            When n_pole>0, selects which multipole of that order contributes:
+            True gives the electric multipole a_n, False the magnetic
+            multipole b_n. The two add up to the full order-n_pole
+            contribution for qext and qsca. Ignored when n_pole is 0.
+
     Returns:
         tuple:
             qext (float or array-like):
@@ -170,7 +252,8 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
                 scattered in the exact backward direction (theta = 180 degrees).
             g (float or array-like):
                 Asymmetry parameter, representing the average cosine of the scattering
-                angle over all angles.
+                angle over all angles. This is exactly zero when n_pole > 0, because a
+                single multipole of one parity scatters symmetrically about 90 degrees.
 
     Notes:
         - Ensure m and x have compatible dimensions if passed as arrays.
@@ -179,21 +262,32 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
         - This implementation assumes spherical, homogeneous particles in a
           non-absorbing medium.
 
+    Raises:
+        ValueError: if m or x is not finite, x is negative, or the real part of
+            m is negative.  A perfect conductor is m.real == 0, not m.real < 0.
+
     Examples:
-        Compute efficiencies for a sphere with fixed parameters:
+        Compute efficiencies for one sphere:
 
         >>> import miepython as mie
-        >>> mie.efficiencies(1.5 - 0.01j, 2.0, 0)
-        (qext: 1.81, qsca: 1.72, qback: 0.27, g: 0.63)
+        >>> qext, qsca, qback, g = mie.efficiencies_mx(1.5 - 0.01j, 2.0)
+        >>> print(f"{qext:.6f} {qsca:.6f} {qback:.6f} {g:.6f}")
+        1.812597 1.724396 0.266214 0.630214
 
-        Compute efficiencies for wavelength-dependent refractive indices:
+        Compute efficiencies for a wavelength-dependent refractive index:
 
-        >>> import miepython as mie
+        >>> import numpy as np
         >>> m_array = np.array([1.5 - 0.01j, 1.45 - 0.02j])
         >>> x_array = np.array([2.0, 2.5])
-        >>> mie.efficiencies(m_array, x_array, 0)
-        (qext: [1.81, 2.15], qsca: [1.72, 1.95], qback: [0.27, 0.31], g: [0.63, 0.70])
+        >>> qext, qsca, qback, g = mie.efficiencies_mx(m_array, x_array)
+        >>> np.round(qext, 6)
+        array([1.812597, 2.14972 ])
+
+        Use :func:`efficiencies` instead when the diameter and wavelength are
+        known rather than the size parameter.
     """
+    _check_m_x(m, x)
+
     # ensure imaginary part of refractive index is negative
     if np.isscalar(m):
         m = np.conj(m) if np.imag(m) > 0 else m
@@ -234,7 +328,12 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
     return qext, qsca, qback, g
 
 
-def normalization_factor(m, x, norm_str):
+def _mie_efficiencies(m, x):
+    """Return the full Mie efficiencies, the default source for normalization."""
+    return single_sphere(m, x, 0, True)
+
+
+def normalization_factor(m, x, norm_str, efficiency_source=_mie_efficiencies):
     """
     Figure out scattering function normalization.
 
@@ -242,6 +341,10 @@ def normalization_factor(m, x, norm_str):
         m: complex index of refraction of sphere
         x: dimensionless sphere size
         norm_str: string describing type of normalization
+        efficiency_source: callable returning ``(qext, qsca, qback, g)`` for ``m``
+            and ``x``.  Defaults to the full Mie solution; ``miepython.rayleigh``
+            passes its own so that the two share these rules rather than keeping
+            a second copy of them.
 
     Returns:
         scaling factor needed for scattering function
@@ -259,7 +362,16 @@ def normalization_factor(m, x, norm_str):
         factor = x * np.sqrt(np.pi)
 
     else:
-        qext, qsca, _, _ = single_sphere(m, x, 0, True)
+        qext, qsca, _, _ = efficiency_source(m, x)
+
+        # every remaining choice divides by qext or qsca
+        if qext <= 0 or qsca <= 0:
+            raise ValueError(
+                "normalization %r needs a sphere that scatters, but qext=%g and qsca=%g. "
+                "A sphere of zero size, or one whose index matches its surroundings, has "
+                "no scattering to normalize against. Use norm='wiscombe', 'bohren' or "
+                "'qsca' if an unnormalized amplitude is what you want." % (norm_str, qext, qsca)
+            )
 
         if norm in ["a", "albedo"]:
             factor = x * np.sqrt(np.pi * qext)
@@ -297,21 +409,34 @@ def S1_S2(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter of the sphere
-        mu: the angles, cos(theta), to calculate scattering amplitudes
+        mu: the angles, cos(theta), to calculate scattering amplitudes. A scalar,
+            list, tuple or array is accepted; a scalar is treated as one angle,
+            so the returned amplitudes are still length-one arrays.
         norm: (optional) string describing scattering function normalization
-        n_pole: return n_pole term from series (default=0 means include all terms)
+        n_pole: isolate a single multipole order, 1=dipole, 2=quadrupole,
+            3=octupole (default=0 means include all terms). Summing over
+            every order reproduces the full series, so n_pole uses the same
+            convention as `efficiencies_mx`. Orders beyond the truncated
+            series raise a ValueError.
 
     Returns:
         S1, S2: the scattering amplitudes at each angle mu [sr**(-0.5)]
+
+    Raises:
+        ValueError: if m or x is not finite, x is negative, or the real part of
+            m is negative.  A perfect conductor is m.real == 0, not m.real < 0.
+            Also if m or x is an array, since this describes one sphere.
     """
+    _check_m_x(m, x)
+    _check_one_sphere(m, x)
     if np.imag(m) > 0:  # ensure imaginary part of refractive index is negative
         m = np.conj(m)
 
-    if np.isscalar(mu):
-        mu_array = np.array([mu], dtype=float)
-        S1, S2 = _S1_S2(m, x, mu_array, n_pole)
-    else:
-        S1, S2 = _S1_S2(m, x, mu, n_pole)
+    # The numba kernel is declared for float64[:], so a list or an integer array
+    # would be rejected there while numpy accepted it.  Coercing here keeps both
+    # backends callable with exactly the same arguments.
+    mu_array = np.atleast_1d(np.asarray(mu, dtype=float))
+    S1, S2 = _S1_S2(m, x, mu_array, n_pole)
 
     normalization = normalization_factor(m, x, norm)
 
@@ -345,7 +470,9 @@ def phase_matrix(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter of the sphere
-        mu: the angles, cos(theta), of the phase scattering matrix
+        mu: the angles, cos(theta), of the phase scattering matrix. Unlike the
+            other angular functions this one squeezes a single angle away, so a
+            scalar gives a bare 4x4 matrix rather than 4x4x1.
         n_pole: return n_pole term from series (default=0 means include all terms)
         norm: (optional) string describing scattering function normalization
 
@@ -390,7 +517,9 @@ def i_per(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m (complex): Complex index of refraction of the sphere.
         x (float): Size parameter of the sphere.
-        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which intensity is desired.
+        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which
+            intensity is desired. A scalar counts as one angle and yields a
+            length-one array, not a bare number.
         norm (str, optional): Normalization method for the scattered intensity. Default is 'albedo'.
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.
@@ -419,7 +548,9 @@ def i_par(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m (complex): Complex index of refraction of the sphere.
         x (float): Size parameter of the sphere.
-        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which intensity is desired.
+        mu (array-like): Cosine of the scattering angle(s), cos(θ), for which
+            intensity is desired. A scalar counts as one angle and yields a
+            length-one array, not a bare number.
         norm (str, optional): Normalization method for the scattered intensity. Default is 'albedo'.
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.
@@ -449,7 +580,8 @@ def i_unpolarized(m, x, mu, norm="albedo", n_pole=0):
     Args:
         m: the complex index of refraction of the sphere
         x: the size parameter
-        mu: the cos(theta) of each direction desired
+        mu: the cos(theta) of each direction desired. A scalar counts as one
+            direction and yields a length-one array, not a bare number.
         norm: (optional) string describing scattering function normalization
         n_pole (int, optional): If greater than zero, returns only the nth multipole term;
             default is 0, which returns the sum of all terms.