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

miepython/mie_nojit.py

@@ -111,9 +111,73 @@ def _D_upwards(z, N, D):
         D[n] = 1 / (n / z - D[n - 1]) - n / z
 
 
+def _psi_downwards_py(z, nstop):
+    """
+    Compute the Riccati-Bessel functions psi_0(z)..psi_nstop(z).
+
+    The three-term upwards recurrence
+    ``psi_{n+1} = (2n+1)/z psi_n - psi_{n-1}`` is contaminated by the growing
+    chi_n solution once n exceeds ``|z|``, which is the normal case for psi_n(mx)
+    whenever the relative index is below one.  Miller's algorithm is used
+    instead: seed the recurrence well above ``|z|`` where psi_n is the decaying
+    solution, run it downwards, then fix the arbitrary scale against whichever
+    of psi_0 or psi_1 is larger.  sin(z) and cos(z) cannot both be small, so one
+    of those two seeds is always well conditioned.
+
+    Args:
+        z: function argument (the refractive index times the size parameter)
+        nstop: highest order needed
+
+    Returns:
+        Array of psi_k(z) for k=0 to nstop
+    """
+    abs_z = abs(z)
+    n_start = int(max(float(nstop), abs_z)) + 25 + int(1.5 * np.sqrt(abs_z))
+
+    psi = np.zeros(n_start + 2, dtype=np.complex128)
+    psi[n_start] = 1e-50
+    for n in range(n_start, 0, -1):
+        psi[n - 1] = (2 * n + 1) / z * psi[n] - psi[n + 1]
+        if abs(psi[n - 1]) > 1e200:  # keep the growing tail in range
+            psi[n - 1 :] /= 1e200
+
+    sin_z = np.sin(z)
+    psi_0 = sin_z
+    psi_1 = sin_z / z - np.cos(z)
+    if abs(psi_1) > abs(psi_0):
+        psi *= psi_1 / psi[1]
+    else:
+        psi *= psi_0 / psi[0]
+
+    return psi[: nstop + 1]
+
+
+def _D_calc_down_py(z, N):
+    """
+    Compute D_1(z)..D_N(z) using only the downwards recurrence.
+
+    ``_D_calc_py`` picks between the upwards and downwards recurrences with
+    Wiscombe's criterion, which considers the refractive index but not the number
+    of terms.  The upwards recurrence loses accuracy once N exceeds ``|z|`` (about
+    4 digits for a small sphere), and the resulting noise differs between the
+    numba and pure-python backends.  The internal-field coefficients are not on
+    the hot path, so they always take the stable route.
+
+    Args:
+        z: function argument (already multiplied by the refractive index)
+        N: highest order needed
+
+    Returns:
+        Array of logarithmic derivatives D_k(z) for k=1 to N
+    """
+    D = np.zeros(N + 1, dtype=np.complex128)
+    _D_downwards(z, N, D)
+    return D[1:]
+
+
 def _D_calc_py(m, x, N):
     """
-    Compute the logarithmic derivative of ψ_n(z) using the best method.
+    Compute the logarithmic derivative of ψ_n(z) using the downwards recurrence.
 
     D_n(z) = d[log ψ_n(z)] = ψ_n'(z)/ψ_n(z)
 
@@ -122,6 +186,14 @@ def _D_calc_py(m, x, N):
 
     The zero-based array, D[:], is shifted so that D[0] = D₁(z) = ψ₁'(z)/ψ₁(z)
 
+    Wiscombe's criterion used to pick between the upwards and downwards
+    recurrences from the refractive index alone.  The upwards recurrence is
+    contaminated once N passes ``|mx|``, which is the case for every small sphere,
+    and it left the Mie coefficients wrong by as much as 1% near m=1.  The
+    downwards recurrence is stable everywhere, and the criterion already chose it
+    for most large spheres, so always taking it costs little.  ``_D_upwards`` is
+    kept for comparison and testing.
+
     Args:
         m: the np.complex128 index of refraction of the sphere
         x: the size parameter of the sphere
@@ -130,16 +202,7 @@ def _D_calc_py(m, x, N):
     Returns:
         Array of logarithmic derivatives D_k(z) for k=1 to N-1.
     """
-    n = m.real
-    kappa = np.abs(m.imag)
-    D = np.zeros(N + 1, dtype=np.complex128)
-    mx = np.complex128(m * x)  # ensure np.complex128
-
-    if n < 1 or n > 10 or kappa > 10 or x * kappa >= 3.9 - 10.8 * n + 13.78 * n**2:
-        _D_downwards(mx, N, D)
-    else:
-        _D_upwards(mx, N, D)
-    return D[1:]
+    return _D_calc_down_py(np.complex128(m * x), N)
 
 
 def _an_bn_py(m, x, n_pole=0):
