miepython 3.3.0__tar.gz → 3.3.1__tar.gz

{miepython-3.3.0 → miepython-3.3.1}/CHANGELOG.rst

@@ -1,6 +1,84 @@
 Changelog
 =========
 
+3.3.1 (10/28/2026)
+-------------------
+*   fix ``rayleigh.efficiencies_mx`` subtracting scattering from extinction.  With
+    the m = n - ik convention the absorption term is negative, so
+    ``abs(absorption + qsca)`` gave absorption minus scattering, and qext for
+    m = 1.5 - 1e-6j at x = 0.01 came out 21% low (thanks @antonsoo).  The x**4 term
+    now follows Bohren & Huffman's ``Re(ratio**2)`` rather than ``|ratio|**2``,
+    which agrees with Mie to 2e-5 instead of 6e-4 at m = 1.5 - 1j, x = 0.1.  ``m``
+    is conjugated first, as ``core.py`` does.  The Rayleigh ``qext`` also sets the
+    ``albedo`` and ``qext`` normalizations, so ``rayleigh.S1_S2`` and the
+    intensities change too
+*   handle perfectly conducting spheres in ``rayleigh``.  As elsewhere in the
+    package, m.real == 0 now means a perfect conductor, which radiates a magnetic
+    dipole b1 = -a1/2 alongside its electric one: qext = qsca = 10/3 x**4,
+    qback = 9 x**4 and g = -2/5.  The dielectric formulas were used before, so
+    m = -1j gave a qext about three times the Mie value; it now agrees to 2e-5 at
+    x = 0.01
+*   validate input to the ``rayleigh`` functions as ``core.py`` now does.  A NaN or
+    infinite m or x, a negative x, or a negative real part of m raises
+    ``ValueError``; before, ``rayleigh.efficiencies_mx(nan, 0.05)`` returned NaN and
+    ``m = -1.5 - 0.1j`` or ``x = -0.05`` returned normal-looking efficiencies
+*   say why ``S1_S2`` and the functions built on it reject an array of spheres, in
+    both ``core`` and ``rayleigh``.  They vectorize over mu and describe one sphere,
+    but an array m or x failed with numpy's "truth value of an array is ambiguous"
+*   return ``g`` from ``rayleigh.efficiencies_mx`` with the same shape and type as
+    the other efficiencies.  It was the int 0 even for an array of spheres
+*   document the ``rayleigh`` module: what the approximation is, which expressions
+    go beyond the leading Rayleigh term, its accuracy against Mie, and tested
+    examples
+*   support Python 3.11 through 3.15.  ``requires-python`` is now ``>=3.11``, 3.10 is
+    dropped from the classifiers, the black target versions and the CI matrix, and
+    3.15 is added to all three
+*   raise ``ValueError`` for a refractive index or size parameter the kernels would
+    misread.  The kernels treat any index that fails ``m.real > 0`` as a perfect
+    conductor, so ``m = nan`` or ``m = -1.5`` silently returned the answer for a metal
+    sphere, and an infinite m returned NaN.  A NaN x raised "cannot convert float
+    NaN to integer" on the pure-Python backend while numba returned NaN, an infinite
+    x raised a different unhelpful error on each backend, and a negative x returned
+    zeros.  ``coefficients``, ``efficiencies_mx``, ``S1_S2`` and the near fields, and
+    everything built on them, now reject a NaN or infinite m or x, a negative x, and
+    a negative real part of m, checking every entry of an array.  ``m.real == 0``
+    still means a perfect conductor and x = 0 is still allowed
+*   fix ``monte_carlo.mu_with_uniform_cdf`` returning wrong angles for fine tables.
+    ``cdf`` began at I(-1)/num rather than zero, so a target below that value left
+    the inversion loop at index zero and interpolated against the last entry.
+    ``cdf`` now integrates the phase function with the trapezoidal rule, starting at
+    exactly 0 and ending at exactly 1 (it used to end slightly above 1), so tables
+    differ slightly from 3.3.0.  ``cdf`` and ``mu_with_uniform_cdf`` also raise
+    ``ValueError`` when num is less than 2 (thanks @antonsoo)
+*   replace the inversion loop in ``monte_carlo.mu_with_uniform_cdf`` with
+    ``np.interp``
+*   warn when ``monte_carlo.cdf`` uses too few angles to resolve the phase function.
+    The raw integral should be one, so a ``RuntimeWarning`` is issued when it is off
+    by more than 1%; normalizing used to hide the error silently.  A large sphere
+    needs roughly x**2 angles, because its forward peak is only about 8/x**2 wide in
+    cos(theta)
+*   size the table inside ``monte_carlo.mu_with_uniform_cdf`` from x, as
+    max(2000, 5*x**2) angles instead of a fixed 2000.  At x = 100 the sampled mean
+    cosine was 0.930 against g = 0.868; it is now 0.869.  Large spheres are slower
+    to tabulate: seconds at x = 100, about a minute at x = 300
+*   raise ``ValueError`` from ``monte_carlo.cdf`` and ``mu_with_uniform_cdf`` when the
+    phase function is not finite
+*   rewrite the ``monte_carlo`` docstrings, with tested examples of drawing random
+    scattering angles
+*   name the encoding on every text read and write.  ``open(path)`` and
+    ``Path.read_text()`` decode with the locale's preferred encoding, which is UTF-8
+    on Linux and macOS but cp1252 on Windows, so ``tests/test_makefile.py`` passed
+    everywhere except the four Windows jobs, where it died on the emoji in the
+    Makefile's echo lines.  Two more latent cases are fixed alongside it: the
+    scattnlay metadata read in ``tests/test_scattnlay_reference.py``, which survived
+    only because that JSON happens to be pure ASCII, and the ``write_text`` in
+    ``docs/data/generate_scattnlay_reference_fields.py``
+*   check for locale-dependent text I/O in the test suite, by walking the syntax trees
+    of every Python file in the repository and requiring an explicit ``encoding=``.
+    The failure is invisible on the platforms this package is developed on, so a
+    Windows-only break was waiting for whoever next added a non-ASCII character to a
+    file something reads
+
 3.3.0 (07/28/2026)
 -------------------
 *   fix the docstring examples in ``core.py``, which had rotted unnoticed.  The

