path: root/doc/release/1.14.0-notes.rst

==========================
NumPy 1.14.0 Release Notes
==========================

This release supports Python 2.7 and 3.4 - 3.6.


Highlights
==========

* The `np.einsum` function will use BLAS when possible


New functions
=============

* ``parametrize``: decorator added to numpy.testing
* ``chebinterpolate``: Interpolate function at Chebyshev points.


Deprecations
============


Future Changes
==============

``np.issubdtype`` will stop downcasting dtype-like arguments
------------------------------------------------------------
It would be expected that ``issubdtype(np.float32, 'float64')`` and
``issubdtype(np.float32, np.float64)`` mean the same thing - however, there
was an undocumented special case that translated the former into
``issubdtype(np.float32, np.floating)``, giving the surprising result of True.

This translation now gives a warning explaining what translation is occuring.
In future, the translation will be disabled, and the first example will be made
equivalent to the second.

``np.linalg.lstsq`` default for ``rcond`` will be changed
---------------------------------------------------------

The ``rcond`` parameter to ``np.linalg.lstsq`` will change its default to the
better value of machine precision times the maximum of the input matrix
dimensions. A FutureWarning is given if the parameter is not passed explicitly.
* ``a.flat.__array__()`` will return a writeable copy of ``a`` when ``a`` is
  non-contiguous. Previously it returned an UPDATEIFCOPY array when ``a`` was
  writeable. Currently it returns a non-writeable copy. See gh-7054 for a
  discussion of the issue.



Build System Changes
====================


Compatibility notes
===================

``a.flat.__array__()`` returns non-writeable arrays when ``a`` is non-contiguous
--------------------------------------------------------------------------------
The intent is that the UPDATEIFCOPY array previously returned when ``a`` was
non-contiguous will be replaced by a writeable copy in the future. This
temporary measure is aimed to notify folks who expect the underlying array be
modified in this situation that that will no longer be the case. The most
likely places for this to be noticed is when expressions of the form
``np.asarray(a.flat)`` are used, or when ``a.flat`` is passed as the out
parameter to a ufunc.

``np.tensordot`` now returns zero array when contracting over 0-length dimension
--------------------------------------------------------------------------------
Previously ``np.tensordot`` raised a ValueError when contracting over 0-length
dimension. Now it returns a zero array, which is consistent with the behaviour
of ``np.dot`` and ``np.einsum``.

``np.ma`` functions producing ``fill_value``s have changed
----------------------------------------------------------
Previously, ``np.ma.default_fill_value`` would return a 0d array, but
``np.ma.minimum_fill_value`` and ``np.ma.maximum_fill_value`` would return a
tuple of the fields. Instead, all three methods return a structured ``np.void``
object, which is what you would already find in the ``.fill_value`` attribute.

Additionally, the dtype guessing now matches that of ``np.array`` - so when
passing a python scalar ``x``, ``maximum_fill_value(x)`` is always the same as
``maximum_fill_value(np.array(x))``. Previously ``x = long(1)`` on Python 2
violated this assumption.

``numpy.testing`` reorganized
-----------------------------
This is not expected to cause problems, but possibly something has been left
out. If you experience an unexpected import problem using ``numpy.testing``
let us know.

``np.asfarray`` no longer accepts non-dtypes through the ``dtype`` argument
---------------------------------------------------------------------------
This previously would accept ``dtype=some_array``, with the implied semantics
of ``dtype=some_array.dtype``. This was undocumented, unique across the numpy
functions, and if used would likely correspond to a typo.

1D ``np.linalg.norm`` preserves float input types, even for arbitrary orders
----------------------------------------------------------------------------
Previously, this would promote to ``float64`` when arbitrary orders were
passed, despite not doing so under the simple cases::

    >>> f32 = np.float32([1, 2])
    >>> np.linalg.norm(f32, 2.0).dtype
    dtype('float32')
    >>> np.linalg.norm(f32, 2.0001).dtype
    dtype('float64')  # numpy 1.13
    dtype('float32')  # numpy 1.14

This change affects only ``float32`` and ``float16`` arrays.

``__init__.py`` files added to test directories
-----------------------------------------------
This is for pytest compatibility in the case of duplicate test file names in
the different directories. As a result, ``run_module_suite`` no longer works,
i.e., ``python <path-to-test-file>`` results in an error.

``MaskedArray.squeeze`` never returns ``np.ma.masked``
------------------------------------------------------
``np.squeeze`` is documented as returning a view, but the masked variant would
sometimes return ``masked``, which is not a view. This has been fixed, so that
the result is always a view on the original masked array.
This breaks any code that used ``masked_arr.squeeze() is np.ma.masked``, but
fixes code that writes to the result of `.squeeze()`.

Renamed first parameter of ``can_cast`` from ``from`` to ``from_``
------------------------------------------------------------------
The previous parameter name ``from`` is a reserved keyword in Python, which made
it difficult to pass the argument by name. This has been fixed by renaming
the parameter to ``from_``.


C API changes
=============


New Features
============

External ``nose`` plugins are usable by ``numpy.testing.Tester``
----------------------------------------------------------------
``numpy.testing.Tester`` is now aware of ``nose`` plugins that are outside the
``nose`` built-in ones.  This allows using, for example, ``nose-timer`` like
so:  ``np.test(extra_argv=['--with-timer', '--timer-top-n', '20'])`` to
obtain the runtime of the 20 slowest tests.  An extra keyword ``timer`` was
also added to ``Tester.test``, so ``np.test(timer=20)`` will also report the 20
slowest tests.