@@ -150,8 +213,8 @@ def _an_bn_py(m, x, n_pole=0):
     formula. The length of the arrays is chosen so that the error when the series
     is summed is around 1e-6.
 
-    If n_pole>0, then the array sizes will be n_pole+1. This is useful when
-    trying to isolate the behavior of a particular multipole.
+    If n_pole>0, then the arrays hold exactly n_pole terms, orders 1 to n_pole.
+    This is useful when trying to isolate the behavior of a particular multipole.
 
     To support resonance calculations, one can specify the number of terms
     to be calculated.  In general, using too few or too many terms increases the
@@ -164,58 +227,64 @@ def _an_bn_py(m, x, n_pole=0):
         n_pole: the number of An and Bn terms (0 does autosizing)
 
     Returns:
-        a, b: arrays of Mie coefficents An and Bn
+        a, b: arrays of Mie coefficents An and Bn, one entry per order,
+        with no padding.  ``_cn_dn`` returns the same number of terms.
     """
     if m.imag > 0:  # ensure imaginary part of refractive index is negative
         m = np.conj(m)
 
+    # Wiscombe's truncation: the series is summed through order n_terms
     if n_pole == 0:
-        nstop = int(x + 4.05 * x**0.33333 + 2.0) + 1
+        n_terms = int(x + 4.05 * x**0.33333 + 2.0)
     else:
-        nstop = n_pole + 1
+        n_terms = n_pole
 
-    a = np.zeros(nstop, dtype=np.complex128)
-    b = np.zeros(nstop, dtype=np.complex128)
+    a = np.zeros(n_terms, dtype=np.complex128)
+    b = np.zeros(n_terms, dtype=np.complex128)
     if x <= 0:
         return a, b
 
     inv_x = 1.0 / x
-    psi_nm1 = np.sin(x)  # nm1 = n-1 = 0
-    psi_n = psi_nm1 * inv_x - np.cos(x)
-    xi_nm1 = np.complex128(psi_nm1 + 1j * np.cos(x))
-    xi_n = np.complex128(psi_n + 1j * (np.cos(x) * inv_x + np.sin(x)))
+    sin_x = np.sin(x)
+    cos_x = np.cos(x)
+
+    # psi comes from Miller's downwards recurrence.  The upwards one is fine while
+    # n stays below x, which is all Wiscombe's truncation needs, but its relative
+    # accuracy is already down to about 1e-6 at n = n_terms and it collapses
+    # completely past that, so a caller asking for extra orders used to get noise.
+    psi = _psi_downwards_py(np.complex128(x), n_terms).real
+
+    # chi is the growing solution, so its upwards recurrence is the stable one.
+    # Building xi as psi + i*chi keeps xi exactly consistent with the psi above,
+    # which the lossless identity Re(a_n) == |a_n|**2 depends on.
+    chi_nm1 = cos_x
+    chi_n = cos_x * inv_x + sin_x
 
     if m.real > 0.0:
-        D = _D_calc_py(m, x, nstop + 1)
+        D = _D_calc_py(m, x, n_terms + 2)
 
-        for n in range(1, nstop):
+        for n in range(1, n_terms + 1):
             n_over_x = n * inv_x
+            xi_nm1 = psi[n - 1] + 1j * chi_nm1
+            xi_n = psi[n] + 1j * chi_n
             temp = D[n - 1] / m + n_over_x
-            a[n - 1] = (temp * psi_n - psi_nm1) / (temp * xi_n - xi_nm1)
+            a[n - 1] = (temp * psi[n] - psi[n - 1]) / (temp * xi_n - xi_nm1)
             temp = D[n - 1] * m + n_over_x
-            b[n - 1] = (temp * psi_n - psi_nm1) / (temp * xi_n - xi_nm1)
-            two_np1_over_x = (2 * n + 1) * inv_x
-            psi = two_np1_over_x * psi_n - psi_nm1
-            xi = two_np1_over_x * xi_n - xi_nm1
-            xi_nm1 = xi_n
-            xi_n = xi
-            psi_nm1 = psi_n
-            psi_n = psi
+            b[n - 1] = (temp * psi[n] - psi[n - 1]) / (temp * xi_n - xi_nm1)
+            chi = (2 * n + 1) * inv_x * chi_n - chi_nm1
+            chi_nm1 = chi_n
+            chi_n = chi
 
     else:
-        for n in range(1, nstop):
+        for n in range(1, n_terms + 1):
             n_over_x = n * inv_x
-            a[n - 1] = (n_over_x * psi_n - psi_nm1) / (n_over_x * xi_n - xi_nm1)
-            b[n - 1] = psi_n / xi_n
-            xi = (2 * n + 1) * inv_x * xi_n - xi_nm1
-            xi_nm1 = xi_n
-            xi_n = xi
-            psi_nm1 = psi_n
-            psi_n = xi_n.real
-
-    if n_pole != 0:
-        a = a[:-1]
-        b = b[:-1]
+            xi_nm1 = psi[n - 1] + 1j * chi_nm1
+            xi_n = psi[n] + 1j * chi_n
+            a[n - 1] = (n_over_x * psi[n] - psi[n - 1]) / (n_over_x * xi_n - xi_nm1)
+            b[n - 1] = psi[n] / xi_n
+            chi = (2 * n + 1) * inv_x * chi_n - chi_nm1
+            chi_nm1 = chi_n
+            chi_n = chi
 
     return np.conjugate(a), np.conjugate(b)
 
@@ -237,55 +306,46 @@ def _cn_dn_py(m, x, n_pole):
         m = np.conj(m)
     mx = m * x
 
+    # same truncation as _an_bn_py so the internal and external series match
     if n_pole == 0:
-        nstop = int(x + 4.05 * x**0.33333 + 2.0) + 1
+        n_terms = int(x + 4.05 * x**0.33333 + 2.0)
     else:
-        nstop = n_pole + 1
+        n_terms = n_pole
 
-    c = np.zeros(nstop, dtype=np.complex128)
-    d = np.zeros(nstop, dtype=np.complex128)
+    c = np.zeros(n_terms, dtype=np.complex128)
+    d = np.zeros(n_terms, dtype=np.complex128)
     if x <= 0:
         return c, d
 
     inv_x = 1.0 / x
     # no need to calculate anything when sphere is perfectly conducting
-    if m.real > 0.0 and not np.isinf(m.real) or not np.isinf(m.imag):
-        psi_nm1 = np.sin(x)  # nm1 = n-1 = 0
-        psi_n = psi_nm1 * inv_x - np.cos(x)
-
-        inv_mx = 1.0 / mx
-        psi_nm1_mx = np.sin(mx)  # nm1 = n-1 = 0
-        psi_n_mx = psi_nm1_mx * inv_mx - np.cos(mx)
-
-        xi_nm1 = np.complex128(psi_nm1 + 1j * np.cos(x))
-        xi_n = np.complex128(psi_n + 1j * (np.cos(x) * inv_x + np.sin(x)))
-
-        Dmx = _D_calc_py(np.complex128(m), x, nstop + 1)
-        Dx = _D_calc_py(np.complex128(1), x, nstop + 1)
-
-        for n in range(1, nstop + 1):
+    # (m.real <= 0 or an infinite index): there is no internal field, so c and d
+    # stay zero.  The `and` chain must not be mixed with `or` here, otherwise the
+    # test is true for every finite index and m=0 divides by zero below.
+    if m.real > 0.0 and not np.isinf(m.real) and not np.isinf(m.imag):
+        sin_x = np.sin(x)
+        cos_x = np.cos(x)
+
+        # xi is the growing solution, so seeding it and running upwards is stable
+        xi_nm1 = np.complex128(sin_x + 1j * cos_x)
+        xi_n = np.complex128((sin_x * inv_x - cos_x) + 1j * (cos_x * inv_x + sin_x))
+
+        psi_x = _psi_downwards_py(np.complex128(x), n_terms + 1)
+        psi_mx = _psi_downwards_py(np.complex128(mx), n_terms + 1)
+        Dmx = _D_calc_down_py(np.complex128(mx), n_terms + 2)
+        Dx = _D_calc_down_py(np.complex128(x), n_terms + 2)
+
+        for n in range(1, n_terms + 1):
             n_over_x = n * inv_x
-            common = (psi_n / psi_n_mx) * ((Dx[n - 1] + n_over_x) * xi_n - xi_nm1)
+            common = (psi_x[n] / psi_mx[n]) * ((Dx[n - 1] + n_over_x) * xi_n - xi_nm1)
 
             c[n - 1] = m * common / ((m * Dmx[n - 1] + n_over_x) * xi_n - xi_nm1)
             d[n - 1] = common / ((Dmx[n - 1] / m + n_over_x) * xi_n - xi_nm1)
 
-            two_np1 = 2 * n + 1
-            psi = two_np1 * inv_x * psi_n - psi_nm1
-            psi_nm1 = psi_n
-            psi_n = psi
-
-            psi_mx = two_np1 * inv_mx * psi_n_mx - psi_nm1_mx
-            psi_nm1_mx = psi_n_mx
-            psi_n_mx = psi_mx
-
-            xi = two_np1 * inv_x * xi_n - xi_nm1
+            xi = (2 * n + 1) * inv_x * xi_n - xi_nm1
             xi_nm1 = xi_n
             xi_n = xi
 
-    if n_pole != 0:
-        c = c[:-1]
-        d = d[:-1]
     return np.conjugate(c), np.conjugate(d)
 
 
@@ -322,6 +382,9 @@ def _pi_tau_py(mu, pi, tau):
         pi[n] = ((2 * n + 1) * mu * temp - (n + 1) * pi_nm2) / n
         pi_nm2 = temp
 
+    # each pass sets tau one order behind pi, so the highest order is still due
+    tau[n_terms - 1] = n_terms * mu * pi[n_terms - 1] - (n_terms + 1) * pi_nm2
+
 
 def _S1_S2_py(m, x, mu, n_pole):
     """