{miepython-3.3.0 → miepython-3.3.1}/CITATION.cff

@@ -2,9 +2,9 @@ cff-version: 1.2.0
 type: software
 message: If you use this software, please cite it as below.
 title: 'miepython: Pure python calculation of Mie scattering'
-version: 3.2.0
+version: 3.3.0
 doi: 10.5281/zenodo.7949264
-date-released: '2026-03-06'
+date-released: '2026-07-28'
 url: https://doi.org/10.5281/zenodo.7949264
 repository-code: https://github.com/scottprahl/miepython
 license: MIT
@@ -33,7 +33,7 @@ preferred-citation:
   type: software
   title: 'miepython: Pure python calculation of Mie scattering'
   year: 2026
-  version: 3.2.0
+  version: 3.3.0
   doi: 10.5281/zenodo.7949264
   url: https://doi.org/10.5281/zenodo.7949264
   authors:

{miepython-3.3.0 → miepython-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: miepython
-Version: 3.3.0
+Version: 3.3.1
 Summary: Mie scattering of a plane wave by a sphere
 Author-email: Scott Prahl <scott.prahl@oit.edu>
 License-Expression: MIT
@@ -14,12 +14,12 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: numpy
@@ -47,7 +47,6 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: check-manifest; extra == "dev"
 Requires-Dist: libarchive-c; extra == "dev"
 Requires-Dist: pyyaml; extra == "dev"
-Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: jupyterlab; extra == "dev"
 Requires-Dist: nbconvert; extra == "dev"
 Requires-Dist: nbformat; extra == "dev"
@@ -211,7 +210,7 @@ Citation
 
 If you use ``miepython`` in academic, instructional, or applied technical work, please cite:
 
-Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
+Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.3.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
 
 BibTeX:
 
@@ -223,7 +222,7 @@ BibTeX:
       url     = {https://github.com/scottprahl/miepython},
       doi     = {10.5281/zenodo.7949263},
       year    = {2026},
-      version = {3.2.0},
+      version = {3.3.0},
       publisher = {Zenodo}
     }
 

{miepython-3.3.0 → miepython-3.3.1}/README.rst

@@ -153,7 +153,7 @@ Citation
 
 If you use ``miepython`` in academic, instructional, or applied technical work, please cite:
 
-Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
+Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.3.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
 
 BibTeX:
 
@@ -165,7 +165,7 @@ BibTeX:
       url     = {https://github.com/scottprahl/miepython},
       doi     = {10.5281/zenodo.7949263},
       year    = {2026},
-      version = {3.2.0},
+      version = {3.3.0},
       publisher = {Zenodo}
     }
 

{miepython-3.3.0 → miepython-3.3.1}/miepython/__init__.py

@@ -178,7 +178,7 @@ __all__ = (
     "_D_downwards",
 )
 
-__version__ = "3.3.0"
+__version__ = "3.3.1"
 __author__ = "Scott Prahl"
 __email__ = "scott.prahl@oit.edu"
 __copyright__ = "2017-2026, Scott Prahl"

{miepython-3.3.0 → miepython-3.3.1}/miepython/core.py

@@ -69,6 +69,55 @@ def wiscombe_terms(x):
     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.
@@ -103,6 +152,10 @@ def coefficients(m, x, n_pole=0, internal=False):
           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:
 
@@ -123,6 +176,7 @@ def coefficients(m, x, n_pole=0, internal=False):
         >>> 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
 
@@ -208,6 +262,10 @@ 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 one sphere:
 
@@ -228,6 +286,8 @@ def efficiencies_mx(m, x, n_pole=0, e_field=True):
         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
@@ -361,7 +421,14 @@ def S1_S2(m, x, mu, norm="albedo", n_pole=0):
 
     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)
 