``parametrize`` decorator added to ``numpy.testing``
----------------------------------------------------
A basic ``parametrize`` decorator is now available in ``numpy.testing``. It is
intended to allow rewriting yield based tests that have been deprecated in
pytest so as to facilitate the transition to pytest in the future. The nose
testing framework has not been supported for several years and looks like
abandonware.

The new ``parametrize`` decorator does not have the full functionality of the
one in pytest. It doesn't work for classes, doesn't support nesting, and does
not substitute variable names. Even so, it should be adequate to rewrite the
NumPy tests.

``chebinterpolate`` function added to ``numpy.polynomial.chebyshev``
--------------------------------------------------------------------
The new ``chebinterpolate`` function interpolates a given function at the
Chebyshev points of the first kind. A new ``Chebyshev.interpolate`` class
method adds support for interpolation over arbitrary intervals using the scaled
and shifted Chebyshev points of the first kind.


Improvements
============

Numerator degrees of freedom in ``random.noncentral_f`` need only be positive.
------------------------------------------------------------------------------
Prior to NumPy 1.14.0, the numerator degrees of freedom needed to be > 1, but
the distribution is valid for values > 0, which is the new requirement.

The GIL is released for all ``np.einsum`` variations
----------------------------------------------------
Some specific loop structures which have an accelerated loop version
did not release the GIL prior to NumPy 1.14.0.  This oversight has been
fixed.

The `np.einsum` function will use BLAS when possible and optimize by default
----------------------------------------------------------------------------
The ``np.einsum`` function will now call ``np.tensordot`` when appropriate.
Because ``np.tensordot`` uses BLAS when possible, that will speed up execution.
By default, ``np.einsum`` will also attempt optimization as the overhead is
small relative to the potential improvement in speed.

The ``repr`` of ``np.polynomial`` classes is more explicit
----------------------------------------------------------
It now shows the domain and window parameters as keyword arguments to make
them more clear::

    >>> np.polynomial.Polynomial(range(4))
    Polynomial([ 0.,  1.,  2.,  3.], domain=[-1,  1], window=[-1,  1])

f2py now handles arrays of dimension 0
--------------------------------------
f2py now allows for the allocation of arrays of dimension 0. This allows for
more consistent handling of corner cases downstream.

``numpy.distutils`` supports using MSVC and mingw64-gfortran together
---------------------------------------------------------------------

Numpy distutils now supports using MSVC and Mingw64-gfortran compilers
together. This enables producing Python extension modules on Windows
containing Fortran code, while retaining compatibility with the
binaries distributed by Python.org. Not all use cases are supported,
but most common ways to wrap Fortran for Python are functional.

Compilation in this mode is usually enabled automatically, and can be
selected via the ``--fcompiler`` and ``--compiler`` options to
``setup.py``. Moreover, linking Fortran codes to static OpenBLAS is
supported; by default a gfortran-compatible static archive
``openblas.a`` is looked for.

``np.linalg.pinv`` now works on stacked matrices
------------------------------------------------
Previously it was limited to a single 2d array.

``numpy.save`` aligns data to 64 bytes instead of 16
----------------------------------------------------
Saving NumPy arrays in the ``npy`` format with ``numpy.save`` inserts
padding before the array data to align it at 64 bytes.  Previously
this was only 16 bytes (and sometimes less due to a bug in the code
for version 2).  Now the alignment is 64 bytes, which matches the
widest SIMD instruction set commonly available, and is also the most
common cache line size.  This makes ``npy`` files easier to use in
programs which open them with ``mmap``, especially on Linux where an
``mmap`` offset must be a multiple of the page size.


Changes
=======

0d arrays now print their elements like other arrays
----------------------------------------------------
0d arrays now use the array2string formatters to print their elements, like
other arrays. The ``style`` argument of ``array2string`` is now non-functional.

Integer scalars are now unaffected by ``np.set_string_function``
----------------------------------------------------------------
Previously the str/repr of integer scalars could be controlled by
``np.set_string_function``, unlike most other numpy scalars. This is no longer
the case.

Multiple-field indexing/assignment of structured arrays
-------------------------------------------------------
The indexing and assignment of structured arrays with multiple fields has
changed in a number of ways:

First, indexing a structured array with multiple fields (eg,
``arr[['f1', 'f3']]``) returns a view into the original array instead of a
copy. The returned view will have extra padding bytes corresponding to
intervening fields in the original array, unlike the copy in 1.13, which will
affect code such as ``arr[['f1', 'f3']].view(newdtype)``.

Second, assignment between structured arrays will now occur "by position"
instead of "by field name". The Nth field of the destination will be set to the
Nth field of the source regardless of field name, unlike in numpy versions 1.6
to 1.13 in which fields in the destination array were set to the
identically-named field in the source array or to 0 if the source did not have
a field.

Correspondingly, the order of fields in a structured dtypes now matters when
computing dtype equality. For example with the dtypes
`x = dtype({'names': ['A', 'B'], 'formats': ['i4', 'f4'], 'offsets': [0, 4]})`
`y = dtype({'names': ['B', 'A'], 'formats': ['f4', 'i4'], 'offsets': [4, 0]})`
now `x == y` will return `False`, unlike before. This makes dictionary-based
dtype specifications like `dtype({'a': ('i4', 0), 'b': ('f4', 4)})` dangerous
in python < 3.6 since dict key-order is not preserved in those versions.

Assignment from a structured array to a boolean array now raises a ValueError,
unlike in 1.13 where it always set the destination elements to `True`.

Assignment from structured array with more than one field to a non-structured
array now raises a ValueError. In 1.13 this copied just the first field of the
source to the destination.

Using field "titles" in multiple-field indexing is now disallowed, as is
repeating a field name in a multiple-field index.