Merge remote branch 'upstream/master' into f2py-assumed-shape

* upstream/master: (310 commits)
  REL: add 1.6.0 release notes.
  DEP: remove deprecated np.lib.ufunclike.log2 function.
  DOC: fix typo in test guidelines.
  DEP: remove deprecated items from ma/core.py
  DEP: remove deprecated get_numpy_include.
  DEP: remove unique1d, setmember1d and intersect1d_nu.
  DEP: remove deprecated names in fftpack.
  DEP: remove deprecated methods sync() and close() from memmap.
  DEP: Update deprecation messages in genloadtxt with a version number.
  BLD: update C API version again after Mark's renaming of functions.
  DOC: Replace 'deprecated' with 'superceded' in a few places, fix a typo.
  STY: Remove a micro-optimization to make code more clear
  DOC: Add some missing documentation, hyper-link the iterator documentation
  API: Remove PyArray_FillWithZero from public API
  API: Rename the iterator function pointer types to be more consistent with NumPy convention
  STY: Work around lack of variadic macros in debug tracing
  API: Change iterator API parameters ndim and niter from npy_intp to int
  ENH: add Intel 64-bit C compiler. Closes #960.
  TST: fix two divide-by-zero test warnings.
  BUG: Broadcast shape was backwards in error message (Ticket #1762)
  ...

1 files changed, 715 insertions, 43 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index baf5285f0..187180c5a 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -284,6 +284,36 @@ add_newdoc('numpy.core', 'broadcast', ('size',
 
     """))
 
+add_newdoc('numpy.core', 'broadcast', ('reset',
+    """
+    reset()
+
+    Reset the broadcasted result's iterator(s).
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> x = np.array([1, 2, 3])
+    >>> y = np.array([[4], [5], [6]]
+    >>> b = np.broadcast(x, y)
+    >>> b.index
+    0
+    >>> b.next(), b.next(), b.next()
+    ((1, 4), (2, 4), (3, 4))
+    >>> b.index
+    3
+    >>> b.reset()
+    >>> b.index
+    0
+
+    """))
 
 ###############################################################################
 #
@@ -330,6 +360,15 @@ add_newdoc('numpy.core.multiarray', 'array',
         array should have.  Ones will be pre-pended to the shape as
         needed to meet this requirement.
 
+    Returns
+    -------
+    out : ndarray
+        An array object satisfying the specified requirements.
+
+    See Also
+    --------
+    empty, empty_like, zeros, zeros_like, ones, ones_like, fill
+
     Examples
     --------
     >>> np.array([1, 2, 3])
@@ -413,6 +452,58 @@ add_newdoc('numpy.core.multiarray', 'empty',
 
     """)
 
+add_newdoc('numpy.core.multiarray', 'empty_like',
+    """
+    empty_like(a, dtype=None, order='K')
+
+    Return a new array with the same shape and type as a given array.
+
+    Parameters
+    ----------
+    a : array_like
+        The shape and data-type of `a` define these same attributes of the
+        returned array.
+    dtype : data-type, optional
+        Overrides the data type of the result.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Overrides the memory layout of the result. 'C' means C-order,
+        'F' means F-order, 'A' means 'F' if ``a`` is Fortran contiguous,
+        'C' otherwise. 'K' means match the layout of ``a`` as closely
+        as possible.
+
+    Returns
+    -------
+    out : ndarray
+        Array of uninitialized (arbitrary) data with the same
+        shape and type as `a`.
+
+    See Also
+    --------
+    ones_like : Return an array of ones with shape and type of input.
+    zeros_like : Return an array of zeros with shape and type of input.
+    empty : Return a new uninitialized array.
+    ones : Return a new array setting values to one.
+    zeros : Return a new array setting values to zero.
+
+    Notes
+    -----
+    This function does *not* initialize the returned array; to do that use
+    `zeros_like` or `ones_like` instead.  It may be marginally faster than
+    the functions that do set the array values.
+
+    Examples
+    --------
+    >>> a = ([1,2,3], [4,5,6])                         # a is array-like
+    >>> np.empty_like(a)
+    array([[-1073741821, -1073741821,           3],    #random
+           [          0,           0, -1073741821]])
+    >>> a = np.array([[1., 2., 3.],[4.,5.,6.]])
+    >>> np.empty_like(a)
+    array([[ -2.00000715e+000,   1.48219694e-323,  -2.00000572e+000],#random
+           [  4.38791518e-305,  -2.00000715e+000,   4.17269252e-309]])
+
+    """)
+
 
 add_newdoc('numpy.core.multiarray', 'scalar',
     """
@@ -481,6 +572,35 @@ add_newdoc('numpy.core.multiarray', 'zeros',
 
     """)
 
+add_newdoc('numpy.core.multiarray', 'count_nonzero',
+    """
+    count_nonzero(a)
+
+    Counts the number of non-zero values in the array ``a``.
+
+    Parameters
+    ----------
+    a : array_like
+        The array for which to count non-zeros.
+
+    Returns
+    -------
+    count : int
+        Number of non-zero values in the array.
+
+    See Also
+    --------
+    nonzero : Return the coordinates of all the non-zero values.
+
+    Examples
+    --------
+    >>> np.count_nonzero(np.eye(4))
+    4
+
+    >>> np.count_nonzero([[0,1,7,0,0],[3,0,0,2,19]])
+    5
+    """)
+
 add_newdoc('numpy.core.multiarray','set_typeDict',
     """set_typeDict(dict)
 
@@ -493,28 +613,29 @@ add_newdoc('numpy.core.multiarray', 'fromstring',
     """
     fromstring(string, dtype=float, count=-1, sep='')
 
-    Return a new 1-D array initialized from raw binary or text data in string.
+    A new 1-D array initialized from raw binary or text data in a string.
 
     Parameters
     ----------
     string : str
         A string containing the data.
-    dtype : dtype, optional
-        The data type of the array. For binary input data, the data must be
-        in exactly this format.
+    dtype : data-type, optional
+        The data type of the array; default: float.  For binary input data,
+        the data must be in exactly this format.
     count : int, optional
-        Read this number of `dtype` elements from the data. If this is
-        negative, then the size will be determined from the length of the
-        data.
+        Read this number of `dtype` elements from the data.  If this is
+        negative (the default), the count will be determined from the
+        length of the data.
     sep : str, optional
-        If provided and not empty, then the data will be interpreted as
-        ASCII text with decimal numbers. This argument is interpreted as the
-        string separating numbers in the data. Extra whitespace between
-        elements is also ignored.
+        If not provided or, equivalently, the empty string, the data will
+        be interpreted as binary data; otherwise, as ASCII text with
+        decimal numbers.  Also in this latter case, this argument is
+        interpreted as the string separating numbers in the data; extra
+        whitespace between elements is also ignored.
 
     Returns
     -------
-    arr : array
+    arr : ndarray
         The constructed array.
 
     Raises
@@ -523,6 +644,10 @@ add_newdoc('numpy.core.multiarray', 'fromstring',
         If the string is not the correct size to satisfy the requested
         `dtype` and `count`.
 
+    See Also
+    --------
+    frombuffer, fromfile, fromiter
+
     Examples
     --------
     >>> np.fromstring('\\x01\\x02', dtype=np.uint8)
@@ -534,17 +659,6 @@ add_newdoc('numpy.core.multiarray', 'fromstring',
     >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3)
     array([1, 2, 3], dtype=uint8)
 
-    Invalid inputs:
-
-    >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.int32)
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-    ValueError: string size must be a multiple of element size
-    >>> np.fromstring('\\x01\\x02', dtype=np.uint8, count=3)
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-    ValueError: string is smaller than requested size
-
     """)
 
 add_newdoc('numpy.core.multiarray', 'fromiter',
@@ -558,9 +672,9 @@ add_newdoc('numpy.core.multiarray', 'fromiter',
     iterable : iterable object
         An iterable object providing data for the array.
     dtype : data-type
-        The data type of the returned array.
+        The data-type of the returned array.
     count : int, optional
-        The number of items to read from iterable. The default is -1,
+        The number of items to read from *iterable*.  The default is -1,
         which means all data is read.
 
     Returns
@@ -570,9 +684,8 @@ add_newdoc('numpy.core.multiarray', 'fromiter',
 
     Notes
     -----
-    Specify ``count`` to improve performance.  It allows
-    ``fromiter`` to pre-allocate the output array, instead of
-    resizing it on demand.
+    Specify `count` to improve performance.  It allows ``fromiter`` to
+    pre-allocate the output array, instead of resizing it on demand.
 
     Examples
     --------
@@ -665,26 +778,26 @@ add_newdoc('numpy.core.multiarray', 'frombuffer',
 
     Parameters
     ----------
-    buffer
+    buffer : buffer_like
         An object that exposes the buffer interface.
     dtype : data-type, optional
-        Data type of the returned array.
+        Data-type of the returned array; default: float.
     count : int, optional
         Number of items to read. ``-1`` means all data in the buffer.
     offset : int, optional
-        Start reading the buffer from this offset.
+        Start reading the buffer from this offset; default: 0.
 
     Notes
     -----
-    If the buffer has data that is not in machine byte-order, this
-    should be specified as part of the data-type, e.g.::
+    If the buffer has data that is not in machine byte-order, this should
+    be specified as part of the data-type, e.g.::
 
       >>> dt = np.dtype(int)
       >>> dt = dt.newbyteorder('>')
       >>> np.frombuffer(buf, dtype=dt)
 
-    The data of the resulting array will not be byteswapped,
-    but will be interpreted correctly.
+    The data of the resulting array will not be byteswapped, but will be
+    interpreted correctly.
 
     Examples
     --------
@@ -797,6 +910,7 @@ add_newdoc('numpy.core', 'inner',
     --------
     tensordot : Sum products over arbitrary axes.
     dot : Generalised matrix product, using second last dimension of `b`.
+    einsum : Einstein summation convention.
 
     Notes
     -----
@@ -1115,9 +1229,12 @@ add_newdoc('numpy.core.multiarray', 'lexsort',
 
 add_newdoc('numpy.core.multiarray', 'can_cast',
     """
-    can_cast(fromtype, totype)
+    can_cast(from, totype, casting = 'safe')
 
-    Returns True if cast between data types can occur without losing precision.
+    Returns True if cast between data types can occur according to the
+    casting rule.  If from is a scalar or array scalar, also returns
+    True if the scalar value can be cast without overflow or truncation
+    to an integer.
 
     Parameters
     ----------
@@ -1125,14 +1242,19 @@ add_newdoc('numpy.core.multiarray', 'can_cast',
         Data type to cast from.
     totype : dtype or dtype specifier
         Data type to cast to.
+    casting : casting rule
+        May be any of 'no', 'equiv', 'safe', 'same_kind', or 'unsafe'.
 
     Returns
     -------
     out : bool
-        True if cast can occur without losing precision.
+        True if cast can occur according to the casting rule.
 
     Examples
     --------
+
+    Basic examples
+
     >>> np.can_cast(np.int32, np.int64)
     True
     >>> np.can_cast(np.float64, np.complex)
@@ -1147,6 +1269,183 @@ add_newdoc('numpy.core.multiarray', 'can_cast',
     >>> np.can_cast('i4', 'S4')
     True
 
+    Casting scalars
+
+    >>> np.can_cast(100, 'i1')
+    True
+    >>> np.can_cast(150, 'i1')
+    False
+    >>> np.can_cast(150, 'u1')
+    True
+
+    >>> np.can_cast(3.5e100, np.float32)
+    False
+    >>> np.can_cast(1000.0, np.float32)
+    True
+
+    Array scalar checks the value, array does not
+
+    >>> np.can_cast(np.array(1000.0), np.float32)
+    True
+    >>> np.can_cast(np.array([1000.0]), np.float32)
+    False
+
+    Using the casting rules
+
+    >>> np.can_cast('i8', 'i8', 'no')
+    True
+    >>> np.can_cast('<i8', '>i8', 'no')
+    False
+
+    >>> np.can_cast('<i8', '>i8', 'equiv')
+    True
+    >>> np.can_cast('<i4', '>i8', 'equiv')
+    False
+
+    >>> np.can_cast('<i4', '>i8', 'safe')
+    True
+    >>> np.can_cast('<i8', '>i4', 'safe')
+    False
+
+    >>> np.can_cast('<i8', '>i4', 'same_kind')
+    True
+    >>> np.can_cast('<i8', '>u4', 'same_kind')
+    False
+
+    >>> np.can_cast('<i8', '>u4', 'unsafe')
+    True
+
+    """)
+
+add_newdoc('numpy.core.multiarray', 'promote_types',
+    """
+    promote_types(type1, type2)
+
+    Returns the data type with the smallest size and smallest scalar
+    kind to which both ``type1`` and ``type2`` may be safely cast.
+    The returned data type is always in native byte order.
+
+    Parameters
+    ----------
+    type1 : dtype or dtype specifier
+        First data type.
+    type2 : dtype or dtype specifier
+        Second data type.
+
+    Returns
+    -------
+    out : dtype
+        The promoted data type.
+
+    See Also
+    --------
+    issctype, issubsctype, issubdtype, obj2sctype, sctype2char,
+    maximum_sctype, min_scalar_type
+
+    Examples
+    --------
+    >>> np.promote_types('f4', 'f8')
+    dtype('float64')
+
+    >>> np.promote_types('i8', 'f4')
+    dtype('float64')
+
+    >>> np.promote_types('>i8', '<c8')
+    dtype('complex128')
+
+    >>> np.promote_types('i1', 'S8')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: invalid type promotion
+
+    """)
+
+add_newdoc('numpy.core.multiarray', 'min_scalar_type',
+    """
+    min_scalar_type(a)
+
+    For scalar ``a``, returns the data type with the smallest size
+    and smallest scalar kind which can hold its value.  For non-scalar
+    array ``a``, returns the vector's dtype unmodified.
+
+    As a special case, floating point values are not demoted to integers,
+    and complex values are not demoted to floats.
+
+    Parameters
+    ----------
+    a : scalar or array_like
+        The value whose minimal data type is to be found.
+
+    Returns
+    -------
+    out : dtype
+        The minimal data type.
+
+
+    See Also
+    --------
+    issctype, issubsctype, issubdtype, obj2sctype, sctype2char,
+    maximum_sctype, promote_types
+
+    Examples
+    --------
+    >>> np.min_scalar_type(10)
+    dtype('uint8')
+
+    >>> np.min_scalar_type(-260)
+    dtype('int16')
+
+    >>> np.min_scalar_type(3.1)
+    dtype('float16')
+
+    >>> np.min_scalar_type(1e50)
+    dtype('float64')
+
+    >>> np.min_scalar_type(np.arange(4,dtype='f8'))
+    dtype('float64')
+
+    """)
+
+add_newdoc('numpy.core.multiarray', 'result_type',
+    """
+    result_type(*arrays_and_dtypes)
+
+    Returns the type that results from applying the NumPy
+    type promotion rules to the arguments.
+
+    Type promotion in NumPy works similarly to the rules in languages
+    like C++, with some slight differences.  When both scalars and
+    arrays are used, the array's type takes precedence and the actual value
+    of the scalar is taken into account.
+
+    For example, calculating 3*a, where a is an array of 32-bit floats,
+    intuitively should result in a 32-bit float output.  If the 3 is a
+    32-bit integer, the NumPy rules indicate it can't convert losslessly
+    into a 32-bit float, so a 64-bit float should be the result type.
+    By examining the value of the constant, '3', we see that it fits in
+    an 8-bit integer, which can be cast losslessly into the 32-bit float.
+
+    Parameters
+    ----------
+    arrays_and_dtypes : list of arrays and dtypes
+        The operands of some operation whose result type is needed.
+
+    Returns
+    -------
+    out : dtype
+        The result type.
+
+    Examples
+    --------
+    >>> np.result_type(3, np.arange(7, dtype='i1'))
+    dtype('int8')
+
+    >>> np.result_type('i4', 'c8')
+    dtype('complex128')
+
+    >>> np.result_type(3.0, -2)
+    dtype('float64')
+
     """)
 
 add_newdoc('numpy.core.multiarray','newbuffer',
@@ -1192,7 +1491,7 @@ add_newdoc('numpy.core.multiarray', 'getbuffer',
 
 add_newdoc('numpy.core', 'dot',
     """
-    dot(a, b)
+    dot(a, b, out=None)
 
     Dot product of two arrays.
 
@@ -1209,6 +1508,13 @@ add_newdoc('numpy.core', 'dot',
         First argument.
     b : array_like
         Second argument.
+    out : ndarray, optional
+        Output argument. This must have the exact kind that would be returned
+        if it was not used. In particular, it must have the right type, must be
+        C-contiguous, and its dtype must be the dtype that would be returned
+        for `dot(a,b)`. This is a performance feature. Therefore, if these
+        conditions are not met, an exception is raised, instead of attempting
+        to be flexible.
 
     Returns
     -------
@@ -1216,6 +1522,7 @@ add_newdoc('numpy.core', 'dot',
         Returns the dot product of `a` and `b`.  If `a` and `b` are both
         scalars or both 1-D arrays then a scalar is returned; otherwise
         an array is returned.
+        If `out` is given, then it is returned.
 
     Raises
     ------
@@ -1227,6 +1534,7 @@ add_newdoc('numpy.core', 'dot',
     --------
     vdot : Complex-conjugating dot product.
     tensordot : Sum products over arbitrary axes.
+    einsum : Einstein summation convention.
 
     Examples
     --------
@@ -1255,6 +1563,194 @@ add_newdoc('numpy.core', 'dot',
 
     """)
 
+add_newdoc('numpy.core', 'einsum',
+    """
+    einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe')
+
+    Evaluates the Einstein summation convention on the operands.
+
+    Using the Einstein summation convention, many common multi-dimensional
+    array operations can be represented in a simple fashion.  This function
+    provides a way compute such summations. The best way to understand this
+    function is to try the examples below, which show how many common NumPy
+    functions can be implemented as calls to `einsum`.
+
+    Parameters
+    ----------
+    subscripts : str
+        Specifies the subscripts for summation.
+    operands : list of array_like
+        These are the arrays for the operation.
+    out : ndarray, optional
+        If provided, the calculation is done into this array.
+    dtype : data-type, optional
+        If provided, forces the calculation to use the data type specified.
+        Note that you may have to also give a more liberal `casting`
+        parameter to allow the conversions.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Controls the memory layout of the output. 'C' means it should
+        be C contiguous. 'F' means it should be Fortran contiguous,
+        'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise.
+        'K' means it should be as close to the layout as the inputs as
+        is possible, including arbitrarily permuted axes.
+        Default is 'K'.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur.  Setting this to
+        'unsafe' is not recommended, as it can adversely affect accumulations.
+
+          * 'no' means the data types should not be cast at all.
+          * 'equiv' means only byte-order changes are allowed.
+          * 'safe' means only casts which can preserve values are allowed.
+          * 'unsafe' means any data conversions may be done.
+          * 'same_kind' means only safe casts or casts within a kind,
+            like float64 to float32, are allowed.
+
+    Returns
+    -------
+    output : ndarray
+        The calculation based on the Einstein summation convention.
+
+    See Also
+    --------
+    dot, inner, outer, tensordot
+
+    Notes
+    -----
+    The subscripts string is a comma-separated list of subscript labels,
+    where each label refers to a dimension of the corresponding operand.
+    Repeated subscripts labels in one operand take the diagonal.  For example,
+    ``np.einsum('ii', a)`` is equivalent to ``np.trace(a)``.
+
+    Whenever a label is repeated, it is summed, so ``np.einsum('i,i', a, b)``
+    is equivalent to ``np.inner(a,b)``.  If a label appears only once,
+    it is not summed, so ``np.einsum('i', a)`` produces a view of ``a``
+    with no changes.
+
+    The order of labels in the output is by default alphabetical.  This
+    means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while
+    ``np.einsum('ji', a)`` takes its transpose.
+
+    The output can be controlled by specifying output subscript labels
+    as well.  This specifies the label order, and allows summing to
+    be disallowed or forced when desired.  The call ``np.einsum('i->', a)``
+    is like ``np.sum(a, axis=-1)``, and ``np.einsum('ii->i', a)``
+    is like ``np.diag(a)``.  The difference is that `einsum` does not
+    allow broadcasting by default.
+
+    To enable and control broadcasting, use an ellipsis.  Default
+    NumPy-style broadcasting is done by adding an ellipsis
+    to the left of each term, like ``np.einsum('...ii->...i', a)``.
+    To take the trace along the first and last axes,
+    you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix
+    product with the left-most indices instead of rightmost, you can do
+    ``np.einsum('ij...,jk...->ik...', a, b)``.
+
+    When there is only one operand, no axes are summed, and no output
+    parameter is provided, a view into the operand is returned instead
+    of a new array.  Thus, taking the diagonal as ``np.einsum('ii->i', a)``
+    produces a view.
+
+    An alternative way to provide the subscripts and operands is as
+    ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``. The examples
+    below have corresponding `einsum` calls with the two parameter methods.
+
+    Examples
+    --------
+    >>> a = np.arange(25).reshape(5,5)
+    >>> b = np.arange(5)
+    >>> c = np.arange(6).reshape(2,3)
+
+    >>> np.einsum('ii', a)
+    60
+    >>> np.einsum(a, [0,0])
+    60
+    >>> np.trace(a)
+    60
+
+    >>> np.einsum('ii->i', a)
+    array([ 0,  6, 12, 18, 24])
+    >>> np.einsum(a, [0,0], [0])
+    array([ 0,  6, 12, 18, 24])
+    >>> np.diag(a)
+    array([ 0,  6, 12, 18, 24])
+
+    >>> np.einsum('ij,j', a, b)
+    array([ 30,  80, 130, 180, 230])
+    >>> np.einsum(a, [0,1], b, [1])
+    array([ 30,  80, 130, 180, 230])
+    >>> np.dot(a, b)
+    array([ 30,  80, 130, 180, 230])
+
+    >>> np.einsum('ji', c)
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+    >>> np.einsum(c, [1,0])
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+    >>> c.T
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+
+    >>> np.einsum('..., ...', 3, c)
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+    >>> np.einsum(3, [Ellipsis], c, [Ellipsis])
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+    >>> np.multiply(3, c)
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+
+    >>> np.einsum('i,i', b, b)
+    30
+    >>> np.einsum(b, [0], b, [0])
+    30
+    >>> np.inner(b,b)
+    30
+
+    >>> np.einsum('i,j', np.arange(2)+1, b)
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+    >>> np.einsum(np.arange(2)+1, [0], b, [1])
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+    >>> np.outer(np.arange(2)+1, b)
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+
+    >>> np.einsum('i...->...', a)
+    array([50, 55, 60, 65, 70])
+    >>> np.einsum(a, [0,Ellipsis], [Ellipsis])
+    array([50, 55, 60, 65, 70])
+    >>> np.sum(a, axis=0)
+    array([50, 55, 60, 65, 70])
+
+    >>> a = np.arange(60.).reshape(3,4,5)
+    >>> b = np.arange(24.).reshape(4,3,2)
+    >>> np.einsum('ijk,jil->kl', a, b)
+    array([[ 4400.,  4730.],
+           [ 4532.,  4874.],
+           [ 4664.,  5018.],
+           [ 4796.,  5162.],
+           [ 4928.,  5306.]])
+    >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
+    array([[ 4400.,  4730.],
+           [ 4532.,  4874.],
+           [ 4664.,  5018.],
+           [ 4796.,  5162.],
+           [ 4928.,  5306.]])
+    >>> np.tensordot(a,b, axes=([1,0],[0,1]))
+    array([[ 4400.,  4730.],
+           [ 4532.,  4874.],
+           [ 4664.,  5018.],
+           [ 4796.,  5162.],
+           [ 4928.,  5306.]])
+
+    """)
+
 add_newdoc('numpy.core', 'alterdot',
     """
     Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions.
@@ -2154,9 +2650,15 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('astype',
 
     Parameters
     ----------
-    t : string or dtype
+    t : str or dtype
         Typecode or data-type to which the array is cast.
 
+    Raises
+    ------
+    ComplexWarning :
+        When casting from complex to float or int. To avoid this,
+        one should use ``a.real.astype(t)``.
+
     Examples
     --------
     >>> x = np.array([1, 2, 2.5])
@@ -2365,6 +2867,35 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal',
     """))
 
 
+add_newdoc('numpy.core.multiarray', 'ndarray', ('dot',
+    """
+    a.dot(b, out=None)
+
+    Dot product of two arrays.
+
+    Refer to `numpy.dot` for full documentation.
+
+    See Also
+    --------
+    numpy.dot : equivalent function
+
+    Examples
+    --------
+    >>> a = np.eye(2)
+    >>> b = np.ones((2, 2)) * 2
+    >>> a.dot(b)
+    array([[ 2.,  2.],
+           [ 2.,  2.]])
+
+    This array method can be conveniently chained:
+
+    >>> a.dot(b).dot(b)
+    array([[ 8.,  8.],
+           [ 8.,  8.]])
+
+    """))
+
+
 add_newdoc('numpy.core.multiarray', 'ndarray', ('dump',
     """a.dump(file)
 
@@ -2613,6 +3144,37 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset',
     """))
 
 
+add_newdoc('numpy.core.multiarray', 'ndarray', ('setasflat',
+    """
+    a.setasflat(arr)
+
+    Equivalent to a.flat = arr.flat, but is generally more efficient.
+    This function does not check for overlap, so if ``arr`` and ``a``
+    are viewing the same data with different strides, the results will
+    be unpredictable.
+
+    Parameters
+    ----------
+    arr : array_like
+        The array to copy into a.
+
+    Examples
+    --------
+    >>> a = np.arange(2*4).reshape(2,4)[:,:-1]; a
+    array([[0, 1, 2],
+           [4, 5, 6]])
+    >>> b = np.arange(3*3, dtype='f4').reshape(3,3).T[::-1,:-1]; b
+    array([[ 2.,  5.],
+           [ 1.,  4.],
+           [ 0.,  3.]], dtype=float32)
+    >>> a.setasflat(b)
+    >>> a
+    array([[2, 5, 1],
+           [4, 0, 3]])
+
+    """))
+
+
 add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
     """
     a.max(axis=None, out=None)
@@ -3796,12 +4358,15 @@ add_newdoc('numpy.lib._compiled_base', 'digitize',
 
 add_newdoc('numpy.lib._compiled_base', 'bincount',
     """
-    bincount(x, weights=None)
+    bincount(x, weights=None, minlength=None)
 
     Count number of occurrences of each value in array of non-negative ints.
 
     The number of bins (of size 1) is one larger than the largest value in
-    `x`. Each bin gives the number of occurrences of its index value in `x`.
+    `x`. If `minlength` is specified, there will be at least this number
+    of bins in the output array (though it will be longer if necessary,
+    depending on the contents of `x`).
+    Each bin gives the number of occurrences of its index value in `x`.
     If `weights` is specified the input array is weighted by it, i.e. if a
     value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead
     of ``out[n] += 1``.
@@ -3812,6 +4377,10 @@ add_newdoc('numpy.lib._compiled_base', 'bincount',
         Input array.
     weights : array_like, optional
         Weights, array of the same shape as `x`.
+    minlength : int, optional
+        .. versionadded:: 1.6.0
+
+        A minimum number of bins for the output array.
 
     Returns
     -------
@@ -3823,7 +4392,7 @@ add_newdoc('numpy.lib._compiled_base', 'bincount',
     ------
     ValueError
         If the input is not 1-dimensional, or contains elements with negative
-        values.
+        values, or if `minlength` is non-positive.
     TypeError
         If the type of the input is float or complex.
 
@@ -3842,6 +4411,9 @@ add_newdoc('numpy.lib._compiled_base', 'bincount',
     >>> np.bincount(x).size == np.amax(x)+1
     True
 
+    The input array needs to be of integer dtype, otherwise a
+    TypeError is raised:
+
     >>> np.bincount(np.arange(5, dtype=np.float))
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
@@ -3857,6 +4429,106 @@ add_newdoc('numpy.lib._compiled_base', 'bincount',
 
     """)
 
+add_newdoc('numpy.lib._compiled_base', 'ravel_coords',
+    """
+    ravel_coords(coords, dims, mode='raise', order='C')
+
+    Converts a tuple of coordinate arrays into an array of flat
+    indices, applying boundary modes to the coordinates.
+
+    Parameters
+    ----------
+    coords : tuple of array_like
+        A tuple of integer arrays, one array for each dimension.
+    dims : tuple of ints
+        The shape of array into which the indices from ``coords`` apply.
+    mode : {'raise', 'wrap', 'clip'}, optional
+        Specifies how out-of-bounds indices are handled.  Can specify
+        either one mode or a tuple of modes, one mode per index.
+
+        * 'raise' -- raise an error (default)
+        * 'wrap' -- wrap around
+        * 'clip' -- clip to the range
+
+        In 'clip' mode, a negative index which would normally
+        wrap will clip to 0 instead.
+    order : {'C', 'F'}, optional
+        Determines whether the coords should be viewed as indexing in
+        C (row-major) order or FORTRAN (column-major) order.
+
+    Returns
+    -------
+    raveled_indices : ndarray
+        An array of indices into the flattened version of an array
+        of dimensions ``dims``.
+
+    See Also
+    --------
+    unravel_index
+
+    Notes
+    -----
+    .. versionadded:: 1.6.0
+
+    Examples
+    --------
+    >>> arr = np.array([[3,6,6],[4,5,1]])
+    >>> np.ravel_coords(arr, (7,6))
+    array([22, 41, 37])
+    >>> np.ravel_coords(arr, (7,6), order='F')
+    array([31, 41, 13])
+    >>> np.ravel_coords(arr, (4,6), mode='clip')
+    array([22, 23, 19])
+    >>> np.ravel_coords(arr, (4,4), mode=('clip','wrap'))
+    array([12, 13, 13])
+
+    >>> np.ravel_coords((3,1,4,1), (6,7,8,9))
+    1621
+    """)
+
+add_newdoc('numpy.lib._compiled_base', 'unravel_index',
+    """
+    unravel_index(indices, dims, order='C')
+
+    Converts a flat index or array of flat indices into a tuple
+    of coordinate arrays.
+
+    Parameters
+    ----------
+    indices : array_like
+        An integer array whose elements are indices into the flattened
+        version of an array of dimensions ``dims``. Before version 1.6.0,
+        this function accepted just one index value.
+    dims : tuple of ints
+        The shape of the array to use for unraveling ``indices``.
+    order : {'C', 'F'}, optional
+        .. versionadded:: 1.6.0
+
+        Determines whether the indices should be viewed as indexing in
+        C (row-major) order or FORTRAN (column-major) order.
+
+    Returns
+    -------
+    unraveled_coords : tuple of ndarray
+        Each array in the tuple has the same shape as the ``indices``
+        array.
+
+    See Also
+    --------
+    ravel_coords
+
+    Examples
+    --------
+    >>> np.unravel_index([22, 41, 37], (7,6))
+    (array([3, 6, 6]), array([4, 5, 1]))
+    >>> np.unravel_index([31, 41, 13], (7,6), order='F')
+    (array([3, 6, 6]), array([4, 5, 1]))
+
+    >>> np.unravel_index(1621, (6,7,8,9))
+    (3, 1, 4, 1)
+
+    """)
+
 add_newdoc('numpy.lib._compiled_base', 'add_docstring',
     """
     docstring(obj, docstring)