@@ -343,6 +406,9 @@ def _S1_S2_py(m, x, mu, n_pole):
     """
     a, b = _an_bn_py(m, x, 0)
     N = len(a)
+    if n_pole < 0 or n_pole > N:
+        raise ValueError("n_pole must be 0 (all terms) or a multipole order in 1.." + str(N))
+
     pi = np.zeros(N)
     tau = np.zeros(N)
     scale = _series_scale_factors(N)
@@ -353,14 +419,17 @@ def _S1_S2_py(m, x, mu, n_pole):
     S1 = np.zeros(nangles, dtype=np.complex128)
     S2 = np.zeros(nangles, dtype=np.complex128)
 
+    # zero-based arrays: multipole order n lives at index n-1
+    j = n_pole - 1
+
     for k in range(nangles):
         _pi_tau_py(mu[k], pi, tau)
         if n_pole == 0:
             S1[k] = np.dot(pi, scale_a) + np.dot(tau, scale_b)
             S2[k] = np.dot(tau, scale_a) + np.dot(pi, scale_b)
         else:
-            S1[k] = scale[n_pole] * (pi[n_pole] * a[n_pole] + tau[n_pole] * b[n_pole])
-            S2[k] = scale[n_pole] * (tau[n_pole] * a[n_pole] + pi[n_pole] * b[n_pole])
+            S1[k] = scale[j] * (pi[j] * a[j] + tau[j] * b[j])
+            S2[k] = scale[j] * (tau[j] * a[j] + pi[j] * b[j])
 
     return np.conjugate(S1), np.conjugate(S2)
 
@@ -457,7 +526,9 @@ def _single_sphere_py(m, x, n_pole, e_field):
         m: the complex index of refraction of the sphere
         x: the size parameter of the sphere
         n_pole: a non-zero value returns the contribution by the n_pole multipole
-        e_field: Electric (True) or Magnetic Field otherwise
+        e_field: selects which multipole of order n_pole contributes, the
+            electric one a_n (True) or the magnetic one b_n (False).
+            Ignored when n_pole == 0.
 
     Returns:
         qext: the total extinction efficiency
@@ -465,7 +536,10 @@ def _single_sphere_py(m, x, n_pole, e_field):
         qback: the backscatter efficiency
         g: the average cosine of the scattering phase function
     """
