miepython 3.2.0__py3-none-any.whl → 3.3.0__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,5 +1,35 @@
 """
-Monte Carlo and Mie scattering.
+Sample scattering angles from the Mie phase function.
+
+Monte Carlo photon transport needs a random exit direction distributed according to
+the phase function.  This module builds the inverse-transform table that provides
+one: ``mu_with_uniform_cdf`` returns angles spaced so that equal steps along the
+cumulative distribution are equally likely, and ``generate_mie_costheta`` draws from
+that table.  ``docs/06_random_deviates.ipynb`` works through the whole procedure.
+
+Importing
+---------
+
+This module is *not* imported with the package, because it imports ``miepython``
+itself and doing so from ``miepython/__init__.py`` would be circular.  Ask for it by
+name::
+
+    import numpy as np
+    import miepython.monte_carlo as mc
+
+    m, x = 1.33, 2.0                              # a water droplet
+    mu, cdf = mc.mu_with_uniform_cdf(m, x, 500)   # 500-entry lookup table
+
+    rng = np.random.default_rng(12345)
+    cosines = [mc.generate_mie_costheta(mu, rng=rng) for _ in range(10000)]
+
+Build the table once and reuse it: it costs a full Mie calculation, while each draw
+off it costs one random number.  The number of table entries sets how finely the
+phase function is resolved, so strongly forward-scattering spheres need more of
+them.
+
+Passing ``rng`` keeps the draws reproducible without disturbing the process-wide
+``numpy.random``; omitting it falls back to that global generator.
 """
 
 import numpy as np
@@ -96,7 +126,7 @@ def mu_with_uniform_cdf(m, x, num):
     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 +137,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

miepython/rayleigh.py

@@ -2,6 +2,8 @@
 
 import numpy as np
 
