Merge pull request #16156 from WarrenWeckesser/deprecate-dual

DEP: Deprecate `numpy.dual`.

7 files changed, 28 insertions, 13 deletions

diff --git a/numpy/__init__.py b/numpy/__init__.py
index 575e8ea3d..e6a24f0d1 100644
--- a/numpy/__init__.py
+++ b/numpy/__init__.py
@@ -79,7 +79,9 @@ test
 show_config
     Show numpy build configuration
 dual
-    Overwrite certain functions with high-performance Scipy tools
+    Overwrite certain functions with high-performance SciPy tools.
+    Note: `numpy.dual` is deprecated.  Use the functions from NumPy or Scipy
+    directly instead of importing them from `numpy.dual`.
 matlib
     Make everything matrices.
 __version__
diff --git a/numpy/dual.py b/numpy/dual.py
index 92afec52d..eb7e61aac 100644
--- a/numpy/dual.py
+++ b/numpy/dual.py
@@ -1,15 +1,29 @@
 """
-Aliases for functions which may be accelerated by Scipy.
+.. deprecated:: 1.20
 
-Scipy_ can be built to use accelerated or otherwise improved libraries
+*This module is deprecated.  Instead of importing functions from*
+``numpy.dual``, *the functions should be imported directly from NumPy
+or SciPy*.
+
+Aliases for functions which may be accelerated by SciPy.
+
+SciPy_ can be built to use accelerated or otherwise improved libraries
 for FFTs, linear algebra, and special functions. This module allows
 developers to transparently support these accelerated functions when
-scipy is available but still support users who have only installed
+SciPy is available but still support users who have only installed
 NumPy.
 
-.. _Scipy : https://www.scipy.org
+.. _SciPy : https://www.scipy.org
 
 """
+import warnings
+
+
+warnings.warn('The module numpy.dual is deprecated.  Instead of using dual, '
+              'use the functions directly from numpy or scipy.',
+              category=DeprecationWarning,
+              stacklevel=2)
+
 # This module should be used for functions both in numpy and scipy if
 #  you want to use the numpy version if available but the scipy version
 #  otherwise.
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 2d1adc362..0b23dbebd 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -3256,7 +3256,6 @@ def kaiser(M, beta):
     >>> plt.show()
 
     """
-    from numpy.dual import i0
     if M == 1:
         return np.array([1.])
     n = arange(0, M)
diff --git a/numpy/matrixlib/defmatrix.py b/numpy/matrixlib/defmatrix.py
index a13ff23f4..a9ee74a5b 100644
--- a/numpy/matrixlib/defmatrix.py
+++ b/numpy/matrixlib/defmatrix.py
@@ -829,9 +829,9 @@ class matrix(N.ndarray):
         """
         M, N = self.shape
         if M == N:
-            from numpy.dual import inv as func
+            from numpy.linalg import inv as func
         else:
-            from numpy.dual import pinv as func
+            from numpy.linalg import pinv as func
         return asmatrix(func(self))
 
     @property
diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx
index e5bb02e24..111c2790c 100644
--- a/numpy/random/_generator.pyx
+++ b/numpy/random/_generator.pyx
@@ -3502,14 +3502,14 @@ cdef class Generator:
         # GH10839, ensure double to make tol meaningful
         cov = cov.astype(np.double)
         if method == 'svd':
-            from numpy.dual import svd
+            from numpy.linalg import svd
             (u, s, vh) = svd(cov)
         elif method == 'eigh':
-            from numpy.dual import eigh
+            from numpy.linalg import eigh
             # could call linalg.svd(hermitian=True), but that calculates a vh we don't need
             (s, u)  = eigh(cov)
         else:
-            from numpy.dual import cholesky
+            from numpy.linalg import cholesky
             l = cholesky(cov)
 
         # make sure check_valid is ignored whe method == 'cholesky'
diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx
index 54d656e3b..f2805871d 100644
--- a/numpy/random/mtrand.pyx
+++ b/numpy/random/mtrand.pyx
@@ -4049,7 +4049,7 @@ cdef class RandomState:
         [True, True] # random
 
         """
-        from numpy.dual import svd
+        from numpy.linalg import svd
 
         # Check preconditions on arguments
         mean = np.array(mean)
diff --git a/numpy/tests/test_public_api.py b/numpy/tests/test_public_api.py
index fb7ec5d83..7ce74bc43 100644
--- a/numpy/tests/test_public_api.py
+++ b/numpy/tests/test_public_api.py
@@ -154,7 +154,6 @@ PUBLIC_MODULES = ['numpy.' + s for s in [
     "doc.structured_arrays",
     "doc.subclassing",
     "doc.ufuncs",
-    "dual",
     "f2py",
     "fft",
     "lib",
@@ -258,6 +257,7 @@ PRIVATE_BUT_PRESENT_MODULES = ['numpy.' + s for s in [
     "distutils.numpy_distribution",
     "distutils.pathccompiler",
     "distutils.unixccompiler",
+    "dual",
     "f2py.auxfuncs",
     "f2py.capi_maps",
     "f2py.cb_rules",