-    _ = e_field  # currently unused in scalar aggregate efficiencies
+    # a sphere of zero size scatters nothing; every efficiency tends to zero,
+    # including qback, whose small-sphere form is 0/0 at x=0
+    if x <= 0:
+        return 0.0, 0.0, 0.0, 0.0
 
     # case when sphere matches its environment
     if abs(m.real - 1) <= 1e-8 and abs(m.imag) < 1e-8:
@@ -507,12 +581,18 @@ def _single_sphere_py(m, x, n_pole, e_field):
         g = 4.0 * np.sum(asy1 + asy2) / qsca / x2
 
     else:
+        # isolate one multipole: the electric term a_n or the magnetic term b_n
         cn = 2.0 * n_pole + 1
-        qback = np.abs((-1) ** n_pole * cn * (a[-1] - b[-1])) ** 2 / x2
-        qext = 2.0 * cn * (a[-1].real + b[-1].real) / x2
+        coeff = a[-1] if e_field else b[-1]
+        qext = 2.0 * cn * coeff.real / x2
+        # the (-1)**n_pole and the sign of b_n drop out of the modulus
+        qback = np.abs(cn * coeff) ** 2 / x2
         qsca = qext
         if m.imag < 0:
-            qsca = 2.0 * cn * (np.abs(a[-1]) ** 2 + np.abs(b[-1]) ** 2) / x2
-        g = None
+            qsca = 2.0 * cn * np.abs(coeff) ** 2 / x2
+
+        # pi_n**2 and tau_n**2 are both even in mu, so an isolated multipole of
+        # one parity scatters symmetrically about 90 degrees and <cos(theta)>=0
+        g = 0.0
 
     return qext, qsca, qback, g

