Computes the inverse of rfftn.
This function computes the inverse of the N-dimensional discrete Fourier Transform for real input over any number of axes in an M-dimensional array by means of the Fast Fourier Transform (FFT). In other words, irfftn(rfftn(a), a.shape) == a to within numerical accuracy. (The a.shape is necessary like len(a) is for irfft, and for the same reason.)
The input should be ordered in the same way as is returned by rfftn, i.e. as for irfft for the final transformation axis, and as for ifftn along all the other axes.
Input array.
Shape (length of each transformed axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). s is also the number of input points used along this axis, except for the last axis, where s[-1]//2+1 points of the input are used. Along any axis, if the shape indicated by s is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. If s is not given, the shape of the input along the axes specified by axes is used. Except for the last axis which is taken to be 2*(m-1) where m is the length of the input along that axis.
Axes over which to compute the inverse FFT. If not given, the last len(s) axes are used, or all axes if s is also not specified. Repeated indices in axes means that the inverse transform over that axis is performed multiple times.
New in version 1.10.0.
Normalization mode (see numpy.fft). Default is “backward”. Indicates which direction of the forward/backward pair of transforms is scaled and with what normalization factor.
New in version 1.20.0: The “backward”, “forward” values were added.
The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s or a, as explained in the parameters section above. The length of each transformed axis is as given by the corresponding element of s, or the length of the input in every axis except for the last one if s is not given. In the final transformed axis the length of the output when s is not given is 2*(m-1) where m is the length of the final transformed axis of the input. To get an odd number of output points in the final axis, s must be specified.
If s and axes have different length.
If an element of axes is larger than than the number of axes of a.
See also
The forward n-dimensional FFT of real input, of which ifftn is the inverse.
The one-dimensional FFT, with definitions and conventions used.
The inverse of the one-dimensional FFT of real input.
The inverse of the two-dimensional FFT of real input.
See fft for definitions and conventions used.
See rfft for definitions and conventions used for real input.
The correct interpretation of the hermitian input depends on the shape of the original data, as given by s. This is because each input shape could correspond to either an odd or even length signal. By default, irfftn assumes an even output length which puts the last entry at the Nyquist frequency; aliasing with its symmetric counterpart. When performing the final complex to real transform, the last value is thus treated as purely real. To avoid losing information, the correct shape of the real input must be given.


Compute the one-dimensional discrete Fourier Transform for real input.
This function computes the one-dimensional n-point discrete Fourier Transform (DFT) of a real-valued array by means of an efficient algorithm called the Fast Fourier Transform (FFT).
Input array
Number of points along transformation axis in the input to use. If n is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.
Axis over which to compute the FFT. If not given, the last axis is used.
New in version 1.10.0.
Normalization mode (see numpy.fft). Default is “backward”. Indicates which direction of the forward/backward pair of transforms is scaled and with what normalization factor.
New in version 1.20.0: The “backward”, “forward” values were added.
The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified. If n is even, the length of the transformed axis is (n/2)+1. If n is odd, the length is (n+1)/2.
If axis is not a valid axis of a.
See also
For definition of the DFT and conventions used.
The inverse of rfft.
The one-dimensional FFT of general (complex) input.
The n-dimensional FFT.
The n-dimensional FFT of real input.
When the DFT is computed for purely real input, the output is Hermitian-symmetric, i.e. the negative frequency terms are just the complex conjugates of the corresponding positive-frequency terms, and the negative-frequency terms are therefore redundant. This function does not compute the negative frequency terms, and the length of the transformed axis of the output is therefore n//2 + 1.
When A = rfft(a) and fs is the sampling frequency, A[0] contains the zero-frequency term 0*fs, which is real due to Hermitian symmetry.
If n is even, A[-1] contains the term representing both positive and negative Nyquist frequency (+fs/2 and -fs/2), and must also be purely real. If n is odd, there is no term at fs/2; A[-1] contains the largest positive frequency (fs/2*(n-1)/n), and is complex in the general case.
If the input a contains an imaginary part, it is silently discarded.
Notice how the final element of the fft output is the complex conjugate of the second element, for real input. For rfft, this symmetry is exploited to compute only the non-negative frequency terms.


Compute the 2-dimensional FFT of a real array.
Input array, taken to be real.
Shape of the FFT.
Axes over which to compute the FFT.
New in version 1.10.0.
Normalization mode (see numpy.fft). Default is “backward”. Indicates which direction of the forward/backward pair of transforms is scaled and with what normalization factor.
New in version 1.20.0: The “backward”, “forward” values were added.
The result of the real 2-D FFT.
See also
Compute the N-dimensional discrete Fourier Transform for real input.
This is really just rfftn with different default behavior. For more details see rfftn.


Return the Discrete Fourier Transform sample frequencies (for usage with rfft, irfft).
The returned float array f contains the frequency bin centers in cycles per unit of the sample spacing (with zero at the start). For instance, if the sample spacing is in seconds, then the frequency unit is cycles/second.
Given a window length n and a sample spacing d:
Unlike fftfreq (but like scipy.fftpack.rfftfreq) the Nyquist frequency component is considered to be positive.
Window length.
Sample spacing (inverse of the sampling rate). Defaults to 1.
Array of length n//2 + 1 containing the sample frequencies.


Compute the N-dimensional discrete Fourier Transform for real input.
This function computes the N-dimensional discrete Fourier Transform over any number of axes in an M-dimensional real array by means of the Fast Fourier Transform (FFT). By default, all axes are transformed, with the real transform performed over the last axis, while the remaining transforms are complex.
Input array, taken to be real.
Shape (length along each transformed axis) to use from the input. (s[0] refers to axis 0, s[1] to axis 1, etc.). The final element of s corresponds to n for rfft(x, n), while for the remaining axes, it corresponds to n for fft(x, n). Along any axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used.
Axes over which to compute the FFT. If not given, the last len(s) axes are used, or all axes if s is also not specified.
New in version 1.10.0.
Normalization mode (see numpy.fft). Default is “backward”. Indicates which direction of the forward/backward pair of transforms is scaled and with what normalization factor.
New in version 1.20.0: The “backward”, “forward” values were added.
The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s and a, as explained in the parameters section above. The length of the last axis transformed will be s[-1]//2+1, while the remaining transformed axes will have lengths according to s, or unchanged from the input.
If s and axes have different length.
If an element of axes is larger than than the number of axes of a.
See also
The inverse of rfftn, i.e. the inverse of the n-dimensional FFT of real input.
The one-dimensional FFT, with definitions and conventions used.
The one-dimensional FFT of real input.
The n-dimensional FFT.
The two-dimensional FFT of real input.
The transform for real input is performed over the last transformation axis, as by rfft, then the transform over the remaining axes is performed as by fftn. The order of the output is as for rfft for the final transformation axis, and as for fftn for the remaining transformation axes.
See fft for details, definitions and conventions used.


attribute
A reference to the array that is iterated over.


attribute
An N-dimensional tuple of current coordinates.


method
Get a copy of the iterator as a 1-D array.


attribute
Current flat index into the array.


method
sc.__array__(dtype) return 0-dim array from scalar with specified dtype


method
sc.__array_wrap__(obj) return scalar from array


attribute
Scalar attribute identical to the corresponding array attribute.
Please see ndarray.base.


method
Scalar method identical to the corresponding array attribute.
Please see ndarray.byteswap.


attribute
The imaginary part of the scalar.


attribute
The length of one element in bytes.


attribute
The number of array dimensions.


method
Scalar method identical to the corresponding array attribute.
Please see ndarray.setflags.


attribute
The number of elements in the gentype.


method
Scalar method identical to the corresponding array attribute.
Please see ndarray.squeeze.


attribute
Tuple of bytes steps in each dimension.


attribute
Scalar attribute identical to the corresponding array attribute.
Please see ndarray.T.


Return a path to a temporary directory where temporary files should be placed.


Returns the numpy.distutils config command instance.


Return the distutils distribution object for self.


Get resources information.
Return information (from system_info.get_info) for all of the names in the argument list in a single dictionary.


Return list of subpackage configurations.
Name of the subpackage to get the configuration. ‘*’ in subpackage_name is handled as a wildcard.
If None, then the path is assumed to be the local path plus the subpackage_name. If a setup.py file is not found in the subpackage_path, then a default configuration is used.
Parent name.


Try to get version string of a package.
Return a version string of the current package or None if the version information could not be detected.
This method scans files named __version__.py, <packagename>_version.py, version.py, and __svn_version__.py for string variables version, __version__, and <packagename>_version, until a version number is found.


Check for availability of Fortran 77 compiler.
Use it inside source generating function to ensure that setup distribution instance has been initialized.
True if a Fortran 77 compiler is available (because a simple Fortran 77 code was able to be compiled successfully).


Check for availability of Fortran 90 compiler.
Use it inside source generating function to ensure that setup distribution instance has been initialized.
True if a Fortran 90 compiler is available (because a simple Fortran 90 code was able to be compiled successfully)


