1========================= 2NumPy 1.7.0 Release Notes 3========================= 4 5This release includes several new features as well as numerous bug fixes and 6refactorings. It supports Python 2.4 - 2.7 and 3.1 - 3.3 and is the last 7release that supports Python 2.4 - 2.5. 8 9Highlights 10========== 11 12* ``where=`` parameter to ufuncs (allows the use of boolean arrays to choose 13 where a computation should be done) 14* ``vectorize`` improvements (added 'excluded' and 'cache' keyword, general 15 cleanup and bug fixes) 16* ``numpy.random.choice`` (random sample generating function) 17 18 19Compatibility notes 20=================== 21 22In a future version of numpy, the functions np.diag, np.diagonal, and the 23diagonal method of ndarrays will return a view onto the original array, 24instead of producing a copy as they do now. This makes a difference if you 25write to the array returned by any of these functions. To facilitate this 26transition, numpy 1.7 produces a FutureWarning if it detects that you may 27be attempting to write to such an array. See the documentation for 28np.diagonal for details. 29 30Similar to np.diagonal above, in a future version of numpy, indexing a 31record array by a list of field names will return a view onto the original 32array, instead of producing a copy as they do now. As with np.diagonal, 33numpy 1.7 produces a FutureWarning if it detects that you may be attempting 34to write to such an array. See the documentation for array indexing for 35details. 36 37In a future version of numpy, the default casting rule for UFunc out= 38parameters will be changed from 'unsafe' to 'same_kind'. (This also applies 39to in-place operations like a += b, which is equivalent to np.add(a, b, 40out=a).) Most usages which violate the 'same_kind' rule are likely bugs, so 41this change may expose previously undetected errors in projects that depend 42on NumPy. In this version of numpy, such usages will continue to succeed, 43but will raise a DeprecationWarning. 44 45Full-array boolean indexing has been optimized to use a different, 46optimized code path. This code path should produce the same results, 47but any feedback about changes to your code would be appreciated. 48 49Attempting to write to a read-only array (one with ``arr.flags.writeable`` 50set to ``False``) used to raise either a RuntimeError, ValueError, or 51TypeError inconsistently, depending on which code path was taken. It now 52consistently raises a ValueError. 53 54The <ufunc>.reduce functions evaluate some reductions in a different order 55than in previous versions of NumPy, generally providing higher performance. 56Because of the nature of floating-point arithmetic, this may subtly change 57some results, just as linking NumPy to a different BLAS implementations 58such as MKL can. 59 60If upgrading from 1.5, then generally in 1.6 and 1.7 there have been 61substantial code added and some code paths altered, particularly in the 62areas of type resolution and buffered iteration over universal functions. 63This might have an impact on your code particularly if you relied on 64accidental behavior in the past. 65 66New features 67============ 68 69Reduction UFuncs Generalize axis= Parameter 70------------------------------------------- 71 72Any ufunc.reduce function call, as well as other reductions like sum, prod, 73any, all, max and min support the ability to choose a subset of the axes to 74reduce over. Previously, one could say axis=None to mean all the axes or 75axis=# to pick a single axis. Now, one can also say axis=(#,#) to pick a 76list of axes for reduction. 77 78Reduction UFuncs New keepdims= Parameter 79---------------------------------------- 80 81There is a new keepdims= parameter, which if set to True, doesn't throw 82away the reduction axes but instead sets them to have size one. When this 83option is set, the reduction result will broadcast correctly to the 84original operand which was reduced. 85 86Datetime support 87---------------- 88 89.. note:: The datetime API is *experimental* in 1.7.0, and may undergo changes 90 in future versions of NumPy. 91 92There have been a lot of fixes and enhancements to datetime64 compared 93to NumPy 1.6: 94 95* the parser is quite strict about only accepting ISO 8601 dates, with a few 96 convenience extensions 97* converts between units correctly 98* datetime arithmetic works correctly 99* business day functionality (allows the datetime to be used in contexts where 100 only certain days of the week are valid) 101 102The notes in `doc/source/reference/arrays.datetime.rst <https://github.com/numpy/numpy/blob/maintenance/1.7.x/doc/source/reference/arrays.datetime.rst>`_ 103(also available in the online docs at `arrays.datetime.html 104<https://docs.scipy.org/doc/numpy/reference/arrays.datetime.html>`_) should be 105consulted for more details. 106 107Custom formatter for printing arrays 108------------------------------------ 109 110See the new ``formatter`` parameter of the ``numpy.set_printoptions`` 111function. 112 113New function numpy.random.choice 114-------------------------------- 115 116A generic sampling function has been added which will generate samples from 117a given array-like. The samples can be with or without replacement, and 118with uniform or given non-uniform probabilities. 119 120New function isclose 121-------------------- 122 123Returns a boolean array where two arrays are element-wise equal within a 124tolerance. Both relative and absolute tolerance can be specified. 125 126Preliminary multi-dimensional support in the polynomial package 127--------------------------------------------------------------- 128 129Axis keywords have been added to the integration and differentiation 130functions and a tensor keyword was added to the evaluation functions. 131These additions allow multi-dimensional coefficient arrays to be used in 132those functions. New functions for evaluating 2-D and 3-D coefficient 133arrays on grids or sets of points were added together with 2-D and 3-D 134pseudo-Vandermonde matrices that can be used for fitting. 135 136 137Ability to pad rank-n arrays 138---------------------------- 139 140A pad module containing functions for padding n-dimensional arrays has been 141added. The various private padding functions are exposed as options to a 142public 'pad' function. Example:: 143 144 pad(a, 5, mode='mean') 145 146Current modes are ``constant``, ``edge``, ``linear_ramp``, ``maximum``, 147``mean``, ``median``, ``minimum``, ``reflect``, ``symmetric``, ``wrap``, and 148``<function>``. 149 150 151New argument to searchsorted 152---------------------------- 153 154The function searchsorted now accepts a 'sorter' argument that is a 155permutation array that sorts the array to search. 156 157Build system 158------------ 159 160Added experimental support for the AArch64 architecture. 161 162C API 163----- 164 165New function ``PyArray_RequireWriteable`` provides a consistent interface 166for checking array writeability -- any C code which works with arrays whose 167WRITEABLE flag is not known to be True a priori, should make sure to call 168this function before writing. 169 170NumPy C Style Guide added (``doc/C_STYLE_GUIDE.rst.txt``). 171 172Changes 173======= 174 175General 176------- 177 178The function np.concatenate tries to match the layout of its input arrays. 179Previously, the layout did not follow any particular reason, and depended 180in an undesirable way on the particular axis chosen for concatenation. A 181bug was also fixed which silently allowed out of bounds axis arguments. 182 183The ufuncs logical_or, logical_and, and logical_not now follow Python's 184behavior with object arrays, instead of trying to call methods on the 185objects. For example the expression (3 and 'test') produces the string 186'test', and now np.logical_and(np.array(3, 'O'), np.array('test', 'O')) 187produces 'test' as well. 188 189The ``.base`` attribute on ndarrays, which is used on views to ensure that the 190underlying array owning the memory is not deallocated prematurely, now 191collapses out references when you have a view-of-a-view. For example:: 192 193 a = np.arange(10) 194 b = a[1:] 195 c = b[1:] 196 197In numpy 1.6, ``c.base`` is ``b``, and ``c.base.base`` is ``a``. In numpy 1.7, 198``c.base`` is ``a``. 199 200To increase backwards compatibility for software which relies on the old 201behaviour of ``.base``, we only 'skip over' objects which have exactly the same 202type as the newly created view. This makes a difference if you use ``ndarray`` 203subclasses. For example, if we have a mix of ``ndarray`` and ``matrix`` objects 204which are all views on the same original ``ndarray``:: 205 206 a = np.arange(10) 207 b = np.asmatrix(a) 208 c = b[0, 1:] 209 d = c[0, 1:] 210 211then ``d.base`` will be ``b``. This is because ``d`` is a ``matrix`` object, 212and so the collapsing process only continues so long as it encounters other 213``matrix`` objects. It considers ``c``, ``b``, and ``a`` in that order, and 214``b`` is the last entry in that list which is a ``matrix`` object. 215 216Casting Rules 217------------- 218 219Casting rules have undergone some changes in corner cases, due to the 220NA-related work. In particular for combinations of scalar+scalar: 221 222* the `longlong` type (`q`) now stays `longlong` for operations with any other 223 number (`? b h i l q p B H I`), previously it was cast as `int_` (`l`). The 224 `ulonglong` type (`Q`) now stays as `ulonglong` instead of `uint` (`L`). 225 226* the `timedelta64` type (`m`) can now be mixed with any integer type (`b h i l 227 q p B H I L Q P`), previously it raised `TypeError`. 228 229For array + scalar, the above rules just broadcast except the case when 230the array and scalars are unsigned/signed integers, then the result gets 231converted to the array type (of possibly larger size) as illustrated by the 232following examples:: 233 234 >>> (np.zeros((2,), dtype=np.uint8) + np.int16(257)).dtype 235 dtype('uint16') 236 >>> (np.zeros((2,), dtype=np.int8) + np.uint16(257)).dtype 237 dtype('int16') 238 >>> (np.zeros((2,), dtype=np.int16) + np.uint32(2**17)).dtype 239 dtype('int32') 240 241Whether the size gets increased depends on the size of the scalar, for 242example:: 243 244 >>> (np.zeros((2,), dtype=np.uint8) + np.int16(255)).dtype 245 dtype('uint8') 246 >>> (np.zeros((2,), dtype=np.uint8) + np.int16(256)).dtype 247 dtype('uint16') 248 249Also a ``complex128`` scalar + ``float32`` array is cast to ``complex64``. 250 251In NumPy 1.7 the `datetime64` type (`M`) must be constructed by explicitly 252specifying the type as the second argument (e.g. ``np.datetime64(2000, 'Y')``). 253 254 255Deprecations 256============ 257 258General 259------- 260 261Specifying a custom string formatter with a `_format` array attribute is 262deprecated. The new `formatter` keyword in ``numpy.set_printoptions`` or 263``numpy.array2string`` can be used instead. 264 265The deprecated imports in the polynomial package have been removed. 266 267``concatenate`` now raises DepractionWarning for 1D arrays if ``axis != 0``. 268Versions of numpy < 1.7.0 ignored axis argument value for 1D arrays. We 269allow this for now, but in due course we will raise an error. 270 271C-API 272----- 273 274Direct access to the fields of PyArrayObject* has been deprecated. Direct 275access has been recommended against for many releases. Expect similar 276deprecations for PyArray_Descr* and other core objects in the future as 277preparation for NumPy 2.0. 278 279The macros in old_defines.h are deprecated and will be removed in the next 280major release (>= 2.0). The sed script tools/replace_old_macros.sed can be 281used to replace these macros with the newer versions. 282 283You can test your code against the deprecated C API by adding a line 284composed of ``#define NPY_NO_DEPRECATED_API`` and the target version number, 285such as ``NPY_1_7_API_VERSION``, before including any NumPy headers. 286 287The ``NPY_CHAR`` member of the ``NPY_TYPES`` enum is deprecated and will be 288removed in NumPy 1.8. See the discussion at 289`gh-2801 <https://github.com/numpy/numpy/issues/2801>`_ for more details. 290