{miepython-3.3.0 → miepython-3.3.1}/miepython/field.py

@@ -82,7 +82,7 @@ import numpy as np
 from scipy.special import factorial2, spherical_jn
 from ._backend import D_calc, pi_tau
 from .bessel import spherical_h1
-from .core import S1_S2, coefficients, wiscombe_terms
+from .core import S1_S2, _check_m_x, coefficients, wiscombe_terms
 from .util import cartesian_to_spherical, spherical_vector_to_cartesian
 
 __all__ = (
@@ -287,6 +287,7 @@ def _coefficients_abcd(lambda0, d_sphere, m_sphere, n_env, n_pole):
     """
     x = np.pi * d_sphere * n_env / lambda0
     m_rel = m_sphere / n_env
+    _check_m_x(m_rel, x)  # before wiscombe_terms, which cannot take a NaN x
     if n_pole == 0:
         # Wiscombe's criterion truncates the scattered series, which converges
         # faster than the field evaluated right at the surface.  Now that an_bn

miepython-3.3.1/miepython/monte_carlo.py

@@ -0,0 +1,215 @@
+"""
+Sample random scattering angles from the Mie phase function.
+
+A Monte Carlo simulation of light transport needs, at every scattering event, a
+random direction in which the photon leaves the sphere. For unpolarized light
+only the polar angle theta depends on the sphere, and it must be drawn so that
+its cosine mu follows the phase function. This module does that by inverse
+transform sampling: build the cumulative distribution of mu once, then map each
+uniform random number u to the cosine at which the distribution reaches u.
+
+``cdf``
+    The cumulative distribution at evenly spaced cosines.
+``mu_with_uniform_cdf``
+    The cosines at which the cumulative distribution reaches evenly spaced
+    probabilities, a lookup table that makes each draw cheap.
+``generate_mie_costheta``
+    One random cosine drawn from that table.
+
+``docs/06_random_deviates.ipynb`` works through the whole procedure.
+
+This module is *not* imported with the package, because it imports
+``miepython`` itself and doing so from ``miepython/__init__.py`` would be
+circular. Import it by name, as the examples below do.
+
+Examples:
+    Invert the distribution with ``np.interp`` to draw many cosines at once.
+    Their average is the asymmetry parameter g:
+
+    >>> import numpy as np
+    >>> import miepython as mie
+    >>> import miepython.monte_carlo as mc
+    >>> m, x = 1.33, 2.0                          # a water droplet
+    >>> mu, cdf = mc.cdf(m, x, 1000)
+    >>> rng = np.random.default_rng(42)
+    >>> cosines = np.interp(rng.random(100_000), cdf, mu)
+    >>> print(f"{np.mean(cosines):.2f}")
+    0.67
+    >>> qext, qsca, qback, g = mie.efficiencies_mx(m, x)
+    >>> print(f"{g:.2f}")
+    0.67
+
+    Or build a lookup table once and draw one cosine at a time, as a photon
+    transport loop does:
+
+    >>> mu_table, _ = mc.mu_with_uniform_cdf(m, x, 1000)
+    >>> cosines = [mc.generate_mie_costheta(mu_table, rng=rng) for _ in range(100_000)]
+    >>> print(f"{np.mean(cosines):.2f}")
+    0.67
+
+Building either table costs a full Mie calculation, while each draw costs only a
+random number or two, so build it once and reuse it. Evenly spaced cosines
+resolve the narrow forward peak of a large sphere poorly; ``cdf`` explains how
+many are needed and warns when there are too few, while ``mu_with_uniform_cdf``
+chooses enough by itself.
+
+Passing ``rng`` keeps the draws reproducible without disturbing the process-wide
+``numpy.random``; omitting it falls back to that global generator.
+"""
+
+import warnings
+
+import numpy as np
+import miepython as mie
+
+__all__ = (
+    "cdf",
+    "mu_with_uniform_cdf",
+    "generate_mie_costheta",
+)
+
+# Largest acceptable relative error in the integral of the phase function
+CDF_TOLERANCE = 0.01
+
+
+def cdf(m, x, num):
+    """
+    Cumulative distribution of the unpolarized phase function in cos(theta).
+
+    The cosines mu are evenly spaced from -1 (backscattering) to 1 (forward
+    scattering), and cdf[i] is the probability that a scattered photon leaves
+    with a cosine no greater than mu[i]. It is found by integrating the phase
+    function with the trapezoidal rule, so cdf[0] is exactly 0 and the values
+    never decrease.
+
+    A large sphere scatters much of its light into a diffraction peak about
+    4/x radians wide around the forward direction. Near theta = 0, mu = cos(theta)
+    is close to 1 - theta**2/2, so that peak spans only about 8/x**2 in mu,
+    while the cosines are 2/(num - 1) apart. To put several cosines inside the
+    peak, num must therefore grow roughly as x**2; x = 30 needs about 5000.
+
+    The phase function integrates to exactly one, so the raw trapezoidal sum
+    shows how well num resolves it. If that sum is off by more than
+    ``CDF_TOLERANCE``, a ``RuntimeWarning`` is issued; increase num until it
+    stops. The result is then divided by the sum so that cdf[-1] is exactly 1.
+
+    Args:
+        m: complex index of refraction of the sphere
+        x: size parameter of the sphere
+        num: number of cosines, at least two
+
+    Returns:
+        mu: evenly spaced cosines of the scattering angle, from -1 to 1
+        cdf: cumulative probability at each cosine, from 0 to 1
+
+    Raises:
+        ValueError: if num is less than two or the phase function is not finite
+    """
+    if num < 2:
+        raise ValueError("num must be at least 2")
+    return _trapezoid_cdf(m, x, num, stacklevel=3)
+
+
+def _trapezoid_cdf(m, x, num, stacklevel):
+    """Integrate the phase function at num cosines, warning at the caller's caller."""
+    mu = np.linspace(-1, 1, num)
+    intensity_per_mu = mie.i_unpolarized(m, x, mu, norm="4pi") / 2
+    cdf_values = np.zeros(num)
+    cdf_values[1:] = np.cumsum((intensity_per_mu[1:] + intensity_per_mu[:-1]) * np.diff(mu) / 2)
+    total = cdf_values[-1]
+    if not np.isfinite(total):
+        raise ValueError(f"phase function is not finite for m={m}, x={x}")
+    if abs(total - 1) > CDF_TOLERANCE:
+        warnings.warn(
+            f"phase function under-resolved for x={x}: integral over {num} angles is {total:.4g}, "
+            "not 1, so sampled angles will be inaccurate; use more angles",
+            RuntimeWarning,
+            stacklevel=stacklevel,
+        )
+    cdf_values /= total
+    return mu, cdf_values
+
+
+def mu_with_uniform_cdf(m, x, num):
+    """
+    Inverse-transform table for sampling the unpolarized phase function.
+
+    The table holds num cosines mu running from -1 (backscattering) to 1
+    (forward scattering), spaced so that a scattered photon is equally likely
+    to fall between any two neighbours: cdf[i] is exactly i/(num - 1). The
+    cosines are therefore bunched where scattering is strong and sparse where
+    it is weak. ``generate_mie_costheta`` draws random cosines from this table.
+
+    The table is found by calculating ``cdf`` at max(2000, 5*x**2) evenly
+    spaced cosines, enough to resolve the forward peak whatever num is (see
+    ``cdf``), and interpolating to find where it reaches each step. Because
+    that count grows as x**2, building the table takes seconds at x = 100 and
+    over a minute at x = 300.
+
+    Args:
+        m: complex index of refraction of the sphere
+        x: size parameter of the sphere
+        num: number of entries in the table, at least two
+
+    Returns:
+        mu: unevenly spaced cosines of the scattering angle, from -1 to 1
+        cdf: evenly spaced cumulative probabilities, from 0 to 1
+
+    Raises:
+        ValueError: if num is less than two or the phase function is not finite
+    """
+    if num < 2:
+        raise ValueError("num must be at least 2")
+    big_num = max(2000, int(5 * x**2))  # resolve the forward peak, see cdf
+    big_mu, big_cdf = _trapezoid_cdf(m, x, big_num, stacklevel=3)
+    cdf_values = np.arange(num) / (num - 1)
+    mu = np.interp(cdf_values, big_cdf, big_mu)
+
+    return [mu, cdf_values]
+
+
+def generate_mie_costheta(mu_cdf, rng=None):
+    """
+    Generate a new scattering angle using a cdf.
+
+    A uniformly spaced cumulative distribution function (CDF) is needed.
+    New random angles are generated by selecting a random interval
+    mu[i] to mu[i+1] and choosing an angle uniformly distributed over
+    the interval.
+
+    Args:
+       mu_cdf: a cumulative distribution function
+       rng: optional source of randomness, anything with a ``random()`` method
+           such as ``numpy.random.default_rng()``.  Omitting it uses the process
+           wide ``numpy.random``, whose stream a caller cannot control without
+           reseeding the whole program, so pass a generator when reproducibility
+           matters.
+
+    Returns:
+       The cosine of the scattering angle
+
+    Examples:
+        Draw a reproducible angle without disturbing the global stream:
+
+        >>> import numpy as np
+        >>> import miepython.monte_carlo as mc
+        >>> mu, cdf = mc.mu_with_uniform_cdf(1.33, 1.7, 50)
+        >>> rng = np.random.default_rng(42)
+        >>> first = mc.generate_mie_costheta(mu, rng=rng)
+        >>> bool(-1.0 <= first <= 1.0)
+        True
+        >>> bool(first == mc.generate_mie_costheta(mu, rng=np.random.default_rng(42)))
+        True
+    """
+    if rng is None:
+        rng = np.random
+
+    # rng.random() draws from [0, 1), so int(r * num) never reaches num and
+    # index + 1 stays inside the table.  No clamp is needed.
+    num = len(mu_cdf) - 1
+    index = int(rng.random() * num)
+
+    x = mu_cdf[index]
+    x += (mu_cdf[index + 1] - mu_cdf[index]) * rng.random()
+
+    return x