The Simple Wrapper and Interface Generator (or SWIG) is a powerful tool for generating wrapper code for interfacing to a wide variety of scripting languages. SWIG can parse header files, and using only the code prototypes, create an interface to the target language. But SWIG is not omnipotent. For example, it cannot know from the prototype:
what exactly seq is. Is it a single value to be altered in-place? Is it an array, and if so what is its length? Is it input-only? Output-only? Input-output? SWIG cannot determine these details, and does not attempt to do so.
If we designed rms, we probably made it a routine that takes an input-only array of length n of double values called seq and returns the root mean square. The default behavior of SWIG, however, will be to create a wrapper function that compiles, but is nearly impossible to use from the scripting language in the way the C routine was intended.
For Python, the preferred way of handling contiguous (or technically, strided) blocks of homogeneous data is with NumPy, which provides full object-oriented access to multidimensial arrays of data. Therefore, the most logical Python interface for the rms function would be (including doc string):
where seq would be a NumPy array of double values, and its length n would be extracted from seq internally before being passed to the C routine. Even better, since NumPy supports construction of arrays from arbitrary Python sequences, seq itself could be a nearly arbitrary sequence (so long as each element can be converted to a double) and the wrapper code would internally convert it to a NumPy array before extracting its data and length.
SWIG allows these types of conversions to be defined via a mechanism called typemaps. This document provides information on how to use numpy.i, a SWIG interface file that defines a series of typemaps intended to make the type of array-related conversions described above relatively simple to implement. For example, suppose that the rms function prototype defined above was in a header file named rms.h. To obtain the Python interface discussed above, your SWIG interface file would need the following:
Typemaps are keyed off a list of one or more function arguments, either by type or by type and name. We will refer to such lists as signatures. One of the many typemaps defined by numpy.i is used above and has the signature (double* IN_ARRAY1, int DIM1). The argument names are intended to suggest that the double* argument is an input array of one dimension and that the int represents the size of that dimension. This is precisely the pattern in the rms prototype.
Most likely, no actual prototypes to be wrapped will have the argument names IN_ARRAY1 and DIM1. We use the SWIG %apply directive to apply the typemap for one-dimensional input arrays of type double to the actual prototype used by rms. Using numpy.i effectively, therefore, requires knowing what typemaps are available and what they do.
A SWIG interface file that includes the SWIG directives given above will produce wrapper code that looks something like:
The typemaps from numpy.i are responsible for the following lines of code: 12–20, 25 and 30. Line 10 parses the input to the rms function. From the format string "O:rms", we can see that the argument list is expected to be a single Python object (specified by the O before the colon) and whose pointer is stored in obj0. A number of functions, supplied by numpy.i, are called to make and check the (possible) conversion from a generic Python object to a NumPy array. These functions are explained in the section Helper Functions, but hopefully their names are self-explanatory. At line 12 we use obj0 to construct a NumPy array. At line 17, we check the validity of the result: that it is non-null and that it has a single dimension of arbitrary length. Once these states are verified, we extract the data buffer and length in lines 19 and 20 so that we can call the underlying C function at line 22. Line 25 performs memory management for the case where we have created a new array that is no longer needed.
This code has a significant amount of error handling. Note the SWIG_fail is a macro for goto fail, referring to the label at line 28. If the user provides the wrong number of arguments, this will be caught at line 10. If construction of the NumPy array fails or produces an array with the wrong number of dimensions, these errors are caught at line 17. And finally, if an error is detected, memory is still managed correctly at line 30.
Note that if the C function signature was in a different order:
that SWIG would not match the typemap signature given above with the argument list for rms. Fortunately, numpy.i has a set of typemaps with the data pointer given last:
This simply has the effect of switching the definitions of arg1 and arg2 in lines 3 and 4 of the generated code above, and their assignments in lines 19 and 20.
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.
A simple module that only uses a single SWIG interface file should include the following:
Within a compiled Python module, import_array() should only get called once. This could be in a C/C++ file that you have written and is linked to the module. If this is the case, then none of your interface files should #define SWIG_FILE_WITH_INIT or call import_array(). Or, this initialization call could be in a wrapper file generated by SWIG from an interface file that has the %init block as above. If this is the case, and you have more than one SWIG interface file, then only one interface file should #define SWIG_FILE_WITH_INIT and call import_array().
The typemap directives provided by numpy.i for arrays of different data types, say double and int, and dimensions of different types, say int or long, are identical to one another except for the C and NumPy type specifications. The typemaps are therefore implemented (typically behind the scenes) via a macro:
that can be invoked for appropriate (DATA_TYPE, DATA_TYPECODE,
DIM_TYPE) triplets. For example:
The numpy.i interface file uses the %numpy_typemaps macro to implement typemaps for the following C data types and int dimension types:
In the following descriptions, we reference a generic DATA_TYPE, which could be any of the C data types listed above, and DIM_TYPE which should be one of the many types of integers.
The typemap signatures are largely differentiated on the name given to the buffer pointer. Names with FARRAY are for Fortran-ordered arrays, and names with ARRAY are for C-ordered (or 1D arrays).
Input arrays are defined as arrays of data that are passed into a routine but are not altered in-place or returned to the user. The Python input array is therefore allowed to be almost any Python sequence (such as a list) that can be converted to the requested type of array. The input array signatures are
1D:
2D:
3D:
4D:
The first signature listed, ( DATA_TYPE IN_ARRAY[ANY] ) is for one-dimensional arrays with hard-coded dimensions. Likewise, ( DATA_TYPE IN_ARRAY2[ANY][ANY] ) is for two-dimensional arrays with hard-coded dimensions, and similarly for three-dimensional.
In-place arrays are defined as arrays that are modified in-place. The input values may or may not be used, but the values at the time the function returns are significant. The provided Python argument must therefore be a NumPy array of the required type. The in-place signatures are
1D:
2D:
3D:
4D:
These typemaps now check to make sure that the INPLACE_ARRAY arguments use native byte ordering. If not, an exception is raised.
There is also a “flat” in-place array for situations in which you would like to modify or process each element, regardless of the number of dimensions. One example is a “quantization” function that quantizes each element of an array in-place, be it 1D, 2D or whatever. This form checks for continuity but allows either C or Fortran ordering.
ND:
Argout arrays are arrays that appear in the input arguments in C, but are in fact output arrays. This pattern occurs often when there is more than one output variable and the single return argument is therefore not sufficient. In Python, the conventional way to return multiple arguments is to pack them into a sequence (tuple, list, etc.) and return the sequence. This is what the argout typemaps do. If a wrapped function that uses these argout typemaps has more than one return argument, they are packed into a tuple or list, depending on the version of Python. The Python user does not pass these arrays in, they simply get returned. For the case where a dimension is specified, the python user must provide that dimension as an argument. The argout signatures are
1D:
2D:
3D:
4D:
These are typically used in situations where in C/C++, you would allocate a(n) array(s) on the heap, and call the function to fill the array(s) values. In Python, the arrays are allocated for you and returned as new array objects.
Note that we support DATA_TYPE* argout typemaps in 1D, but not 2D or 3D. This is because of a quirk with the SWIG typemap syntax and cannot be avoided. Note that for these types of 1D typemaps, the Python function will take a single argument representing DIM1.
Argoutview arrays are for when your C code provides you with a view of its internal data and does not require any memory to be allocated by the user. This can be dangerous. There is almost no way to guarantee that the internal data from the C code will remain in existence for the entire lifetime of the NumPy array that encapsulates it. If the user destroys the object that provides the view of the data before destroying the NumPy array, then using that array may result in bad memory references or segmentation faults. Nevertheless, there are situations, working with large data sets, where you simply have no other choice.
The C code to be wrapped for argoutview arrays are characterized by pointers: pointers to the dimensions and double pointers to the data, so that these values can be passed back to the user. The argoutview typemap signatures are therefore
1D:
2D:
3D:
4D:
Note that arrays with hard-coded dimensions are not supported. These cannot follow the double pointer signatures of these typemaps.
A recent addition to numpy.i are typemaps that permit argout arrays with views into memory that is managed. See the discussion here.
1D:
2D:
3D:
4D:
The numpy.i interface file does not support typemaps for output arrays, for several reasons. First, C/C++ return arguments are limited to a single value. This prevents obtaining dimension information in a general way. Second, arrays with hard-coded lengths are not permitted as return arguments. In other words:
is not legal C/C++ syntax. Therefore, we cannot provide typemaps of the form:
If you run into a situation where a function or method is returning a pointer to an array, your best bet is to write your own version of the function to be wrapped, either with %extend for the case of class methods or %ignore and %rename for the case of functions.
Note that C++ type bool is not supported in the list in the Available Typemaps section. NumPy bools are a single byte, while the C++ bool is four bytes (at least on my system). Therefore:
will result in typemaps that will produce code that reference improper data lengths. You can implement the following macro expansion:
to fix the data length problem, and Input Arrays will work fine, but In-Place Arrays might fail type-checking.
Typemap conversions for complex floating-point types is also not supported automatically. This is because Python and NumPy are written in C, which does not have native complex types. Both Python and NumPy implement their own (essentially equivalent) struct definitions for complex variables:
We could have implemented:
which would have provided automatic type conversions for arrays of type Py_complex, npy_cfloat and npy_cdouble. However, it seemed unlikely that there would be any independent (non-Python, non-NumPy) application code that people would be using SWIG to generate a Python interface to, that also used these definitions for complex types. More likely, these application codes will define their own complex types, or in the case of C++, use std::complex. Assuming these data structures are compatible with Python and NumPy complex types, %numpy_typemap expansions as above (with the user’s complex type substituted for the first argument) should work.
SWIG has sophisticated type checking for numerical types. For example, if your C/C++ routine expects an integer as input, the code generated by SWIG will check for both Python integers and Python long integers, and raise an overflow error if the provided Python integer is too big to cast down to a C integer. With the introduction of NumPy scalar arrays into your Python code, you might conceivably extract an integer from a NumPy array and attempt to pass this to a SWIG-wrapped C/C++ function that expects an int, but the SWIG type checking will not recognize the NumPy array scalar as an integer. (Often, this does in fact work – it depends on whether NumPy recognizes the integer type you are using as inheriting from the Python integer type on the platform you are using. Sometimes, this means that code that works on a 32-bit machine will fail on a 64-bit machine.)
If you get a Python error that looks like the following:
and the argument you are passing is an integer extracted from a NumPy array, then you have stumbled upon this problem. The solution is to modify the SWIG type conversion system to accept NumPy array scalars in addition to the standard integer types. Fortunately, this capability has been provided for you. Simply copy the file:
to the working build directory for you project, and this problem will be fixed. It is suggested that you do this anyway, as it only increases the capabilities of your Python interface.
The SWIG type checking and conversion system is a complicated combination of C macros, SWIG macros, SWIG typemaps and SWIG fragments. Fragments are a way to conditionally insert code into your wrapper file if it is needed, and not insert it if not needed. If multiple typemaps require the same fragment, the fragment only gets inserted into your wrapper code once.
There is a fragment for converting a Python integer to a C long. There is a different fragment that converts a Python integer to a C int, that calls the routine defined in the long fragment. We can make the changes we want here by changing the definition for the long fragment. SWIG determines the active definition for a fragment using a “first come, first served” system. That is, we need to define the fragment for long conversions prior to SWIG doing it internally. SWIG allows us to do this by putting our fragment definitions in the file pyfragments.swg. If we were to put the new fragment definitions in numpy.i, they would be ignored.
The numpy.i file contains several macros and routines that it uses internally to build its typemaps. However, these functions may be useful elsewhere in your interface file. These macros and routines are implemented as fragments, which are described briefly in the previous section. If you try to use one or more of the following macros or functions, but your compiler complains that it does not recognize the symbol, then you need to force these fragments to appear in your code using:
in your SWIG interface file.
Evaluates as true if a is non-NULL and can be cast to a PyArrayObject*.
Evaluates to the integer data type code of a, assuming a can be cast to a PyArrayObject*.
Evaluates to the integer number of dimensions of a, assuming a can be cast to a PyArrayObject*.
Evaluates to an array of type npy_intp and length array_numdims(a), giving the lengths of all of the dimensions of a, assuming a can be cast to a PyArrayObject*.
Evaluates to the i-th dimension size of a, assuming a can be cast to a PyArrayObject*.
Evaluates to an array of type npy_intp and length array_numdims(a), giving the stridess of all of the dimensions of a, assuming a can be cast to a PyArrayObject*. A stride is the distance in bytes between an element and its immediate neighbor along the same axis.
Evaluates to the i-th stride of a, assuming a can be cast to a PyArrayObject*.
Evaluates to a pointer of type void* that points to the data buffer of a, assuming a can be cast to a PyArrayObject*.
Returns a borrowed reference to the dtype property (PyArray_Descr*) of a, assuming a can be cast to a PyArrayObject*.
Returns an integer representing the flags of a, assuming a can be cast to a PyArrayObject*.
Sets the flag represented by f of a, assuming a can be cast to a PyArrayObject*.
Evaluates as true if a is a contiguous array. Equivalent to (PyArray_ISCONTIGUOUS(a)).
Evaluates as true if the data buffer of a uses native byte order. Equivalent to (PyArray_ISNOTSWAPPED(a)).
Evaluates as true if a is FORTRAN ordered.
pytype_string()
Return type: const char*
Arguments:
Return a string describing the type of py_obj.
typecode_string()
Return type: const char*
Arguments:
Return a string describing the type corresponding to the NumPy typecode.
type_match()
Return type: int
Arguments:
Make sure that actual_type is compatible with desired_type. For example, this allows character and byte types, or int and long types, to match. This is now equivalent to PyArray_EquivTypenums().
obj_to_array_no_conversion()
Return type: PyArrayObject*
Arguments:
Cast input to a PyArrayObject* if legal, and ensure that it is of type typecode. If input cannot be cast, or the typecode is wrong, set a Python error and return NULL.
obj_to_array_allow_conversion()
Return type: PyArrayObject*
Arguments:
Convert input to a NumPy array with the given typecode. On success, return a valid PyArrayObject* with the correct type. On failure, the Python error string will be set and the routine returns NULL.
make_contiguous()
Return type: PyArrayObject*
Arguments:
Check to see if ary is contiguous. If so, return the input pointer and flag it as not a new object. If it is not contiguous, create a new PyArrayObject* using the original data, flag it as a new object and return the pointer.
make_fortran()
Return type: PyArrayObject*
Arguments
Check to see if ary is Fortran contiguous. If so, return the input pointer and flag it as not a new object. If it is not Fortran contiguous, create a new PyArrayObject* using the original data, flag it as a new object and return the pointer.
obj_to_array_contiguous_allow_conversion()
Return type: PyArrayObject*
Arguments:
Convert input to a contiguous PyArrayObject* of the specified type. If the input object is not a contiguous PyArrayObject*, a new one will be created and the new object flag will be set.
obj_to_array_fortran_allow_conversion()
Return type: PyArrayObject*
Arguments:
Convert input to a Fortran contiguous PyArrayObject* of the specified type. If the input object is not a Fortran contiguous PyArrayObject*, a new one will be created and the new object flag will be set.
require_contiguous()
Return type: int
Arguments:
Test whether ary is contiguous. If so, return 1. Otherwise, set a Python error and return 0.
require_native()
Return type: int
Arguments:
Require that ary is not byte-swapped. If the array is not byte-swapped, return 1. Otherwise, set a Python error and return 0.
require_dimensions()
Return type: int
Arguments:
Require ary to have a specified number of dimensions. If the array has the specified number of dimensions, return 1. Otherwise, set a Python error and return 0.
require_dimensions_n()
Return type: int
Arguments:
Require ary to have one of a list of specified number of dimensions. If the array has one of the specified number of dimensions, return 1. Otherwise, set the Python error string and return 0.
require_size()
Return type: int
Arguments:
Require ary to have a specified shape. If the array has the specified shape, return 1. Otherwise, set the Python error string and return 0.
require_fortran()
Return type: int
Arguments:
Require the given PyArrayObject to to be Fortran ordered. If the PyArrayObject is already Fortran ordered, do nothing. Else, set the Fortran ordering flag and recompute the strides.
There are many C or C++ array/NumPy array situations not covered by a simple %include "numpy.i" and subsequent %apply directives.
Consider a reasonable prototype for a dot product function:
The Python interface that we want is:
The problem here is that there is one dimension argument and two array arguments, and our typemaps are set up for dimensions that apply to a single array (in fact, SWIG does not provide a mechanism for associating len with vec2 that takes two Python input arguments). The recommended solution is the following:
If the header file that contains the prototype for double dot() also contains other prototypes that you want to wrap, so that you need to %include this header file, then you will also need a %ignore
dot; directive, placed after the %rename and before the %include directives. Or, if the function in question is a class method, you will want to use %extend rather than %inline in addition to %ignore.
A note on error handling: Note that my_dot returns a double but that it can also raise a Python error. The resulting wrapper function will return a Python float representation of 0.0 when the vector lengths do not match. Since this is not NULL, the Python interpreter will not know to check for an error. For this reason, we add the %exception directive above for my_dot to get the behavior we want (note that $action is a macro that gets expanded to a valid call to my_dot). In general, you will probably want to write a SWIG macro to perform this task.
There are other wrapping situations in which numpy.i may be helpful when you encounter them.
In some situations, it is possible that you could use the %numpy_typemaps macro to implement typemaps for your own types. See the Other Common Types: bool or Other Common Types: complex sections for examples. Another situation is if your dimensions are of a type other than int (say long for example):
When you use the %apply directive, as is usually necessary to use numpy.i, it will remain in effect until you tell SWIG that it shouldn’t be. If the arguments to the functions or methods that you are wrapping have common names, such as length or vector, these typemaps may get applied in situations you do not expect or want. Therefore, it is always a good idea to add a %clear directive after you are done with a specific typemap:
In general, you should target these typemap signatures specifically where you want them, and then clear them after you are done.
Out of the box, numpy.i provides typemaps that support conversion between NumPy arrays and C arrays:
That support 74 different argument signatures for each data type, including:
The numpy.i interface file also provides additional tools for wrapper developers, including:


Returns a dtype based off the given description.
This is essentially the reverse of dtype_to_descr(). It will remove the valueless padding fields created by, i.e. simple fields like dtype(‘float32’), and then convert the description to its corresponding dtype.
The object retrieved by dtype.descr. Can be passed to numpy.dtype() in order to replicate the input dtype.
The dtype constructed by the description.


Get a serializable descriptor from the dtype.
The .descr attribute of a dtype object cannot be round-tripped through the dtype() constructor. Simple types, like dtype(‘float32’), have a descr which looks like a record array with one field with ‘’ as a name. The dtype() constructor interprets this as a request to give a default name. Instead, we construct descriptor that can be passed to dtype().
The dtype of the array that will be written to disk.
An object that can be passed to numpy.dtype() in order to replicate the input dtype.


Get the dictionary of header metadata from a numpy.ndarray.
This has the appropriate entries for writing its string representation to the header of the file.


Return the magic string for the given file format version.


Open a .npy file as a memory-mapped array.
This may be used to read an existing file or create a new one.
The name of the file on disk. This may not be a file-like object.
The mode in which to open the file; the default is ‘r+’. In addition to the standard file modes, ‘c’ is also accepted to mean “copy on write.” See memmap for the available mode strings.
The data type of the array if we are creating a new file in “write” mode, if not, dtype is ignored. The default value is None, which results in a data-type of float64.
The shape of the array if we are creating a new file in “write” mode, in which case this parameter is required. Otherwise, this parameter is ignored and is thus optional.
Whether the array should be Fortran-contiguous (True) or C-contiguous (False, the default) if we are creating a new file in “write” mode.
If the mode is a “write” mode, then this is the version of the file format used to create the file. None means use the oldest supported version that is able to store the data. Default: None
The memory-mapped array.
If the data or the mode is invalid.
If the file is not found or cannot be opened correctly.
See also


Read an array from an NPY file.
If this is not a real file object, then this may take extra memory and time.
Whether to allow writing pickled data. Default: False
Changed in version 1.16.3: Made default False in response to CVE-2019-6446.
Additional keyword arguments to pass to pickle.load. These are only useful when loading object arrays saved on Python 2 when using Python 3.
The array from the data on disk.
If the data is invalid, or allow_pickle=False and the file contains an object array.


Read an array header from a filelike object using the 1.0 file format version.
This will leave the file object located just after the header.
A file object or something with a read() method like a file.
The shape of the array.
The array data will be written out directly if it is either C-contiguous or Fortran-contiguous. Otherwise, it will be made contiguous before writing it out.
The dtype of the file’s data.
If the data is invalid.


