Merge pull request #4789 from juliantaylor/release-notes-19b1

DOC: add some highlights to release notes

2 files changed, 144 insertions, 149 deletions

diff --git a/doc/release/1.9.0-notes.rst b/doc/release/1.9.0-notes.rst
index 29b2703b0..e1e958e9d 100644
--- a/doc/release/1.9.0-notes.rst
+++ b/doc/release/1.9.0-notes.rst
@@ -6,6 +6,12 @@ This release supports Python 2.6 - 2.7 and 3.2 - 3.4.
 
 Highlights
 ==========
+* Addition of `__numpy_ufunc__` to allow overriding ufuncs in ndarray
+  subclasses.
+* Numerous performance improvements in various areas, most notably indexing and
+  operations on small arrays are significantly faster.
+  Indexing operations now also release the GIL.
+* Addition of `nanmedian` and `nanpercentile` rounds out the nanfunction set.
 
 
 Dropped Support
@@ -65,20 +71,6 @@ to an array via ``np.array``.
 If the ``overwrite_input`` option is used the input is only partially
 instead of fully sorted.
 
-The ``npy_3kcompat.h`` header changed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The unused ``simple_capsule_dtor`` function has been removed from
-``npy_3kcompat.h``.  Note that this header is not meant to be used outside
-of numpy; other projects should be using their own copy of this file when
-needed.
-
-Negative indices in C-Api ``sq_item`` and ``sq_ass_item`` sequence methods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When directly accessing the ``sq_item`` or ``sq_ass_item`` PyObject slots
-for item getting, negative indices will not be supported anymore.
-``PySequence_GetItem`` and ``PySequence_SetItem`` however fix negative
-indices so that they can be used there.
-
 ndarray.tofile exception type
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All ``tofile`` exceptions are now ``IOError``, some were previously
@@ -94,11 +86,6 @@ Two changes to numpy.ma.core._check_fill_value:
 * When the fill value overflows the array type, TypeError is raised instead
   of OverflowError.
 
-
-The ``doc/swig`` directory moved
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``doc/swig`` directory has been moved to ``tools/swig``.
-
 Polynomial Classes no longer derived from PolyBase
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This may cause problems with folks who depended on the polynomial classes
@@ -123,6 +110,136 @@ Applications that now fail can be fixed by masking the higher 32 bit values to
 zero: ``seed = seed & 0xFFFFFFFF``. This is what is done silently in older
 versions so the random stream remains the same.
 
