DOC: Finish documenting new functions in the polynomial package.

The old functions could use a review, but that isn't pressing.

1 files changed, 140 insertions, 71 deletions

diff --git a/numpy/polynomial/legendre.py b/numpy/polynomial/legendre.py
index da2c2d846..bc9b5c2e6 100644
--- a/numpy/polynomial/legendre.py
+++ b/numpy/polynomial/legendre.py
@@ -684,6 +684,8 @@ def legder(c, m=1, scl=1, axis=0) :
     axis : int, optional
         Axis over which the derivative is taken. (Default: 0).
 
+        .. versionadded:: 1.7.0
+
     Returns
     -------
     der : ndarray
@@ -791,6 +793,8 @@ def legint(c, m=1, k=[], lbnd=0, scl=1, axis=0):
     axis : int, optional
         Axis over which the derivative is taken. (Default: 0).
 
+        .. versionadded:: 1.7.0
+
     Returns
     -------
     S : ndarray
@@ -987,8 +991,6 @@ def legval2d(x, y, c):
     If `c` is a 1-D array a one is implicitly appended to its shape to make
     it 2-D. The shape of the result will be c.shape[2:] + x.shape.
 
-    .. versionadded::1.7.0
-
     Parameters
     ----------
     x, y : array_like, compatible objects
@@ -1012,6 +1014,11 @@ def legval2d(x, y, c):
     --------
     legval, leggrid2d, legval3d, leggrid3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     try:
         x, y = np.array((x, y), copy=0)
@@ -1044,8 +1051,6 @@ def leggrid2d(x, y, c):
     its shape to make it 2-D. The shape of the result will be c.shape[2:] +
     x.shape + y.shape.
 
-    .. versionadded:: 1.7.0
-
     Parameters
     ----------
     x, y : array_like, compatible objects
@@ -1069,6 +1074,11 @@ def leggrid2d(x, y, c):
     --------
     legval, legval2d, legval3d, leggrid3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     c = legval(x, c)
     c = legval(y, c)
@@ -1093,8 +1103,6 @@ def legval3d(x, y, z, c):
     shape to make it 3-D. The shape of the result will be c.shape[3:] +
     x.shape.
 
-    .. versionadded::1.7.0
-
     Parameters
     ----------
     x, y, z : array_like, compatible object
@@ -1119,6 +1127,11 @@ def legval3d(x, y, z, c):
     --------
     legval, legval2d, leggrid2d, leggrid3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     try:
         x, y, z = np.array((x, y, z), copy=0)
@@ -1154,8 +1167,6 @@ def leggrid3d(x, y, z, c):
     its shape to make it 3-D. The shape of the result will be c.shape[3:] +
     x.shape + yshape + z.shape.
 
-    .. versionadded:: 1.7.0
-
     Parameters
     ----------
     x, y, z : array_like, compatible objects
@@ -1180,6 +1191,11 @@ def leggrid3d(x, y, z, c):
     --------
     legval, legval2d, leggrid2d, legval3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     c = legval(x, c)
     c = legval(y, c)
@@ -1188,28 +1204,38 @@ def leggrid3d(x, y, z, c):
 
 
 def legvander(x, deg) :
-    """Vandermonde matrix of given degree.
+    """Pseudo-Vandermonde matrix of given degree.
 
-    Returns the Vandermonde matrix of degree `deg` and sample points `x`.
-    This isn't a true Vandermonde matrix because `x` can be an arbitrary
-    ndarray and the Legendre polynomials aren't powers. If ``V`` is the
-    returned matrix and `x` is a 2d array, then the elements of ``V`` are
-    ``V[i,j,k] = P_k(x[i,j])``, where ``P_k`` is the Legendre polynomial
-    of degree ``k``.
+    Returns the pseudo-Vandermonde matrix of degree `deg` and sample points
+    `x`. The pseudo-Vandermonde matrix is defined by
+
+    .. math:: V[..., i] = L_i(x)
+
+    where `0 <= i <= deg`. The leading indices of `V` index the elements of
+    `x` and the last index is the degree of the Legendre polynomial.
+
+    If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the
+    array ``V = legvander(x, n)``, then ``np.dot(V, c)`` and
+    ``legval(x, c)`` are the same up to roundoff. This equivalence is
+    useful both for least squares fitting and for the evaluation of a large
+    number of Legendre series of the same degree and sample points.
 
     Parameters
     ----------
     x : array_like
-        Array of points. The values are converted to double or complex
-        doubles. If x is scalar it is converted to a 1D array.
-    deg : integer
+        Array of points. The dtype is converted to float64 or complex128
+        depending on whether any of the elements are complex. If `x` is
+        scalar it is converted to a 1-D array.
+    deg : int
         Degree of the resulting matrix.
 
     Returns
     -------
