PyNeb  1.1.2 PyNeb Reference Manua
pyneb.utils.chebyshev Namespace Reference

## Functions

def poly2cheb (pol)

def cheb2poly (cs)

def chebline (off, scl)

def chebfromroots (roots)

def chebsub (c1, c2)

def chebmulx (cs)

def chebmul (c1, c2)

def chebdiv (c1, c2)

def chebpow

def chebder

def chebint

def chebval (x, cs)

def chebvander (x, deg)

def chebfit

def chebroots (cs)

def chebpts1 (npts)

def chebpts2 (npts)

## Variables

list __all__

chebtrim = trimcoef

tuple chebdomain = np.array([-1,1])

tuple chebzero = np.array([0])

tuple chebone = np.array([1])

tuple chebx = np.array([0,1])

## Detailed Description

Objects for dealing with Chebyshev series.

This module provides a number of objects (mostly functions) useful for
dealing with Chebyshev series, including a Chebyshev class that
encapsulates the usual arithmetic operations.  (General information
on how this module represents and works with such polynomials is in the
docstring for its "parent" sub-package, numpy.polynomial).

Constants
---------
- chebdomain -- Chebyshev series default domain, [-1,1].
- chebzero -- (Coefficients of the) Chebyshev series that evaluates
identically to 0.
- chebone -- (Coefficients of the) Chebyshev series that evaluates
identically to 1.
- chebx -- (Coefficients of the) Chebyshev series for the identity map,
f(x) = x.

Arithmetic
----------
- chebadd -- add two Chebyshev series.
- chebsub -- subtract one Chebyshev series from another.
- chebmul -- multiply two Chebyshev series.
- chebdiv -- divide one Chebyshev series by another.
- chebpow -- raise a Chebyshev series to an positive integer power
- chebval -- evaluate a Chebyshev series at given points.

Calculus
--------
- chebder -- differentiate a Chebyshev series.
- chebint -- integrate a Chebyshev series.

Misc Functions
--------------
- chebfromroots -- create a Chebyshev series with specified roots.
- chebroots -- find the roots of a Chebyshev series.
- chebvander -- Vandermonde-like matrix for Chebyshev polynomials.
- chebfit -- least-squares fit returning a Chebyshev series.
- chebpts1 -- Chebyshev points of the first kind.
- chebpts2 -- Chebyshev points of the second kind.
- chebtrim -- trim leading coefficients from a Chebyshev series.
- chebline -- Chebyshev series representing given straight line.
- cheb2poly -- convert a Chebyshev series to a polynomial.
- poly2cheb -- convert a polynomial to a Chebyshev series.

Classes
-------
- Chebyshev -- A Chebyshev series class.

--------
numpy.polynomial

Notes
-----
The implementations of multiplication, division, integration, and
differentiation use the algebraic identities [1]_:

.. math ::
T_n(x) = \\frac{z^n + z^{-n}}{2} \\\\
z\\frac{dx}{dz} = \\frac{z - z^{-1}}{2}.

where

.. math :: x = \\frac{z + z^{-1}}{2}.

These identities allow a Chebyshev series to be expressed as a finite,
symmetric Laurent series.  In this module, this sort of Laurent series
is referred to as a "z-series."

