Merge pull request scipy#22156 from jorenham/special.lpn-lpmn-clpmn-deprecation-warning

steppi · web-flow · commit e117396e87b4 · 2024-12-22T18:16:07.000-05:00
DEP: deprecation warnings for ``special.lpn`` and ``[c]lpmn``
diff --git a/scipy/special/_basic.py b/scipy/special/_basic.py
@@ -21,6 +21,7 @@
 from ._comb import _comb_int
 from ._multiufuncs import (assoc_legendre_p_all,
                            legendre_p_all)
+from scipy._lib.deprecation import _deprecated
 
 
 __all__ = [
@@ -87,6 +88,11 @@
 ]
 
 
+__DEPRECATION_MSG_1_15 = (
+    "`scipy.special.{}` is deprecated as of SciPy 1.15.0 and will be "
+    "removed in SciPy 1.17.0. Please use `scipy.special.{}` instead."
+)
+
 # mapping k to last n such that factorialk(n, k) < np.iinfo(np.int64).max
 _FACTORIALK_LIMITS_64BITS = {1: 20, 2: 33, 3: 44, 4: 54, 5: 65,
                              6: 74, 7: 84, 8: 93, 9: 101}
@@ -1703,6 +1709,7 @@ def mathieu_odd_coef(m, q):
     return fc[:km]
 
 
+@_deprecated(__DEPRECATION_MSG_1_15.format("lpmn", "assoc_legendre_p_all"))
 def lpmn(m, n, z):
     """Sequence of associated Legendre functions of the first kind.
 
@@ -1715,8 +1722,8 @@ def lpmn(m, n, z):
     use clpmn instead.
 
     .. deprecated:: 1.15.0
-        This function is deprecated and will be removed in a future version.
-        Use `scipy.special.assoc_legendre_p_all` instead.
+        This function is deprecated and will be removed in SciPy 1.17.0.
+        Please `scipy.special.assoc_legendre_p_all` instead.
 
     Parameters
     ----------
@@ -1782,6 +1789,7 @@ def lpmn(m, n, z):
     return p, pd
 
 
+@_deprecated(__DEPRECATION_MSG_1_15.format("clpmn", "assoc_legendre_p_all"))
 def clpmn(m, n, z, type=3):
     """Associated Legendre function of the first kind for complex arguments.
 
@@ -1791,8 +1799,8 @@ def clpmn(m, n, z, type=3):
     ``Pmn'(z)`` for all orders from ``0..m`` and degrees from ``0..n``.
 
     .. deprecated:: 1.15.0
-        This function is deprecated and will be removed in a future version.
-        Use `scipy.special.assoc_legendre_p_all` instead.
+        This function is deprecated and will be removed in SciPy 1.17.0.
+        Please use `scipy.special.assoc_legendre_p_all` instead.
 
     Parameters
     ----------
@@ -2033,6 +2041,7 @@ def euler(n):
     return _specfun.eulerb(n1)[:(n+1)]
 
 
+@_deprecated(__DEPRECATION_MSG_1_15.format("lpn", "legendre_p_all"))
 def lpn(n, z):
     """Legendre function of the first kind.
 
@@ -2042,8 +2051,8 @@ def lpn(n, z):
     See also special.legendre for polynomial class.
 
     .. deprecated:: 1.15.0
-        This function is deprecated and will be removed in a future version.
-        Use `scipy.special.legendre_p_all` instead.
+        This function is deprecated and will be removed in SciPy 1.17.0.
+        Please use `scipy.special.legendre_p_all` instead.
 
     References
     ----------
@@ -3464,7 +3473,7 @@ def zeta(x, q=None, out=None):
         ``None``, complex inputs `x` are supported. If `q` is not ``None``,
         then currently only real inputs `x` with ``x >= 1`` are supported,
         even when ``q = 1.0`` (corresponding to the Riemann zeta function).
-        
+
     out : ndarray, optional
         Output array for the computed values.
 
@@ -3530,7 +3539,7 @@ def zeta(x, q=None, out=None):
     else:
         return _ufuncs._zeta(x, q, out)
 
-      
+
 def softplus(x, **kwargs):
     r"""
     Compute the softplus function element-wise.
@@ -3554,7 +3563,7 @@ def softplus(x, **kwargs):
     Examples
     --------
     >>> from scipy import special
-    
+
     >>> special.softplus(0)
     0.6931471805599453
 