+Argmin and argmax out argument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``out`` argument to ``np.argmin`` and ``np.argmax`` and their
+equivalent C-API functions is now checked to match the desired output shape
+exactly.  If the check fails a ``ValueError`` instead of ``TypeError`` is
+raised.
+
+Einsum
+~~~~~~
+Remove unnecessary broadcasting notation restrictions.
+``np.einsum('ijk,j->ijk', A, B)`` can also be written as
+``np.einsum('ij...,j->ij...', A, B)`` (ellipsis is no longer required on 'j')
+
+Indexing
+~~~~~~~~
+
+The NumPy indexing has seen a complete rewrite in this version. This makes
+most advanced integer indexing operations much faster and should have no
+other implications.  However some subtle changes and deprecations were
+introduced in advanced indexing operations:
+
+* Boolean indexing into scalar arrays will always return a new 1-d array.
+  This means that ``array(1)[array(True)]`` gives ``array([1])`` and
+  not the original array.
+
+* Advanced indexing into one dimensional arrays used to have
+  (undocumented) special handling regarding repeating the value array in
+  assignments when the shape of the value array was too small or did not
+  match.  Code using this will raise an error. For compatibility you can
+  use ``arr.flat[index] = values``, which uses the old code branch.  (for
+  example ``a = np.ones(10); a[np.arange(10)] = [1, 2, 3]``)
+
+* The iteration order over advanced indexes used to be always C-order.
+  In NumPy 1.9. the iteration order adapts to the inputs and is not
+  guaranteed (with the exception of a *single* advanced index which is
+  never reversed for compatibility reasons). This means that the result
+  is undefined if multiple values are assigned to the same element.  An
+  example for this is ``arr[[0, 0], [1, 1]] = [1, 2]``, which may set
+  ``arr[0, 1]`` to either 1 or 2.
+
+* Equivalent to the iteration order, the memory layout of the advanced
+  indexing result is adapted for faster indexing and cannot be predicted.
+
+* All indexing operations return a view or a copy. No indexing operation
+  will return the original array object. (For example ``arr[...]``)
+
+* In the future Boolean array-likes (such as lists of python bools) will
+  always be treated as Boolean indexes and Boolean scalars (including
+  python ``True``) will be a legal *boolean* index. At this time, this is
+  already the case for scalar arrays to allow the general
+  ``positive = a[a > 0]`` to work when ``a`` is zero dimensional.
+
+* In NumPy 1.8 it was possible to use ``array(True)`` and
+  ``array(False)`` equivalent to 1 and 0 if the result of the operation
+  was a scalar.  This will raise an error in NumPy 1.9 and, as noted
+  above, treated as a boolean index in the future.
+
+* All non-integer array-likes are deprecated, object arrays of custom
+  integer like objects may have to be cast explicitly.
+
+* The error reporting for advanced indexing is more informative, however
+  the error type has changed in some cases. (Broadcasting errors of
+  indexing arrays are reported as ``IndexError``)
+
+* Indexing with more then one ellipsis (``...``) is deprecated.
+
+``promote_types`` and string dtype
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``promote_types`` function now returns a valid string length when given an
+integer or float dtype as one argument and a string dtype as another
+argument.  Previously it always returned the input string dtype, even if it
+wasn't long enough to store the max integer/float value converted to a
+string.
+
+``can_cast`` and string dtype
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``can_cast`` function now returns False in "safe" casting mode for
+integer/float dtype and string dtype if the string dtype length is not long
+enough to store the max integer/float value converted to a string.
+Previously ``can_cast`` in "safe" mode returned True for integer/float
+dtype and a string dtype of any length.
+
+astype and string dtype
+~~~~~~~~~~~~~~~~~~~~~~~
+The ``astype`` method now returns an error if the string dtype to cast to
+is not long enough in "safe" casting mode to hold the max value of
+integer/float array that is being casted. Previously the casting was
+allowed even if the result was truncated.
+
+`npyio.recfromcsv` keyword arguments change
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`npyio.recfromcsv` no longer accepts the undocumented `update` keyword,
+which used to override the `dtype` keyword.
+
+The ``doc/swig`` directory moved
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``doc/swig`` directory has been moved to ``tools/swig``.
+
+The ``npy_3kcompat.h`` header changed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The unused ``simple_capsule_dtor`` function has been removed from
+``npy_3kcompat.h``.  Note that this header is not meant to be used outside
+of numpy; other projects should be using their own copy of this file when
+needed.
+
+Negative indices in C-Api ``sq_item`` and ``sq_ass_item`` sequence methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When directly accessing the ``sq_item`` or ``sq_ass_item`` PyObject slots
+for item getting, negative indices will not be supported anymore.
+``PySequence_GetItem`` and ``PySequence_SetItem`` however fix negative
+indices so that they can be used there.
+
+NDIter
+~~~~~~
+When ``NpyIter_RemoveAxis`` is now called, the iterator range will be reset.
+
+When a multi index is being tracked and an iterator is not buffered, it is
+possible to use ``NpyIter_RemoveAxis``. In this case an iterator can shrink
+in size. Because the total size of an iterator is limited, the iterator
+may be too large before these calls. In this case its size will be set to ``-1``
+and an error issued not at construction time but when removing the multi
+index, setting the iterator range, or getting the next function.
+
+This has no effect on currently working code, but highlights the necessity
+of checking for an error return if these conditions can occur. In most
+cases the arrays being iterated are as large as the iterator so that such
+a problem cannot occur.
+
+This change was already applied to the 1.8.1 release.
+
 
 New Features
 ============
@@ -165,7 +282,7 @@ in Python 3 where ``str`` and ``bytes`` are not the same.
 
 Build system
 ~~~~~~~~~~~~
-Added experimental support for the ppc64le architecture.
+Added experimental support for the ppc64le and OpenRISC architecture.
 
 Compatibility to python ``numbers`` module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -204,6 +321,12 @@ of columns. A new format 2.0 has been added which extends the header size to 4
 GiB. `np.save` will automatically save in 2.0 format if the data requires it,
 else it will always use the more compatible 1.0 format.
 
+Full broadcasting support for ``np.cross``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``np.cross`` now properly broadcasts its two input arrays, even if they
+have different number of dimensions. In earlier versions this would result
+in either an error being raised, or wrong results computed.
+
 
 Improvements
 ============
@@ -227,12 +350,6 @@ data type's ``compare`` function to perform the search, but is now
 implemented by type specific functions. Depending on the size of the
 inputs, this can result in performance improvements over 2x.
 
-Full broadcasting support for ``np.cross``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``np.cross`` now properly broadcasts its two input arrays, even if they
-have different number of dimensions. In earlier versions this would result
-in either an error being raised, or wrong results computed.
-
 Optional reduced verbosity for np.distutils
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Set ``numpy.distutils.system_info.system_info.verbosity = 0`` and then
@@ -265,128 +382,6 @@ Built-in assumptions that the baseclass behaved like a plain array are being
 removed. In particalur, ``repr`` and ``str`` should now work more reliably.
 
 