Read an array header from a filelike object using the 2.0 file format version.
This will leave the file object located just after the header.
New in version 1.9.0.
A file object or something with a read() method like a file.
The shape of the array.
The array data will be written out directly if it is either C-contiguous or Fortran-contiguous. Otherwise, it will be made contiguous before writing it out.
The dtype of the file’s data.
If the data is invalid.


Read the magic string to get the version of the file format.


Write an array to an NPY file, including a header.
If the array is neither C-contiguous nor Fortran-contiguous AND the file_like object is not a real file object, this function will have to copy data in memory.
An open, writable file object, or similar object with a .write() method.
The array to write to disk.
The version number of the format. None means use the oldest supported version that is able to store the data. Default: None
Whether to allow writing pickled data. Default: True
Additional keyword arguments to pass to pickle.dump, excluding ‘protocol’. These are only useful when pickling objects in object arrays on Python 3 to Python 2 compatible format.
If the array cannot be persisted. This includes the case of allow_pickle=False and array being an object array.
If the array contains Python objects as part of its dtype, the process of pickling them may raise various errors if the objects are not picklable.


Write the header for an array using the 1.0 format.
This has the appropriate entries for writing its string representation to the header of the file.


The 2.0 format allows storing very large structured arrays.
New in version 1.9.0.
This has the appropriate entries for writing its string representation to the header of the file.


Compute the inverse cosine of x.
Return the “principal value” (for a description of this, see numpy.arccos) of the inverse cosine of x. For real x such that abs(x) <= 1, this is a real number in the closed interval \([0, \pi]\). Otherwise, the complex principle value is returned.
The value(s) whose arccos is (are) required.
The inverse cosine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.
See also
For an arccos() that returns NAN when real x is not in the interval [-1,1], use numpy.arccos.


Compute the inverse sine of x.
Return the “principal value” (for a description of this, see numpy.arcsin) of the inverse sine of x. For real x such that abs(x) <= 1, this is a real number in the closed interval \([-\pi/2, \pi/2]\). Otherwise, the complex principle value is returned.
The value(s) whose arcsin is (are) required.
The inverse sine(s) of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.
See also
For an arcsin() that returns NAN when real x is not in the interval [-1,1], use numpy.arcsin.


Compute the inverse hyperbolic tangent of x.
Return the “principal value” (for a description of this, see numpy.arctanh) of arctanh(x). For real x such that abs(x) < 1, this is a real number. If abs(x) > 1, or if x is complex, the result is complex. Finally, x = 1 returns``inf`` and x=-1 returns -inf.
The value(s) whose arctanh is (are) required.
The inverse hyperbolic tangent(s) of the x value(s). If x was a scalar so is out, otherwise an array is returned.
See also
For an arctanh() that returns NAN when real x is not in the interval (-1,1), use numpy.arctanh (this latter, however, does return +/-inf for x = +/-1).


Compute the natural logarithm of x.
Return the “principal value” (for a description of this, see numpy.log) of \(log_e(x)\). For real x > 0, this is a real number (log(0) returns -inf and log(np.inf) returns inf). Otherwise, the complex principle value is returned.
The value(s) whose log is (are) required.
The log of the x value(s). If x was a scalar, so is out, otherwise an array is returned.
See also
For a log() that returns NAN when real x < 0, use numpy.log (note, however, that otherwise numpy.log and this log are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).
Negative arguments are handled “correctly” (recall that exp(log(x)) == x does not hold for real x < 0):


Compute the logarithm base 10 of x.
Return the “principal value” (for a description of this, see numpy.log10) of \(log_{10}(x)\). For real x > 0, this is a real number (log10(0) returns -inf and log10(np.inf) returns inf). Otherwise, the complex principle value is returned.
The value(s) whose log base 10 is (are) required.
The log base 10 of the x value(s). If x was a scalar, so is out, otherwise an array object is returned.
See also
For a log10() that returns NAN when real x < 0, use numpy.log10 (note, however, that otherwise numpy.log10 and this log10 are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).
(We set the printing precision so the example can be auto-tested)


Compute the logarithm base 2 of x.
Return the “principal value” (for a description of this, see numpy.log2) of \(log_2(x)\). For real x > 0, this is a real number (log2(0) returns -inf and log2(np.inf) returns inf). Otherwise, the complex principle value is returned.
The value(s) whose log base 2 is (are) required.
The log base 2 of the x value(s). If x was a scalar, so is out, otherwise an array is returned.
See also
For a log2() that returns NAN when real x < 0, use numpy.log2 (note, however, that otherwise numpy.log2 and this log2 are identical, i.e., both return -inf for x = 0, inf for x = inf, and, notably, the complex principle value if x.imag != 0).
We set the printing precision so the example can be auto-tested:


Take log base n of x.
If x contains negative inputs, the answer is computed and returned in the complex domain.
The integer base(s) in which the log is taken.
The value(s) whose log base n is (are) required.
The log base n of the x value(s). If x was a scalar, so is out, otherwise an array is returned.


Return x to the power p, (x**p).
If x contains negative values, the output is converted to the complex domain.
The input value(s).
The power(s) to which x is raised. If x contains multiple values, p has to either be a scalar, or contain the same number of values as x. In the latter case, the result is x[0]**p[0], x[1]**p[1], ....
The result of x**p. If x and p are scalars, so is out, otherwise an array is returned.
See also


Compute the square root of x.
For negative input elements, a complex value is returned (unlike numpy.sqrt which returns NaN).
The input value(s).
The square root of x. If x was a scalar, so is out, otherwise an array is returned.
See also
For real, non-negative inputs this works just like numpy.sqrt:
But it automatically handles negative inputs:


Create a view into the array with the given shape and strides.
Warning
This function has to be used with extreme care, see notes.
Array to create a new.
The shape of the new array. Defaults to x.shape.
The strides of the new array. Defaults to x.strides.
New in version 1.10.
If True, subclasses are preserved.
New in version 1.12.
If set to False, the returned array will always be readonly. Otherwise it will be writable if the original array was. It is advisable to set this to False if possible (see Notes).
See also
broadcast an array to a given shape.
reshape an array.
userfriendly and safe function for the creation of sliding window views.
as_strided creates a view into the array given the exact strides and shape. This means it manipulates the internal data structure of ndarray and, if done incorrectly, the array elements can point to invalid memory and can corrupt results or crash your program. It is advisable to always use the original x.strides when calculating new strides to avoid reliance on a contiguous memory layout.
Furthermore, arrays created with this function often contain self overlapping memory, so that two elements are identical. Vectorized write operations on such arrays will typically be unpredictable. They may even give different results for small, large, or transposed arrays. Since writing to these arrays has to be tested and done with great care, you may want to use writeable=False to avoid accidental write operations.
For these reasons it is advisable to avoid as_strided when possible.


Create a sliding window view into the array with the given window shape.
Also known as rolling or moving window, the window slides across all dimensions of the array and extracts subsets of the array at all window positions.
New in version 1.20.0.
Array to create the sliding window view from.
Size of window over each axis that takes part in the sliding window. If axis is not present, must have same length as the number of input array dimensions. Single integers i are treated as if they were the tuple (i,).
Axis or axes along which the sliding window is applied. By default, the sliding window is applied to all axes and window_shape[i] will refer to axis i of x. If axis is given as a tuple of int, window_shape[i] will refer to the axis axis[i] of x. Single integers i are treated as if they were the tuple (i,).
If True, sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default).
When true, allow writing to the returned view. The default is false, as this should be used with caution: the returned view contains the same memory location multiple times, so writing to one location will cause others to change.
Sliding window view of the array. The sliding window dimensions are inserted at the end, and the original dimensions are trimmed as required by the size of the sliding window. That is, view.shape = x_shape_trimmed + window_shape, where x_shape_trimmed is x.shape with every entry reduced by one less than the corresponding window size.
See also
A lower-level and less safe routine for creating arbitrary views from custom shape and strides.
broadcast an array to a given shape.
For many applications using a sliding window view can be convenient, but potentially very slow. Often specialized solutions exist, for example:
As a rough estimate, a sliding window approach with an input size of N and a window size of W will scale as O(N*W) where frequently a special algorithm can achieve O(N). That means that the sliding window variant for a window size of 100 can be a 100 times slower than a more specialized version.
Nevertheless, for small window sizes, when no custom algorithm exists, or as a prototyping and developing tool, this function can be a good solution.
This also works in more dimensions, e.g.
The axis can be specified explicitly:
The same axis can be used several times. In that case, every use reduces the corresponding original dimension:
Combining with stepped slicing (::step), this can be used to take sliding views which skip elements:
or views which move by multiple elements
A common application of sliding_window_view is the calculation of running statistics. The simplest example is the moving average:
Note that a sliding window approach is often not optimal (see Notes).


Cholesky decomposition.
Return the Cholesky decomposition, L * L.H, of the square matrix a, where L is lower-triangular and .H is the conjugate transpose operator (which is the ordinary transpose if a is real-valued). a must be Hermitian (symmetric if real-valued) and positive-definite. No checking is performed to verify whether a is Hermitian or not. In addition, only the lower-triangular and diagonal elements of a are used. Only L is actually returned.
Hermitian (symmetric if all elements are real), positive-definite input matrix.
Upper or lower-triangular Cholesky factor of a. Returns a matrix object if a is a matrix object.
If the decomposition fails, for example, if a is not positive-definite.
See also
Similar function in SciPy.
Cholesky decompose a banded Hermitian positive-definite matrix.
Cholesky decomposition of a matrix, to use in scipy.linalg.cho_solve.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
The Cholesky decomposition is often used as a fast way of solving
(when A is both Hermitian/symmetric and positive-definite).
First, we solve for \(\mathbf{y}\) in
and then for \(\mathbf{x}\) in