-    vander : Vandermonde matrix.
-        The shape of the returned matrix is ``x.shape + (deg+1,)``. The last
-        index is the degree.
+    vander: ndarray
+        The pseudo-Vandermonde matrix. The shape of the returned matrix is
+        ``x.shape + (deg + 1,)``, where The last index is the degree of the
+        corresponding Legendre polynomial.  The dtype will be the same as
+        the converted `x`.
 
     """
     ideg = int(deg)
@@ -1231,36 +1257,50 @@ def legvander(x, deg) :
 
 
 def legvander2d(x, y, deg) :
-    """Pseudo Vandermonde matrix of given degree.
-
-    Returns the pseudo Vandermonde matrix for 2D Legendre series in `x` and
-    `y`. The sample point coordinates must all have the same shape after
-    conversion to arrays and the dtype will be converted to either float64
-    or complex128 depending on whether any of `x` or 'y' are complex.  The
-    maximum degrees of the 2D Legendre series in each variable are specified in
-    the list `deg` in the form ``[xdeg, ydeg]``. The return array has the
-    shape ``x.shape + (order,)`` if `x`, and `y` are arrays or ``(1, order)
-    if they are scalars. Here order is the number of elements in a
-    flattened coefficient array of original shape ``(xdeg + 1, ydeg + 1)``.
-    The flattening is done so that the resulting pseudo Vandermonde array
-    can be easily used in least squares fits.
+    """Pseudo-Vandermonde matrix of given degrees.
+
+    Returns the pseudo-Vandermonde matrix of degrees `deg` and sample
+    points `(x, y)`. The pseudo-Vandermonde matrix is defined by
+
+    .. math:: V[..., deg[1]*i + j] = L_i(x) * L_j(y),
+
+    where `0 <= i <= deg[0]` and `0 <= j <= deg[1]`. The leading indices of
+    `V` index the points `(x, y)` and the last index encodes the degrees of
+    the Legendre polynomials.
+
+    If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V`
+    is the matrix ``V = legvander2d(x, y, [m, n])``, then
+    ``np.dot(V, c.flat)`` and ``legval2d(x, y, c)`` are the same up to
+    roundoff. This equivalence is useful both for least squares fitting and
+    for the evaluation of a large number of 2-D Legendre series of the same
+    degrees and sample points.
 
     Parameters
     ----------
-    x,y : array_like
-        Arrays of point coordinates, each of the same shape.
-    deg : list
+    x, y : array_like
+        Arrays of point coordinates, all of the same shape. The dtypes
+        will be converted to either float64 or complex128 depending on
+        whether any of the elements are complex. Scalars are converted to
+        1-D arrays.
+    deg : list of ints
         List of maximum degrees of the form [x_deg, y_deg].
 
     Returns
     -------
     vander2d : ndarray
-        The shape of the returned matrix is described above.
+        The shape of the returned matrix is ``x.shape + (order,)``, where
+        :math:`order = (deg[0]+1)*(deg([1]+1)`.  The dtype will be the same
+        as the converted `x` and `y`.
 
     See Also
     --------
     legvander, legvander3d. legval2d, legval3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     ideg = [int(d) for d in deg]
     is_valid = [id == d and id >= 0 for id, d in zip(ideg, deg)]
@@ -1276,37 +1316,51 @@ def legvander2d(x, y, deg) :
 
 
 def legvander3d(x, y, z, deg) :
-    """Pseudo Vandermonde matrix of given degree.
-
-    Returns the pseudo Vandermonde matrix for 3D Legendre series in `x`, `y`,
-    or `z`. The sample point coordinates must all have the same shape after
-    conversion to arrays and the dtype will be converted to either float64
-    or complex128 depending on whether any of `x`, `y`, or 'z' are complex.
-    The maximum degrees of the 3D Legendre series in each variable are
-    specified in the list `deg` in the form ``[xdeg, ydeg, zdeg]``. The
-    return array has the shape ``x.shape + (order,)`` if `x`, `y`, and `z`
-    are arrays or ``(1, order) if they are scalars. Here order is the
-    number of elements in a flattened coefficient array of original shape
-    ``(xdeg + 1, ydeg + 1, zdeg + 1)``.  The flattening is done so that the
-    resulting pseudo Vandermonde array can be easily used in least squares
-    fits.
+    """Pseudo-Vandermonde matrix of given degrees.
+
+    Returns the pseudo-Vandermonde matrix of degrees `deg` and sample
+    points `(x, y, z)`. If `l, m, n` are the given degrees in `x, y, z`,
+    then The pseudo-Vandermonde matrix is defined by
+
+    .. math:: V[..., (m+1)(n+1)i + (n+1)j + k] = L_i(x)*L_j(y)*L_k(z),
+
+    where `0 <= i <= l`, `0 <= j <= m`, and `0 <= j <= n`.  The leading
+    indices of `V` index the points `(x, y, z)` and the last index encodes
+    the degrees of the Legendre polynomials.
+
+    If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)`
+    and `V` is the matrix ``V = legvander3d(x, y, z, [l, m, n])``, then
+    ``np.dot(V, c.flat)`` and ``legval3d(x, y, z, c)`` are the same up to
+    roundoff. This equivalence is useful both for least squares fitting and
+    for the evaluation of a large number of 3-D Legendre series of the same
+    degrees and sample points.
 
     Parameters
     ----------
-    x,y,z : array_like
-        Arrays of point coordinates, each of the same shape.
-    deg : list
+    x, y, z : array_like
+        Arrays of point coordinates, all of the same shape. The dtypes will
+        be converted to either float64 or complex128 depending on whether
+        any of the elements are complex. Scalars are converted to 1-D
+        arrays.
+    deg : list of ints
         List of maximum degrees of the form [x_deg, y_deg, z_deg].
 
     Returns
     -------
     vander3d : ndarray
-        The shape of the returned matrix is described above.
+        The shape of the returned matrix is ``x.shape + (order,)``, where
+        :math:`order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1)`.  The dtype will
+        be the same as the converted `x`, `y`, and `z`.
 
     See Also
     --------
     legvander, legvander3d. legval2d, legval3d
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     ideg = [int(d) for d in deg]
     is_valid = [id == d and id >= 0 for id, d in zip(ideg, deg)]
@@ -1490,9 +1544,9 @@ def legcompanion(c):
     """Return the scaled companion matrix of c.
 
     The basis polynomials are scaled so that the companion matrix is