-Changes
-=======
-
-Argmin and argmax out argument
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``out`` argument to ``np.argmin`` and ``np.argmax`` and their
-equivalent C-API functions is now checked to match the desired output shape
-exactly.  If the check fails a ``ValueError`` instead of ``TypeError`` is
-raised.
-
-
-Einsum
-~~~~~~
-Remove unnecessary broadcasting notation restrictions.
-``np.einsum('ijk,j->ijk', A, B)`` can also be written as
-``np.einsum('ij...,j->ij...', A, B)`` (ellipsis is no longer required on 'j')
-
-
-Indexing
-~~~~~~~~
-
-The NumPy indexing has seen a complete rewrite in this version. This makes
-most advanced integer indexing operations much faster and should have no
-other implications.  However some subtle changes and deprecations were
-introduced in advanced indexing operations:
-
-* Boolean indexing into scalar arrays will always return a new 1-d array.
-  This means that ``array(1)[array(True)]`` gives ``array([1])`` and
-  not the original array.
-
-* Advanced indexing into one dimensional arrays used to have
-  (undocumented) special handling regarding repeating the value array in
-  assignments when the shape of the value array was too small or did not
-  match.  Code using this will raise an error. For compatibility you can
-  use ``arr.flat[index] = values``, which uses the old code branch.  (for
-  example ``a = np.ones(10); a[np.arange(10)] = [1, 2, 3]``)
-
-* The iteration order over advanced indexes used to be always C-order.
-  In NumPy 1.9. the iteration order adapts to the inputs and is not
-  guaranteed (with the exception of a *single* advanced index which is
-  never reversed for compatibility reasons). This means that the result
-  is undefined if multiple values are assigned to the same element.  An
-  example for this is ``arr[[0, 0], [1, 1]] = [1, 2]``, which may set
-  ``arr[0, 1]`` to either 1 or 2.
-
-* Equivalent to the iteration order, the memory layout of the advanced
-  indexing result is adapted for faster indexing and cannot be predicted.
-
-* All indexing operations return a view or a copy. No indexing operation
-  will return the original array object. (For example ``arr[...]``)
-
-* In the future Boolean array-likes (such as lists of python bools) will
-  always be treated as Boolean indexes and Boolean scalars (including
-  python ``True``) will be a legal *boolean* index. At this time, this is
-  already the case for scalar arrays to allow the general
-  ``positive = a[a > 0]`` to work when ``a`` is zero dimensional.
-
-* In NumPy 1.8 it was possible to use ``array(True)`` and
-  ``array(False)`` equivalent to 1 and 0 if the result of the operation
-  was a scalar.  This will raise an error in NumPy 1.9 and, as noted
-  above, treated as a boolean index in the future.
-
-* All non-integer array-likes are deprecated, object arrays of custom
-  integer like objects may have to be cast explicitly.
-
-* The error reporting for advanced indexing is more informative, however
-  the error type has changed in some cases. (Broadcasting errors of
-  indexing arrays are reported as ``IndexError``)
-
-* Indexing with more then one ellipsis (``...``) is deprecated.
-
-
-``promote_types`` and string dtype
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``promote_types`` function now returns a valid string length when given an
-integer or float dtype as one argument and a string dtype as another
-argument.  Previously it always returned the input string dtype, even if it
-wasn't long enough to store the max integer/float value converted to a
-string.
-
-
-``can_cast`` and string dtype
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``can_cast`` function now returns False in "safe" casting mode for
-integer/float dtype and string dtype if the string dtype length is not long
-enough to store the max integer/float value converted to a string.
-Previously ``can_cast`` in "safe" mode returned True for integer/float
-dtype and a string dtype of any length.
-
-
-astype and string dtype
-~~~~~~~~~~~~~~~~~~~~~~~
-The ``astype`` method now returns an error if the string dtype to cast to
-is not long enough in "safe" casting mode to hold the max value of
-integer/float array that is being casted. Previously the casting was
-allowed even if the result was truncated.
-
-
-NDIter
-~~~~~~
-When ``NpyIter_RemoveAxis`` is now called, the iterator range will be reset.
-
-When a multi index is being tracked and an iterator is not buffered, it is
-possible to use ``NpyIter_RemoveAxis``. In this case an iterator can shrink
-in size. Because the total size of an iterator is limited, the iterator
-may be too large before these calls. In this case its size will be set to ``-1``
-and an error issued not at construction time but when removing the multi
-index, setting the iterator range, or getting the next function.
-
-This has no effect on currently working code, but highlights the necessity
-of checking for an error return if these conditions can occur. In most
-cases the arrays being iterated are as large as the iterator so that such
-a problem cannot occur.
-
-This change was already applied to the 1.8.1 release.
-
-`npyio.recfromcsv` keyword arguments change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-`npyio.recfromcsv` no longer accepts the undocumented `update` keyword,
-which used to override the `dtype` keyword.
-
-
 C-API
 ~~~~~
 
diff --git a/doc/source/reference/swig.interface-file.rst b/doc/source/reference/swig.interface-file.rst
index d835a4c4f..c381feb85 100644
--- a/doc/source/reference/swig.interface-file.rst
+++ b/doc/source/reference/swig.interface-file.rst
@@ -166,7 +166,7 @@ assignments in lines 19 and 20.
 Using numpy.i
 -------------
 
-The ``numpy.i`` file is currently located in the ``numpy/docs/swig``
+The ``numpy.i`` file is currently located in the ``tools/swig``
 sub-directory under the ``numpy`` installation directory.  Typically,
 you will want to copy it to the directory where you are developing
 your wrappers.