Merge pull request #16174 from rossbar/doc/libpoly_docstring_note

DOC: Add transition note to all lib/poly functions

1 files changed, 66 insertions, 0 deletions

diff --git a/numpy/lib/polynomial.py b/numpy/lib/polynomial.py
index 5a0fa5431..420ec245b 100644
--- a/numpy/lib/polynomial.py
+++ b/numpy/lib/polynomial.py
@@ -46,6 +46,12 @@ def poly(seq_of_zeros):
     """
     Find the coefficients of a polynomial with the given sequence of roots.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Returns the coefficients of the polynomial whose leading coefficient
     is one for the given sequence of zeros (multiple roots must be included
     in the sequence as many times as their multiplicity; see Examples).
@@ -168,6 +174,12 @@ def roots(p):
     """
     Return the roots of a polynomial with coefficients given in p.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     The values in the rank-1 array `p` are coefficients of a polynomial.
     If the length of `p` is n+1 then the polynomial is described by::
 
@@ -258,6 +270,12 @@ def polyint(p, m=1, k=None):
     """
     Return an antiderivative (indefinite integral) of a polynomial.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     The returned order `m` antiderivative `P` of polynomial `p` satisfies
     :math:`\\frac{d^m}{dx^m}P(x) = p(x)` and is defined up to `m - 1`
     integration constants `k`. The constants determine the low-order
@@ -357,6 +375,12 @@ def polyder(p, m=1):
     """
     Return the derivative of the specified order of a polynomial.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Parameters
     ----------
     p : poly1d or sequence
@@ -431,6 +455,12 @@ def polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False):
     """
     Least squares polynomial fit.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Fit a polynomial ``p(x) = p[0] * x**deg + ... + p[deg]`` of degree `deg`
     to points `(x, y)`. Returns a vector of coefficients `p` that minimises
     the squared error in the order `deg`, `deg-1`, ... `0`.
@@ -667,6 +697,12 @@ def polyval(p, x):
     """
     Evaluate a polynomial at specific values.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     If `p` is of length N, this function returns the value:
 
         ``p[0]*x**(N-1) + p[1]*x**(N-2) + ... + p[N-2]*x + p[N-1]``
@@ -744,6 +780,12 @@ def polyadd(a1, a2):
     """
     Find the sum of two polynomials.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Returns the polynomial resulting from the sum of two input polynomials.
     Each input must be either a poly1d object or a 1D sequence of polynomial
     coefficients, from highest to lowest degree.
@@ -806,6 +848,12 @@ def polysub(a1, a2):
     """
     Difference (subtraction) of two polynomials.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Given two polynomials `a1` and `a2`, returns ``a1 - a2``.
     `a1` and `a2` can be either array_like sequences of the polynomials'
     coefficients (including coefficients equal to zero), or `poly1d` objects.
@@ -854,6 +902,12 @@ def polymul(a1, a2):
     """
     Find the product of two polynomials.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     Finds the polynomial resulting from the multiplication of the two input
     polynomials. Each input must be either a poly1d object or a 1D sequence
     of polynomial coefficients, from highest to lowest degree.
@@ -915,6 +969,12 @@ def polydiv(u, v):
     """
     Returns the quotient and remainder of polynomial division.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     The input arrays are the coefficients (including any coefficients
     equal to zero) of the "numerator" (dividend) and "denominator"
     (divisor) polynomials, respectively.
@@ -1009,6 +1069,12 @@ class poly1d:
     """
     A one-dimensional polynomial class.
 
+    .. note::
+       This forms part of the old polynomial API. Since version 1.4, the
+       new polynomial API defined in `numpy.polynomial` is preferred.
+       A summary of the differences can be found in the
+       :doc:`transition guide </reference/routines.polynomials>`.
+
     A convenience class, used to encapsulate "natural" operations on
     polynomials so that said operations may take on their customary
     form in code (see Examples).