numpy  2.0.0
src/multiarray/mapping.h File Reference

Go to the source code of this file.

Data Structures

struct  npy_index_info

Functions

NPY_NO_EXPORT Py_ssize_t array_length (PyArrayObject *self)
NPY_NO_EXPORT PyObject * array_item_asarray (PyArrayObject *self, npy_intp i)
NPY_NO_EXPORT PyObject * array_item_asscalar (PyArrayObject *self, npy_intp i)
NPY_NO_EXPORT PyObject * array_item (PyArrayObject *self, Py_ssize_t i)
NPY_NO_EXPORT PyObject * array_subscript_asarray (PyArrayObject *self, PyObject *op)
NPY_NO_EXPORT PyObject * array_subscript (PyArrayObject *self, PyObject *op)
NPY_NO_EXPORT int array_assign_item (PyArrayObject *self, Py_ssize_t i, PyObject *v)
NPY_NO_EXPORT void PyArray_MapIterReset (PyArrayMapIterObject *mit)
NPY_NO_EXPORT void PyArray_MapIterNext (PyArrayMapIterObject *mit)
NPY_NO_EXPORT int PyArray_MapIterCheckIndices (PyArrayMapIterObject *mit)
NPY_NO_EXPORT void PyArray_MapIterSwapAxes (PyArrayMapIterObject *mit, PyArrayObject **ret, int getmap)
NPY_NO_EXPORT PyObject * PyArray_MapIterNew (npy_index_info *indices, int index_num, int index_type, int ndim, int fancy_ndim, PyArrayObject *arr, PyArrayObject *subspace, npy_uint32 subspace_iter_flags, npy_uint32 subspace_flags, npy_uint32 extra_op_flags, PyArrayObject *extra_op, PyArray_Descr *extra_op_dtype)

Variables

NPY_NO_EXPORT PyMappingMethods array_as_mapping

Function Documentation

NPY_NO_EXPORT int array_assign_item ( PyArrayObject self,
Py_ssize_t  i,
PyObject *  op 
)
Python C-Api level item assignment (implementation for PySequence_SetItem)
Negative indices are not accepted because PySequence_SetItem converts them to positive indices before calling this.
This is an error, but undo PySequence_SetItem fix for message

Referenced by array_contains().

NPY_NO_EXPORT PyObject* array_item ( PyArrayObject self,
Py_ssize_t  i 
)
Python C-Api level item subscription (implementation for PySequence_GetItem)
Negative indices are not accepted because PySequence_GetItem converts them to positive indices before calling this.
This is an error, but undo PySequence_GetItem fix for message

Referenced by array_contains().

NPY_NO_EXPORT PyObject* array_item_asarray ( PyArrayObject self,
npy_intp  i 
)
C-level integer indexing always returning an array and never a scalar. Works also for subclasses, but it will not be called on one from the Python API.
This function does not accept negative indices because it is called by PySequence_GetItem (through array_item) and that converts them to positive indices.
This is an error, but undo PySequence_GetItem fix for message
NPY_NO_EXPORT Py_ssize_t array_length ( PyArrayObject self)
System Message: SEVERE/4 (<string>, line 1)
Title overline & underline mismatch.

                    IMPLEMENT MAPPING PROTOCOL                          ***
 

References PyArrayMapIterObject::nd, NPY_ANYORDER, PyArray_Dims::ptr, PyArray_DIMS, PyArray_NDIM, and PyArray_Newshape().

Referenced by array_contains().