miepython/monte_carlo.py

@@ -1,7 +1,64 @@
 """
-Monte Carlo and Mie scattering.
+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
 
@@ -11,92 +68,107 @@ __all__ = (
     "generate_mie_costheta",
 )
 
+# Largest acceptable relative error in the integral of the phase function
+CDF_TOLERANCE = 0.01
+
 
 def cdf(m, x, num):
     """
-    Create a CDF for unpolarized scattering uniformly spaced in cos(theta).
+    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.
 
-    The CDF covers scattered (exit) angles ranging from 180 to 0 degrees.
-    (The cosines are uniformly distributed over -1 to 1.) Because the angles
-    are uniformly distributed in cos(theta), the scattering function is not
-    sampled uniformly and therefore huge array sizes are needed to adequately
-    sample highly anisotropic phase functions.
+    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.
 
-    Since this is a cumulative distribution function, the maximum value
-    should be 1.
+    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: the complex index of refraction of the sphere
-        x: the size parameter of the sphere
-        num: length of desired CDF array
+        m: complex index of refraction of the sphere
+        x: size parameter of the sphere
+        num: number of cosines, at least two
 
     Returns:
-        mu: array of cosines of angles
-        cdf: array of cumulative distribution function values
+        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") / num
-    cdf_values = np.cumsum(intensity_per_mu)
+    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):
     """
-    Create a CDF for unpolarized scattering for uniform CDF.
-
-    The CDF covers scattered (exit) angles ranging from 180 to 0 degrees.
-    (The cosines are uniformly distributed over -1 to 1.) These angles mu
-    correspond to uniform spacing of the cumulative distribution function
-    for unpolarized Mie scattering where cdf[i] = i/(num-1).
+    Inverse-transform table for sampling the unpolarized phase function.
 
-    This is a brute force implementation that solves the problem by
-    calculating the CDF at many points and then scanning to find the
-    specific angles that correspond to uniform interval of the CDF.
+    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.
 
-    Since this is a cumulative distribution function, the maximum value
-    should be 1.
+    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: the complex index of refraction of the sphere
-        x: the size parameter of the sphere
-        num: length of desired CDF array
+        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: array of cosines of angles (irregularly spaced)
-        cdf: array of cumulative distribution function values
-    """
-    big_num = 2000  # large to work with x up to 10
-    big_mu, big_cdf = cdf(m, x, big_num)
-    mu = np.empty(num)
-    cdf_values = np.empty(num)
-
-    mu[0] = -1  # cos[180 degrees] is -1
-    cdf_values[0] = 0  # initial cdf is zero
+        mu: unevenly spaced cosines of the scattering angle, from -1 to 1
+        cdf: evenly spaced cumulative probabilities, from 0 to 1
 
-    big_k = 0  # index into big_cdf
-    for k in range(1, num - 1):
-
-        target = k / (num - 1)
-        while big_cdf[big_k] < target:
-            big_k += 1
-
-        delta = big_cdf[big_k] - target
-        delta_cdf = big_cdf[big_k] - big_cdf[big_k - 1]
-        delta_mu = big_mu[big_k] - big_mu[big_k - 1]
-
-        mu[k] = big_mu[big_k] - delta / delta_cdf * delta_mu  # interpolate
-        cdf_values[k] = target
-
-    #       print(' mu[',k,']=% .5f'%mu[k],' cdf[',k,']=% .5f'%cdf[k],
-    #       'cdf=',big_cdf[big_k], fraction)
-
-    mu[num - 1] = 1  # cos[0 degrees] is 1
-    cdf_values[num - 1] = 1  # last cdf is one
+    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):
+def generate_mie_costheta(mu_cdf, rng=None):
     """
     Generate a new scattering angle using a cdf.
 
@@ -107,18 +179,37 @@ def generate_mie_costheta(mu_cdf):
 
     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
     """
-    # the following should be equivalent to these four lines
-    # index = np.random.randint(0, high=len(mu_cdf))
+    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(np.random.random() * num)
-    if index >= num:
-        index = num - 1
+    index = int(rng.random() * num)
 
     x = mu_cdf[index]
-    x += (mu_cdf[index + 1] - mu_cdf[index]) * np.random.random()
+    x += (mu_cdf[index + 1] - mu_cdf[index]) * rng.random()
 
     return x