-    symmetric when `c` represents a single Legendre polynomial. This
-    provides better eigenvalue estimates than the unscaled case and in the
-    single polynomial case the eigenvalues are guaranteed to be real if
+    symmetric when `c` is an Legendre basis polynomial. This provides
+    better eigenvalue estimates than the unscaled case and for basis
+    polynomials the eigenvalues are guaranteed to be real if
     `numpy.linalg.eigvalsh` is used to obtain them.
 
     Parameters
@@ -1506,6 +1560,11 @@ def legcompanion(c):
     mat : ndarray
         Scaled companion matrix of dimensions (deg, deg).
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     # c is a trimmed copy
     [c] = pu.as_series([c])
@@ -1582,12 +1641,13 @@ def legroots(c):
 
 
 def leggauss(deg):
-    """Gauss Legendre quadrature.
+    """
+    Gauss-Legendre quadrature.
 
     Computes the sample points and weights for Gauss-Legendre quadrature.
     These sample points and weights will correctly integrate polynomials of
-    degree ``2*deg - 1`` or less over the interval ``[-1, 1]`` with the
-    weight function ``f(x) = 1``.
+    degree :math:`2*deg - 1` or less over the interval :math:`[-1, 1]` with
+    the weight function :math:`f(x) = 1`.
 
     Parameters
     ----------
@@ -1603,14 +1663,17 @@ def leggauss(deg):
 
     Notes
     -----
-    The results have only been tested up to degree 100. Higher degrees may
+
+    .. versionadded::1.7.0
+
+    The results have only been tested up to degree 100, higher degrees may
     be problematic. The weights are determined by using the fact that
 
-          w = c / (L'_n(x_k) * L_{n-1}(x_k))
+    .. math:: w_k = c / (L'_n(x_k) * L_{n-1}(x_k))
 
-    where ``c`` is a constant independent of ``k`` and ``x_k`` is the k'th
-    root of ``L_n``, and then scaling the results to get the right value
-    when integrating 1.
+    where :math:`c` is a constant independent of :math:`k` and :math:`x_k`
+    is the k'th root of :math:`L_n`, and then scaling the results to get
+    the right value when integrating 1.
 
     """
     ideg = int(deg)
@@ -1647,11 +1710,12 @@ def leggauss(deg):
 
 
 def legweight(x):
-    """Weight function of the Legendre polynomials.
+    """
+    Weight function of the Legendre polynomials.
 
-    The weight function for which the Legendre polynomials are orthogonal.
-    In this case the weight function is simply one. Note that the Legendre
-    polynomials are not normalized.
+    The weight function is :math:`1` and the interval of integration is
+    :math:`[-1, 1]`. The Legendre polynomials are orthogonal, but not
+    normalized, with respect to this weight function.
 
     Parameters
     ----------
@@ -1663,6 +1727,11 @@ def legweight(x):
     w : ndarray
        The weight function at `x`.
 
+    Notes
+    -----
+
+    .. versionadded::1.7.0
+
     """
     w = x*0.0 + 1.0
     return w