========================== 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.masked`` is no longer writeable --------------------------------------- Attempts to mutate the ``masked`` constant now error, as the underlying arrays are marked readonly. In the past, it was possible to get away with:: # emulating a function that sometimes returns np.ma.masked val = random.choice([np.ma.masked, 10]) var_arr = np.asarray(val) val_arr += 1 # now errors, previously changed np.ma.masked.data ``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 `` 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. ``concatenate`` and ``stack`` gained an ``out`` argument -------------------------------------------------------- A preallocated buffer of the desired dtype can now be used for the output of these functions. ``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. User-defined types now need to implement ``__str__`` and ``__repr__`` --------------------------------------------------------------------- Previously, user-defined types could fall back to a default implementation of ``__str__`` and ``__repr__`` implemented in numpy, but this has now been removed. Now user-defined types will fall back to the python default ``object.__str__`` and ``object.__repr__``. ``np.linalg.matrix_rank`` is more efficient for hermitian matrices ------------------------------------------------------------------ The keyword argument ``hermitian`` was added to toggle between standard SVD-based matrix rank calculation and the more efficient eigenvalue-based method for symmetric/hermitian matrices. Integer and Void scalars are now unaffected by ``np.set_string_function`` ------------------------------------------------------------------------- Previously the ``str`` and ``repr`` of integer and void 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. ``sign`` option added to ``np.setprintoptions`` and ``np.array2string`` ----------------------------------------------------------------------- This option controls printing of the sign of floating-point types, and may be one of the characters '-', '+' or ' ', or the string 'legacy'. With '+' numpy always prints the sign of positive values, with ' ' it always prints a space (whitespace character) in the sign position of positive values, and with '-' it will omit the sign character for positive values, and with 'legacy' it will behave like ' ' except no space is printed in 0d arrays. The new default is '-'. Unneeded whitespace in float array printing removed --------------------------------------------------- The new default of ``sign='-'`` (see last note) means that the ``repr`` of float arrays now often omits the whitespace characters previously used to display the sign. This new behavior can be disabled to mostly reproduce numpy 1.13 behavior by calling ``np.set_printoptions(sign='legacy')``. ``threshold`` and ``edgeitems`` options added to ``np.array2string`` ----------------------------------------------------------------- These options could previously be controlled using ``np.set_printoptions``, but now can be changed on a per-call basis as arguments to ``np.array2string``.