diff options
| author | Charles Harris <charlesr.harris@gmail.com> | 2011-12-28 18:43:17 -0700 |
|---|---|---|
| committer | Charles Harris <charlesr.harris@gmail.com> | 2012-01-09 11:09:36 -0700 |
| commit | dc7719f66452288d7c0192f93c07c8b18d870b75 (patch) | |
| tree | 54d6102e9dab5896fa402afa9e22807647173a59 | |
| parent | c462637f9b398600d25ca449aef8586d8d9d6210 (diff) | |
| download | numpy-dc7719f66452288d7c0192f93c07c8b18d870b75.tar.gz | |
DOC: Finish documenting new functions in the polynomial package.
The old functions could use a review, but that isn't pressing.
| -rw-r--r-- | numpy/polynomial/chebyshev.py | 241 | ||||
| -rw-r--r-- | numpy/polynomial/hermite.py | 213 | ||||
| -rw-r--r-- | numpy/polynomial/hermite_e.py | 215 | ||||
| -rw-r--r-- | numpy/polynomial/laguerre.py | 212 | ||||
| -rw-r--r-- | numpy/polynomial/legendre.py | 211 | ||||
| -rw-r--r-- | numpy/polynomial/polynomial.py | 173 |
6 files changed, 838 insertions, 427 deletions
diff --git a/numpy/polynomial/chebyshev.py b/numpy/polynomial/chebyshev.py index a81085921..d66ec5ef3 100644 --- a/numpy/polynomial/chebyshev.py +++ b/numpy/polynomial/chebyshev.py @@ -669,6 +669,7 @@ def chebmulx(c): Notes ----- + .. versionadded:: 1.5.0 """ @@ -883,6 +884,8 @@ def chebder(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 @@ -990,6 +993,8 @@ def chebint(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 @@ -1185,8 +1190,6 @@ def chebval2d(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 @@ -1210,6 +1213,11 @@ def chebval2d(x, y, c): -------- chebval, chebgrid2d, chebval3d, chebgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y = np.array((x, y), copy=0) @@ -1242,8 +1250,6 @@ def chebgrid2d(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 @@ -1267,6 +1273,11 @@ def chebgrid2d(x, y, c): -------- chebval, chebval2d, chebval3d, chebgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = chebval(x, c) c = chebval(y, c) @@ -1291,8 +1302,6 @@ def chebval3d(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 @@ -1317,6 +1326,11 @@ def chebval3d(x, y, z, c): -------- chebval, chebval2d, chebgrid2d, chebgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y, z = np.array((x, y, z), copy=0) @@ -1352,8 +1366,6 @@ def chebgrid3d(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 @@ -1378,6 +1390,11 @@ def chebgrid3d(x, y, z, c): -------- chebval, chebval2d, chebgrid2d, chebval3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = chebval(x, c) c = chebval(y, c) @@ -1386,28 +1403,38 @@ def chebgrid3d(x, y, z, c): def chebvander(x, deg) : - """Vandermonde matrix of given degree. + """Pseudo-Vandermonde matrix of given degree. + + Returns the pseudo-Vandermonde matrix of degree `deg` and sample points + `x`. The pseudo-Vandermonde matrix is defined by + + .. math:: V[..., i] = T_i(x), - 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 Chebyshev 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] = T_k(x[i,j])``, where ``T_k`` is the Chebyshev polynomial - of degree ``k``. + where `0 <= i <= deg`. The leading indices of `V` index the elements of + `x` and the last index is the degree of the Chebyshev polynomial. + + If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the + matrix ``V = chebvander(x, n)``, then ``np.dot(V, c)`` and + ``chebval(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 Chebyshev 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 Chebyshev polynomial. The dtype will be the same as + the converted `x`. """ ideg = int(deg) @@ -1429,36 +1456,50 @@ def chebvander(x, deg) : def chebvander2d(x, y, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 2D Chebyshev 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 Chebyshev 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] = T_i(x) * T_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 Chebyshev polynomials. + + If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V` + is the matrix ``V = chebvander2d(x, y, [m, n])``, then + ``np.dot(V, c.flat)`` and ``chebval2d(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 Chebyshev 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 -------- chebvander, chebvander3d. chebval2d, chebval3d + 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)] @@ -1474,37 +1515,51 @@ def chebvander2d(x, y, deg) : def chebvander3d(x, y, z, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 3D Chebyshev 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 Chebeshev 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] = T_i(x)*T_j(y)*T_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 Chebyshev polynomials. + + If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)` + and `V` is the matrix ``V = chebvander3d(x, y, z, [l, m, n])``, then + ``np.dot(V, c.flat)`` and ``chebval3d(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 Chebyshev 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 -------- chebvander, chebvander3d. chebval2d, chebval3d + 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)] @@ -1688,15 +1743,15 @@ def chebcompanion(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 Chebyshev polynomial. This - provides better eigenvalue estimates than the unscaled case and in the - single polynomial case the eigenvalues are guaranteed to be real if - np.eigvalsh is used to obtain them. + symmetric when `c` is aa Chebyshev 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 ---------- c : array_like - 1-d array of Legendre series coefficients ordered from low to high + 1-d array of Chebyshev series coefficients ordered from low to high degree. Returns @@ -1704,6 +1759,11 @@ def chebcompanion(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]) @@ -1781,12 +1841,13 @@ def chebroots(c): def chebgauss(deg): - """Gauss Chebyshev quadrature. + """ + Gauss-Chebyshev quadrature. Computes the sample points and weights for Gauss-Chebyshev 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/sqrt(1 - x**2)``. + degree :math:`2*deg - 1` or less over the interval :math:`[-1, 1]` with + the weight function :math:`f(x) = 1/\sqrt{1 - x^2}`. Parameters ---------- @@ -1802,16 +1863,16 @@ def chebgauss(deg): Notes ----- - The results have only been tested up to degree 100. Higher degrees may - be problematic. There are closed form solutions for the sample points - and weights. If ``n = deg``, then - ``x_i = cos(pi*(2*i - 1)/(2*n))`` - ``w_i = pi/n`` + .. versionadded:: 1.7.0 + + The results have only been tested up to degree 100, higher degrees may + be problematic. For Gauss-Chebyshev there are closed form solutions for + the sample points and weights. If n = `deg`, then + + .. math:: x_i = \cos(\pi (2 i - 1) / (2 n)) - 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. + .. math:: w_i = \pi / n """ ideg = int(deg) @@ -1825,11 +1886,12 @@ def chebgauss(deg): def chebweight(x): - """Weight function of the Chebyshev polynomials. + """ + The weight function of the Chebyshev polynomials. - The weight function for which the Chebyshev polynomials are orthogonal. - In this case the weight function is ``1/(1 - x**2)``. Note that the - Chebyshev polynomials are not normalized. + The weight function is :math:`1/\sqrt{1 - x^2}` and the interval of + integration is :math:`[-1, 1]`. The Chebyshev polynomials are orthogonal, but + not normalized, with respect to this weight function. Parameters ---------- @@ -1841,16 +1903,22 @@ def chebweight(x): w : ndarray The weight function at `x`. + Notes + ----- + + .. versionadded:: 1.7.0 + """ w = 1./(np.sqrt(1. + x) * np.sqrt(1. - x)) return w def chebpts1(npts): - """Chebyshev points of the first kind. + """ + Chebyshev points of the first kind. - Chebyshev points of the first kind are the set ``{cos(x_k)}``, - where ``x_k = pi*(k + .5)/npts`` for k in ``range(npts}``. + The Chebyshev points of the first kind are the points ``cos(x)``, + where ``x = [pi*(k + .5)/npts for k in range(npts)]``. Parameters ---------- @@ -1860,10 +1928,15 @@ def chebpts1(npts): Returns ------- pts : ndarray - The Chebyshev points of the second kind. + The Chebyshev points of the first kind. + + See Also + -------- + chebpts2 Notes ----- + .. versionadded:: 1.5.0 """ @@ -1878,10 +1951,11 @@ def chebpts1(npts): def chebpts2(npts): - """Chebyshev points of the second kind. + """ + Chebyshev points of the second kind. - Chebyshev points of the second kind are the set ``{cos(x_k)}``, - where ``x_k = pi*/(npts - 1)`` for k in ``range(npts}``. + The Chebyshev points of the second kind are the points ``cos(x)``, + where ``x = [pi*k/(npts - 1) for k in range(npts)]``. Parameters ---------- @@ -1895,6 +1969,7 @@ def chebpts2(npts): Notes ----- + .. versionadded:: 1.5.0 """ diff --git a/numpy/polynomial/hermite.py b/numpy/polynomial/hermite.py index ace91d2e2..8781ff1e2 100644 --- a/numpy/polynomial/hermite.py +++ b/numpy/polynomial/hermite.py @@ -654,6 +654,8 @@ def hermder(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 @@ -752,6 +754,8 @@ def hermint(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 @@ -950,8 +954,6 @@ def hermval2d(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 @@ -975,6 +977,11 @@ def hermval2d(x, y, c): -------- hermval, hermgrid2d, hermval3d, hermgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y = np.array((x, y), copy=0) @@ -1007,8 +1014,6 @@ def hermgrid2d(x, y, c): 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 @@ -1032,6 +1037,11 @@ def hermgrid2d(x, y, c): -------- hermval, hermval2d, hermval3d, hermgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = hermval(x, c) c = hermval(y, c) @@ -1056,8 +1066,6 @@ def hermval3d(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 @@ -1082,6 +1090,11 @@ def hermval3d(x, y, z, c): -------- hermval, hermval2d, hermgrid2d, hermgrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y, z = np.array((x, y, z), copy=0) @@ -1117,8 +1130,6 @@ def hermgrid3d(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 @@ -1143,6 +1154,11 @@ def hermgrid3d(x, y, z, c): -------- hermval, hermval2d, hermgrid2d, hermval3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = hermval(x, c) c = hermval(y, c) @@ -1151,28 +1167,38 @@ def hermgrid3d(x, y, z, c): def hermvander(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 Hermite 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 Hermite 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] = H_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 Hermite polynomial. + + If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the + array ``V = hermvander(x, n)``, then ``np.dot(V, c)`` and + ``hermval(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 Hermite 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 Hermite polynomial. The dtype will be the same as + the converted `x`. Examples -------- @@ -1202,36 +1228,50 @@ def hermvander(x, deg) : def hermvander2d(x, y, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 2D Hermite 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 Hermite 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] = H_i(x) * H_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 Hermite polynomials. + + If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V` + is the matrix ``V = hermvander2d(x, y, [m, n])``, then + ``np.dot(V, c.flat)`` and ``hermval2d(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 Hermite 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 -------- hermvander, hermvander3d. hermval2d, hermval3d + 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)] @@ -1247,37 +1287,51 @@ def hermvander2d(x, y, deg) : def hermvander3d(x, y, z, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 3D Hermite 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 Hermite 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] = H_i(x)*H_j(y)*H_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 Hermite polynomials. + + If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)` + and `V` is the matrix ``V = hermvander3d(x, y, z, [l, m, n])``, then + ``np.dot(V, c.flat)`` and ``hermval3d(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 Hermite 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 -------- hermvander, hermvander3d. hermval2d, hermval3d + 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)] @@ -1466,15 +1520,15 @@ def hermcompanion(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 Hermite 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 Hermite 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 ---------- c : array_like - 1-d array of Legendre series coefficients ordered from low to high + 1-d array of Hermite series coefficients ordered from low to high degree. Returns @@ -1482,6 +1536,11 @@ def hermcompanion(c): mat : ndarray Scaled companion matrix of dimensions (deg, deg). + Notes + ----- + + .. versionadded::1.7.0 + """ accprod = np.multiply.accumulate # c is a trimmed copy @@ -1563,12 +1622,13 @@ def hermroots(c): def hermgauss(deg): - """Gauss Hermite quadrature. + """ + Gauss-Hermite quadrature. Computes the sample points and weights for Gauss-Hermite quadrature. These sample points and weights will correctly integrate polynomials of - degree ``2*deg - 1`` or less over the interval ``[-inf, inf]`` with the - weight function ``f(x) = exp(-x**2)``. + degree :math:`2*deg - 1` or less over the interval :math:`[-\inf, \inf]` + with the weight function :math:`f(x) = \exp(-x^2)`. Parameters ---------- @@ -1584,14 +1644,17 @@ def hermgauss(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 / (H'_n(x_k) * H_{n-1}(x_k)) + .. math:: w_k = c / (H'_n(x_k) * H_{n-1}(x_k)) - where ``c`` is a constant independent of ``k`` and ``x_k`` is the k'th - root of ``H_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:`H_n`, and then scaling the results to get + the right value when integrating 1. """ ideg = int(deg) @@ -1628,11 +1691,12 @@ def hermgauss(deg): def hermweight(x): - """Weight function of the Hermite polynomials. + """ + Weight function of the Hermite polynomials. - The weight function for which the Hermite polynomials are orthogonal. - In this case the weight function is ``exp(-x**2)``. Note that the - Hermite polynomials are not normalized. + The weight function is :math:`\exp(-x^2)` and the interval of + integration is :math:`[-\inf, \inf]`. the Hermite polynomials are + orthogonal, but not normalized, with respect to this weight function. Parameters ---------- @@ -1644,6 +1708,11 @@ def hermweight(x): w : ndarray The weight function at `x`. + Notes + ----- + + .. versionadded::1.7.0 + """ w = np.exp(-x**2) return w diff --git a/numpy/polynomial/hermite_e.py b/numpy/polynomial/hermite_e.py index caf9d8d80..7a42d48a3 100644 --- a/numpy/polynomial/hermite_e.py +++ b/numpy/polynomial/hermite_e.py @@ -652,6 +652,8 @@ def hermeder(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 @@ -750,6 +752,8 @@ def hermeint(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 @@ -947,8 +951,6 @@ def hermeval2d(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 @@ -972,6 +974,11 @@ def hermeval2d(x, y, c): -------- hermeval, hermegrid2d, hermeval3d, hermegrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y = np.array((x, y), copy=0) @@ -1004,8 +1011,6 @@ def hermegrid2d(x, y, c): 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 @@ -1029,6 +1034,11 @@ def hermegrid2d(x, y, c): -------- hermeval, hermeval2d, hermeval3d, hermegrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = hermeval(x, c) c = hermeval(y, c) @@ -1053,8 +1063,6 @@ def hermeval3d(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 @@ -1079,6 +1087,11 @@ def hermeval3d(x, y, z, c): -------- hermeval, hermeval2d, hermegrid2d, hermegrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y, z = np.array((x, y, z), copy=0) @@ -1114,8 +1127,6 @@ def hermegrid3d(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 @@ -1140,6 +1151,11 @@ def hermegrid3d(x, y, z, c): -------- hermeval, hermeval2d, hermegrid2d, hermeval3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = hermeval(x, c) c = hermeval(y, c) @@ -1148,28 +1164,38 @@ def hermegrid3d(x, y, z, c): def hermevander(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 Hermite 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 Hermite 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] = He_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 HermiteE polynomial. + + If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the + array ``V = hermevander(x, n)``, then ``np.dot(V, c)`` and + ``hermeval(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 HermiteE 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 HermiteE polynomial. The dtype will be the same as + the converted `x`. Examples -------- @@ -1198,36 +1224,50 @@ def hermevander(x, deg) : def hermevander2d(x, y, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 2D Hermite_e 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 Hermite_e 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] = He_i(x) * He_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 HermiteE polynomials. + + If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V` + is the matrix ``V = hermevander2d(x, y, [m, n])``, then + ``np.dot(V, c.flat)`` and ``hermeval2d(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 HermiteE 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 -------- hermevander, hermevander3d. hermeval2d, hermeval3d + 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)] @@ -1243,37 +1283,51 @@ def hermevander2d(x, y, deg) : def hermevander3d(x, y, z, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 3D Hermite_e 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 Hermite_e 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 Hehe pseudo-Vandermonde matrix is defined by + + .. math:: V[..., (m+1)(n+1)i + (n+1)j + k] = He_i(x)*He_j(y)*He_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 HermiteE polynomials. + + If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)` + and `V` is the matrix ``V = hermevander3d(x, y, z, [l, m, n])``, then + ``np.dot(V, c.flat)`` and ``hermeval3d(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 HermiteE 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 -------- hermevander, hermevander3d. hermeval2d, hermeval3d + 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)] @@ -1459,18 +1513,19 @@ def hermefit(x, y, deg, rcond=None, full=False, w=None): def hermecompanion(c): - """Return the scaled companion matrix of 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 HermiteE 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 HermiteE 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 ---------- c : array_like - 1-d array of Legendre series coefficients ordered from low to high + 1-d array of HermiteE series coefficients ordered from low to high degree. Returns @@ -1478,6 +1533,11 @@ def hermecompanion(c): mat : ndarray Scaled companion matrix of dimensions (deg, deg). + Notes + ----- + + .. versionadded::1.7.0 + """ accprod = np.multiply.accumulate # c is a trimmed copy @@ -1559,12 +1619,13 @@ def hermeroots(c): def hermegauss(deg): - """Gauss Hermite_e quadrature. + """ + Gauss-HermiteE quadrature. - Computes the sample points and weights for Gauss-Hermite_e quadrature. + Computes the sample points and weights for Gauss-HermiteE quadrature. These sample points and weights will correctly integrate polynomials of - degree ``2*deg - 1`` or less over the interval ``[-inf, inf]`` with the - weight function ``f(x) = exp(-.5*x**2)``. + degree :math:`2*deg - 1` or less over the interval :math:`[-\inf, \inf]` + with the weight function :math:`f(x) = \exp(-x^2/2)`. Parameters ---------- @@ -1580,14 +1641,17 @@ def hermegauss(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 / (He'_n(x_k) * He_{n-1}(x_k)) + .. math:: w_k = c / (He'_n(x_k) * He_{n-1}(x_k)) - where ``c`` is a constant independent of ``k`` and ``x_k`` is the k'th - root of ``He_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:`He_n`, and then scaling the results to get + the right value when integrating 1. """ ideg = int(deg) @@ -1626,9 +1690,9 @@ def hermegauss(deg): def hermeweight(x): """Weight function of the Hermite_e polynomials. - The weight function for which the Hermite_e polynomials are orthogonal. - In this case the weight function is ``exp(-.5*x**2)``. Note that the - Hermite_e polynomials are not normalized. + The weight function is :math:`\exp(-x^2/2)` and the interval of + integration is :math:`[-\inf, \inf]`. the HermiteE polynomials are + orthogonal, but not normalized, with respect to this weight function. Parameters ---------- @@ -1640,6 +1704,11 @@ def hermeweight(x): w : ndarray The weight function at `x`. + Notes + ----- + + .. versionadded::1.7.0 + """ w = np.exp(-.5*x**2) return w diff --git a/numpy/polynomial/laguerre.py b/numpy/polynomial/laguerre.py index 489ecb8a2..710b480d9 100644 --- a/numpy/polynomial/laguerre.py +++ b/numpy/polynomial/laguerre.py @@ -650,6 +650,8 @@ def lagder(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 @@ -751,6 +753,8 @@ def lagint(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 @@ -950,8 +954,6 @@ def lagval2d(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 @@ -975,6 +977,11 @@ def lagval2d(x, y, c): -------- lagval, laggrid2d, lagval3d, laggrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y = np.array((x, y), copy=0) @@ -1007,8 +1014,6 @@ def laggrid2d(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 @@ -1032,6 +1037,11 @@ def laggrid2d(x, y, c): -------- lagval, lagval2d, lagval3d, laggrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = lagval(x, c) c = lagval(y, c) @@ -1056,8 +1066,6 @@ def lagval3d(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 @@ -1082,6 +1090,11 @@ def lagval3d(x, y, z, c): -------- lagval, lagval2d, laggrid2d, laggrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y, z = np.array((x, y, z), copy=0) @@ -1117,8 +1130,6 @@ def laggrid3d(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 @@ -1143,6 +1154,11 @@ def laggrid3d(x, y, z, c): -------- lagval, lagval2d, laggrid2d, lagval3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = lagval(x, c) c = lagval(y, c) @@ -1151,28 +1167,38 @@ def laggrid3d(x, y, z, c): def lagvander(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 Laguerre 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 Laguerre 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 Laguerre polynomial. + + If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the + array ``V = lagvander(x, n)``, then ``np.dot(V, c)`` and + ``lagval(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 Laguerre 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 Laguerre polynomial. The dtype will be the same as + the converted `x`. Examples -------- @@ -1201,36 +1227,50 @@ def lagvander(x, deg) : def lagvander2d(x, y, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 2D Laguerre 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 Laguerre 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 Laguerre polynomials. + + If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V` + is the matrix ``V = lagvander2d(x, y, [m, n])``, then + ``np.dot(V, c.flat)`` and ``lagval2d(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 Laguerre 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 -------- lagvander, lagvander3d. lagval2d, lagval3d + 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)] @@ -1246,37 +1286,51 @@ def lagvander2d(x, y, deg) : def lagvander3d(x, y, z, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 3D Laguerre 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 Laguerre 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 Laguerre polynomials. + + If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)` + and `V` is the matrix ``V = lagvander3d(x, y, z, [l, m, n])``, then + ``np.dot(V, c.flat)`` and ``lagval3d(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 Laguerre 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 -------- lagvander, lagvander3d. lagval2d, lagval3d + 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)] @@ -1462,11 +1516,12 @@ def lagfit(x, y, deg, rcond=None, full=False, w=None): def lagcompanion(c): - """Return the companion matrix of c. + """ + Return the companion matrix of c. - The unscaled companion matrix of the Laguerre polynomials is already - symmetric when `c` represents a single Laguerre polynomial, so no - further scaling is needed. + The usual companion matrix of the Laguerre polynomials is already + symmetric when `c` is a basis Laguerre polynomial, so no scaling is + applied. Parameters ---------- @@ -1479,6 +1534,11 @@ def lagcompanion(c): mat : ndarray Companion matrix of dimensions (deg, deg). + Notes + ----- + + .. versionadded::1.7.0 + """ accprod = np.multiply.accumulate # c is a trimmed copy @@ -1560,12 +1620,13 @@ def lagroots(c): def laggauss(deg): - """Gauss Laguerre quadrature. + """ + Gauss-Laguerre quadrature. Computes the sample points and weights for Gauss-Laguerre quadrature. These sample points and weights will correctly integrate polynomials of - degree ``2*deg - 1`` or less over the interval ``[0, inf]`` with the - weight function ``f(x) = exp(-x)``. + degree :math:`2*deg - 1` or less over the interval :math:`[0, \inf]` with the + weight function :math:`f(x) = \exp(-x)`. Parameters ---------- @@ -1581,14 +1642,17 @@ def laggauss(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) @@ -1623,10 +1687,9 @@ def laggauss(deg): def lagweight(x): """Weight function of the Laguerre polynomials. - The weight function for which the Laguerre polynomials are orthogonal. - In this case the weight function is ``exp(-x)``. Note that the Laguerre - polynomials are not normalized, indeed, may be much greater than the - normalized versions. + The weight function is :math:`exp(-x)` and the interval of integration + is :math:`[0, \inf]`. The Laguerre polynomials are orthogonal, but not + normalized, with respect to this weight function. Parameters ---------- @@ -1638,6 +1701,11 @@ def lagweight(x): w : ndarray The weight function at `x`. + Notes + ----- + + .. versionadded::1.7.0 + """ w = np.exp(-x) return w 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 diff --git a/numpy/polynomial/polynomial.py b/numpy/polynomial/polynomial.py index 99a555e71..b7c0ae774 100644 --- a/numpy/polynomial/polynomial.py +++ b/numpy/polynomial/polynomial.py @@ -302,6 +302,7 @@ def polymulx(c): Notes ----- + .. versionadded:: 1.5.0 """ @@ -490,6 +491,8 @@ def polyder(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 @@ -584,6 +587,8 @@ def polyint(c, m=1, k=[], lbnd=0, scl=1, axis=0): axis : int, optional Axis over which the integral is taken. (Default: 0). + .. versionadded:: 1.7.0 + Returns ------- S : ndarray @@ -779,8 +784,6 @@ def polyval2d(x, y, c): 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 @@ -804,6 +807,11 @@ def polyval2d(x, y, c): -------- polyval, polygrid2d, polyval3d, polygrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y = np.array((x, y), copy=0) @@ -836,8 +844,6 @@ def polygrid2d(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 @@ -861,6 +867,11 @@ def polygrid2d(x, y, c): -------- polyval, polyval2d, polyval3d, polygrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = polyval(x, c) c = polyval(y, c) @@ -885,8 +896,6 @@ def polyval3d(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 @@ -911,6 +920,11 @@ def polyval3d(x, y, z, c): -------- polyval, polyval2d, polygrid2d, polygrid3d + Notes + ----- + + .. versionadded::1.7.0 + """ try: x, y, z = np.array((x, y, z), copy=0) @@ -946,8 +960,6 @@ def polygrid3d(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 @@ -972,6 +984,11 @@ def polygrid3d(x, y, z, c): -------- polyval, polyval2d, polygrid2d, polyval3d + Notes + ----- + + .. versionadded::1.7.0 + """ c = polyval(x, c) c = polyval(y, c) @@ -982,24 +999,35 @@ def polygrid3d(x, y, z, c): def polyvander(x, deg) : """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. If ``V`` is the returned matrix and `x` is a 2d array, then - the elements of ``V`` are ``V[i,j,k] = x[i,j]**k`` + Returns the Vandermonde matrix of degree `deg` and sample points + `x`. The Vandermonde matrix is defined by + + .. math:: V[..., i] = x^i, + + where `0 <= i <= deg`. The leading indices of `V` index the elements of + `x` and the last index is the power of `x`. + + If `c` is a 1-D array of coefficients of length `n + 1` and `V` is the + matrix ``V = polyvander(x, n)``, then ``np.dot(V, c)`` and + ``polyval(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 polynomials 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 Vandermonde matrix. The shape of the returned matrix is + ``x.shape + (deg + 1,)``, where the last index is the power of `x`. + The dtype will be the same as the converted `x`. See Also -------- @@ -1023,31 +1051,40 @@ def polyvander(x, deg) : def polyvander2d(x, y, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 2D polynomials 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 polynomials 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] = x^i * y^j, + + 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 powers of + `x` and `y`. + + If `c` is a 2-D array of coefficients of shape `(m + 1, n + 1)` and `V` + is the matrix ``V = polyvander2d(x, y, [m, n])``, then + ``np.dot(V, c.flat)`` and ``polyval2d(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 polynomials 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 -------- @@ -1070,37 +1107,51 @@ def polyvander2d(x, y, deg) : def polyvander3d(x, y, z, deg) : - """Pseudo Vandermonde matrix of given degree. - - Returns the pseudo Vandermonde matrix for 3D polynomials 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 polynomials 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] = x^i * y^j * z^k, + + 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 powers of `x`, `y`, and `z`. + + If `c` is a 3-D array of coefficients of shape `(l + 1, m + 1, n + 1)` + and `V` is the matrix ``V = polyvander3d(x, y, z, [l, m, n])``, then + ``np.dot(V, c.flat)`` and ``polyval3d(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 polynomials 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 -------- polyvander, polyvander3d. polyval2d, polyval3d + 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)] @@ -1307,18 +1358,28 @@ def polyfit(x, y, deg, rcond=None, full=False, w=None): def polycompanion(c): - """Return the companion matrix of c. + """ + Return the companion matrix of c. + The companion matrix for power series cannot be made symmetric by + scaling the basis, so this function differs from those for the + orthogonal polynomials. Parameters ---------- c : array_like - 1-d array of series coefficients ordered from low to high degree. + 1-d array of polynomial coefficients ordered from low to high + degree. Returns ------- mat : ndarray - Scaled companion matrix of dimensions (deg, deg). + Companion matrix of dimensions (deg, deg). + + Notes + ----- + + .. versionadded:: 1.7.0 """ # c is a trimmed copy |