Compute the condition number of a matrix.
This function is capable of returning the condition number using one of seven different norms, depending on the value of p (see Parameters below).
The matrix whose condition number is sought.
Order of the norm used in the condition number computation:
p
norm for matrices
None
2-norm, computed directly using the SVD
‘fro’
Frobenius norm
inf
max(sum(abs(x), axis=1))
-inf
min(sum(abs(x), axis=1))
1
max(sum(abs(x), axis=0))
-1
min(sum(abs(x), axis=0))
2
2-norm (largest sing. value)
-2
smallest singular value
inf means the numpy.inf object, and the Frobenius norm is the root-of-sum-of-squares norm.
The condition number of the matrix. May be infinite.
See also
The condition number of x is defined as the norm of x times the norm of the inverse of x [1]; the norm can be the usual L2-norm (root-of-sum-of-squares) or one of a number of other matrix norms.
G. Strang, Linear Algebra and Its Applications, Orlando, FL, Academic Press, Inc., 1980, pg. 285.


Compute the determinant of an array.
Input array to compute determinants for.
Determinant of a.
See also
Another way to represent the determinant, more suitable for large matrices where underflow/overflow may occur.
Similar function in SciPy.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
The determinant is computed via LU factorization using the LAPACK routine z/dgetrf.
The determinant of a 2-D array [[a, b], [c, d]] is ad - bc:
Computing determinants for a stack of matrices:


Compute the eigenvalues and right eigenvectors of a square array.
Matrices for which the eigenvalues and right eigenvectors will be computed
The eigenvalues, each repeated according to its multiplicity. The eigenvalues are not necessarily ordered. The resulting array will be of complex type, unless the imaginary part is zero in which case it will be cast to a real type. When a is real the resulting eigenvalues will be real (0 imaginary part) or occur in conjugate pairs
The normalized (unit “length”) eigenvectors, such that the column v[:,i] is the eigenvector corresponding to the eigenvalue w[i].
If the eigenvalue computation does not converge.
See also
eigenvalues of a non-symmetric array.
eigenvalues and eigenvectors of a real symmetric or complex Hermitian (conjugate symmetric) array.
eigenvalues of a real symmetric or complex Hermitian (conjugate symmetric) array.
Similar function in SciPy that also solves the generalized eigenvalue problem.
Best choice for unitary and other non-Hermitian normal matrices.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
This is implemented using the _geev LAPACK routines which compute the eigenvalues and eigenvectors of general square arrays.
The number w is an eigenvalue of a if there exists a vector v such that a @ v = w * v. Thus, the arrays a, w, and v satisfy the equations a @ v[:,i] = w[i] * v[:,i] for \(i \in \{0,...,M-1\}\).
The array v of eigenvectors may not be of maximum rank, that is, some of the columns may be linearly dependent, although round-off error may obscure that fact. If the eigenvalues are all different, then theoretically the eigenvectors are linearly independent and a can be diagonalized by a similarity transformation using v, i.e, inv(v) @ a @ v is diagonal.
For non-Hermitian normal matrices the SciPy function scipy.linalg.schur is preferred because the matrix v is guaranteed to be unitary, which is not the case when using eig. The Schur factorization produces an upper triangular matrix rather than a diagonal matrix, but for normal matrices only the diagonal of the upper triangular matrix is needed, the rest is roundoff error.
Finally, it is emphasized that v consists of the right (as in right-hand side) eigenvectors of a. A vector y satisfying y.T @ a = z * y.T for some number z is called a left eigenvector of a, and, in general, the left and right eigenvectors of a matrix are not necessarily the (perhaps conjugate) transposes of each other.
G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, Various pp.
(Almost) trivial example with real e-values and e-vectors.
Real matrix possessing complex e-values and e-vectors; note that the e-values are complex conjugates of each other.
Complex-valued matrix with real e-values (but complex-valued e-vectors); note that a.conj().T == a, i.e., a is Hermitian.
Be careful about round-off error!


Return the eigenvalues and eigenvectors of a complex Hermitian (conjugate symmetric) or a real symmetric matrix.
Returns two objects, a 1-D array containing the eigenvalues of a, and a 2-D square array or matrix (depending on the input type) of the corresponding eigenvectors (in columns).
Hermitian or real symmetric matrices whose eigenvalues and eigenvectors are to be computed.
Specifies whether the calculation is done with the lower triangular part of a (‘L’, default) or the upper triangular part (‘U’). Irrespective of this value only the real parts of the diagonal will be considered in the computation to preserve the notion of a Hermitian matrix. It therefore follows that the imaginary part of the diagonal will always be treated as zero.
The eigenvalues in ascending order, each repeated according to its multiplicity.
The column v[:, i] is the normalized eigenvector corresponding to the eigenvalue w[i]. Will return a matrix object if a is a matrix object.
If the eigenvalue computation does not converge.
See also
eigenvalues of real symmetric or complex Hermitian (conjugate symmetric) arrays.
eigenvalues and right eigenvectors for non-symmetric arrays.
eigenvalues of non-symmetric arrays.
Similar function in SciPy (but also solves the generalized eigenvalue problem).
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
The eigenvalues/eigenvectors are computed using LAPACK routines _syevd, _heevd.
The eigenvalues of real symmetric or complex Hermitian matrices are always real. [1] The array v of (column) eigenvectors is unitary and a, w, and v satisfy the equations dot(a, v[:, i]) = w[i] * v[:, i].
G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pg. 222.


Compute the eigenvalues of a general matrix.
Main difference between eigvals and eig: the eigenvectors aren’t returned.
A complex- or real-valued matrix whose eigenvalues will be computed.
The eigenvalues, each repeated according to its multiplicity. They are not necessarily ordered, nor are they necessarily real for real matrices.
If the eigenvalue computation does not converge.
See also
eigenvalues and right eigenvectors of general arrays
eigenvalues of real symmetric or complex Hermitian (conjugate symmetric) arrays.
eigenvalues and eigenvectors of real symmetric or complex Hermitian (conjugate symmetric) arrays.
Similar function in SciPy.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
This is implemented using the _geev LAPACK routines which compute the eigenvalues and eigenvectors of general square arrays.
Illustration, using the fact that the eigenvalues of a diagonal matrix are its diagonal elements, that multiplying a matrix on the left by an orthogonal matrix, Q, and on the right by Q.T (the transpose of Q), preserves the eigenvalues of the “middle” matrix. In other words, if Q is orthogonal, then Q * A * Q.T has the same eigenvalues as A:
Now multiply a diagonal matrix by Q on one side and by Q.T on the other:


Compute the eigenvalues of a complex Hermitian or real symmetric matrix.
Main difference from eigh: the eigenvectors are not computed.
A complex- or real-valued matrix whose eigenvalues are to be computed.
Specifies whether the calculation is done with the lower triangular part of a (‘L’, default) or the upper triangular part (‘U’). Irrespective of this value only the real parts of the diagonal will be considered in the computation to preserve the notion of a Hermitian matrix. It therefore follows that the imaginary part of the diagonal will always be treated as zero.
The eigenvalues in ascending order, each repeated according to its multiplicity.
If the eigenvalue computation does not converge.
See also
eigenvalues and eigenvectors of real symmetric or complex Hermitian (conjugate symmetric) arrays.
eigenvalues of general real or complex arrays.
eigenvalues and right eigenvectors of general real or complex arrays.
Similar function in SciPy.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
The eigenvalues are computed using LAPACK routines _syevd, _heevd.


Compute the (multiplicative) inverse of a matrix.
Given a square matrix a, return the matrix ainv satisfying dot(a, ainv) = dot(ainv, a) = eye(a.shape[0]).
Matrix to be inverted.
(Multiplicative) inverse of the matrix a.
If a is not square or inversion fails.
See also
Similar function in SciPy.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
If a is a matrix object, then the return value is a matrix as well:
Inverses of several matrices can be computed at once:


Generic Python-exception-derived object raised by linalg functions.
General purpose exception class, derived from Python’s exception.Exception class, programmatically raised in linalg functions when a Linear Algebra-related condition would prevent further correct execution of the function.


Return the least-squares solution to a linear matrix equation.
Computes the vector x that approximately solves the equation a @ x = b. The equation may be under-, well-, or over-determined (i.e., the number of linearly independent rows of a can be less than, equal to, or greater than its number of linearly independent columns). If a is square and of full rank, then x (but for round-off error) is the “exact” solution of the equation. Else, x minimizes the Euclidean 2-norm \(||b - ax||\). If there are multiple minimizing solutions, the one with the smallest 2-norm \(||x||\) is returned.
“Coefficient” matrix.
Ordinate or “dependent variable” values. If b is two-dimensional, the least-squares solution is calculated for each of the K columns of b.
Cut-off ratio for small singular values of a. For the purposes of rank determination, singular values are treated as zero if they are smaller than rcond times the largest singular value of a.
Changed in version 1.14.0: If not set, a FutureWarning is given. The previous default of -1 will use the machine precision as rcond parameter, the new default will use the machine precision times max(M, N). To silence the warning and use the new default, use rcond=None, to keep using the old behavior, use rcond=-1.
Least-squares solution. If b is two-dimensional, the solutions are in the K columns of x.
Sums of squared residuals: Squared Euclidean 2-norm for each column in b - a @ x. If the rank of a is < N or M <= N, this is an empty array. If b is 1-dimensional, this is a (1,) shape array. Otherwise the shape is (K,).
Rank of matrix a.
Singular values of a.
If computation does not converge.
See also
Similar function in SciPy.
If b is a matrix, then all array results are returned as matrices.
Fit a line, y = mx + c, through some noisy data-points:
By examining the coefficients, we see that the line should have a gradient of roughly 1 and cut the y-axis at, more or less, -1.
We can rewrite the line equation as y = Ap, where A = [[x 1]] and p = [[m], [c]]. Now use lstsq to solve for p:
Plot the data along with the fitted line:


Raise a square matrix to the (integer) power n.
For positive integers n, the power is computed by repeated matrix squarings and matrix multiplications. If n == 0, the identity matrix of the same shape as M is returned. If n < 0, the inverse is computed and then raised to the abs(n).
Note
Stacks of object matrices are not currently supported.
Matrix to be “powered”.
The exponent can be any integer or long integer, positive, negative, or zero.
The return value is the same shape and type as M; if the exponent is positive or zero then the type of the elements is the same as those of M. If the exponent is negative the elements are floating-point.
For matrices that are not square or that (for negative powers) cannot be inverted numerically.
Somewhat more sophisticated example


