Elep

"""
Utility classes and functions for the polynomial modules.

This module provides: error and warning objects; a polynomial base class;
and some routines used in both the `polynomial` and `chebyshev` modules.

Error objects
-------------

.. autosummary::
   :toctree: generated/

PolyError            base class for this sub-package's errors.
   PolyDomainError      raised when domains are mismatched.

Warning objects
---------------

.. autosummary::
   :toctree: generated/

RankWarning  raised in least-squares fit for rank-deficient matrix.

Base class
----------

.. autosummary::
   :toctree: generated/

PolyBase Obsolete base class for the polynomial classes. Do not use.

Functions
---------

.. autosummary::
   :toctree: generated/

as_series    convert list of array_likes into 1-D arrays of common type.
   trimseq      remove trailing zeros.
   trimcoef     remove small trailing coefficients.
   getdomain    return the domain appropriate for a given set of abscissae.
   mapdomain    maps points between domains.
   mapparms     parameters of the linear map between domains.

"""
from __future__ import division, absolute_import, print_function

import numpy as np

__all__ = [
    'RankWarning', 'PolyError', 'PolyDomainError', 'as_series', 'trimseq',
    'trimcoef', 'getdomain', 'mapdomain', 'mapparms', 'PolyBase']

#
# Warnings and Exceptions
#

class RankWarning(UserWarning):
    """Issued by chebfit when the design matrix is rank deficient."""
    pass

class PolyError(Exception):
    """Base class for errors in this module."""
    pass

class PolyDomainError(PolyError):
    """Issued by the generic Poly class when two domains don't match.

This is raised when an binary operation is passed Poly objects with
    different domains.

"""
    pass

#
# Base class for all polynomial types
#

class PolyBase(object):
    """
    Base class for all polynomial types.

Deprecated in numpy 1.9.0, use the abstract
    ABCPolyBase class instead. Note that the latter
    requires a number of virtual functions to be
    implemented.

"""
    pass

#
# Helper functions to convert inputs to 1-D arrays
#
def trimseq(seq):
    """Remove small Poly series coefficients.

Parameters
    ----------
    seq : sequence
        Sequence of Poly series coefficients. This routine fails for
        empty sequences.

Returns
    -------
    series : sequence
        Subsequence with trailing zeros removed. If the resulting sequence
        would be empty, return the first element. The returned sequence may
        or may not be a view.

Notes
    -----
    Do not lose the type info if the sequence contains unknown objects.

"""
    if len(seq) == 0:
        return seq
    else:
        for i in range(len(seq) - 1, -1, -1):
            if seq[i] != 0:
                break
        return seq[:i+1]

def as_series(alist, trim=True):
    """
    Return argument as a list of 1-d arrays.

The returned list contains array(s) of dtype double, complex double, or
    object.  A 1-d argument of shape ``(N,)`` is parsed into ``N`` arrays of
    size one; a 2-d argument of shape ``(M,N)`` is parsed into ``M`` arrays
    of size ``N`` (i.e., is "parsed by row"); and a higher dimensional array
    raises a Value Error if it is not first reshaped into either a 1-d or 2-d
    array.

Parameters
    ----------
    alist : array_like
        A 1- or 2-d array_like
    trim : boolean, optional
        When True, trailing zeros are removed from the inputs.
        When False, the inputs are passed through intact.

Returns
    -------
    [a1, a2,...] : list of 1-D arrays
        A copy of the input data as a list of 1-d arrays.

Raises
    ------
    ValueError
        Raised when `as_series` cannot convert its input to 1-d arrays, or at
        least one of the resulting arrays is empty.

Examples
    --------
    >>> from numpy import polynomial as P
    >>> a = np.arange(4)
    >>> P.as_series(a)
    [array([ 0.]), array([ 1.]), array([ 2.]), array([ 3.])]
    >>> b = np.arange(6).reshape((2,3))
    >>> P.as_series(b)
    [array([ 0.,  1.,  2.]), array([ 3.,  4.,  5.])]

"""
    arrays = [np.array(a, ndmin=1, copy=0) for a in alist]
    if min([a.size for a in arrays]) == 0:
        raise ValueError("Coefficient array is empty")
    if any([a.ndim != 1 for a in arrays]):
        raise ValueError("Coefficient array is not 1-d")
    if trim:
        arrays = [trimseq(a) for a in arrays]

if any([a.dtype == np.dtype(object) for a in arrays]):
        ret = []
        for a in arrays:
            if a.dtype != np.dtype(object):
                tmp = np.empty(len(a), dtype=np.dtype(object))
                tmp[:] = a[:]
                ret.append(tmp)
            else:
                ret.append(a.copy())
    else:
        try:
            dtype = np.common_type(*arrays)
        except:
            raise ValueError("Coefficient arrays have no common type")
        ret = [np.array(a, copy=1, dtype=dtype) for a in arrays]
    return ret

def trimcoef(c, tol=0):
    """
    Remove "small" "trailing" coefficients from a polynomial.

"Small" means "small in absolute value" and is controlled by the
    parameter `tol`; "trailing" means highest order coefficient(s), e.g., in
    ``[0, 1, 1, 0, 0]`` (which represents ``0 + x + x**2 + 0*x**3 + 0*x**4``)
    both the 3-rd and 4-th order coefficients would be "trimmed."

Parameters
    ----------
    c : array_like
        1-d array of coefficients, ordered from lowest order to highest.
    tol : number, optional
        Trailing (i.e., highest order) elements with absolute value less
        than or equal to `tol` (default value is zero) are removed.

Returns
    -------
    trimmed : ndarray
        1-d array with trailing zeros removed.  If the resulting series
        would be empty, a series containing a single zero is returned.

Raises
    ------
    ValueError
        If `tol` < 0