diff --git a/scipy/special/tests/test_basic.py b/scipy/special/tests/test_basic.py
@@ -41,6 +41,7 @@
 from scipy.special import elliprc, elliprd, elliprf, elliprg, elliprj
 from scipy.special import softplus
 from scipy.special import mathieu_odd_coef, mathieu_even_coef, stirling2
+from scipy.special import lpn, lpmn, clpmn
 from scipy._lib._util import np_long, np_ulong
 from scipy._lib._array_api import xp_assert_close, xp_assert_equal, SCIPY_ARRAY_API
 
@@ -4633,3 +4634,17 @@ def test_temme_rel_max_error(self):
             denom = stirling2([n], k_entries, exact=True)
             num = denom - stirling2([n], k_entries, exact=False)
             assert np.max(np.abs(num / denom)) < 2e-5
+
+
+class TestLegendreDeprecation:
+
+    def test_warn_lpn(self):
+        msg = "`scipy.special.lpn` is deprecated..."
+        with pytest.deprecated_call(match=msg):
+            _ = lpn(1, 0)
+
+    @pytest.mark.parametrize("xlpmn", [lpmn, clpmn])
+    def test_warn_xlpmn(self, xlpmn):
+        message = f"`scipy.special.{xlpmn.__name__}` is deprecated..."
+        with pytest.deprecated_call(match=message):
+            _ = xlpmn(1, 1, 0)
diff --git a/scipy/special/tests/test_data.py b/scipy/special/tests/test_data.py
@@ -84,13 +84,17 @@ def legendre_p_via_assoc_(nu, x):
     return lpmv(0, nu, x)
 
 def lpn_(n, x):
-    return lpn(n.astype('l'), x)[0][-1]
+    with suppress_warnings() as sup:
+        sup.filter(category=DeprecationWarning)
+        return lpn(n.astype('l'), x)[0][-1]
 
 def lqn_(n, x):
     return lqn(n.astype('l'), x)[0][-1]
 
 def legendre_p_via_lpmn(n, x):
-    return lpmn(0, n, x)[0][0,-1]
+    with suppress_warnings() as sup:
+        sup.filter(category=DeprecationWarning)
+        return lpmn(0, n, x)[0][0,-1]
 
 def legendre_q_via_lqmn(n, x):
     return lqmn(0, n, x)[0][0,-1]
diff --git a/scipy/special/tests/test_legendre.py b/scipy/special/tests/test_legendre.py
@@ -4,7 +4,7 @@
 
 import pytest
 from numpy.testing import (assert_equal, assert_almost_equal, assert_array_almost_equal,
-    assert_allclose)
+    assert_allclose, suppress_warnings)
 
 from scipy import special
 from scipy.special import (legendre_p, legendre_p_all, assoc_legendre_p,
@@ -32,8 +32,11 @@ def test_legendre(self):
     @pytest.mark.parametrize('zi', [9.766818, 0.2999083, 8.24726, -22.84843,
                                     -0.8792666])
     def test_lpn_against_clpmn(self, n, zr, zi):
-        reslpn = special.lpn(n, zr + zi*1j)
-        resclpmn = special.clpmn(0, n, zr+zi*1j)
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            reslpn = special.lpn(n, zr + zi*1j)
+            resclpmn = special.clpmn(0, n, zr+zi*1j)
+
         assert_allclose(reslpn[0], resclpmn[0][0])
         assert_allclose(reslpn[1], resclpmn[1][0])
 
@@ -73,7 +76,10 @@ def test_all_ode(self, n_max, x_shape):
         np.testing.assert_allclose(err, 0, atol=1e-10)
 
     def test_legacy(self):
-        p, pd = special.lpn(2, 0.5)
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            p, pd = special.lpn(2, 0.5)
+
         assert_array_almost_equal(p, [1.00000, 0.50000, -0.12500], 4)
         assert_array_almost_equal(pd, [0.00000, 1.00000, 1.50000], 4)
 
@@ -327,13 +333,16 @@ def test_legacy(self, m_max, n_max):
         x = 0.5
         p, p_jac = assoc_legendre_p_all(n_max, m_max, x, diff_n=1)
 
-        p_legacy, p_jac_legacy = special.lpmn(m_max, n_max, x)
-        for m in range(m_max + 1):
-            np.testing.assert_allclose(p_legacy[m], p[:, m])
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
 
-        p_legacy, p_jac_legacy = special.lpmn(-m_max, n_max, x)
-        for m in range(m_max + 1):
-            np.testing.assert_allclose(p_legacy[m], p[:, -m])
+            p_legacy, p_jac_legacy = special.lpmn(m_max, n_max, x)
+            for m in range(m_max + 1):
+                np.testing.assert_allclose(p_legacy[m], p[:, m])
+
+            p_legacy, p_jac_legacy = special.lpmn(-m_max, n_max, x)
+            for m in range(m_max + 1):
+                np.testing.assert_allclose(p_legacy[m], p[:, -m])
 
 class TestMultiAssocLegendreP:
     @pytest.mark.parametrize("shape", [(1000,), (4, 9), (3, 5, 7)])
@@ -388,7 +397,7 @@ def test_specific(self, shape, branch_cut, z_min, z_max, norm):
             assoc_legendre_p_2_m2(z, branch_cut=branch_cut, norm=norm))
         np.testing.assert_allclose(p[2, -1],
             assoc_legendre_p_2_m1(z, branch_cut=branch_cut, norm=norm))