Return matrix rank of array using SVD method
Rank of the array is the number of singular values of the array that are greater than tol.
Changed in version 1.14: Can now operate on stacks of matrices
Input vector or stack of matrices.
Threshold below which SVD values are considered zero. If tol is None, and S is an array with singular values for M, and eps is the epsilon value for datatype of S, then tol is set to S.max() * max(M, N) * eps.
Changed in version 1.14: Broadcasted against the stack of matrices
If True, A is assumed to be Hermitian (symmetric if real-valued), enabling a more efficient method for finding singular values. Defaults to False.
New in version 1.14.
Rank of A.
The default threshold to detect rank deficiency is a test on the magnitude of the singular values of A. By default, we identify singular values less than S.max() * max(M, N) * eps as indicating rank deficiency (with the symbols defined above). This is the algorithm MATLAB uses [1]. It also appears in Numerical recipes in the discussion of SVD solutions for linear least squares [2].
This default threshold is designed to detect rank deficiency accounting for the numerical errors of the SVD computation. Imagine that there is a column in A that is an exact (in floating point) linear combination of other columns in A. Computing the SVD on A will not produce a singular value exactly equal to 0 in general: any difference of the smallest SVD value from 0 will be caused by numerical imprecision in the calculation of the SVD. Our threshold for small SVD values takes this numerical imprecision into account, and the default threshold will detect such numerical rank deficiency. The threshold may declare a matrix A rank deficient even if the linear combination of some columns of A is not exactly equal to another column of A but only numerically very close to another column of A.
We chose our default threshold because it is in wide use. Other thresholds are possible. For example, elsewhere in the 2007 edition of Numerical recipes there is an alternative threshold of S.max() *
np.finfo(A.dtype).eps / 2. * np.sqrt(m + n + 1.). The authors describe this threshold as being based on “expected roundoff error” (p 71).
The thresholds above deal with floating point roundoff error in the calculation of the SVD. However, you may have more information about the sources of error in A that would make you consider other tolerance values to detect effective rank deficiency. The most useful measure of the tolerance depends on the operations you intend to use on your matrix. For example, if your data come from uncertain measurements with uncertainties greater than floating point epsilon, choosing a tolerance near that uncertainty may be preferable. The tolerance may be absolute if the uncertainties are absolute rather than relative.
MATLAB reference documentation, “Rank” https://www.mathworks.com/help/techdoc/ref/rank.html
W. H. Press, S. A. Teukolsky, W. T. Vetterling and B. P. Flannery, “Numerical Recipes (3rd edition)”, Cambridge University Press, 2007, page 795.


Compute the dot product of two or more arrays in a single function call, while automatically selecting the fastest evaluation order.
multi_dot chains numpy.dot and uses optimal parenthesization of the matrices [1] [2]. Depending on the shapes of the matrices, this can speed up the multiplication a lot.
If the first argument is 1-D it is treated as a row vector. If the last argument is 1-D it is treated as a column vector. The other arguments must be 2-D.
Think of multi_dot as:
If the first argument is 1-D it is treated as row vector. If the last argument is 1-D it is treated as column vector. The other arguments must be 2-D.
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.
New in version 1.19.0.
Returns the dot product of the supplied arrays.
See also
dot multiplication with two arguments.
The cost for a matrix multiplication can be calculated with the following function:
Assume we have three matrices \(A_{10x100}, B_{100x5}, C_{5x50}\).
The costs for the two different parenthesizations are as follows:
Cormen, “Introduction to Algorithms”, Chapter 15.2, p. 370-378
https://en.wikipedia.org/wiki/Matrix_chain_multiplication
multi_dot allows you to write:
instead of:


Matrix or vector norm.
This function is able to return one of eight different matrix norms, or one of an infinite number of vector norms (described below), depending on the value of the ord parameter.
Input array. If axis is None, x must be 1-D or 2-D, unless ord is None. If both axis and ord are None, the 2-norm of x.ravel will be returned.
Order of the norm (see table under Notes). inf means numpy’s inf object. The default is None.
If axis is an integer, it specifies the axis of x along which to compute the vector norms. If axis is a 2-tuple, it specifies the axes that hold 2-D matrices, and the matrix norms of these matrices are computed. If axis is None then either a vector norm (when x is 1-D) or a matrix norm (when x is 2-D) is returned. The default is None.
New in version 1.8.0.
If this is set to True, the axes which are normed over are left in the result as dimensions with size one. With this option the result will broadcast correctly against the original x.
New in version 1.10.0.
Norm of the matrix or vector(s).
See also
Similar function in SciPy.
For values of ord < 1, the result is, strictly speaking, not a mathematical ‘norm’, but it may still be useful for various numerical purposes.
The following norms can be calculated:
ord
norm for matrices
norm for vectors
None
Frobenius norm
2-norm
‘fro’
Frobenius norm
–
‘nuc’
nuclear norm
–
inf
max(sum(abs(x), axis=1))
max(abs(x))
-inf
min(sum(abs(x), axis=1))
min(abs(x))
0
–
sum(x != 0)
1
max(sum(abs(x), axis=0))
as below
-1
min(sum(abs(x), axis=0))
as below
2
2-norm (largest sing. value)
as below
-2
smallest singular value
as below
other
–
sum(abs(x)**ord)**(1./ord)
The Frobenius norm is given by [1]:
\(||A||_F = [\sum_{i,j} abs(a_{i,j})^2]^{1/2}\)
The nuclear norm is the sum of the singular values.
Both the Frobenius and nuclear norm orders are only defined for matrices and raise a ValueError when x.ndim != 2.
G. H. Golub and C. F. Van Loan, Matrix Computations, Baltimore, MD, Johns Hopkins University Press, 1985, pg. 15
Using the axis argument to compute vector norms:
Using the axis argument to compute matrix norms:


Compute the (Moore-Penrose) pseudo-inverse of a matrix.
Calculate the generalized inverse of a matrix using its singular-value decomposition (SVD) and including all large singular values.
Changed in version 1.14: Can now operate on stacks of matrices
Matrix or stack of matrices to be pseudo-inverted.
Cutoff for small singular values. Singular values less than or equal to rcond * largest_singular_value are set to zero. Broadcasts against the stack of matrices.
If True, a is assumed to be Hermitian (symmetric if real-valued), enabling a more efficient method for finding singular values. Defaults to False.
New in version 1.17.0.
The pseudo-inverse of a. If a is a matrix instance, then so is B.
If the SVD computation does not converge.
See also
Similar function in SciPy.
Similar function in SciPy (SVD-based).
Compute the (Moore-Penrose) pseudo-inverse of a Hermitian matrix.
The pseudo-inverse of a matrix A, denoted \(A^+\), is defined as: “the matrix that ‘solves’ [the least-squares problem] \(Ax = b\),” i.e., if \(\bar{x}\) is said solution, then \(A^+\) is that matrix such that \(\bar{x} = A^+b\).
It can be shown that if \(Q_1 \Sigma Q_2^T = A\) is the singular value decomposition of A, then \(A^+ = Q_2 \Sigma^+ Q_1^T\), where \(Q_{1,2}\) are orthogonal matrices, \(\Sigma\) is a diagonal matrix consisting of A’s so-called singular values, (followed, typically, by zeros), and then \(\Sigma^+\) is simply the diagonal matrix consisting of the reciprocals of A’s singular values (again, followed by zeros). [1]
G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.
The following example checks that a * a+ * a == a and a+ * a * a+ == a+:


Compute the qr factorization of a matrix.
Factor the matrix a as qr, where q is orthonormal and r is upper-triangular.
An array-like object with the dimensionality of at least 2.
If K = min(M, N), then
(…, M, K), (…, K, N) (default)
The options ‘reduced’, ‘complete, and ‘raw’ are new in numpy 1.8, see the notes for more information. The default is ‘reduced’, and to maintain backward compatibility with earlier versions of numpy both it and the old default ‘full’ can be omitted. Note that array h returned in ‘raw’ mode is transposed for calling Fortran. The ‘economic’ mode is deprecated. The modes ‘full’ and ‘economic’ may be passed using only the first letter for backwards compatibility, but all others must be spelled out. See the Notes for more explanation.
A matrix with orthonormal columns. When mode = ‘complete’ the result is an orthogonal/unitary matrix depending on whether or not a is real/complex. The determinant may be either +/- 1 in that case. In case the number of dimensions in the input array is greater than 2 then a stack of the matrices with above properties is returned.
The upper-triangular matrix or a stack of upper-triangular matrices if the number of dimensions in the input array is greater than 2.
The array h contains the Householder reflectors that generate q along with r. The tau array contains scaling factors for the reflectors. In the deprecated ‘economic’ mode only h is returned.
If factoring fails.
See also
Similar function in SciPy.
Compute RQ decomposition of a matrix.
This is an interface to the LAPACK routines dgeqrf, zgeqrf, dorgqr, and zungqr.
For more information on the qr factorization, see for example: https://en.wikipedia.org/wiki/QR_factorization
Subclasses of ndarray are preserved except for the ‘raw’ mode. So if a is of type matrix, all the return values will be matrices too.
New ‘reduced’, ‘complete’, and ‘raw’ options for mode were added in NumPy 1.8.0 and the old option ‘full’ was made an alias of ‘reduced’. In addition the options ‘full’ and ‘economic’ were deprecated. Because ‘full’ was the previous default and ‘reduced’ is the new default, backward compatibility can be maintained by letting mode default. The ‘raw’ option was added so that LAPACK routines that can multiply arrays by q using the Householder reflectors can be used. Note that in this case the returned arrays are of type np.double or np.cdouble and the h array is transposed to be FORTRAN compatible. No routines using the ‘raw’ return are currently exposed by numpy, but some are available in lapack_lite and just await the necessary work.
Example illustrating a common use of qr: solving of least squares problems
What are the least-squares-best m and y0 in y = y0 + mx for the following data: {(0,1), (1,0), (1,2), (2,1)}. (Graph the points and you’ll see that it should be y0 = 0, m = 1.) The answer is provided by solving the over-determined matrix equation Ax = b, where:
If A = qr such that q is orthonormal (which is always possible via Gram-Schmidt), then x = inv(r) * (q.T) * b. (In numpy practice, however, we simply use lstsq.)