+from .core import normalization_factor as core_normalization_factor
+
 __all__ = (
     "efficiencies_mx",
     "efficiencies",
@@ -62,7 +64,10 @@ def efficiencies(m, d, lambda0, n_env=1.0):
 
 def normalization_factor(m, x, norm_str):
     """
-    Figure out scattering function normalization.
+    Figure out scattering function normalization for a small sphere.
+
+    The rules are the same as for the full Mie solution, so they live in
+    ``miepython.core``; only the efficiencies feeding them are the Rayleigh ones.
 
     Args:
         m: complex index of refraction of sphere
@@ -72,38 +77,7 @@ def normalization_factor(m, x, norm_str):
     Returns:
         scaling factor needed for scattering function
     """
-    factor = None
-    norm = norm_str.lower()
-
-    if norm in ["bohren"]:
-        factor = 1 / 2
-
-    elif norm in ["wiscombe"]:
-        factor = 1
-
-    elif norm in ["qsca", "scattering_efficiency"]:
-        factor = x * np.sqrt(np.pi)
-
-    else:
-        qext, qsca, _, _ = efficiencies_mx(m, x)
-
-        if norm in ["a", "albedo"]:
-            factor = x * np.sqrt(np.pi * qext)
-
-        if norm in ["1", "one", "unity"]:
-            factor = x * np.sqrt(qsca * np.pi)
-
-        if norm in ["four_pi", "4pi"]:
-            factor = x * np.sqrt(qsca / 4)
-
-        if norm in ["qext", "extinction_efficiency"]:
-            factor = x * np.sqrt(qsca * np.pi / qext)
-
-    if factor is None:
-        raise ValueError(
-            "normalization must be one of 'albedo' (default), 'one', '4pi', 'qext', 'qsca', 'bohren', or 'wiscombe'"
-        )
-    return factor
+    return core_normalization_factor(m, x, norm_str, efficiency_source=efficiencies_mx)
 
 
 def S1_S2(m, x, mu, norm="albedo"):

miepython/util.py

@@ -2,10 +2,11 @@
 
 import numpy as np
 
-_all_ = (
+__all__ = (
     "cs_scalar",
     "cs_vector",
     "cs",
+    "phasor_str_scalar",
     "phasor_str",
     "cartesian_to_spherical",
     "spherical_to_cartesian",
@@ -14,10 +15,29 @@ _all_ = (
 
 
 def cartesian_to_spherical(x, y, z):
-    """Convert Cartesian coordinates (x, y, z) to spherical (r, theta, phi)."""
-    r = np.sqrt(x**2 + y**2 + z**2)
-    theta = np.arccos(z / r) if r != 0 else 0  # Polar angle (0 to pi)
-    phi = np.arctan2(y, x)  # Azimuthal angle (-pi to pi)
+    """
+    Convert Cartesian coordinates (x, y, z) to spherical (r, theta, phi).
+
+    Scalars and arrays are both accepted and the three inputs are broadcast
+    against each other.  At the origin theta is reported as 0, and z/r is clipped
+    so that rounding cannot push the arccos argument outside [-1, 1].
+
+    Args:
+        x: Cartesian x coordinate, scalar or array-like
+        y: Cartesian y coordinate, scalar or array-like
+        z: Cartesian z coordinate, scalar or array-like
+
+    Returns:
+        r, theta, phi: radius, polar angle from +z, azimuth from +x toward +y
+    """
+    xx, yy, zz = np.broadcast_arrays(np.asarray(x), np.asarray(y), np.asarray(z))
+    r = np.sqrt(xx**2 + yy**2 + zz**2)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        cos_theta = np.where(r == 0, 1.0, np.clip(zz / r, -1.0, 1.0))
+
+    theta = np.arccos(cos_theta)  # polar angle (0 to pi)
+    phi = np.arctan2(yy, xx)  # azimuthal angle (-pi to pi)
     return r, theta, phi
 
 

miepython/vsh.py

@@ -29,18 +29,27 @@ Bessel Function Selection:
 
 Functions:
 
-    M_odd(n, k, d_sphere, r, theta, phi)
+    All four take the same arguments ``(n, lambda0, d_sphere, m_index, r, theta,
+    phi)``: the multipole order, the vacuum wavelength, the sphere diameter, the
+    refractive index of the medium the point lies in, and the spherical coordinates
+    of that point.  ``lambda0``, ``d_sphere`` and ``r`` share one length unit.
+
+    M_odd(n, lambda0, d_sphere, m_index, r, theta, phi)
         Compute the nth odd magnetic vector spherical harmonic (m=1).
 
-    M_even(n, k, d_sphere, r, theta, phi)
+    M_even(n, lambda0, d_sphere, m_index, r, theta, phi)
         Compute the nth even magnetic vector spherical harmonic (m=1).
 
-    N_odd(n, k, d_sphere, r, theta, phi)
+    N_odd(n, lambda0, d_sphere, m_index, r, theta, phi)
         Compute the nth odd electric vector spherical harmonic (m=1).
 
-    N_even(n, k, d_sphere, r, theta, phi)
+    N_even(n, lambda0, d_sphere, m_index, r, theta, phi)
         Compute the nth even electric vector spherical harmonic (m=1).
 
+    Each has an ``*_array`` counterpart -- ``M_odd_array``, ``M_even_array``,
+    ``N_odd_array``, ``N_even_array`` -- with the identical signature, taking
+    array-valued ``r``, ``theta`` and ``phi``.
+
 Additional Utility Functions:
 
     mie_pi(n, theta, deg=False)
@@ -54,8 +63,8 @@ Additional Utility Functions:
 
 import numpy as np
 from scipy.special import spherical_jn, lpmv, factorial2
-from miepython.bessel import spherical_h1, d_riccati_bessel_h1
-import miepython as mie
+from .bessel import spherical_h1, d_riccati_bessel_h1
+from ._backend import D_calc
 
 __all__ = (
     "mie_tau",
@@ -312,7 +321,7 @@ def N_base(n, m_index, kr, theta, inside):
         else:
             factor1 = spherical_jn(n, rho)
             # D_calc returns D_1..D_N; request one extra term and take D_n.
-            Dn = mie.D_calc(m_index, kr, n + 1)[n - 1]
+            Dn = D_calc(m_index, kr, n + 1)[n - 1]
             factor2 = factor1 * Dn
             factor1 /= rho
     else:

{miepython-3.2.0.dist-info → miepython-3.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: miepython
-Version: 3.2.0
+Version: 3.3.0
 Summary: Mie scattering of a plane wave by a sphere
 Author-email: Scott Prahl <scott.prahl@oit.edu>
 License-Expression: MIT
@@ -34,6 +34,7 @@ Requires-Dist: sphinx_automodapi; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: imageio; extra == "dev"
 Requires-Dist: requests; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -72,7 +73,7 @@ Dynamic: license-file
    :alt: DOI
 
 .. |license| image:: https://img.shields.io/github/license/scottprahl/miepython?color=68CA66
-   :target: https://github.com/scottprahl/miepython/blob/master/LICENSE.txt
+   :target: https://github.com/scottprahl/miepython/blob/main/LICENSE.txt
    :alt: License
 
 .. |test| image:: https://github.com/scottprahl/miepython/actions/workflows/test.yaml/badge.svg
@@ -208,9 +209,9 @@ JIT Enabled  0.15 s       27×
 Citation
 --------
 
-If you use ``laserbeamsize`` in academic, instructional, or applied technical work, please cite:
+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.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
+Prahl, S. (2026). *miepython: Pure python calculation of Mie scattering* (Version 3.2.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.7949263
 
 BibTeX:
 
@@ -222,7 +223,7 @@ BibTeX:
       url     = {https://github.com/scottprahl/miepython},
       doi     = {10.5281/zenodo.7949263},
       year    = {2026},
-      version = {3.1.0},
+      version = {3.2.0},
       publisher = {Zenodo}
     }