- 
+
         np.testing.assert_allclose(p[3, 0],
             assoc_legendre_p_3_0(z, branch_cut=branch_cut, norm=norm))
         np.testing.assert_allclose(p[3, 1],
@@ -678,7 +687,11 @@ def test_ode(self, shape):
 class TestLegendreFunctions:
     def test_clpmn(self):
         z = 0.5+0.3j
-        clp = special.clpmn(2, 2, z, 3)
+
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            clp = special.clpmn(2, 2, z, 3)
+
         assert_array_almost_equal(clp,
                    (np.array([[1.0000, z, 0.5*(3*z*z-1)],
                            [0.0000, np.sqrt(z*z-1), 3*z*np.sqrt(z*z-1)],
@@ -693,8 +706,12 @@ def test_clpmn_close_to_real_2(self):
         m = 1
         n = 3
         x = 0.5
-        clp_plus = special.clpmn(m, n, x+1j*eps, 2)[0][m, n]
-        clp_minus = special.clpmn(m, n, x-1j*eps, 2)[0][m, n]
+
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            clp_plus = special.clpmn(m, n, x+1j*eps, 2)[0][m, n]
+            clp_minus = special.clpmn(m, n, x-1j*eps, 2)[0][m, n]
+
         assert_array_almost_equal(np.array([clp_plus, clp_minus]),
                                   np.array([special.lpmv(m, n, x),
                                          special.lpmv(m, n, x)]),
@@ -705,8 +722,12 @@ def test_clpmn_close_to_real_3(self):
         m = 1
         n = 3
         x = 0.5
-        clp_plus = special.clpmn(m, n, x+1j*eps, 3)[0][m, n]
-        clp_minus = special.clpmn(m, n, x-1j*eps, 3)[0][m, n]
+
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            clp_plus = special.clpmn(m, n, x+1j*eps, 3)[0][m, n]
+            clp_minus = special.clpmn(m, n, x-1j*eps, 3)[0][m, n]
+
         assert_array_almost_equal(np.array([clp_plus, clp_minus]),
                                   np.array([special.lpmv(m, n, x)*np.exp(-0.5j*m*np.pi),
                                          special.lpmv(m, n, x)*np.exp(0.5j*m*np.pi)]),
@@ -717,33 +738,41 @@ def test_clpmn_across_unit_circle(self):
         m = 1
         n = 1
         x = 1j
-        for type in [2, 3]:
-            assert_almost_equal(special.clpmn(m, n, x+1j*eps, type)[0][m, n],
-                            special.clpmn(m, n, x-1j*eps, type)[0][m, n], 6)
+
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            for type in [2, 3]:
+                assert_almost_equal(special.clpmn(m, n, x+1j*eps, type)[0][m, n],
+                                special.clpmn(m, n, x-1j*eps, type)[0][m, n], 6)
 
     def test_inf(self):
-        for z in (1, -1):
-            for n in range(4):
-                for m in range(1, n):
-                    lp = special.clpmn(m, n, z)
-                    assert np.isinf(lp[1][1,1:]).all()
-                    lp = special.lpmn(m, n, z)
-                    assert np.isinf(lp[1][1,1:]).all()
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            for z in (1, -1):
+                for n in range(4):
+                    for m in range(1, n):
+                        lp = special.clpmn(m, n, z)
+                        assert np.isinf(lp[1][1,1:]).all()
+                        lp = special.lpmn(m, n, z)
+                        assert np.isinf(lp[1][1,1:]).all()
 
     def test_deriv_clpmn(self):
         # data inside and outside of the unit circle
         zvals = [0.5+0.5j, -0.5+0.5j, -0.5-0.5j, 0.5-0.5j,
                  1+1j, -1+1j, -1-1j, 1-1j]
         m = 2
         n = 3
-        for type in [2, 3]:
-            for z in zvals:
-                for h in [1e-3, 1e-3j]:
-                    approx_derivative = (special.clpmn(m, n, z+0.5*h, type)[0]
-                                         - special.clpmn(m, n, z-0.5*h, type)[0])/h
-                    assert_allclose(special.clpmn(m, n, z, type)[1],
-                                    approx_derivative,
-                                    rtol=1e-4)
+
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            for type in [2, 3]:
+                for z in zvals:
+                    for h in [1e-3, 1e-3j]:
+                        approx_derivative = (special.clpmn(m, n, z+0.5*h, type)[0]
+                                            - special.clpmn(m, n, z-0.5*h, type)[0])/h
+                        assert_allclose(special.clpmn(m, n, z, type)[1],
+                                        approx_derivative,
+                                        rtol=1e-4)
 
     """
     @pytest.mark.parametrize("m_max", [3])
@@ -834,7 +863,9 @@ def test_array_inputs_lxn(self, function, n, z_complex, z_inexact, input_shape):
         if z_complex:
             z = 1j * z + 0.5j * z
 
-        P_z, P_d_z = function(n, z)
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            P_z, P_d_z = function(n, z)
         assert P_z.shape == (n + 1, ) + input_shape
         assert P_d_z.shape == (n + 1, ) + input_shape
 
@@ -877,7 +908,10 @@ def test_array_inputs_clxmn(self, function, m, n, input_shape):
         z = rng.uniform(-1, 1, size=input_shape)
         z = 1j * z + 0.5j * z
 
-        P_z, P_d_z = function(m, n, z)
+        with suppress_warnings() as sup:
+            sup.filter(category=DeprecationWarning)
+            P_z, P_d_z = function(m, n, z)
+
         assert P_z.shape == (m + 1, n + 1) + input_shape
         assert P_d_z.shape == (m + 1, n + 1) + input_shape
 
diff --git a/scipy/special/tests/test_mpmath.py b/scipy/special/tests/test_mpmath.py
@@ -3,7 +3,7 @@
 
 """
 import numpy as np
-from numpy.testing import assert_, assert_allclose
+from numpy.testing import assert_, assert_allclose, suppress_warnings
 from numpy import pi
 import pytest
 import itertools
@@ -1321,7 +1321,7 @@ def test_gamma_complex(self):
         assert_mpmath_equal(
             sc.gamma,
             exception_to_nan(mpmath.gamma),
-            [ComplexArg()], 
+            [ComplexArg()],
             rtol=5e-13,
         )
 
@@ -1659,7 +1659,9 @@ def test_legendre_int(self):
     def test_legenp(self):
         def lpnm(n, m, z):
             try:
-                v = sc.lpmn(m, n, z)[0][-1,-1]
+                with suppress_warnings() as sup:
+                    sup.filter(category=DeprecationWarning)
+                    v = sc.lpmn(m, n, z)[0][-1,-1]
             except ValueError:
                 return np.nan
             if abs(v) > 1e306:
@@ -1710,7 +1712,9 @@ def legenp(n, m, z):
     def test_legenp_complex_2(self):
         def clpnm(n, m, z):
             try:
-                return sc.clpmn(m.real, n.real, z, type=2)[0][-1,-1]
+                with suppress_warnings() as sup:
+                    sup.filter(category=DeprecationWarning)
+                    return sc.clpmn(m.real, n.real, z, type=2)[0][-1,-1]
             except ValueError:
                 return np.nan
 
@@ -1738,7 +1742,9 @@ def legenp(n, m, z):
     def test_legenp_complex_3(self):
         def clpnm(n, m, z):
             try:
-                return sc.clpmn(m.real, n.real, z, type=3)[0][-1,-1]
+                with suppress_warnings() as sup:
+                    sup.filter(category=DeprecationWarning)
+                    return sc.clpmn(m.real, n.real, z, type=3)[0][-1,-1]
             except ValueError:
                 return np.nan
 