References
----------
.. [1] A. T. Benjamin, et al., "Combinatorial Trigonometry with Chebyshev
Polynomials," *Journal of Statistical Planning and Inference 14*, 2008
(preprint: http://www.math.hmc.edu/~benjamin/papers/CombTrig.pdf, pg. 4)

## Function Documentation

 def pyneb.utils.chebyshev.cheb2poly ( cs )
Convert a Chebyshev series to a polynomial.

Convert an array representing the coefficients of a Chebyshev series,
ordered from lowest degree to highest, to an array of the coefficients
of the equivalent polynomial (relative to the "standard" basis) ordered
from lowest to highest degree.

Parameters
----------
cs : array_like
1-d array containing the Chebyshev series coefficients, ordered
from lowest order term to highest.

Returns
-------
pol : ndarray
1-d array containing the coefficients of the equivalent polynomial
(relative to the "standard" basis) ordered from lowest order term
to highest.

--------
poly2cheb

Notes
-----
The easy way to do conversions between polynomial basis sets
is to use the convert method of a class instance.

Examples
--------
>>> from numpy import polynomial as P
>>> c = P.Chebyshev(range(4))
>>> c
Chebyshev([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> p = c.convert(kind=P.Polynomial)
>>> p
Polynomial([ -2.,  -8.,   4.,  12.], [-1.,  1.])
>>> P.cheb2poly(range(4))
array([ -2.,  -8.,   4.,  12.])
 def pyneb.utils.chebyshev.chebadd ( c1, c2 )
Add one Chebyshev series to another.

Returns the sum of two Chebyshev series c1 + c2.  The arguments
are sequences of coefficients ordered from lowest order term to
highest, i.e., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters
----------
c1, c2 : array_like
1-d arrays of Chebyshev series coefficients ordered from low to
high.

Returns
-------
out : ndarray
Array representing the Chebyshev series of their sum.

--------
chebsub, chebmul, chebdiv, chebpow

Notes
-----
Unlike multiplication, division, etc., the sum of two Chebyshev series
is a Chebyshev series (without having to "reproject" the result onto
the basis set) so addition, just like that of "standard" polynomials,
is simply "component-wise."

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
array([ 4.,  4.,  4.])
 def pyneb.utils.chebyshev.chebder ( cs, m = 1, scl = 1 )
Differentiate a Chebyshev series.

Returns the series cs differentiated m times.  At each iteration the
result is multiplied by scl (the scaling factor is for use in a linear
change of variable).  The argument cs is the sequence of coefficients
from lowest order "term" to highest, e.g., [1,2,3] represents the series
T_0 + 2*T_1 + 3*T_2.

Parameters
----------
cs: array_like
1-d array of Chebyshev series coefficients ordered from low to high.
m : int, optional
Number of derivatives taken, must be non-negative. (Default: 1)
scl : scalar, optional
Each differentiation is multiplied by scl.  The end result is
multiplication by scl**m.  This is for use in a linear change of
variable. (Default: 1)

Returns
-------
der : ndarray
Chebyshev series of the derivative.

--------
chebint

Notes
-----
In general, the result of differentiating a C-series needs to be
"re-projected" onto the C-series basis set. Thus, typically, the
result of this function is "un-intuitive," albeit correct; see Examples
section below.

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> cs = (1,2,3,4)
>>> C.chebder(cs)
array([ 14.,  12.,  24.])
>>> C.chebder(cs,3)
array([ 96.])
>>> C.chebder(cs,scl=-1)
array([-14., -12., -24.])
>>> C.chebder(cs,2,-1)
array([ 12.,  96.])
 def pyneb.utils.chebyshev.chebdiv ( c1, c2 )
Divide one Chebyshev series by another.

Returns the quotient-with-remainder of two Chebyshev series
c1 / c2.  The arguments are sequences of coefficients from lowest
order "term" to highest, e.g., [1,2,3] represents the series
T_0 + 2*T_1 + 3*T_2.

Parameters
----------
c1, c2 : array_like
1-d arrays of Chebyshev series coefficients ordered from low to
high.

Returns
-------
[quo, rem] : ndarrays
Of Chebyshev series coefficients representing the quotient and
remainder.

--------

Notes
-----
In general, the (polynomial) division of one C-series by another
results in quotient and remainder terms that are not in the Chebyshev
polynomial basis set.  Thus, to express these results as C-series, it
is typically necessary to "re-project" the results onto said basis
set, which typically produces "un-intuitive" (but correct) results;
see Examples section below.

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebdiv(c1,c2) # quotient "intuitive," remainder not
(array([ 3.]), array([-8., -4.]))
>>> c2 = (0,1,2,3)
>>> C.chebdiv(c2,c1) # neither "intuitive"
(array([ 0.,  2.]), array([-2., -4.]))
 def pyneb.utils.chebyshev.chebfit ( x, y, deg, rcond = None, full = False, w = None )
Least squares fit of Chebyshev series to data.

Fit a Chebyshev series p(x) = p[0] * T_{0}(x) + ... + p[deg] *
T_{deg}(x) of degree deg to points (x, y). Returns a vector of
coefficients p that minimises the squared error.

Parameters
----------
x : array_like, shape (M,)
x-coordinates of the M sample points (x[i], y[i]).
y : array_like, shape (M,) or (M, K)
y-coordinates of the sample points. Several data sets of sample
points sharing the same x-coordinates can be fitted at once by
passing in a 2D-array that contains one dataset per column.
deg : int
Degree of the fitting polynomial
rcond : float, optional
Relative condition number of the fit. Singular values smaller than
this relative to the largest singular value will be ignored. The
default value is len(x)*eps, where eps is the relative precision of
the float type, about 2e-16 in most cases.
full : bool, optional
Switch determining nature of return value. When it is False (the
default) just the coefficients are returned, when True diagnostic
information from the singular value decomposition is also returned.
w : array_like, shape (M,), optional
Weights. If not None, the contribution of each point
(x[i],y[i]) to the fit is weighted by w[i]. Ideally the
weights are chosen so that the errors of the products w[i]*y[i]
all have the same variance.  The default value is None.

Returns
-------
coef : ndarray, shape (M,) or (M, K)
Chebyshev coefficients ordered from low to high. If y was 2-D,
the coefficients for the data in column k  of y are in column
k.

[residuals, rank, singular_values, rcond] : present when full = True
Residuals of the least-squares fit, the effective rank of the
scaled Vandermonde matrix and its singular values, and the
specified value of rcond. For more details, see linalg.lstsq.

Warns
-----
RankWarning
The rank of the coefficient matrix in the least-squares fit is
deficient. The warning is only raised if full = False.  The
warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

--------
chebval : Evaluates a Chebyshev series.
chebvander : Vandermonde matrix of Chebyshev series.
polyfit : least squares fit using polynomials.
linalg.lstsq : Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline : Computes spline fits.

Notes
-----
The solution are the coefficients c[i] of the Chebyshev series
T(x) that minimizes the squared error

E = \\sum_j |y_j - T(x_j)|^2.

This problem is solved by setting up as the overdetermined matrix
equation

V(x)*c = y,

where V is the Vandermonde matrix of x, the elements of c are
the coefficients to be solved for, and the elements of y are the
observed values.  This equation is then solved using the singular value
decomposition of V.

If some of the singular values of V are so small that they are
neglected, then a RankWarning will be issued. This means that the
coeficient values may be poorly determined. Using a lower order fit
will usually get rid of the warning.  The rcond parameter can also be
set to a value smaller than its default, but the resulting fit may be
spurious and have large contributions from roundoff error.

Fits using Chebyshev series are usually better conditioned than fits
using power series, but much can depend on the distribution of the
sample points and the smoothness of the data. If the quality of the fit
is inadequate splines may be a good alternative.

References
----------
.. [1] Wikipedia, "Curve fitting",
http://en.wikipedia.org/wiki/Curve_fitting

Examples
--------
 def pyneb.utils.chebyshev.chebfromroots ( roots )
Generate a Chebyshev series with the given roots.

Return the array of coefficients for the C-series whose roots (a.k.a.
"zeros") are given by *roots*.  The returned array of coefficients is
ordered from lowest order "term" to highest, and zeros of multiplicity
greater than one must be included in *roots* a number of times equal
to their multiplicity (e.g., if 2 is a root of multiplicity three,
then [2,2,2] must be in *roots*).

Parameters
----------
roots : array_like
Sequence containing the roots.

Returns
-------
out : ndarray
1-d array of the C-series' coefficients, ordered from low to
high.  If all roots are real, out.dtype is a float type;
otherwise, out.dtype is a complex type, even if all the
coefficients in the result are real (see Examples below).

--------
polyfromroots

Notes
-----
What is returned are the :math:c_i such that:

.. math::

\\sum_{i=0}^{n} c_i*T_i(x) = \\prod_{i=0}^{n} (x - roots[i])

where n == len(roots) and :math:T_i(x) is the i-th Chebyshev
(basis) polynomial over the domain [-1,1].  Note that, unlike
polyfromroots, due to the nature of the C-series basis set, the
above identity *does not* imply :math:c_n = 1 identically (see
Examples).

Examples
--------
>>> import numpy.polynomial.chebyshev as C
>>> C.chebfromroots((-1,0,1)) # x^3 - x relative to the standard basis
array([ 0.  , -0.25,  0.  ,  0.25])
>>> j = complex(0,1)
>>> C.chebfromroots((-j,j)) # x^2 + 1 relative to the standard basis
array([ 1.5+0.j,  0.0+0.j,  0.5+0.j])
 def pyneb.utils.chebyshev.chebint ( cs, m = 1, k = [], lbnd = 0, scl = 1 )
Integrate a Chebyshev series.

Returns, as a C-series, the input C-series cs, integrated m times
from lbnd to x.  At each iteration the resulting series is
**multiplied** by scl and an integration constant, k, is added.
The scaling factor is for use in a linear change of variable.  ("Buyer
beware": note that, depending on what one is doing, one may want scl
to be the reciprocal of what one might expect; for more information,
see the Notes section below.)  The argument cs is a sequence of
coefficients, from lowest order C-series "term" to highest, e.g.,
[1,2,3] represents the series :math:T_0(x) + 2T_1(x) + 3T_2(x).

Parameters
----------
cs : array_like
1-d array of C-series coefficients, ordered from low to high.
m : int, optional
Order of integration, must be positive. (Default: 1)
k : {[], list, scalar}, optional
Integration constant(s).  The value of the first integral at zero
is the first value in the list, the value of the second integral
at zero is the second value, etc.  If k == [] (the default),
all constants are set to zero.  If m == 1, a single scalar can
be given instead of a list.
lbnd : scalar, optional
The lower bound of the integral. (Default: 0)
scl : scalar, optional
Following each integration the result is *multiplied* by scl
before the integration constant is added. (Default: 1)

Returns
-------
S : ndarray
C-series coefficients of the integral.

Raises
------
ValueError
If m < 1, len(k) > m, np.isscalar(lbnd) == False, or
np.isscalar(scl) == False.

--------
chebder

Notes
-----
Note that the result of each integration is *multiplied* by scl.
Why is this important to note?  Say one is making a linear change of
variable :math:u = ax + b in an integral relative to x.  Then
:math:dx = du/a, so one will need to set scl equal to :math:1/a
- perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs
to be "re-projected" onto the C-series basis set.  Thus, typically,
the result of this function is "un-intuitive," albeit correct; see
Examples section below.

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> cs = (1,2,3)
>>> C.chebint(cs)
array([ 0.5, -0.5,  0.5,  0.5])
>>> C.chebint(cs,3)
array([ 0.03125   , -0.1875    ,  0.04166667, -0.05208333,  0.01041667,
0.00625   ])
>>> C.chebint(cs, k=3)
array([ 3.5, -0.5,  0.5,  0.5])
>>> C.chebint(cs,lbnd=-2)
array([ 8.5, -0.5,  0.5,  0.5])
>>> C.chebint(cs,scl=-2)
array([-1.,  1., -1., -1.])
 def pyneb.utils.chebyshev.chebline ( off, scl )
Chebyshev series whose graph is a straight line.

Parameters
----------
off, scl : scalars
The specified line is given by off + scl*x.

Returns
-------
y : ndarray
This module's representation of the Chebyshev series for
off + scl*x.

--------
polyline

Examples
--------
>>> import numpy.polynomial.chebyshev as C
>>> C.chebline(3,2)
array([3, 2])
>>> C.chebval(-3, C.chebline(3,2)) # should be -3
-3.0
 def pyneb.utils.chebyshev.chebmul ( c1, c2 )
Multiply one Chebyshev series by another.

Returns the product of two Chebyshev series c1 * c2.  The arguments
are sequences of coefficients, from lowest order "term" to highest,
e.g., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters
----------
c1, c2 : array_like
1-d arrays of Chebyshev series coefficients ordered from low to
high.

Returns
-------
out : ndarray
Of Chebyshev series coefficients representing their product.

--------

Notes
-----
In general, the (polynomial) product of two C-series results in terms
that are not in the Chebyshev polynomial basis set.  Thus, to express
the product as a C-series, it is typically necessary to "re-project"
the product onto said basis set, which typically produces
"un-intuitive" (but correct) results; see Examples section below.

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebmul(c1,c2) # multiplication requires "reprojection"
array([  6.5,  12. ,  12. ,   4. ,   1.5])
 def pyneb.utils.chebyshev.chebmulx ( cs )
Multiply a Chebyshev series by x.

Multiply the polynomial cs by x, where x is the independent
variable.

Parameters
----------
cs : array_like
1-d array of Chebyshev series coefficients ordered from low to
high.

Returns
-------
out : ndarray
Array representing the result of the multiplication.

Notes
-----
.. versionadded:: 1.5.0
 def pyneb.utils.chebyshev.chebpow ( cs, pow, maxpower = 16 )
Raise a Chebyshev series to a power.

Returns the Chebyshev series cs raised to the power pow. The
arguement cs is a sequence of coefficients ordered from low to high.
i.e., [1,2,3] is the series  T_0 + 2*T_1 + 3*T_2.

Parameters
----------
cs : array_like
1d array of chebyshev series coefficients ordered from low to
high.
pow : integer
Power to which the series will be raised
maxpower : integer, optional
Maximum power allowed. This is mainly to limit growth of the series
to umanageable size. Default is 16

Returns
-------
coef : ndarray
Chebyshev series of power.

--------

Examples
--------
 def pyneb.utils.chebyshev.chebpts1 ( npts )
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}.

Parameters
----------
npts : int
Number of sample points desired.

Returns
-------
pts : ndarray
The Chebyshev points of the second kind.

Notes
-----
.. versionadded:: 1.5.0
 def pyneb.utils.chebyshev.chebpts2 ( npts )
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}.

Parameters
----------
npts : int
Number of sample points desired.

Returns
-------
pts : ndarray
The Chebyshev points of the second kind.

Notes
-----
.. versionadded:: 1.5.0
 def pyneb.utils.chebyshev.chebroots ( cs )
Compute the roots of a Chebyshev series.

Return the roots (a.k.a "zeros") of the C-series represented by cs,
which is the sequence of the C-series' coefficients from lowest order
"term" to highest, e.g., [1,2,3] represents the C-series
T_0 + 2*T_1 + 3*T_2.

Parameters
----------
cs : array_like
1-d array of C-series coefficients ordered from low to high.

Returns
-------
out : ndarray
Array of the roots.  If all the roots are real, then so is the
dtype of out; otherwise, out's dtype is complex.

--------
polyroots

Notes
-----
Algorithm(s) used:

Remember: because the C-series basis set is different from the
"standard" basis set, the results of this function *may* not be what
one is expecting.

Examples
--------
>>> import numpy.polynomial as P
>>> import numpy.polynomial.chebyshev as C
>>> P.polyroots((-1,1,-1,1)) # x^3 - x^2 + x - 1 has two complex roots
array([ -4.99600361e-16-1.j,  -4.99600361e-16+1.j,   1.00000e+00+0.j])
>>> C.chebroots((-1,1,-1,1)) # T3 - T2 + T1 - T0 has only real roots
array([ -5.00000000e-01,   2.60860684e-17,   1.00000000e+00])
 def pyneb.utils.chebyshev.chebsub ( c1, c2 )
Subtract one Chebyshev series from another.

Returns the difference of two Chebyshev series c1 - c2.  The
sequences of coefficients are from lowest order term to highest, i.e.,
[1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters
----------
c1, c2 : array_like
1-d arrays of Chebyshev series coefficients ordered from low to
high.

Returns
-------
out : ndarray
Of Chebyshev series coefficients representing their difference.

--------

Notes
-----
Unlike multiplication, division, etc., the difference of two Chebyshev
series is a Chebyshev series (without having to "reproject" the result
onto the basis set) so subtraction, just like that of "standard"
polynomials, is simply "component-wise."

Examples
--------
>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebsub(c1,c2)
array([-2.,  0.,  2.])
>>> C.chebsub(c2,c1) # -C.chebsub(c1,c2)
array([ 2.,  0., -2.])
 def pyneb.utils.chebyshev.chebval ( x, cs )
Evaluate a Chebyshev series.

If cs is of length n, this function returns :

p(x) = cs[0]*T_0(x) + cs[1]*T_1(x) + ... + cs[n-1]*T_{n-1}(x)

If x is a sequence or array then p(x) will have the same shape as x.
If r is a ring_like object that supports multiplication and addition
by the values in cs, then an object of the same type is returned.

Parameters
----------
x : array_like, ring_like
Array of numbers or objects that support multiplication and
addition with themselves and with the elements of cs.
cs : array_like
1-d array of Chebyshev coefficients ordered from low to high.

Returns
-------
values : ndarray, ring_like
If the return is an ndarray then it has the same shape as x.

--------
chebfit

Examples
--------

Notes
-----
The evaluation uses Clenshaw recursion, aka synthetic division.

Examples
--------
 def pyneb.utils.chebyshev.chebvander ( 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 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.

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
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.
 def pyneb.utils.chebyshev.poly2cheb ( pol )
Convert a polynomial to a Chebyshev series.

Convert an array representing the coefficients of a polynomial (relative
to the "standard" basis) ordered from lowest degree to highest, to an
array of the coefficients of the equivalent Chebyshev series, ordered
from lowest to highest degree.

Parameters
----------
pol : array_like
1-d array containing the polynomial coefficients

Returns
-------
cs : ndarray
1-d array containing the coefficients of the equivalent Chebyshev
series.

--------
cheb2poly

Notes
-----
The easy way to do conversions between polynomial basis sets
is to use the convert method of a class instance.

Examples
--------
>>> from numpy import polynomial as P
>>> p = P.Polynomial(range(4))
>>> p
Polynomial([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> c = p.convert(kind=P.Chebyshev)
>>> c
Chebyshev([ 1.  ,  3.25,  1.  ,  0.75], [-1.,  1.])
>>> P.poly2cheb(range(4))
array([ 1.  ,  3.25,  1.  ,  0.75])

## Variable Documentation

 list __all__
Initial value:
1 = ['chebzero', 'chebone', 'chebx', 'chebdomain', 'chebline',
2  'chebadd', 'chebsub', 'chebmulx', 'chebmul', 'chebdiv', 'chebpow',
3  'chebval', 'chebder', 'chebint', 'cheb2poly', 'poly2cheb',
4  'chebfromroots', 'chebvander', 'chebfit', 'chebtrim', 'chebroots',
5  'chebpts1', 'chebpts2', 'Chebyshev']
 tuple chebdomain = np.array([-1,1])
 tuple chebone = np.array([1])
 chebtrim = trimcoef
 tuple chebx = np.array([0,1])
 tuple chebzero = np.array([0])