Compute the sign and (natural) logarithm of the determinant of an array.
If an array has a very small or very large determinant, then a call to det may overflow or underflow. This routine is more robust against such issues, because it computes the logarithm of the determinant rather than the determinant itself.
Input array, has to be a square 2-D array.
A number representing the sign of the determinant. For a real matrix, this is 1, 0, or -1. For a complex matrix, this is a complex number with absolute value 1 (i.e., it is on the unit circle), or else 0.
The natural log of the absolute value of the determinant.
See also
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
New in version 1.6.0.
The determinant is computed via LU factorization using the LAPACK routine z/dgetrf.
The determinant of a 2-D array [[a, b], [c, d]] is ad - bc:
Computing log-determinants for a stack of matrices:
This routine succeeds where ordinary det does not:


Solve a linear matrix equation, or system of linear scalar equations.
Computes the “exact” solution, x, of the well-determined, i.e., full rank, linear matrix equation ax = b.
Coefficient matrix.
Ordinate or “dependent variable” values.
Solution to the system a x = b. Returned shape is identical to b.
If a is singular or not square.
See also
Similar function in SciPy.
New in version 1.8.0.
Broadcasting rules apply, see the numpy.linalg documentation for details.
The solutions are computed using LAPACK routine _gesv.
a must be square and of full-rank, i.e., all rows (or, equivalently, columns) must be linearly independent; if either is not true, use lstsq for the least-squares best “solution” of the system/equation.
G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pg. 22.
Solve the system of equations x0 + 2 * x1 = 1 and 3 * x0 + 5 * x1 = 2:
Check that the solution is correct:


Singular Value Decomposition.
When a is a 2D array, it is factorized as u @ np.diag(s) @ vh
= (u * s) @ vh, where u and vh are 2D unitary arrays and s is a 1D array of a’s singular values. When a is higher-dimensional, SVD is applied in stacked mode as explained below.
A real or complex array with a.ndim >= 2.
If True (default), u and vh have the shapes (..., M, M) and (..., N, N), respectively. Otherwise, the shapes are (..., M, K) and (..., K, N), respectively, where K = min(M, N).
Whether or not to compute u and vh in addition to s. True by default.
If True, a is assumed to be Hermitian (symmetric if real-valued), enabling a more efficient method for finding singular values. Defaults to False.
New in version 1.17.0.
Unitary array(s). The first a.ndim - 2 dimensions have the same size as those of the input a. The size of the last two dimensions depends on the value of full_matrices. Only returned when compute_uv is True.
Vector(s) with the singular values, within each vector sorted in descending order. The first a.ndim - 2 dimensions have the same size as those of the input a.
Unitary array(s). The first a.ndim - 2 dimensions have the same size as those of the input a. The size of the last two dimensions depends on the value of full_matrices. Only returned when compute_uv is True.
If SVD computation does not converge.
See also
Similar function in SciPy.
Compute singular values of a matrix.
Changed in version 1.8.0: Broadcasting rules apply, see the numpy.linalg documentation for details.
The decomposition is performed using LAPACK routine _gesdd.
SVD is usually described for the factorization of a 2D matrix \(A\). The higher-dimensional case will be discussed below. In the 2D case, SVD is written as \(A = U S V^H\), where \(A = a\), \(U= u\), \(S= \mathtt{np.diag}(s)\) and \(V^H = vh\). The 1D array s contains the singular values of a and u and vh are unitary. The rows of vh are the eigenvectors of \(A^H A\) and the columns of u are the eigenvectors of \(A A^H\). In both cases the corresponding (possibly non-zero) eigenvalues are given by s**2.
If a has more than two dimensions, then broadcasting rules apply, as explained in Linear algebra on several matrices at once. This means that SVD is working in “stacked” mode: it iterates over all indices of the first a.ndim - 2 dimensions and for each combination SVD is applied to the last two indices. The matrix a can be reconstructed from the decomposition with either (u * s[..., None, :]) @ vh or u @ (s[..., None] * vh). (The @ operator can be replaced by the function np.matmul for python versions below 3.5.)
If a is a matrix object (as opposed to an ndarray), then so are all the return values.
Reconstruction based on full SVD, 2D case:
Reconstruction based on reduced SVD, 2D case:
Reconstruction based on full SVD, 4D case:
Reconstruction based on reduced SVD, 4D case:


Compute the ‘inverse’ of an N-dimensional array.
The result is an inverse for a relative to the tensordot operation tensordot(a, b, ind), i. e., up to floating-point accuracy, tensordot(tensorinv(a), a, ind) is the “identity” tensor for the tensordot operation.
Tensor to ‘invert’. Its shape must be ‘square’, i. e., prod(a.shape[:ind]) == prod(a.shape[ind:]).
Number of first indices that are involved in the inverse sum. Must be a positive integer, default is 2.
a’s tensordot inverse, shape a.shape[ind:] + a.shape[:ind].
If a is singular or not ‘square’ (in the above sense).
See also


Solve the tensor equation a x = b for x.
It is assumed that all indices of x are summed over in the product, together with the rightmost indices of a, as is done in, for example, tensordot(a, x, axes=b.ndim).
Coefficient tensor, of shape b.shape + Q. Q, a tuple, equals the shape of that sub-tensor of a consisting of the appropriate number of its rightmost indices, and must be such that prod(Q) == prod(b.shape) (in which sense a is said to be ‘square’).
Right-hand tensor, which can be of any shape.
Axes in a to reorder to the right, before inversion. If None (default), no reordering is done.
If a is singular or not ‘square’ (in the above sense).
See also


Returns True if all elements evaluate to True.
The output array is masked where all the values along the given axis are masked: if the output would have been a scalar and that all the values are masked, then the output is masked.
Refer to numpy.all for full documentation.
See also
corresponding function for ndarrays
equivalent function


Returns True if two arrays are element-wise equal within a tolerance.
This function is equivalent to allclose except that masked values are treated as equal (default) or unequal, depending on the masked_equal argument.
Input arrays to compare.
Whether masked values in a and b are considered equal (True) or not (False). They are considered equal by default.
Relative tolerance. The relative difference is equal to rtol * b. Default is 1e-5.
Absolute tolerance. The absolute difference is equal to atol. Default is 1e-8.
Returns True if the two arrays are equal within the given tolerance, False otherwise. If either array contains NaN, then False is returned.
See also
the non-masked allclose.
If the following equation is element-wise True, then allclose returns True:
Return True if all elements of a and b are equal subject to given tolerances.
Masked values are not compared directly.


Return True if all entries of a and b are equal, using fill_value as a truth value where either or both are masked.
Input arrays to compare.
Whether masked values in a or b are considered equal (True) or not (False).
Returns True if the two arrays are equal within the given tolerance, False otherwise. If either array contains NaN, then False is returned.
See also


Compute the anomalies (deviations from the arithmetic mean) along the given axis.
Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed along the given axis.
Axis over which the anomalies are taken. The default is to use the mean of the flattened array as reference.
the default is float32; for arrays of float types it is the same as the array type.
See also
Compute the mean of the array.


Returns True if any of the elements of a evaluate to True.
Masked values are considered as False during computation.
Refer to numpy.any for full documentation.
See also
corresponding function for ndarrays
equivalent function


Append values to the end of an array.
New in version 1.9.0.
Values are appended to a copy of this array.
These values are appended to a copy of a. It must be of the correct shape (the same shape as a, excluding axis). If axis is not specified, b can be any shape and will be flattened before use.
The axis along which v are appended. If axis is not given, both a and b are flattened before use.
A copy of a with b appended to axis. Note that append does not occur in-place: a new array is allocated and filled. If axis is None, the result is a flattened array.
See also
Equivalent function in the top-level NumPy module.


Apply a function to 1-D slices along the given axis.
Execute func1d(a, *args, **kwargs) where func1d operates on 1-D arrays and a is a 1-D slice of arr along axis.
This is equivalent to (but faster than) the following use of ndindex and s_, which sets each of ii, jj, and kk to a tuple of indices:
Equivalently, eliminating the inner loop, this can be expressed as:
This function should accept 1-D arrays. It is applied to 1-D slices of arr along the specified axis.
Axis along which arr is sliced.
Input array.
Additional arguments to func1d.
Additional named arguments to func1d.
New in version 1.9.0.
The output array. The shape of out is identical to the shape of arr, except along the axis dimension. This axis is removed, and replaced with new dimensions equal to the shape of the return value of func1d. So if func1d returns a scalar out will have one fewer dimensions than arr.
See also
Apply a function repeatedly over multiple axes.
For a function that returns a 1D array, the number of dimensions in outarr is the same as arr.
For a function that returns a higher dimensional array, those dimensions are inserted in place of the axis dimension.


Apply a function repeatedly over multiple axes.
func is called as res = func(a, axis), where axis is the first element of axes. The result res of the function call must have either the same dimensions as a or one less dimension. If res has one less dimension than a, a dimension is inserted before axis. The call to func is then repeated for each axis in axes, with res as the first argument.
This function must take two arguments, func(a, axis).
Input array.
Axes over which func is applied; the elements must be integers.
The output array. The number of dimensions is the same as a, but the shape can be different. This depends on whether func changes the shape of its output with respect to its input.
See also
Apply a function to 1-D slices of an array along the given axis.
Tuple axis arguments to ufuncs are equivalent:


Return evenly spaced values within a given interval.
Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments the function is equivalent to the Python built-in range function, but returns an ndarray rather than a list.
When using a non-integer step, such as 0.1, it is often better to use numpy.linspace. See the warnings section below for more information.
Start of interval. The interval includes this value. The default start value is 0.
End of interval. The interval does not include this value, except in some cases where step is not an integer and floating point round-off affects the length of out.
Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. The default step size is 1. If step is specified as a position argument, start must also be given.
The type of the output array. If dtype is not given, infer the data type from the other input arguments.
Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.
New in version 1.20.0.
Array of evenly spaced values.
For floating point arguments, the length of the result is ceil((stop - start)/step). Because of floating point overflow, this rule may result in the last element of out being greater than stop.
Warning
The length of the output might not be numerically stable.
Another stability issue is due to the internal implementation of numpy.arange. The actual step value used to populate the array is dtype(start + step) - dtype(start) and not step. Precision loss can occur here, due to casting or due to using floating points when start is much larger than step. This can lead to unexpected behaviour. For example:
In such cases, the use of numpy.linspace should be preferred.
See also
Evenly spaced numbers with careful handling of endpoints.
Arrays of evenly spaced numbers in N-dimensions.
Grid-shaped arrays of evenly spaced numbers in N-dimensions.


Returns array of indices of the maximum values along the given axis. Masked values are treated as if they had the value fill_value.
If None, the index is into the flattened array, otherwise along the specified axis
Value used to fill in the masked values. If None, the output of maximum_fill_value(self._data) is used instead.
Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.


Return array of indices to the minimum values along the given axis.
If None, the index is into the flattened array, otherwise along the specified axis
Value used to fill in the masked values. If None, the output of minimum_fill_value(self._data) is used instead.
Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
If multi-dimension input, returns a new ndarray of indices to the minimum values along the given axis. Otherwise, returns a scalar of index to the minimum values along the given axis.


Return an ndarray of indices that sort the array along the specified axis. Masked values are filled beforehand to fill_value.
Axis along which to sort. If None, the default, the flattened array is used.
Changed in version 1.13.0: Previously, the default was documented to be -1, but that was in error. At some future date, the default will change to -1, as originally intended. Until then, the axis should be given explicitly when arr.ndim > 1, to avoid a FutureWarning.
The sorting algorithm used.
When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Whether missing values (if any) should be treated as the largest values (True) or the smallest values (False) When the array contains unmasked values at the same extremes of the datatype, the ordering of these values and the masked values is undefined.
Value used internally for the masked values. If fill_value is not None, it supersedes endwith.
Array of indices that sort a along the specified axis. In other words, a[index_array] yields a sorted a.
See also
Describes sorting algorithms used.
Indirect stable sort with multiple keys.
Inplace sort.
See sort for notes on the different sorting algorithms.


Round an array to the given number of decimals.
See also
equivalent function; see for details.


An array class with possibly masked values.
Masked values of True exclude the corresponding element from any computation.
Construction:
Input data.
Mask. Must be convertible to an array of booleans with the same shape as data. True indicates a masked (i.e. invalid) data.
Data type of the output. If dtype is None, the type of the data argument (data.dtype) is used. If dtype is not None and different from data.dtype, a copy is performed.
Whether to copy the input data (True), or to use a reference instead. Default is False.
Whether to return a subclass of MaskedArray if possible (True) or a plain MaskedArray. Default is True.
Minimum number of dimensions. Default is 0.
Value used to fill in the masked values when necessary. If None, a default based on the data-type is used.
Whether to combine mask with the mask of the input data, if any (True), or to use only mask for the output (False). Default is True.
Whether to use a hard mask or not. With a hard mask, masked values cannot be unmasked. Default is False.
Whether to force compression of an empty mask. Default is True.
Specify the order of the array. If order is ‘C’, then the array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the returned array will be in Fortran-contiguous order (first-index varies the fastest). If order is ‘A’ (default), then the returned array may be in any order (either C-, Fortran-contiguous, or even discontiguous), unless a copy is required, in which case it will be C-contiguous.
The mask can be initialized with an array of boolean values with the same shape as data.
Alternatively, the mask can be initialized to homogeneous boolean array with the same shape as data by passing in a scalar boolean value:
Note
The recommended practice for initializing mask with a scalar boolean value is to use True/False rather than np.True_/np.False_. The reason is nomask is represented internally as np.False_.


Convert the input to a masked array, conserving subclasses.
If a is a subclass of MaskedArray, its class is conserved. No copy is performed if the input is already an ndarray.
Input data, in any form that can be converted to an array.
By default, the data-type is inferred from the input data.
Whether to use row-major (‘C’) or column-major (‘FORTRAN’) memory representation. Default is ‘C’.
MaskedArray interpretation of a.
See also
Similar to asanyarray, but does not conserve subclass.


Convert the input to a masked array of the given data-type.
No copy is performed if the input is already an ndarray. If a is a subclass of MaskedArray, a base class MaskedArray is returned.
Input data, in any form that can be converted to a masked array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists, ndarrays and masked arrays.
By default, the data-type is inferred from the input data.
Whether to use row-major (‘C’) or column-major (‘FORTRAN’) memory representation. Default is ‘C’.
Masked array interpretation of a.
See also
Similar to asarray, but conserves subclasses.


Convert inputs to arrays with at least one dimension.
Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved.
One or more input arrays.
An array, or list of arrays, each with a.ndim >= 1. Copies are made only if necessary.
See also
The function is applied to both the _data and the _mask, if any.


View inputs as arrays with at least two dimensions.
One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved.
An array, or list of arrays, each with a.ndim >= 2. Copies are avoided where possible, and views with two or more dimensions are returned.
See also
The function is applied to both the _data and the _mask, if any.


View inputs as arrays with at least three dimensions.
One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved.
An array, or list of arrays, each with a.ndim >= 3. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape (N,) becomes a view of shape (1, N, 1), and a 2-D array of shape (M, N) becomes a view of shape (M, N, 1).
See also
The function is applied to both the _data and the _mask, if any.


Return the weighted average of array over the given axis.
Data to be averaged. Masked entries are not taken into account in the computation.
Axis along which to average a. If None, averaging is done over the flattened array.
The importance that each element has in the computation of the average. The weights array can either be 1-D (in which case its length must be the size of a along the given axis) or of the same shape as a. If weights=None, then all data in a are assumed to have a weight equal to one. The 1-D calculation is:
The only constraint on weights is that sum(weights) must not be 0.
Flag indicating whether a tuple (result, sum of weights) should be returned as output (True), or just the result (False). Default is False.
The average along the specified axis. When returned is True, return a tuple with the average as the first element and the sum of the weights as the second element. The return type is np.float64 if a is of integer type and floats smaller than float64, or the input data-type, otherwise. If returned, sum_of_weights is always float64.


Use an index array to construct a new array from a list of choices.
Given an array of integers and a list of n choice arrays, this method will create a new array that merges each of the choice arrays. Where a value in index is i, the new array will have the value that choices[i] contains in the same place.
This array must contain integers in [0, n-1], where n is the number of choices.
Choice arrays. The index array and all of the choices should be broadcastable to the same shape.
If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.
Specifies how out-of-bounds indices will behave.
See also
equivalent function


Clip (limit) the values in an array.
Given an interval, values outside the interval are clipped to the interval edges. For example, if an interval of [0, 1] is specified, values smaller than 0 become 0, and values larger than 1 become 1.
Equivalent to but faster than np.minimum(a_max, np.maximum(a, a_min)).
No check is performed to ensure a_min < a_max.
Array containing elements to clip.
Minimum and maximum value. If None, clipping is not performed on the corresponding edge. Only one of a_min and a_max may be None. Both are broadcast against a.
The results will be placed in this array. It may be the input array for in-place clipping. out must be of the right shape to hold the output. Its type is preserved.
For other keyword-only arguments, see the ufunc docs.
New in version 1.17.0.
An array with the elements of a, but where values < a_min are replaced with a_min, and those > a_max with a_max.
See also
When a_min is greater than a_max, clip returns an array in which all values are equal to a_max, as shown in the second example.


Returns a list of slices corresponding to the masked clumps of a 1-D array. (A “clump” is defined as a contiguous region of the array).
A one-dimensional masked array.
The list of slices, one for each continuous region of masked elements in a.
See also
New in version 1.4.0.


Return list of slices corresponding to the unmasked clumps of a 1-D array. (A “clump” is defined as a contiguous region of the array).
A one-dimensional masked array.
The list of slices, one for each continuous region of unmasked elements in a.
See also
New in version 1.4.0.


Stack 1-D arrays as columns into a 2-D array.
Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with hstack. 1-D arrays are turned into 2-D columns first.
Arrays to stack. All of them must have the same first dimension.
The array formed by stacking the given arrays.
See also
The function is applied to both the _data and the _mask, if any.


Return the common filling value of two masked arrays, if any.
If a.fill_value == b.fill_value, return the fill value, otherwise return None.
The masked arrays for which to compare fill values.
The common fill value, or None.


Suppress whole columns of a 2-D array that contain masked values.
This is equivalent to np.ma.compress_rowcols(a, 1), see compress_rowcols for details.
See also


Suppress the rows and/or columns of a 2-D array that contain masked values.
The suppression behavior is selected with the axis parameter.
The array to operate on. If not a MaskedArray instance (or if no array elements are masked), x is interpreted as a MaskedArray with mask set to nomask. Must be a 2D array.
Axis along which to perform the operation. Default is None.
The compressed array.


Suppress whole rows of a 2-D array that contain masked values.
This is equivalent to np.ma.compress_rowcols(a, 0), see compress_rowcols for details.
See also


Return all the non-masked data as a 1-D array.
This function is equivalent to calling the “compressed” method of a ma.MaskedArray, see ma.MaskedArray.compressed for details.
See also
Equivalent method.


Concatenate a sequence of arrays along the given axis.
The arrays must have the same shape, except in the dimension corresponding to axis (the first, by default).
The axis along which the arrays will be joined. Default is 0.
The concatenated array with any masked entries preserved.
See also
Equivalent function in the top-level NumPy module.