NPY_NO_EXPORT PyObject* array_subscript ( PyArrayObject self,
PyObject *  op 
)
General function for indexing a NumPy array with a Python object.
Index info array. We can have twice as many indices as dimensions (because of None). The + 1 is to not need to check as much.
return fields if op is a string index
warn if writing to a copy. copies will have no base
Prepare the indices
Full integer index
Because the index is full integer, we do not need to decref
Single boolean array
If it is only a single ellipsis, just return a view
TODO: Should this be a view or not? The only reason not would be
optimization (i.e. of array[...] += 1) I think. Before, it was just self for a single ellipsis.
A single ellipsis, so no need to decref
View based indexing. There are two cases here. First we need to create a simple view, second we need to create a (possibly invalid) view for the subspace to the fancy index. This procedure is identical.
There is a scalar array, so we need to force a copy to simulate fancy indexing.
If there is no fancy indexing, we have the result
Special case for very simple 1-d fancy indexing, which however is quite common. This saves not only a lot of setup time in the iterator, but also is faster (must be exactly fancy because we don't support 0-d booleans here)
The array being indexed has one dimension and it is a fancy index
Check if the index is simple enough
Check if the type is equivalent to INTP
Same order as indices
fancy indexing has to be used. And view is the subspace.
If it is one, the inner loop checks indices, otherwise check indices beforehand, because it is much faster if broadcasting occurs and most likely no big overhead
Reset the outer iterator
Need to create a new array as if the old one never existed.
Clean up indices

References get_item_pointer(), get_view_from_index(), HAS_ELLIPSIS, HAS_INTEGER, PyArray_CopyObject(), PyArray_DIM, PyArray_FailUnlessWriteable(), PyArray_NDIM, PyArray_SETITEM, npy_index_info::type, and npy_index_info::value.

NPY_NO_EXPORT PyObject* array_subscript_asarray ( PyArrayObject self,
PyObject *  op 
)
make sure subscript always returns an array object
Check whether the fancy indices are out of bounds. Returns 0 on success and -1 on failure. (Gets operands from the outer iterator, but iterates them independently)
All indices got broadcast away, do not check as it always was
See if it is possible to just trivially iterate the array
Check if the type is equivalent to INTP
release GIL if it was taken by nditer below
GIL retake at end of function or if nditer path required
Use NpyIter if the trivial iteration is not possible
NPY_NO_EXPORT PyObject* PyArray_MapIterNew ( npy_index_info indices,
int  index_num,
int  index_type,
int  ndim,
int  fancy_ndim,
PyArrayObject arr,
PyArrayObject subspace,
npy_uint32  subspace_iter_flags,
npy_uint32  subspace_flags,
npy_uint32  extra_op_flags,
PyArrayObject extra_op,
PyArray_Descr extra_op_dtype 
)
Create new mapiter.

NOTE: The outer iteration (and subspace if requested buffered) is
created with DELAY_BUFALLOC. It must be reset before usage!
&#64;param Index information filled by prepare_index. &#64;param Number of indices (gotten through prepare_index). &#64;param Kind of index (gotten through preprare_index). &#64;param NpyIter flags for an extra array. If 0 assume that there is no

System Message: ERROR/3 (<string>, line 10) Unexpected indentation.

<blockquote> extra operand. NPY_ITER_ALLOCATE can make sense here.</blockquote>

System Message: WARNING/2 (<string>, line 11) Block quote ends without a blank line; unexpected unindent.
&#64;param Array being indexed &#64;param subspace (result of getting view for the indices) &#64;param Subspace iterator flags can be used to enable buffering.

System Message: ERROR/3 (<string>, line 14) Unexpected indentation.

<blockquote>

NOTE: When no subspace is necessary, the extra operand will
always be buffered! Buffering the subspace when not necessary is very slow when the subspace is small.

</blockquote>

System Message: WARNING/2 (<string>, line 17) Block quote ends without a blank line; unexpected unindent.
&#64;param Subspace operand flags (should just be 0 normally) &#64;param Operand iteration flags for the extra operand, this must not be

System Message: ERROR/3 (<string>, line 19) Unexpected indentation.

<blockquote> 0 if an extra operand should be used, otherwise it must be 0. Should be at least READONLY, WRITEONLY or READWRITE.</blockquote>

System Message: WARNING/2 (<string>, line 21) Block quote ends without a blank line; unexpected unindent.
&#64;param Extra operand. For getmap, this would be the result, for setmap
this would be the arrays to get from. Can be NULL, and will be allocated in that case. However, it matches the mapiter iteration, so you have to call MapIterSwapAxes(mit, &extra_op, 1) on it. The operand has no effect on the shape.
&#64;param Dtype for the extra operand, borrows the reference and must not
be NULL (if extra_op_flags is not 0).
&#64;return A new MapIter (PyObject *) or NULL.

System Message: WARNING/2 (<string>, line 30); backlink Inline emphasis start-string without end-string.
For shape reporting on error
create new MapIter object
set all attributes of mapiter to zero
The subspace, the part of the array which is not indexed by arrays, needs to be iterated when the size of the subspace is larger than 1. If it is one, it has only an effect on the result shape. (Optimizes for example np.newaxis usage)
Fill basic information about the mapiter
Set iteration information of the indexing arrays.
For MapIterArray, it is possible that there is no fancy index. to support this case, add a a dummy iterator. Since it is 0-d its transpose, etc. does not matter.
signal necessity to decref...
Now there are two general cases how extra_op is used:
  1. No subspace iteration is necessary, so the extra_op can be included into the index iterator (it will be buffered)
  2. Subspace iteration is necessary, so the extra op is iterated independently, and the iteration order is fixed at C (could also use Fortran order if the array is Fortran order). In this case the subspace iterator is not buffered.
If subspace iteration is necessary and an extra_op was given, it may also be necessary to transpose the extra_op (or signal the transposing to the advanced iterator).
If we have an extra_op given, need to prepare it.
  1. Subclasses might mess with the shape, so need a baseclass
  2. Need to make sure the shape is compatible
  3. May need to remove leading 1s and transpose dimensions. Normal assignments allows broadcasting away leading 1s, but the transposing code does not like this.
Usual assignments allows removal of leading one dimensions. (or equivalently adding of one dimensions to the array being assigned to). To implement this, reshape the array.
If dimensions need to be prepended (and no swapaxis is needed), use op_axes after extra_op is allocated for sure.
We are not using the subspace, so its size is 1. All dimensions of the extra_op corresponding to the subspace must be equal to 1.
If subspace is not NULL, NpyIter cannot allocate extra_op for us. This is a bit of a kludge. A dummy iterator is created to find the correct output shape and stride permutation. TODO: This can at least partially be replaced, since the shape

System Message: ERROR/3 (<string>, line 5) Unexpected indentation.

<blockquote> is found for broadcasting errors.</blockquote>

Create an iterator, just to broadcast the arrays?!
nditer allows itemsize with npy_intp type, so it works here, but it would not work directly, since elsize is limited to int.
Just use C-order strides (TODO: allow also F-order)
shape is set, and strides is set up to mit->nd, set rest
Allocate new array. Note: Always base class, because subclasses might mess with the shape.
The extra op is now either allocated, can be allocated by NpyIter (no subspace) or is not used at all.
Need to set the axis remapping for the extra_op. This needs to cause ignoring of subspace dimensions and prepending -1 for broadcasting.
(fills subspace dimensions too, but they are not unused)
NOTE: If for some reason someone wishes to use REDUCE_OK, be
careful and fix the error message replacement at the end.
For a single 1-d operand, guarantee iteration order (scipy used this). Note that subspace may be used.
If external array is iterated, and no subspace is needed
NOTE: This small limitation should practically not matter.
(replaces npyiter error)
Use the axis remapping
TODO: Maybe add test for the CORDER, and maybe also allow F
NpyIter cleanup and information:
We may be doing a cast for the buffer, and that may have failed
Get the allocated extra_op
If extra_op is being tracked but subspace is used, we need to create a dedicated iterator for the outer iteration of the extra operand.
Get the full dimension information
Calculate total size of the MapIter
Can now return early if no subspace is being used
Fill in the last bit of mapiter information needed
Now just need to create the correct subspace iterator.
We should iterate the extra_op as well
Buffering is never used here, but in case someone plugs it in somewhere else, set the type correctly then.
NOTE: In this case, need to call PyErr_Occurred() after
basepointer resetting (buffer allocation)
Check whether the operand could not be broadcast and replace the error in that case. This should however normally be found early with a direct goto to broadcast_error
(j < 0 is currently impossible, extra_op is reshaped)
extra_op cannot be broadcast to the indexing result
Report the shape of the original array if it exists

References PyArray_DIM.

This function needs to update the state of the map iterator

and point mit->dataptr to the memory-location of the next object

Note that this function never handles an extra operand but provides compatibility for an old (exposed) API.

Referenced by test_pydatamem_seteventhook_start().

Prototypes for Mapping calls --- not part of the C-API because only useful as part of a getitem call.
Reset the map iterator to the beginning

References NPY_MAXDIMS, PyArray_malloc, and PyArrayMapIter_Type.

NPY_NO_EXPORT void PyArray_MapIterSwapAxes ( PyArrayMapIterObject mit,
PyArrayObject **  ret,
int  getmap 
)
System Message: ERROR/3 (<string>, line 1) Document or section may not begin with a transition.

System Message: ERROR/3 (<string>, line 1) Document may not end with a transition.
arr might not have the right number of dimensions and need to be reshaped first by pre-pending ones
Setting and getting need to have different permutations. On the get we are permuting the returned object, but on setting we are permuting the object-to-be-set. The set permutation is the inverse of the get permutation.
For getting the array the tuple for transpose is (n1,...,n1+n2-1,0,...,n1-1,n1+n2,...,n3-1) n1 is the number of dimensions of the broadcast index array n2 is the number of dimensions skipped at the start n3 is the number of dimensions of the result
For setting the array the tuple for transpose is (n2,...,n1+n2-1,0,...,n2-1,n1+n2,...n3-1)

<

axes to insert at
use n1 as the boundary if getting but n2 if setting

Referenced by PyUFunc_FromFuncAndDataAndSignature().


Variable Documentation

NPY_NO_EXPORT PyMappingMethods array_as_mapping