{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:c-api:array", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array API" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These macros access the " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayObject" }, { "__type": "Text", "__tag": 4046, "value": " structure members and are defined in " }, { "__type": "InlineCode", "__tag": 4051, "value": "ndarraytypes.h" }, { "__type": "Text", "__tag": 4046, "value": ". The input argument, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": ", can be any " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyObject *" }, { "__type": "Text", "__tag": 4046, "value": " that is directly interpretable as a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayObject *" }, { "__type": "Text", "__tag": 4046, "value": " (any instance of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Type" }, { "__type": "Text", "__tag": 4046, "value": " and its sub-types)." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 2.0" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sets the memory location " }, { "__type": "InlineCode", "__tag": 4051, "value": "item" }, { "__type": "Text", "__tag": 4046, "value": " of dtype " }, { "__type": "InlineCode", "__tag": 4051, "value": "descr" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "value" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function is equivalent to setting a single array element with a Python assignment. Returns 0 on success and -1 with an error set on failure." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the " }, { "__type": "InlineCode", "__tag": 4051, "value": "descr" }, { "__type": "Text", "__tag": 4046, "value": " has the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NEEDS_INIT" }, { "__type": "Text", "__tag": 4046, "value": " flag set, the" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "data must be valid or the memory zeroed." } ] } ] } ] } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert obj and place it in the ndarray, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": ", at the place pointed to by itemptr. Return -1 if an error occurs or 0 on success." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In general, prefer the use of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Pack" }, { "__type": "Text", "__tag": 4046, "value": " when" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "handling arbitrary Python objects. Setitem is for example not able to handle arbitrary casts between different dtypes." } ] } ] } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array structure and data access" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These functions and macros provide easy access to elements of the ndarray from C. These work for all arrays. You may need to take care when accessing the data in the array, however, if it is not in machine byte-order, misaligned, or not writeable. In other words, be sure to respect the state of the flags unless you know what you are doing, or have previously guaranteed an array that is writeable, aligned, and in machine byte-order using " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": ". If you wish to handle all types of arrays, the copyswap function for each type is useful for handling misbehaved arrays. Some platforms (e.g. Solaris) do not like misaligned data and will crash if you de-reference a misaligned pointer. Other platforms (e.g. x86 Linux) will just work more slowly with misaligned data." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Quick, inline access to the element at the given coordinates in the ndarray, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": ", which must have respectively 1, 2, 3, or 4 dimensions (this is not checked). The corresponding " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "i" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "j" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "k" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "l" } ] }, { "__type": "Text", "__tag": 4046, "value": " coordinates can be any integer but will be interpreted as " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_intp" }, { "__type": "Text", "__tag": 4046, "value": ". You may want to typecast the returned pointer to the data type of the ndarray." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data access" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Creating arrays" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function steals a reference to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The easiest way to get one is using " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrFromType" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is the main array creation function. Most new arrays are created with this flexible function." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The returned object is an object of Python-type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "subtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", which must be a subtype of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Type" }, { "__type": "Text", "__tag": 4046, "value": ". The array has " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": " dimensions, described by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The data-type descriptor of the new array is " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "subtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " is of an array subclass instead of the base " }, { "__type": "InlineCode", "__tag": 4051, "value": "&PyArray_Type" }, { "__type": "Text", "__tag": 4046, "value": ", then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the object to pass to the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~numpy.class.__array_finalize__", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method of the subclass." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then new unitinialized memory will be allocated and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " can be non-zero to indicate a Fortran-style contiguous array. Use " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FILLWBYTE" }, { "__type": "Text", "__tag": 4046, "value": " to initialize the memory." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " is not " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then it is assumed to point to the memory to be used for the array and the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument is used as the new flags for the array (except the state of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_OWNDATA" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEBACKIFCOPY" }, { "__type": "Text", "__tag": 4046, "value": " flag of the new array will be reset)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In addition, if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " is non-NULL, then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "strides" } ] }, { "__type": "Text", "__tag": 4046, "value": " can also be provided. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "strides" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then the array strides are computed as C-style contiguous (default) or Fortran-style contiguous (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " is nonzero for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " = " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " & " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_F_CONTIGUOUS" }, { "__type": "Text", "__tag": 4046, "value": " is nonzero non-NULL " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Any provided " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "strides" } ] }, { "__type": "Text", "__tag": 4046, "value": " are copied into newly allocated dimension and strides arrays for the new array object." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CheckStrides" }, { "__type": "Text", "__tag": 4046, "value": " can help verify non- " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " stride information." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "data" }, { "__type": "Text", "__tag": 4046, "value": " is provided, it must stay alive for the life of the array. One way to manage this is through " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_SetBaseObject" } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function steals a reference to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": " if it is not NULL. This array creation routine allows for the convenient creation of a new array matching an existing array's shapes and memory layout, possibly changing the layout and/or data type." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "order" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ANYORDER" }, { "__type": "Text", "__tag": 4046, "value": ", the result order is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FORTRANORDER" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "prototype" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a fortran array, " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CORDER" }, { "__type": "Text", "__tag": 4046, "value": " otherwise. When " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "order" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": ", the result order matches that of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "prototype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", even when the axes of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "prototype" } ] }, { "__type": "Text", "__tag": 4046, "value": " aren't in C or Fortran order." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": " is NULL, the data type of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "prototype" } ] }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "subok" } ] }, { "__type": "Text", "__tag": 4046, "value": " is 1, the newly created array will use the sub-type of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "prototype" } ] }, { "__type": "Text", "__tag": 4046, "value": " to create the new array, otherwise it will create a base-class array." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is similar to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_NewFromDescr" }, { "__type": "Text", "__tag": 4046, "value": " (...) except you specify the data-type descriptor with " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type_num" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "itemsize" } ] }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type_num" } ] }, { "__type": "Text", "__tag": 4046, "value": " corresponds to a builtin (or user-defined) type. If the type always has the same number of bytes, then itemsize is ignored. Otherwise, itemsize specifies the particular size of this array." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If data is passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_NewFromDescr" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_New" }, { "__type": "Text", "__tag": 4046, "value": ", this memory must not be deallocated until the new array is deleted. If this data came from another Python object, this can be accomplished using " }, { "__type": "InlineCode", "__tag": 4051, "value": "Py_INCREF" }, { "__type": "Text", "__tag": 4046, "value": " on that object and setting the base member of the new array to point to that object. If strides are passed in they must be consistent with the dimensions, the itemsize, and the data of the array." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create an array wrapper around " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " pointed to by the given pointer. The array flags will have a default that the data area is well-behaved and C-style contiguous. The shape of the array is given by the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": " c-array of length " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The data-type of the array is indicated by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If data comes from another reference-counted Python object, the reference count on this object should be increased after the pointer is passed in, and the base member of the returned ndarray should point to the Python object that owns the data. This will ensure that the provided memory is not freed while the returned array is in existence." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function steals a reference to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create a new array with the provided data-type descriptor, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": ", of the shape determined by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a new " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": " -dimensional array with shape given by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": " and data type given by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "fortran" } ] }, { "__type": "Text", "__tag": 4046, "value": " is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. Fill the memory with zeros (or the 0 object if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " corresponds to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_OBJECT" }, { "__type": "Text", "__tag": 4046, "value": " )." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Macro form of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Zeros" }, { "__type": "Text", "__tag": 4046, "value": " which takes a type-number instead of a data-type object." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a new " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": " -dimensional array with shape given by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": " and data type given by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "fortran" } ] }, { "__type": "Text", "__tag": 4046, "value": " is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. The array is uninitialized unless the data type corresponds to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_OBJECT" }, { "__type": "Text", "__tag": 4046, "value": " in which case the array is filled with " }, { "__type": "InlineCode", "__tag": 4051, "value": "Py_None" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Macro form of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Empty" }, { "__type": "Text", "__tag": 4046, "value": " which takes a type-number, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": ", instead of a data-type object." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a new 1-dimensional array of data-type, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": ", that ranges from " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "start" } ] }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "stop" } ] }, { "__type": "Text", "__tag": 4046, "value": " (exclusive) in increments of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "step" } ] }, { "__type": "Text", "__tag": 4046, "value": " . Equivalent to " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "arange" } ] }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "start" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "stop" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "step" } ] }, { "__type": "Text", "__tag": 4046, "value": ", dtype)." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a new 1-dimensional array of data-type determined by " }, { "__type": "InlineCode", "__tag": 4051, "value": "descr" }, { "__type": "Text", "__tag": 4046, "value": ", that ranges from " }, { "__type": "InlineCode", "__tag": 4051, "value": "start" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "stop" }, { "__type": "Text", "__tag": 4046, "value": " (exclusive) in increments of " }, { "__type": "InlineCode", "__tag": 4051, "value": "step" }, { "__type": "Text", "__tag": 4046, "value": ". Equivalent to arange( " }, { "__type": "InlineCode", "__tag": 4051, "value": "start" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "stop" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "step" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "typenum" }, { "__type": "Text", "__tag": 4046, "value": " )." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "From scratch" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is the main function used to obtain an array from any nested sequence, or object that exposes the array interface, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The parameters allow specification of the required " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", the minimum (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "min_depth" } ] }, { "__type": "Text", "__tag": 4046, "value": ") and maximum (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "max_depth" } ] }, { "__type": "Text", "__tag": 4046, "value": ") number of dimensions acceptable, and other " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "requirements" } ] }, { "__type": "Text", "__tag": 4046, "value": " for the array. This function " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "steals a reference" } ] }, { "__type": "Text", "__tag": 4046, "value": " to the dtype argument, which needs to be a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr" }, { "__type": "Text", "__tag": 4046, "value": " structure indicating the desired data-type (including required byteorder). The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument may be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", indicating that any data-type (and byteorder) is acceptable. Unless " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_FORCECAST" }, { "__type": "Text", "__tag": 4046, "value": " is present in " }, { "__type": "InlineCode", "__tag": 4051, "value": "flags" }, { "__type": "Text", "__tag": 4046, "value": ", this call will generate an error if the data type cannot be safely obtained from the object. If you want to use " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " for the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " and ensure the array is not swapped then use " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CheckFromAny" }, { "__type": "Text", "__tag": 4046, "value": ". A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the following array flags can be added (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "e.g." } ] }, { "__type": "Text", "__tag": 4046, "value": " using |) to get the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "requirements" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument. If your code can handle general (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "e.g." } ] }, { "__type": "Text", "__tag": 4046, "value": " strided, byte-swapped, or unaligned arrays) then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "requirements" } ] }, { "__type": "Text", "__tag": 4046, "value": " may be 0. Also, if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is not already an array (or does not expose the array interface), then a new array will be created (and filled from " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " using the sequence protocol). The new array will have " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_DEFAULT" }, { "__type": "Text", "__tag": 4046, "value": " as its flags member. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "context" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument is unused." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_C_CONTIGUOUS" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure the returned array is C-style contiguous" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_F_CONTIGUOUS" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure the returned array is Fortran-style contiguous." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ALIGNED" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure the returned array is aligned on proper boundaries for its data type. An aligned array has the data pointer and every strides factor as a multiple of the alignment factor for the data-type- descriptor." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEABLE" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure the returned array can be written to." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ENSURECOPY" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure a copy is made of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If this flag is not present, data is not copied if it can be avoided." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ENSUREARRAY" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure the result is a base-class ndarray. By default, if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an instance of a subclass of ndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_FORCECAST" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Force a cast to the output type even if it cannot be done safely. Without this flag, a data cast will occur only if it can be done safely, otherwise an error is raised." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEBACKIFCOPY" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is already an array, but does not satisfy the requirements, then a copy is made (which will satisfy the requirements). If this flag is present and a copy (of an object that is already an array) must be made, then the corresponding " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEBACKIFCOPY" }, { "__type": "Text", "__tag": 4046, "value": " flag is set in the returned copy and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is made to be read-only. You must be sure to call " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ResolveWritebackIfCopy" }, { "__type": "Text", "__tag": 4046, "value": " to copy the contents back into " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " and the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " array will be made writeable again. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is not writeable to begin with, or if it is not already an array, then an error is raised." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "Combinations of array flags", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can also be added." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Nearly identical to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " (...) except " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "requirements" } ] }, { "__type": "Text", "__tag": 4046, "value": " can contain " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_NOTSWAPPED" }, { "__type": "Text", "__tag": 4046, "value": " (over-riding the specification in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ") and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ELEMENTSTRIDES" }, { "__type": "Text", "__tag": 4046, "value": " which indicates that the array should be aligned in the sense that the strides are multiples of the element size." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Special case of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " for when " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is already an array but it needs to be of a specific " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " (including byte-order) or has certain " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "requirements" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return an ndarray object from a Python object that exposes the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~numpy.class.__array__", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method. The third-party implementations of " }, { "__type": "InlineRole", "__tag": 4003, "value": "~numpy.class.__array__", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must take " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy" }, { "__type": "Text", "__tag": 4046, "value": " keyword arguments. " }, { "__type": "InlineCode", "__tag": 4051, "value": "context" }, { "__type": "Text", "__tag": 4046, "value": " is unused." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function returns a (C-style) contiguous and behaved function array from any nested sequence or array interface exporting object, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ", of (non-flexible) type given by the enumerated " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": ", of minimum depth " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "min_depth" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and of maximum depth " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "max_depth" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Equivalent to a call to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " with requirements set to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_DEFAULT" }, { "__type": "Text", "__tag": 4046, "value": " and the type_num member of the type argument set to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function returns a well-behaved C-style contiguous array from any nested sequence or array-interface exporting object. The minimum number of dimensions the array can have is given by " }, { "__type": "InlineRole", "__tag": 4003, "value": "min_depth", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " while the maximum is " }, { "__type": "InlineRole", "__tag": 4003, "value": "max_depth", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". This is equivalent to call " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " with requirements " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_DEFAULT" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ENSUREARRAY" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return an aligned and in native-byteorder array from any nested sequence or array-interface exporting object, op, of a type given by the enumerated typenum. The minimum number of dimensions the array can have is given by min_depth while the maximum is max_depth. This is equivalent to a call to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " with requirements set to BEHAVED." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a one-dimensional ndarray of a single type from a binary or (ASCII) text " }, { "__type": "InlineCode", "__tag": 4051, "value": "string" }, { "__type": "Text", "__tag": 4046, "value": " of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "slen" }, { "__type": "Text", "__tag": 4046, "value": ". The data-type of the array to-be-created is given by " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ". If num is -1, then " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "copy" } ] }, { "__type": "Text", "__tag": 4046, "value": " the entire string and return an appropriately sized array, otherwise, " }, { "__type": "InlineCode", "__tag": 4051, "value": "num" }, { "__type": "Text", "__tag": 4046, "value": " is the number of items to " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "copy" } ] }, { "__type": "Text", "__tag": 4046, "value": " from the string. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "sep" }, { "__type": "Text", "__tag": 4046, "value": " is NULL (or \"\"), then interpret the string as bytes of binary data, otherwise convert the sub-strings separated by " }, { "__type": "InlineCode", "__tag": 4051, "value": "sep" }, { "__type": "Text", "__tag": 4046, "value": " to items of data-type " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ". Some data-types may not be readable in text mode and an error will be raised if that occurs. All errors return NULL." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a one-dimensional ndarray of a single type from a binary or text file. The open file pointer is " }, { "__type": "InlineCode", "__tag": 4051, "value": "fp" }, { "__type": "Text", "__tag": 4046, "value": ", the data-type of the array to be created is given by " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ". This must match the data in the file. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "num" }, { "__type": "Text", "__tag": 4046, "value": " is -1, then read until the end of the file and return an appropriately sized array, otherwise, " }, { "__type": "InlineCode", "__tag": 4051, "value": "num" }, { "__type": "Text", "__tag": 4046, "value": " is the number of items to read. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "sep" }, { "__type": "Text", "__tag": 4046, "value": " is NULL (or \"\"), then read from the file in binary mode, otherwise read from the file in text mode with " }, { "__type": "InlineCode", "__tag": 4051, "value": "sep" }, { "__type": "Text", "__tag": 4046, "value": " providing the item separator. Some array types cannot be read in text mode in which case an error is raised." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a one-dimensional ndarray of a single type from an object, " }, { "__type": "InlineCode", "__tag": 4051, "value": "buf" }, { "__type": "Text", "__tag": 4046, "value": ", that exports the (single-segment) buffer protocol (or has an attribute __buffer\\__ that returns an object that exports the buffer protocol). A writeable buffer will be tried first followed by a read- only buffer. The " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEABLE" }, { "__type": "Text", "__tag": 4046, "value": " flag of the returned array will reflect which one was successful. The data is assumed to start at " }, { "__type": "InlineCode", "__tag": 4051, "value": "offset" }, { "__type": "Text", "__tag": 4046, "value": " bytes from the start of the memory location for the object. The type of the data in the buffer will be interpreted depending on the data- type descriptor, " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype." }, { "__type": "Text", "__tag": 4046, "value": " If " }, { "__type": "InlineCode", "__tag": 4051, "value": "count" }, { "__type": "Text", "__tag": 4046, "value": " is negative then it will be determined from the size of the buffer and the requested itemsize, otherwise, " }, { "__type": "InlineCode", "__tag": 4051, "value": "count" }, { "__type": "Text", "__tag": 4046, "value": " represents how many elements should be converted from the buffer." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Combination of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FROM_OF" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FROM_OT" }, { "__type": "Text", "__tag": 4046, "value": " allowing both a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": " and a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument to be provided." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Similar to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " except the data-type is specified using a typenumber. " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrFromType" }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "typenum" } ] }, { "__type": "Text", "__tag": 4046, "value": ") is passed directly to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": ". This macro also adds " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_DEFAULT" }, { "__type": "Text", "__tag": 4046, "value": " to requirements if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ENSURECOPY" }, { "__type": "Text", "__tag": 4046, "value": " is passed in as requirements." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Encapsulate the functionality of functions and methods that take the axis= keyword and work properly with None as the axis argument. The input array is " }, { "__type": "InlineCode", "__tag": 4051, "value": "obj" }, { "__type": "Text", "__tag": 4046, "value": ", while " }, { "__type": "InlineCode", "__tag": 4051, "value": "*axis" }, { "__type": "Text", "__tag": 4046, "value": " is a converted integer (so that " }, { "__type": "InlineCode", "__tag": 4051, "value": "*axis == NPY_RAVEL_AXIS" }, { "__type": "Text", "__tag": 4046, "value": " is the None value), and " }, { "__type": "InlineCode", "__tag": 4051, "value": "requirements" }, { "__type": "Text", "__tag": 4046, "value": " gives the needed properties of " }, { "__type": "InlineCode", "__tag": 4051, "value": "obj" }, { "__type": "Text", "__tag": 4046, "value": ". The output is a converted version of the input so that requirements are met and if needed a flattening has occurred. On output negative values of " }, { "__type": "InlineCode", "__tag": 4051, "value": "*axis" }, { "__type": "Text", "__tag": 4046, "value": " are converted and the new value is checked to ensure consistency with the shape of " }, { "__type": "InlineCode", "__tag": 4051, "value": "obj" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "From other objects" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Dealing with types" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "op" }, { "__type": "Text", "__tag": 4046, "value": " implements any part of the array interface, then " }, { "__type": "InlineCode", "__tag": 4051, "value": "out" }, { "__type": "Text", "__tag": 4046, "value": " will contain a new reference to the newly created ndarray using the interface or " }, { "__type": "InlineCode", "__tag": 4051, "value": "out" }, { "__type": "Text", "__tag": 4046, "value": " will contain " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " if an error during conversion occurs. Otherwise, out will contain a borrowed reference to Py_NotImplemented and no error condition is set. This version allows setting of the dtype in the part of the array interface that looks for the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~numpy.class.__array__", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " attribute. " }, { "__type": "InlineRole", "__tag": 4003, "value": "context", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is unused." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "General check of Python Type" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some of the descriptor attributes may not always be defined and should or cannot not be accessed directly." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 2.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Prior to NumPy 2.0 the ABI was different but unnecessary large for user DTypes. These accessors were all added in 2.0 and can be backported (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "migration_c_descr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "numpy_2_0_migration_guide" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data-type accessors" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the typenum macros, the argument is an integer representing an enumerated array data type. For the array type checking macros the argument must be a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyObject *" }, { "__type": "Text", "__tag": 4046, "value": " that can be directly interpreted as a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayObject *" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_TRUE" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type2" } ] }, { "__type": "Text", "__tag": 4046, "value": " actually represent equivalent types for this platform (the fortran member of each type is ignored). For example, on 32-bit platforms, " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_LONG" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_INT" }, { "__type": "Text", "__tag": 4046, "value": " are equivalent. Otherwise return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FALSE" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_TRUE" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "a1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "a2" } ] }, { "__type": "Text", "__tag": 4046, "value": " are arrays with equivalent types for this platform." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data-type checking" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return a new array of the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type" } ] }, { "__type": "Text", "__tag": 4046, "value": " specified, casting the elements of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": " as appropriate. The fortran argument specifies the ordering of the output array." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CanCastTypeTo" }, { "__type": "Text", "__tag": 4046, "value": " supersedes this function in NumPy 1.6 and later." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING)." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns non-zero if an array of data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "fromtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " (which can include flexible types) can be cast safely to an array of data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "totype" } ] }, { "__type": "Text", "__tag": 4046, "value": " (which can include flexible types) according to the casting rule " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "casting" } ] }, { "__type": "Text", "__tag": 4046, "value": ". For simple types with " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", this is basically a wrapper around " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CanCastSafely" }, { "__type": "Text", "__tag": 4046, "value": ", but for flexible types such as strings or unicode, it produces results taking into account their sizes. Integer and float types can only be cast to a string or unicode type using " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": " if the string or unicode type is big enough to hold the max value of the integer/float type being cast from." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns non-zero if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": " can be cast to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "totype" } ] }, { "__type": "Text", "__tag": 4046, "value": " according to the casting rule given in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "casting" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an array scalar, its value is taken into account, and non-zero is also returned when the value will not overflow or be truncated to an integer when converting to a smaller type." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finds the data type of smallest size and kind to which " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "type2" } ] }, { "__type": "Text", "__tag": 4046, "value": " may be safely converted. This function is symmetric and associative. A string or unicode result will be the proper size for storing the max value of the input types converted to a string or unicode." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This applies type promotion to all the input arrays and dtype objects, using the NumPy rules for combining scalars and arrays, to determine the output type for an operation with the given set of operands. This is the same result type that ufuncs produce." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See the documentation of " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.result_type", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:result_type" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for more detail about the type promotion algorithm." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The functionality this provides is largely superseded by iterator " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter" }, { "__type": "Text", "__tag": 4046, "value": " introduced in 1.6, with flag " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ITER_COMMON_DTYPE" }, { "__type": "Text", "__tag": 4046, "value": " or with the same dtype parameter for all operands." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert a sequence of Python objects contained in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " to an array of ndarrays each having the same data type. The type is selected in the same way as " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ResultType" }, { "__type": "Text", "__tag": 4046, "value": ". The length of the sequence is returned in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "n" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and an " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "n" } ] }, { "__type": "Text", "__tag": 4046, "value": " -length array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayObject" }, { "__type": "Text", "__tag": 4046, "value": " pointers is the return value (or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " if an error occurs). The returned array must be freed by the caller of this routine (using " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataMem_FREE" }, { "__type": "Text", "__tag": 4046, "value": " ) and all the array objects in it " }, { "__type": "InlineCode", "__tag": 4051, "value": "DECREF" }, { "__type": "Text", "__tag": 4046, "value": " 'd or a memory-leak will occur. The example template-code below shows a typical usage:" } ] }, { "__type": "Code", "__tag": 4050, "value": "mps = PyArray_ConvertToCommonType(obj, &n);\n if (mps==NULL) return NULL;\n {code}\n \n for (i=0; i`" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_UpdateFlags" }, { "__type": "Text", "__tag": 4046, "value": " (obj, flags) will update the " }, { "__type": "InlineCode", "__tag": 4051, "value": "obj->flags" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "InlineCode", "__tag": 4051, "value": "flags" }, { "__type": "Text", "__tag": 4046, "value": " which can be any of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_C_CONTIGUOUS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_F_CONTIGUOUS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_ALIGNED" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ARRAY_WRITEABLE" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Basic Array Flags" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Combinations of array flags" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These constants are used in " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_FromAny" }, { "__type": "Text", "__tag": 4046, "value": " (and its macro forms) to specify desired properties of the new array." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These constants are used in " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_CheckFromAny" }, { "__type": "Text", "__tag": 4046, "value": " (and its macro forms) to specify desired properties of the new array." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Flag-like constants" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For all of these macros " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "arr" } ] }, { "__type": "Text", "__tag": 4046, "value": " must be an instance of a (subclass of) " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Type" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is important to keep the flags updated (using " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_UpdateFlags" }, { "__type": "Text", "__tag": 4046, "value": " can help) whenever a manipulation with an array is performed that might cause them to change. Later calculations in NumPy that rely on the state of these flags do not repeat the calculation to update them." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Flag checking" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "ArrayMethod loops are intended as a generic mechanism for writing loops over arrays, including ufunc loops and casts. The public API is defined in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/dtype_api.h" }, { "__type": "Text", "__tag": 4046, "value": " header. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "arraymethod-structs", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:types-and-structures" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for documentation on the C structs exposed in the ArrayMethod API." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "ArrayMethod API" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These are used to identify which kind of function an ArrayMethod slot implements. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "arraymethod-typedefs", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:array" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " below for documentation on the functions that must be implemented for each slot." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function used to set the descriptors for an operation based on the descriptors of the operands. For example, a ufunc operation with two input operands and one output operand that is called without " }, { "__type": "InlineCode", "__tag": 4051, "value": "out" }, { "__type": "Text", "__tag": 4046, "value": " being set in the python API, " }, { "__type": "InlineCode", "__tag": 4051, "value": "resolve_descriptors" }, { "__type": "Text", "__tag": 4046, "value": " will be passed the descriptors for the two operands and determine the correct descriptor to use for the output based on the output DType set for the ArrayMethod. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "out" }, { "__type": "Text", "__tag": 4046, "value": " is set, then the output descriptor would be passed in as well and should not be overridden." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "method" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a pointer to the underlying cast or ufunc loop. In the future we may expose this struct publicly but for now this is an opaque pointer and the method cannot be inspected. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtypes" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an " }, { "__type": "InlineCode", "__tag": 4051, "value": "nargs" }, { "__type": "Text", "__tag": 4046, "value": " length array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DTypeMeta" }, { "__type": "Text", "__tag": 4046, "value": " pointers, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "given_descrs" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an " }, { "__type": "InlineCode", "__tag": 4051, "value": "nargs" }, { "__type": "Text", "__tag": 4046, "value": " length array of input descriptor instances (output descriptors may be NULL if no output was provided by the user), and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "loop_descrs" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an " }, { "__type": "InlineCode", "__tag": 4051, "value": "nargs" }, { "__type": "Text", "__tag": 4046, "value": " length array of descriptors that must be filled in by the resolve descriptors implementation. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "view_offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " is currently only interesting for casts and can normally be ignored. When a cast does not require any operation, this can be signalled by setting " }, { "__type": "InlineCode", "__tag": 4051, "value": "view_offset" }, { "__type": "Text", "__tag": 4046, "value": " to 0. On error, you must return " }, { "__type": "InlineCode", "__tag": 4051, "value": "(NPY_CASTING)-1" }, { "__type": "Text", "__tag": 4046, "value": " with an error set." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An implementation of an ArrayMethod loop. All of the loop slot IDs listed above must provide a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayMethod_StridedLoop" }, { "__type": "Text", "__tag": 4046, "value": " implementation. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "context" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a struct containing context for the loop operation - in particular the input descriptors. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " are an array of pointers to the beginning of the input and output array buffers. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dimensions" } ] }, { "__type": "Text", "__tag": 4046, "value": " are the loop dimensions for the operation. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "strides" } ] }, { "__type": "Text", "__tag": 4046, "value": " are an " }, { "__type": "InlineCode", "__tag": 4051, "value": "nargs" }, { "__type": "Text", "__tag": 4046, "value": " length array of strides for each input. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "auxdata" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an optional set of auxiliary data that can be passed in to the loop - helpful to turn on and off optional behavior or reduce boilerplate by allowing similar ufuncs to share loop implementations or to allocate space that is persistent over multiple strided loop calls." } ] } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "const npy_intp *strides, PyArrayMethod_StridedLoop **out_loop, \\" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NpyAuxData **out_transferdata, NPY_ARRAYMETHOD_FLAGS *flags);" } ] } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sets the loop to use for an operation at runtime. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "context" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the runtime context for the operation. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "aligned" } ] }, { "__type": "Text", "__tag": 4046, "value": " indicates whether the data access for the loop is aligned (1) or unaligned (0). " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "move_references" } ] }, { "__type": "Text", "__tag": 4046, "value": " indicates whether embedded references in the data should be copied. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "strides" } ] }, { "__type": "Text", "__tag": 4046, "value": " are the strides for the input array, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out_loop" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a pointer that must be filled in with a pointer to the loop implementation. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out_transferdata" } ] }, { "__type": "Text", "__tag": 4046, "value": " can be optionally filled in to allow passing in extra user-defined context to an operation. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "flags" } ] }, { "__type": "Text", "__tag": 4046, "value": " must be filled in with ArrayMethod flags relevant for the operation. This is for example necessary to indicate if the inner loop requires the Python GIL to be held." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Query an ArrayMethod for the initial value for use in reduction. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "context" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the ArrayMethod context, mainly to access the input descriptors. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "reduction_is_empty" } ] }, { "__type": "Text", "__tag": 4046, "value": " indicates whether the reduction is empty. When it is, the value returned may differ. In this case it is a \"default\" value that may differ from the \"identity\" value normally used. For example:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "0.0" }, { "__type": "Text", "__tag": 4046, "value": " is the default for " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum([])" }, { "__type": "Text", "__tag": 4046, "value": ". But " }, { "__type": "InlineCode", "__tag": 4051, "value": "-0.0" }, { "__type": "Text", "__tag": 4046, "value": " is the correct identity otherwise as it preserves the sign for " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum([-0.0])" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We use no identity for object, but return the default of " }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "1" }, { "__type": "Text", "__tag": 4046, "value": " for the empty " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum([], dtype=object)" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "prod([], dtype=object)" }, { "__type": "Text", "__tag": 4046, "value": ". This allows " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.sum(np.array([\"a\", \"b\"], dtype=object))" }, { "__type": "Text", "__tag": 4046, "value": " to work." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "-inf" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "INT_MIN" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "InlineCode", "__tag": 4051, "value": "max" }, { "__type": "Text", "__tag": 4046, "value": " is an identity, but at least " }, { "__type": "InlineCode", "__tag": 4051, "value": "INT_MIN" }, { "__type": "Text", "__tag": 4046, "value": " not a good " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "default" } ] }, { "__type": "Text", "__tag": 4046, "value": " when there are no items." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "initial" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a pointer to the data for the initial value, which should be filled in. Returns -1, 0, or 1 indicating error, no initial value, and the initial value being successfully filled. Errors must not be given when no initial value is correct, since NumPy may call this even when it is not strictly necessary to do so." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Slots and Typedefs" } ], "level": 2, "target": "arraymethod-typedefs" }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Flags" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Typedefs for functions that users of the ArrayMethod API can implement are described below." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A traverse loop working on a single array. This is similar to the general strided-loop function. This is designed for loops that need to visit every element of a single array." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Currently this is used for array clearing, via the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_DT_get_clear_loop" }, { "__type": "Text", "__tag": 4046, "value": " DType API hook, and zero-filling, via the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_DT_get_fill_zero_loop" }, { "__type": "Text", "__tag": 4046, "value": " DType API hook. These are most useful for handling arrays storing embedded references to python objects or heap-allocated data." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the descriptor for the array, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a pointer to the array buffer, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "size" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the 1D size of the array buffer, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "stride" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the stride, and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "auxdata" } ] }, { "__type": "Text", "__tag": 4046, "value": " is optional extra data for the loop." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "traverse_context" } ] }, { "__type": "Text", "__tag": 4046, "value": " is passed in because we may need to pass in Interpreter state or similar in the future, but we don't want to pass in a full context (with pointers to dtypes, method, caller which all make no sense for a traverse function). We assume for now that this context can be just passed through in the future (for structured dtypes)." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Simplified get_loop function specific to dtype traversal" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It should set the flags needed for the traversal loop and set " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out_loop" } ] }, { "__type": "Text", "__tag": 4046, "value": " to the loop function, which must be a valid " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayMethod_TraverseLoop" }, { "__type": "Text", "__tag": 4046, "value": " pointer. Currently this is used for zero-filling and clearing arrays storing embedded references." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Typedefs" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These functions are part of the main numpy array API and were added along with the rest of the ArrayMethod API." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Add loop directly to a ufunc from a given ArrayMethod spec. the main ufunc registration function. This adds a new implementation/loop to a ufunc. It replaces " }, { "__type": "InlineRole", "__tag": 4003, "value": "PyUFunc_RegisterLoopForType", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 2.4" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Add multiple loops to ufuncs from ArrayMethod specs. This also handles the registration of methods for the ufunc-like functions " }, { "__type": "InlineCode", "__tag": 4051, "value": "sort" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsort" }, { "__type": "Text", "__tag": 4046, "value": ". See " }, { "__type": "CrossRef", "__tag": 4002, "value": "array-methods-sorting", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:array" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "slots" }, { "__type": "Text", "__tag": 4046, "value": " argument must be a NULL-terminated array of " }, { "__type": "InlineRole", "__tag": 4003, "value": "PyUFunc_LoopSlot", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (see above), which give the name of the ufunc and spec needed to create the loop." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that currently the output dtypes are always " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " unless they are also part of the signature. This is an implementation detail and could change in the future. However, in general promoters should not have a need for output dtypes. Register a new promoter for a ufunc. The first argument is the ufunc to register the promoter with. The second argument is a Python tuple containing DTypes or None matching the number of inputs and outputs for the ufuncs. The last argument is a promoter is a function stored in a PyCapsule. It is passed the operation and requested DType signatures and can mutate it to attempt a new search for a matching loop/promoter." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Type of the promoter function, which must be wrapped into a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyCapsule" }, { "__type": "Text", "__tag": 4046, "value": " with name " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"numpy._ufunc_promoter\"" }, { "__type": "Text", "__tag": 4046, "value": ". It is passed the operation and requested DType signatures and can mutate the signatures to attempt a search for a new loop or promoter that can accomplish the operation by casting the inputs to the \"promoted\" DTypes." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Checks for a floating point error after performing a floating point operation in a manner that takes into account the error signaling configured via " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.errstate", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:errstate" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". Takes the name of the operation to use in the error message and an integer flag that is one of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FPE_DIVIDEBYZERO" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FPE_OVERFLOW" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FPE_UNDERFLOW" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FPE_INVALID" }, { "__type": "Text", "__tag": 4046, "value": " to indicate which error to check for." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns -1 on failure (an error was raised) and 0 on success." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Allows creating of a fairly lightweight wrapper around an existing ufunc loop. The idea is mainly for units, as this is currently slightly limited in that it enforces that you cannot use a loop from another ufunc." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function to convert the given descriptors (passed in to " }, { "__type": "InlineCode", "__tag": 4051, "value": "resolve_descriptors" }, { "__type": "Text", "__tag": 4046, "value": ") and translates them for the wrapped loop. The new descriptors MUST be viewable with the old ones, " }, { "__type": "InlineRole", "__tag": 4003, "value": "NULL", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must be supported (for output arguments) and should normally be forwarded." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The output of of this function will be used to construct views of the arguments as if they were the translated dtypes and does not use a cast. This means this mechanism is mostly useful for DTypes that \"wrap\" another DType implementation. For example, a unit DType could use this to wrap an existing floating point DType without needing to re-implement low-level ufunc logic. In the unit example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "resolve_descriptors" }, { "__type": "Text", "__tag": 4046, "value": " would handle computing the output unit from the input unit." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function to convert the actual loop descriptors (as returned by the original " }, { "__type": "InlineRole", "__tag": 4003, "value": "resolve_descriptors", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " function) to the ones the output array should use. This function must return \"viewable\" types, it must not mutate them in any form that would break the inner-loop logic. Does not need to support NULL." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "API Functions and Typedefs" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose you want to wrap the " }, { "__type": "InlineCode", "__tag": 4051, "value": "float64" }, { "__type": "Text", "__tag": 4046, "value": " multiply implementation for a " }, { "__type": "InlineCode", "__tag": 4051, "value": "WrappedDoubleDType" }, { "__type": "Text", "__tag": 4046, "value": ". You would add a wrapping loop like so:" } ] }, { "__type": "Code", "__tag": 4050, "value": "PyArray_DTypeMeta *orig_dtypes[3] = {\n &WrappedDoubleDType, &WrappedDoubleDType, &WrappedDoubleDType};\nPyArray_DTypeMeta *wrapped_dtypes[3] = {\n &PyArray_Float64DType, &PyArray_Float64DType, &PyArray_Float64DType}\n\nPyObject *mod = PyImport_ImportModule(\"numpy\");\nif (mod == NULL) {\n return -1;\n}\nPyObject *multiply = PyObject_GetAttrString(mod, \"multiply\");\nPy_DECREF(mod);\n\nif (multiply == NULL) {\n return -1;\n}\n\nint res = PyUFunc_AddWrappingLoop(\n multiply, orig_dtypes, wrapped_dtypes, &translate_given_descrs\n &translate_loop_descrs);\n\nPy_DECREF(multiply);", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that this also requires two functions to be defined above this code:" } ] }, { "__type": "Code", "__tag": 4050, "value": "static int\ntranslate_given_descrs(int nin, int nout,\n PyArray_DTypeMeta *NPY_UNUSED(wrapped_dtypes[]),\n PyArray_Descr *given_descrs[],\n PyArray_Descr *new_descrs[])\n{\n for (int i = 0; i < nin + nout; i++) {\n if (given_descrs[i] == NULL) {\n new_descrs[i] = NULL;\n }\n else {\n new_descrs[i] = PyArray_DescrFromType(NPY_DOUBLE);\n }\n }\n return 0;\n}\n\nstatic int\ntranslate_loop_descrs(int nin, int NPY_UNUSED(nout),\n PyArray_DTypeMeta *NPY_UNUSED(new_dtypes[]),\n PyArray_Descr *given_descrs[],\n PyArray_Descr *original_descrs[],\n PyArray_Descr *loop_descrs[])\n{\n // more complicated parametric DTypes may need to\n // to do additional checking, but we know the wrapped\n // DTypes *have* to be float64 for this example.\n loop_descrs[0] = PyArray_DescrFromType(NPY_FLOAT64);\n Py_INCREF(loop_descrs[0]);\n loop_descrs[1] = PyArray_DescrFromType(NPY_FLOAT64);\n Py_INCREF(loop_descrs[1]);\n loop_descrs[2] = PyArray_DescrFromType(NPY_FLOAT64);\n Py_INCREF(loop_descrs[2]);\n}", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Wrapping Loop Example" } ], "level": 3, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sorting and argsorting methods for dtypes can be registered using the ArrayMethod API. This is done by adding an ArrayMethod spec with the name " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"sort\"" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"argsort\"" }, { "__type": "Text", "__tag": 4046, "value": " respectively. The spec must have " }, { "__type": "InlineCode", "__tag": 4051, "value": "nin=1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "nout=1" }, { "__type": "Text", "__tag": 4046, "value": " for both sort and argsort. Sorting is inplace, hence we enforce that " }, { "__type": "InlineCode", "__tag": 4051, "value": "data[0] == data[1]" }, { "__type": "Text", "__tag": 4046, "value": ". Argsorting returns a new array of indices, so the output must be of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_INTP" }, { "__type": "Text", "__tag": 4046, "value": " type." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "context" }, { "__type": "Text", "__tag": 4046, "value": " passed to the loop contains the " }, { "__type": "InlineCode", "__tag": 4051, "value": "parameters" }, { "__type": "Text", "__tag": 4046, "value": " field which for these operations is a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayMethod_SortParameters *" }, { "__type": "Text", "__tag": 4046, "value": " struct. This struct contains a " }, { "__type": "InlineCode", "__tag": 4051, "value": "flags" }, { "__type": "Text", "__tag": 4046, "value": " field which is a bitwise OR of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SORTKIND" }, { "__type": "Text", "__tag": 4046, "value": " values indicating the kind of sort to perform (that is, whether it is a stable and/or descending sort). If the strided loop depends on the flags, a good way to deal with this is to define " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_METH_get_loop" }, { "__type": "Text", "__tag": 4046, "value": ", and not set any of the other loop slots." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These specs can be registered using " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyUFunc_AddLoopsFromSpecs" }, { "__type": "Text", "__tag": 4046, "value": " along with other ufunc loops." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Sorting and Argsorting" } ], "level": 2, "target": "array-methods-sorting" }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "API for calling array methods" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.getfield", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": "). This function " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "steals a reference" } ], "url": "https://docs.python.org/3/c-api/intro.html?reference-count-details", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr" }, { "__type": "Text", "__tag": 4046, "value": " and returns a new array of the given " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " using the data in the current array at a specified " }, { "__type": "InlineRole", "__tag": 4003, "value": "offset", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " in bytes. The " }, { "__type": "InlineRole", "__tag": 4003, "value": "offset", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " plus the itemsize of the new array type must be less than " }, { "__type": "InlineCode", "__tag": 4051, "value": "self->descr->elsize" }, { "__type": "Text", "__tag": 4046, "value": " or an error is raised. The same shape and strides as the original array are used. Therefore, this function has the effect of returning a field from a structured array. But, it can also be used to select specific bytes or groups of bytes from any array type." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.setfield", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "val" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " ). Set the field starting at " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " in bytes and of the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "val" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " plus " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " ->elsize must be less than " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " ->descr->elsize or an error is raised. Otherwise, the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "val" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument is converted to an array and copied into the field pointed to. If necessary, the elements of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "val" } ] }, { "__type": "Text", "__tag": 4046, "value": " are repeated to fill the destination array, But, the number of elements in the destination must be an integer multiple of the number of elements in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "val" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Write the contents of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " to the file pointer " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "fp" } ] }, { "__type": "Text", "__tag": 4046, "value": " in C-style contiguous fashion. Write the data as binary bytes if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "sep" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the string \"\"or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ". Otherwise, write the contents of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " as text using the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "sep" } ] }, { "__type": "Text", "__tag": 4046, "value": " string as the item separator. Each item will be printed to the file. If the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "format" } ] }, { "__type": "Text", "__tag": 4046, "value": " string is not " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " or \"\", then it is a Python print statement format string showing how the items are to be written." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.view", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return a new view of the array " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " as possibly a different data-type, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and different array subclass " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ptype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then the returned array will have the same data type as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The new data-type must be consistent with the size of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Either the itemsizes must be identical, or " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " must be single-segment and the total number of bytes must be the same. In the latter case the dimensions of the returned array will be altered in the last (or first for Fortran-style contiguous arrays) dimension. The data area of the returned array and self is exactly the same." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Conversion" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Result will be a new array (pointing to the same memory location as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " if possible), but having a shape given by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newshape" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If the new shape is not compatible with the strides of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", then a copy of the array with the new specified shape will be returned." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "matrix objects are always 2-dimensional. Therefore, " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Squeeze" }, { "__type": "Text", "__tag": 4046, "value": " has no effect on arrays of matrix sub-class." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.resize", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newshape" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "refcheck" } ] }, { "__type": "Text", "__tag": 4046, "value": "). This function only works on single-segment arrays. It changes the shape of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " inplace and will reallocate the memory for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newshape" } ] }, { "__type": "Text", "__tag": 4046, "value": " has a different total number of elements then the old shape. If reallocation is necessary, then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " must own its data, have " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " - " }, { "__type": "InlineCode", "__tag": 4051, "value": ">base==NULL" }, { "__type": "Text", "__tag": 4046, "value": ", have " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " - " }, { "__type": "InlineCode", "__tag": 4051, "value": ">weakrefs==NULL" }, { "__type": "Text", "__tag": 4046, "value": ", and (unless refcheck is 0) not be referenced by any other array. The fortran argument can be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ANYORDER" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CORDER" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FORTRANORDER" }, { "__type": "Text", "__tag": 4046, "value": ". It currently has no effect. Eventually it could be used to determine how the resize operation should view the data when constructing a differently-dimensioned array. Returns None on success and NULL on error." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.transpose", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "permute" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Permute the axes of the ndarray object " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " according to the data structure " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "permute" } ] }, { "__type": "Text", "__tag": 4046, "value": " and return the result. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "permute" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then the resulting array has its axes reversed. For example if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " has shape " }, { "__type": "InlineMath", "__tag": 4057, "value": "10\\times20\\times30" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "permute" } ] }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ptr" }, { "__type": "Text", "__tag": 4046, "value": " is (0,2,1) the shape of the result is " }, { "__type": "InlineMath", "__tag": 4057, "value": "10\\times30\\times20." }, { "__type": "Text", "__tag": 4046, "value": " If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "permute" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", the shape of the result is " }, { "__type": "InlineMath", "__tag": 4057, "value": "30\\times20\\times10." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Shape Manipulation" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.take", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "indices" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ret" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "clipmode" } ] }, { "__type": "Text", "__tag": 4046, "value": ") except " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " =None in Python is obtained by setting " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " = " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXDIMS" }, { "__type": "Text", "__tag": 4046, "value": " in C. Extract the items from self indicated by the integer-valued " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "indices" } ] }, { "__type": "Text", "__tag": 4046, "value": " along the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis." } ] }, { "__type": "Text", "__tag": 4046, "value": " The clipmode argument can be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_RAISE" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_WRAP" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CLIP" }, { "__type": "Text", "__tag": 4046, "value": " to indicate what to do with out-of-bound indices. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ret" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument can specify an output array rather than having one created internally." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ".put(" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "indices" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "clipmode" } ] }, { "__type": "Text", "__tag": 4046, "value": " ). Put " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " into " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " at the corresponding (flattened) " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "indices" } ] }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " is too small it will be repeated as necessary." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Place the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " wherever corresponding positions (using a flattened context) in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "mask" } ] }, { "__type": "Text", "__tag": 4046, "value": " are true. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "mask" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " arrays must have the same total number of elements. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " is too small, it will be repeated as necessary." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.repeat", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Copy the elements of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " times along the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Either " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a scalar integer or a sequence of length " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " ->dimensions[ " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " ] indicating how many times to repeat each item along the axis." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.choose", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ret" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "clipmode" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Create a new array by selecting elements from the sequence of arrays in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " based on the integer values in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The arrays must all be broadcastable to the same shape and the entries in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " should be between 0 and len(" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": "). The output is placed in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ret" } ] }, { "__type": "Text", "__tag": 4046, "value": " unless it is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " in which case a new output is created. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "clipmode" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument determines behavior for when entries in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " are not between 0 and len(" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.searchsorted", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "side" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "perm" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Assuming " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a 1-d array in ascending order, then the output is an array of indices the same shape as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " such that, if the elements in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "values" } ] }, { "__type": "Text", "__tag": 4046, "value": " were inserted before the indices, the order of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " would be preserved. No checking is done on whether or not self is in ascending order." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "side" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument indicates whether the index returned should be that of the first suitable location (if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SEARCHLEFT" }, { "__type": "Text", "__tag": 4046, "value": ") or of the last (if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SEARCHRIGHT" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "sorter" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument, if not " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", must be a 1D array of integer indices the same length as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", that sorts it into ascending order. This is typically the result of a call to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ArgSort" }, { "__type": "Text", "__tag": 4046, "value": " (...) Binary search is used to find the required insertion points." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.partition", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ktharray" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "kind" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Partitions the array so that the values of the element indexed by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ktharray" } ] }, { "__type": "Text", "__tag": 4046, "value": " are in the positions they would be if the array is fully sorted and places all elements smaller than the kth before and all elements equal or greater after the kth element. The ordering of all elements within the partitions is undefined. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": "->descr is a data-type with fields defined, then self->descr->names is used to determine the sort order. A comparison where the first field is equal will use the second field and so on. To alter the sort order of a structured array, create a new data-type with a different order of names and construct a view of the array with that new data-type. Returns zero on success and -1 on failure." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.argpartition", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ktharray" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "kind" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return an array of indices such that selection of these indices along the given " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": " would return a partitioned version of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.diagonal", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis1" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis2" } ] }, { "__type": "Text", "__tag": 4046, "value": " ). Return the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " diagonals of the 2-d arrays defined by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis2" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.compress", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "condition" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " ). Return the elements along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " corresponding to elements of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "condition" } ] }, { "__type": "Text", "__tag": 4046, "value": " that are true." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Item selection and manipulation" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "tip", "base_type": "tip", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "tip " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pass in " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_RAVEL_AXIS" }, { "__type": "Text", "__tag": 4046, "value": " for axis in order to achieve the same effect that is obtained by passing in " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis=None" }, { "__type": "Text", "__tag": 4046, "value": " in Python (treating the array as a 1-d array)." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The out argument specifies where to place the result. If out is NULL, then the output array is created, otherwise the output is placed in out which must be the correct size and type. A new reference to the output array is always returned even when out is not NULL. The caller of the routine has the responsibility to " }, { "__type": "InlineCode", "__tag": 4051, "value": "Py_DECREF" }, { "__type": "Text", "__tag": 4046, "value": " out if not NULL or a memory-leak will occur." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.argmax", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return the index of the largest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.argmin", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return the index of the smallest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.max", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Returns the largest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". When the result is a single element, returns a numpy scalar instead of an ndarray." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.min", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return the smallest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". When the result is a single element, returns a numpy scalar instead of an ndarray." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return the difference between the largest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " and the smallest element of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". When the result is a single element, returns a numpy scalar instead of an ndarray." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The rtype argument specifies the data-type the reduction should take place over. This is important if the data-type of the array is not \"large\" enough to handle the output. By default, all integer data-types are made at least as large as " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_LONG" }, { "__type": "Text", "__tag": 4046, "value": " for the \"add\" and \"multiply\" ufuncs (which form the basis for mean, sum, cumsum, prod, and cumprod functions)." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.mean", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Returns the mean of the elements along the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", using the enumerated type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " as the data type to sum in. Default sum behavior is obtained using " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NOTYPE" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.trace", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis1" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis2" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return the sum (using " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " as the data type of summation) over the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offset" } ] }, { "__type": "Text", "__tag": 4046, "value": " diagonal elements of the 2-d arrays defined by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis2" } ] }, { "__type": "Text", "__tag": 4046, "value": " variables. A positive offset chooses diagonals above the main diagonal. A negative offset selects diagonals below the main diagonal." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.clip", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "min" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "max" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Clip an array, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", so that values larger than " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "max" } ] }, { "__type": "Text", "__tag": 4046, "value": " are fixed to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "max" } ] }, { "__type": "Text", "__tag": 4046, "value": " and values less than " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "min" } ] }, { "__type": "Text", "__tag": 4046, "value": " are fixed to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "min" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.round", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "decimals" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Returns the array with elements rounded to the nearest decimal place. The decimal place is defined as the " }, { "__type": "InlineMath", "__tag": 4057, "value": "10^{-\\textrm{decimals}}" }, { "__type": "Text", "__tag": 4046, "value": " digit so that negative " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "decimals" } ] }, { "__type": "Text", "__tag": 4046, "value": " cause rounding to the nearest 10's, 100's, etc. If out is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then the output array is created, otherwise the output is placed in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": " which must be the correct size and type." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.std", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return the standard deviation using data along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " converted to data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.sum", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return 1-d vector sums of elements in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Perform the sum after converting data to data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.cumsum", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return cumulative 1-d sums of elements in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Perform the sum after converting data to data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.prod", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return 1-d products of elements in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Perform the product after converting data to data type " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.cumprod", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rtype" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return 1-d cumulative products of elements in " }, { "__type": "InlineCode", "__tag": 4051, "value": "self" }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": ". Perform the product after converting data to data type " }, { "__type": "InlineCode", "__tag": 4051, "value": "rtype" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.all", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return an array with True elements for every 1-d sub-array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "self" }, { "__type": "Text", "__tag": 4046, "value": " defined by " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": " in which all the elements are True." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Equivalent to " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.any", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Return an array with True elements for every 1-d sub-array of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "self" } ] }, { "__type": "Text", "__tag": 4046, "value": " defined by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "axis" } ] }, { "__type": "Text", "__tag": 4046, "value": " in which any of the elements are True." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Calculation" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Functions" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sometimes it is useful to access a multidimensional array as a C-style multi-dimensional array so that algorithms can be implemented using C's a[i][j][k] syntax. This routine returns a pointer, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ptr" } ] }, { "__type": "Text", "__tag": 4046, "value": ", that simulates this kind of C-style array, for 1-, 2-, and 3-d ndarrays." } ] }, { "__type": "FieldList", "__tag": 4035, "children": [ { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "paramop" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The address to any Python object. This Python object will be replaced with an equivalent well-behaved, C-style contiguous, ndarray of the given data type specified by the last two arguments. Be sure that stealing a reference in this way to the input object is justified." } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "paramptr" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The address to a (ctype* for 1-d, ctype** for 2-d or ctype*** for 3-d) variable where ctype is the equivalent C-type for the data type. On return, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ptr" } ] }, { "__type": "Text", "__tag": 4046, "value": " will be addressable as a 1-d, 2-d, or 3-d array." } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "paramdims" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An output array that contains the shape of the array object. This array gives boundaries on any looping that will take place." } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "paramnd" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dimensionality of the array (1, 2, or 3)." } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "paramtypedescr" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr" }, { "__type": "Text", "__tag": 4046, "value": " structure indicating the desired data-type (including required byteorder). The call will steal a reference to the parameter." } ] } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The simulation of a C-style array is not complete for 2-d and 3-d arrays. For example, the simulated arrays of pointers cannot be passed to subroutines expecting specific, statically-defined 2-d and 3-d arrays. To pass to functions requiring those kind of inputs, you must statically define the required array and copy data." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Same as PyArray_MatrixProduct, but store the result in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The output array must have the correct shape, type, and be C-contiguous, or an exception is raised." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Applies the Einstein summation convention to the array operands provided, returning a new array or placing the result in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The string in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "subscripts" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a comma separated list of index letters. The number of operands is in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nop" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op_in" } ] }, { "__type": "Text", "__tag": 4046, "value": " is an array containing those operands. The data type of the output can be forced with " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", the output order can be forced with " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "order" } ] }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_KEEPORDER" }, { "__type": "Text", "__tag": 4046, "value": " is recommended), and when " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " is specified, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "casting" } ] }, { "__type": "Text", "__tag": 4046, "value": " indicates how permissive the data conversion should be." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See the " }, { "__type": "CrossRef", "__tag": 4002, "value": "einsum", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:einsum" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " function for more details." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the 1-d correlation of the 1-d arrays " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op2" } ] }, { "__type": "Text", "__tag": 4046, "value": " . The correlation is computed at each output point by multiplying " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": " by a shifted version of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op2" } ] }, { "__type": "Text", "__tag": 4046, "value": " and summing the result. As a result of the shift, needed values outside of the defined range of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op2" } ] }, { "__type": "Text", "__tag": 4046, "value": " are interpreted as zero. The mode determines how many shifts to return: 0 - return only shifts that did not need to assume zero- values; 1 - return an object that is the same size as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": ", 2 - return all possible shifts (any overlap at all is accepted)." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "rubric", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Notes" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This does not compute the usual correlation: if op2 is larger than op1, the arguments are swapped, and the conjugate is never taken for complex arrays. See PyArray_Correlate2 for the usual signal processing correlation." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Updated version of PyArray_Correlate, which uses the usual definition of correlation for 1d arrays. The correlation is computed at each output point by multiplying " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": " by a shifted version of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op2" } ] }, { "__type": "Text", "__tag": 4046, "value": " and summing the result. As a result of the shift, needed values outside of the defined range of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op2" } ] }, { "__type": "Text", "__tag": 4046, "value": " are interpreted as zero. The mode determines how many shifts to return: 0 - return only shifts that did not need to assume zero- values; 1 - return an object that is the same size as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op1" } ] }, { "__type": "Text", "__tag": 4046, "value": ", 2 - return all possible shifts (any overlap at all is accepted)." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "rubric", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Notes" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute z as follows " } ] }, { "__type": "Code", "__tag": 4050, "value": "z[k] = sum_n op1[n] * conj(op2[n+k])", "execution_status": null } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If both " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "y" }, { "__type": "Text", "__tag": 4046, "value": " are " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then return " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Nonzero" }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "condition" } ] }, { "__type": "Text", "__tag": 4046, "value": "). Otherwise, both " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "x" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "y" } ] }, { "__type": "Text", "__tag": 4046, "value": " must be given and the object returned is shaped like " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "condition" } ] }, { "__type": "Text", "__tag": 4046, "value": " and has elements of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "x" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "y" } ] }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "condition" } ] }, { "__type": "Text", "__tag": 4046, "value": " is respectively True or False." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array Functions" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determine if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newstrides" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a strides array consistent with the memory of an " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": " -dimensional array with shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "dims" }, { "__type": "Text", "__tag": 4046, "value": " and element-size, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "elsize" } ] }, { "__type": "Text", "__tag": 4046, "value": ". The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newstrides" } ] }, { "__type": "Text", "__tag": 4046, "value": " array is checked to see if jumping by the provided number of bytes in each direction will ever mean jumping more than " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "numbytes" } ] }, { "__type": "Text", "__tag": 4046, "value": " which is the assumed size of the available memory segment. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "numbytes" } ] }, { "__type": "Text", "__tag": 4046, "value": " is 0, then an equivalent " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "numbytes" } ] }, { "__type": "Text", "__tag": 4046, "value": " is computed assuming " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dims" } ] }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "elsize" } ] }, { "__type": "Text", "__tag": 4046, "value": " refer to a single-segment array. Return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_TRUE" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newstrides" } ] }, { "__type": "Text", "__tag": 4046, "value": " is acceptable, otherwise return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FALSE" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Other functions" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When working with more complex dtypes which are composed of other dtypes, such as the struct dtype, creating inner loops that manipulate the dtypes requires carrying along additional data. NumPy supports this idea through a struct " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyAuxData" }, { "__type": "Text", "__tag": 4046, "value": ", mandating a few conventions so that it is possible to do this." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defining an " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyAuxData" }, { "__type": "Text", "__tag": 4046, "value": " is similar to defining a class in C++, but the object semantics have to be tracked manually since the API is in C. Here's an example for a function which doubles up an element using an element copier function as a primitive." } ] }, { "__type": "Code", "__tag": 4050, "value": "typedef struct {\n NpyAuxData base;\n ElementCopier_Func *func;\n NpyAuxData *funcdata;\n} eldoubler_aux_data;\n\nvoid free_element_doubler_aux_data(NpyAuxData *data)\n{\n eldoubler_aux_data *d = (eldoubler_aux_data *)data;\n /* Free the memory owned by this auxdata */\n NPY_AUXDATA_FREE(d->funcdata);\n PyArray_free(d);\n}\n\nNpyAuxData *clone_element_doubler_aux_data(NpyAuxData *data)\n{\n eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));\n if (ret == NULL) {\n return NULL;\n }\n\n /* Raw copy of all data */\n memcpy(ret, data, sizeof(eldoubler_aux_data));\n\n /* Fix up the owned auxdata so we have our own copy */\n ret->funcdata = NPY_AUXDATA_CLONE(ret->funcdata);\n if (ret->funcdata == NULL) {\n PyArray_free(ret);\n return NULL;\n }\n\n return (NpyAuxData *)ret;\n}\n\nNpyAuxData *create_element_doubler_aux_data(\n ElementCopier_Func *func,\n NpyAuxData *funcdata)\n{\n eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));\n if (ret == NULL) {\n PyErr_NoMemory();\n return NULL;\n }\n memset(&ret, 0, sizeof(eldoubler_aux_data));\n ret->base->free = &free_element_doubler_aux_data;\n ret->base->clone = &clone_element_doubler_aux_data;\n ret->func = func;\n ret->funcdata = funcdata;\n\n return (NpyAuxData *)ret;\n}", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Auxiliary data with object semantics" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As of NumPy 1.6.0, these array iterators are superseded by the new array iterator, " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyIter" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An array iterator is a simple way to access the elements of an N-dimensional array quickly and efficiently, as seen in " }, { "__type": "CrossRef", "__tag": 4002, "value": "the example", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:iterator" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " which provides more description of this useful approach to looping over an array from C." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return an array iterator that is broadcast to iterate as an array of the shape provided by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dimensions" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "nd" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Set the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "iterator" } ] }, { "__type": "Text", "__tag": 4046, "value": " index, dataptr, and coordinates members to the location in the array indicated by the N-dimensional c-array, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "destination" } ] }, { "__type": "Text", "__tag": 4046, "value": ", which must have size at least " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "iterator" } ] }, { "__type": "Text", "__tag": 4046, "value": " ->nd_m1+1." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array iterators" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Advance each iterator in a multi-iterator object, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "multi" } ] }, { "__type": "Text", "__tag": 4046, "value": ", to the given " }, { "__type": "InlineMath", "__tag": 4057, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " -dimensional " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "destination" } ] }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "InlineMath", "__tag": 4057, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " is the number of dimensions in the broadcasted array." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Broadcasting (multi-iterators)" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Neighborhood iterators are subclasses of the iterator object, and can be used to iter over a neighborhood of a point. For example, you may want to iterate over every voxel of a 3d image, and for every such voxel, iterate over an hypercube. Neighborhood iterator automatically handle boundaries, thus making this kind of code much easier to write than manual boundaries handling, at the cost of a slight overhead." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function creates a new neighborhood iterator from an existing iterator. The neighborhood will be computed relatively to the position currently pointed by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "iter" } ] }, { "__type": "Text", "__tag": 4046, "value": ", the bounds define the shape of the neighborhood iterator, and the mode argument the boundaries handling mode." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "bounds" } ] }, { "__type": "Text", "__tag": 4046, "value": " argument is expected to be a (2 * iter->ao->nd) arrays, such as the range bound[2*i]->bounds[2*i+1] defines the range where to walk for dimension i (both bounds are included in the walked coordinates). The bounds should be ordered for each dimension (bounds[2*i] <= bounds[2*i+1])." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The mode should be one of:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the mode is constant filling (" }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING" }, { "__type": "Text", "__tag": 4046, "value": "), fill_value should point to an array object which holds the filling value (the first item will be the filling value if the array contains more than one item). For other cases, fill_value may be NULL." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The iterator holds a reference to iter" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return NULL on failure (in which case the reference count of iter is not changed)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "iter itself can be a Neighborhood iterator: this can be useful for .e.g automatic boundaries handling" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "the object returned by this function should be safe to use as a normal iterator" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the position of iter is changed, any subsequent call to PyArrayNeighborhoodIter_Next is undefined behavior, and PyArrayNeighborhoodIter_Reset must be called." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the position of iter is not the beginning of the data and the underlying data for iter is contiguous, the iterator will point to the start of the data instead of position pointed by iter. To avoid this situation, iter should be moved to the required position only after the creation of iterator, and PyArrayNeighborhoodIter_Reset must be called." } ] } ] } ] }, { "__type": "Code", "__tag": 4050, "value": "PyArrayIterObject *iter;\n PyArrayNeighborhoodIterObject *neigh_iter;\n iter = PyArray_IterNew(x);\n\n /*For a 3x3 kernel */\n bounds = {-1, 1, -1, 1};\n neigh_iter = (PyArrayNeighborhoodIterObject*)PyArray_NeighborhoodIterNew(\n iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL);\n\n for(i = 0; i < iter->size; ++i) {\n for (j = 0; j < neigh_iter->size; ++j) {\n /* Walk around the item currently pointed by iter->dataptr */\n PyArrayNeighborhoodIter_Next(neigh_iter);\n }\n\n /* Move to the next point of iter */\n PyArrayIter_Next(iter);\n PyArrayNeighborhoodIter_Reset(neigh_iter);\n }", "execution_status": null } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Reset the iterator position to the first point of the neighborhood. This should be called whenever the iter argument given at PyArray_NeighborhoodIterObject is changed (see example)" } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "After this call, iter->dataptr points to the next point of the neighborhood. Calling this function after every point of the neighborhood has been visited is undefined." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Neighborhood iterator" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return an array scalar object of the given " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": " by " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "copying" } ] }, { "__type": "Text", "__tag": 4046, "value": " from memory pointed to by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "data" } ] }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "base" } ] }, { "__type": "Text", "__tag": 4046, "value": " is expected to be the array object that is the owner of the data. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "base" } ] }, { "__type": "Text", "__tag": 4046, "value": " is required if " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is a " }, { "__type": "InlineCode", "__tag": 4051, "value": "void" }, { "__type": "Text", "__tag": 4046, "value": " scalar, or if the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_USE_GETITEM" }, { "__type": "Text", "__tag": 4046, "value": " flag is set and it is known that the " }, { "__type": "InlineCode", "__tag": 4051, "value": "getitem" }, { "__type": "Text", "__tag": 4046, "value": " method uses the " }, { "__type": "InlineCode", "__tag": 4051, "value": "arr" }, { "__type": "Text", "__tag": 4046, "value": " argument without checking if it is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ". Otherwise " }, { "__type": "InlineRole", "__tag": 4003, "value": "base", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " may be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the data is not in native byte order (as indicated by " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype->byteorder" }, { "__type": "Text", "__tag": 4046, "value": ") then this function will byteswap the data, because array scalars are always in correct machine-byte order." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return a 0-dimensional array of type determined by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "outcode" } ] }, { "__type": "Text", "__tag": 4046, "value": " from " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "scalar" } ] }, { "__type": "Text", "__tag": 4046, "value": " which should be an array-scalar object. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "outcode" } ] }, { "__type": "Text", "__tag": 4046, "value": " is NULL, then the type is determined from " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "scalar" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return the data (cast to the data type indicated by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "outcode" } ] }, { "__type": "Text", "__tag": 4046, "value": ") from the array-scalar, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "scalar" } ] }, { "__type": "Text", "__tag": 4046, "value": ", into the memory pointed to by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "ctypeptr" } ] }, { "__type": "Text", "__tag": 4046, "value": " (which must be large enough to handle the incoming memory)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns -1 on failure, and 0 on success." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Legacy way to query special promotion for scalar values. This is not used in NumPy itself anymore and is expected to be deprecated eventually." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "New DTypes can define promotion rules specific to Python scalars." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Legacy way to query special promotion for scalar values. This is not used in NumPy itself anymore and is expected to be deprecated eventually." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ResultType" }, { "__type": "Text", "__tag": 4046, "value": " for similar purposes." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Array scalars" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Data-type objects must be reference counted so be aware of the action on the data-type reference of different C-API calls. The standard rule is that when a data-type object is returned it is a new reference. Functions that take " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr *" }, { "__type": "Text", "__tag": 4046, "value": " objects and return arrays steal references to the data-type their inputs unless otherwise noted. Therefore, you must own a reference to any data-type object used as input to such a function." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create a new data-type object with the byteorder set according to " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newendian" } ] }, { "__type": "Text", "__tag": 4046, "value": ". All referenced data-type objects (in subdescr and fields members of the data-type object) are also changed (recursively)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The value of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "newendian" } ] }, { "__type": "Text", "__tag": 4046, "value": " is one of these macros:" } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a byteorder of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_IGNORE" }, { "__type": "Text", "__tag": 4046, "value": " is encountered it is left alone. If newendian is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SWAP" }, { "__type": "Text", "__tag": 4046, "value": ", then all byte-orders are swapped. Other valid newendian values are " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NATIVE" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_LITTLE" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_BIG" }, { "__type": "Text", "__tag": 4046, "value": " which all cause the returned data-typed descriptor (and all it's referenced data-type descriptors) to have the corresponding byte- order." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determine an appropriate data-type object from the object " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": " (which should be a \"nested\" sequence object) and the minimum data-type descriptor mintype (which can be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " ). Similar in behavior to array(" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "op" } ] }, { "__type": "Text", "__tag": 4046, "value": ").dtype. Don't confuse this function with " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrConverter" }, { "__type": "Text", "__tag": 4046, "value": ". This function essentially looks at all the objects in the (nested) sequence and determines the data-type from the elements it finds." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert any compatible Python object, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": ", to a data-type object in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ". This version of the converter converts None objects so that the returned data-type is " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ". This function can also be used with the \"O&\" character in PyArg_ParseTuple processing." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Like " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrConverter" }, { "__type": "Text", "__tag": 4046, "value": " except it aligns C-struct-like objects on word-boundaries as the compiler would." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Like " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrConverter2" }, { "__type": "Text", "__tag": 4046, "value": " except it aligns C-struct-like objects on word-boundaries as the compiler would." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data-type descriptors" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function defines the common DType operator. Note that the common DType will not be " }, { "__type": "InlineCode", "__tag": 4051, "value": "object" }, { "__type": "Text", "__tag": 4046, "value": " (unless one of the DTypes is " }, { "__type": "InlineCode", "__tag": 4051, "value": "object" }, { "__type": "Text", "__tag": 4046, "value": "). Similar to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.result_type", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:result_type" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", but works on the classes and not instances." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Promotes a list of DTypes with each other in a way that should guarantee stable results even when changing the order. This function is smarter and can often return successful and unambiguous results when " }, { "__type": "InlineCode", "__tag": 4051, "value": "common_dtype(common_dtype(dt1, dt2), dt3)" }, { "__type": "Text", "__tag": 4046, "value": " would depend on the operation order or fail. Nevertheless, DTypes should aim to ensure that their common-dtype implementation is associative and commutative! (Mainly, unsigned and signed integers are not.)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For guaranteed consistent results DTypes must implement common-Dtype \"transitively\". If A promotes B and B promotes C, than A must generally also promote C; where \"promotes\" means implements the promotion. (There are some exceptions for abstract DTypes)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In general this approach always works as long as the most generic dtype is either strictly larger, or compatible with all other dtypes. For example promoting " }, { "__type": "InlineCode", "__tag": 4051, "value": "float16" }, { "__type": "Text", "__tag": 4046, "value": " with any other float, integer, or unsigned integer again gives a floating point number." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data Type Promotion and Inspection" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 2.0" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These functions allow defining custom flexible data types outside of NumPy. See " }, { "__type": "InlineRole", "__tag": 4003, "value": "NEP 42 ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more details about the rationale and design of the new DType system. See the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy-user-dtypes repository" } ], "url": "https://github.com/numpy/numpy-user-dtypes", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for a number of example DTypes. Also see " }, { "__type": "CrossRef", "__tag": 4002, "value": "dtypemeta", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:types-and-structures" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for documentation on " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DTypeMeta" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayDTypeMeta_Spec" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initialize a new DType. It must currently be a static Python C type that is declared as " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DTypeMeta" }, { "__type": "Text", "__tag": 4046, "value": " and not " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyTypeObject" }, { "__type": "Text", "__tag": 4046, "value": ". Further, it must subclass " }, { "__type": "InlineRole", "__tag": 4003, "value": "np.dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and set its type to " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayDTypeMeta_Type" }, { "__type": "Text", "__tag": 4046, "value": " (before calling " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyType_Ready()" }, { "__type": "Text", "__tag": 4046, "value": "), which has additional fields compared to a normal " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyTypeObject" }, { "__type": "Text", "__tag": 4046, "value": ". See the examples in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy-user-dtypes" }, { "__type": "Text", "__tag": 4046, "value": " repository for usage with both parametric and non-parametric data types." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Custom Data Types" } ], "level": 1, "target": "dtype-api" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flags that can be set on the " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayDTypeMeta_Spec" }, { "__type": "Text", "__tag": 4046, "value": " to initialize the DType." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Flags" } ], "level": 2, "target": "dtype-flags" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These IDs correspond to slots in the DType API and are used to identify implementations of each slot from the items of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "slots" }, { "__type": "Text", "__tag": 4046, "value": " array member of " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArrayDTypeMeta_Spec" }, { "__type": "Text", "__tag": 4046, "value": " struct." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Used during DType inference to find the correct DType for a given PyObject. Must return a descriptor instance appropriate to store the data in the python object that is passed in. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the python object to inspect and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "cls" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the DType class to create a descriptor for." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns the default descriptor instance for the DType. Must be defined for parametric data types. Non-parametric data types return the singleton by default." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given two input DTypes, determines the appropriate \"common\" DType that can store values for both types. Returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "Py_NotImplemented" }, { "__type": "Text", "__tag": 4046, "value": " if no such type exists." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given two input descriptors, determines the appropriate \"common\" descriptor that can store values for both instances. Returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " on error." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns the \"canonical\" representation for a descriptor instance. The notion of a canonical descriptor generalizes the concept of byte order, in that a canonical descriptor always has native byte order. If the descriptor is already canonical, this function returns a new reference to the input descriptor." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If defined, a function that is called to \"finalize\" a descriptor instance after an array is created. One use of this function is to force newly created arrays to have a newly created descriptor instance, no matter what input descriptor is provided by a user." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If defined, allows the DType to expose constant values such as machine limits, special values (infinity, NaN), and floating-point characteristics. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "descr" } ] }, { "__type": "Text", "__tag": 4046, "value": " is the descriptor instance, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "constant_id" } ] }, { "__type": "Text", "__tag": 4046, "value": " is one of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CONSTANT_*" }, { "__type": "Text", "__tag": 4046, "value": " macros, and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a pointer to uninitialized memory where the constant value should be written. The memory pointed to by " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "out" } ] }, { "__type": "Text", "__tag": 4046, "value": " may be unaligned and is uninitialized. Returns 1 on success, 0 if the constant is not available, or -1 with an error set." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Constant IDs" } ] }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following constant IDs are defined for retrieving dtype-specific values:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Basic constants" } ] }, { "__type": "Text", "__tag": 4046, "value": " (available for all numeric types):" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Floating-point special values" } ] }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Floating-point characteristics" } ] }, { "__type": "Text", "__tag": 4046, "value": " (values of the dtype's native type):" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Floating-point characteristics" } ] }, { "__type": "Text", "__tag": 4046, "value": " (integer values, type " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_intp" }, { "__type": "Text", "__tag": 4046, "value": "):" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These constants return integer metadata about the floating-point representation. They are marked with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "1 << 16" }, { "__type": "Text", "__tag": 4046, "value": " bit to indicate they return " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_intp" }, { "__type": "Text", "__tag": 4046, "value": " values rather than the dtype's native type." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Slot IDs and API Function Typedefs" } ], "level": 2, "target": "dtype-slots" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In addition the above slots, the following slots are exposed to allow filling the " }, { "__type": "CrossRef", "__tag": 4002, "value": "arrfuncs-type", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:c-api:types-and-structures" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " struct attached to descriptor instances. Note that in the future these will be replaced by proper DType API slots but for now we have exposed the legacy " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ArrFuncs" }, { "__type": "Text", "__tag": 4046, "value": " slots." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "PyArray_ArrFuncs slots" } ], "level": 3, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These macros and static inline functions are provided to allow more understandable and idiomatic code when working with " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DTypeMeta" }, { "__type": "Text", "__tag": 4046, "value": " instances." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns a " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DTypeMeta *" }, { "__type": "Text", "__tag": 4046, "value": " pointer to a new reference to a DType." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Macros and Static Inline Functions" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Conversion utilities" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All of these functions can be used in " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArg_ParseTuple" }, { "__type": "Text", "__tag": 4046, "value": " (...) with the \"O&\" format specifier to automatically convert any Python object to the required C-object. All of these functions return " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SUCCEED" }, { "__type": "Text", "__tag": 4046, "value": " if successful and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FAIL" }, { "__type": "Text", "__tag": 4046, "value": " if not. The first argument to all of these function is a Python object. The second argument is the " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "address" } ] }, { "__type": "Text", "__tag": 4046, "value": " of the C-type to convert the Python object to." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Be sure to understand what steps you should take to manage the memory when using these conversion functions. These functions can require freeing memory, and/or altering the reference counts of specific objects based on your use." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is a default converter for output arrays given to functions. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "Py_None" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ", then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "\\*address" } ] }, { "__type": "Text", "__tag": 4046, "value": " will be " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": " but the call will succeed. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Check" }, { "__type": "Text", "__tag": 4046, "value": " ( " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": ") is TRUE then it is returned in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "\\*address" } ] }, { "__type": "Text", "__tag": 4046, "value": " without incrementing its reference count." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert Python strings into one of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SEARCHLEFT" }, { "__type": "Text", "__tag": 4046, "value": " (starts with 'l' or 'L'), or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SEARCHRIGHT" }, { "__type": "Text", "__tag": 4046, "value": " (starts with 'r' or 'R')." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert the Python strings 'no', 'equiv', 'safe', 'same_kind', and 'unsafe' into the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CASTING" }, { "__type": "Text", "__tag": 4046, "value": " enumeration " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_NO_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_EQUIV_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_SAME_KIND_CASTING" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_UNSAFE_CASTING" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert the Python strings 'clip', 'wrap', and 'raise' into the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CLIPMODE" }, { "__type": "Text", "__tag": 4046, "value": " enumeration " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CLIP" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_WRAP" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_RAISE" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Converts either a sequence of clipmodes or a single clipmode into a C array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CLIPMODE" }, { "__type": "Text", "__tag": 4046, "value": " values. The number of clipmodes " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "n" } ] }, { "__type": "Text", "__tag": 4046, "value": " must be known before calling this function. This function is provided to help functions allow a different clipmode for each dimension." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "For use with " }, { "__type": "InlineRole", "__tag": 4003, "value": "PyArg_ParseTuple", "domain": "c", "role": "func", "inventory": null } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert any Python sequence (or single Python number) passed in as " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "seq" } ] }, { "__type": "Text", "__tag": 4046, "value": " to (up to) " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "maxvals" } ] }, { "__type": "Text", "__tag": 4046, "value": " pointer-sized integers and place them in the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "vals" } ] }, { "__type": "Text", "__tag": 4046, "value": " array. The sequence can be smaller then " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "maxvals" } ] }, { "__type": "Text", "__tag": 4046, "value": " as the number of converted objects is returned." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Other conversions" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To use the NumPy C-API you typically need to include the " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/ndarrayobject.h" }, { "__type": "Text", "__tag": 4046, "value": " header and " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/ufuncobject.h" }, { "__type": "Text", "__tag": 4046, "value": " for some ufunc related functionality (" }, { "__type": "InlineCode", "__tag": 4051, "value": "arrayobject.h" }, { "__type": "Text", "__tag": 4046, "value": " is an alias for " }, { "__type": "InlineCode", "__tag": 4051, "value": "ndarrayobject.h" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These two headers export most relevant functionality. In general any project which uses the NumPy API must import NumPy using one of the functions " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ImportNumPyAPI()" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "import_array()" }, { "__type": "Text", "__tag": 4046, "value": ". In some places, functionality which requires " }, { "__type": "InlineCode", "__tag": 4051, "value": "import_array()" }, { "__type": "Text", "__tag": 4046, "value": " is not needed, because you only need type definitions. In this case, it is sufficient to include " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/ndarratypes.h" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the typical Python project, multiple C or C++ files will be compiled into a single shared object (the Python C-module) and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ImportNumPyAPI()" }, { "__type": "Text", "__tag": 4046, "value": " should be called inside it's module initialization." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When you have a single C-file, this will consist of:" } ] }, { "__type": "Code", "__tag": 4050, "value": "#include \"numpy/ndarrayobject.h\"\n\nPyMODINIT_FUNC PyInit_my_module(void)\n{\n if (PyArray_ImportNumPyAPI() < 0) {\n return NULL;\n }\n /* Other initialization code. */\n}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "However, most projects will have additional C files which are all linked together into a single Python module. In this case, the helper C files typically do not have a canonical place where " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ImportNumPyAPI" }, { "__type": "Text", "__tag": 4046, "value": " should be called (although it is OK and fast to call it often)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To solve this, NumPy provides the following pattern that the main file is modified to define " }, { "__type": "InlineCode", "__tag": 4051, "value": "PY_ARRAY_UNIQUE_SYMBOL" }, { "__type": "Text", "__tag": 4046, "value": " before the include:" } ] }, { "__type": "Code", "__tag": 4050, "value": "/* Main module file */\n#define PY_ARRAY_UNIQUE_SYMBOL MyModule\n#include \"numpy/ndarrayobject.h\"\n\nPyMODINIT_FUNC PyInit_my_module(void)\n{\n if (PyArray_ImportNumPyAPI() < 0) {\n return NULL;\n }\n /* Other initialization code. */\n}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "while the other files use:" } ] }, { "__type": "Code", "__tag": 4050, "value": "/* Second file without any import */\n#define NO_IMPORT_ARRAY\n#define PY_ARRAY_UNIQUE_SYMBOL MyModule\n#include \"numpy/ndarrayobject.h\"", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can of course add the defines to a local header used throughout. You just have to make sure that the main file does _not_ define " }, { "__type": "InlineCode", "__tag": 4051, "value": "NO_IMPORT_ARRAY" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/ufuncobject.h" }, { "__type": "Text", "__tag": 4046, "value": " the same logic applies, but the unique symbol mechanism is " }, { "__type": "InlineCode", "__tag": 4051, "value": "#define PY_UFUNC_UNIQUE_SYMBOL" }, { "__type": "Text", "__tag": 4046, "value": " (both can match)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additionally, you will probably wish to add a " }, { "__type": "InlineCode", "__tag": 4051, "value": "#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " to avoid warnings about possible use of old API." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you are experiencing access violations make sure that the NumPy API was properly imported and the symbol " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_API" }, { "__type": "Text", "__tag": 4046, "value": " is not " }, { "__type": "InlineCode", "__tag": 4051, "value": "NULL" }, { "__type": "Text", "__tag": 4046, "value": ". When in a debugger, this symbols actual name will be " }, { "__type": "InlineCode", "__tag": 4051, "value": "PY_ARRAY_UNIQUE_SYMBOL``+``PyArray_API" }, { "__type": "Text", "__tag": 4046, "value": ", so for example " }, { "__type": "InlineCode", "__tag": 4051, "value": "MyModulePyArray_API" }, { "__type": "Text", "__tag": 4046, "value": " in the above. (E.g. even a " }, { "__type": "InlineCode", "__tag": 4051, "value": "printf(\"%p\\n\", PyArray_API);" }, { "__type": "Text", "__tag": 4046, "value": " just before the crash.)" } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Including and importing the C API" } ], "level": 1, "target": "including-the-c-api" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The main part of the mechanism is that without NumPy needs to define a " }, { "__type": "InlineCode", "__tag": 4051, "value": "void **PyArray_API" }, { "__type": "Text", "__tag": 4046, "value": " table for you to look up all functions. Depending on your macro setup, this takes different routes depending on whether " }, { "__type": "InlineCode", "__tag": 4051, "value": "NO_IMPORT_ARRAY" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PY_ARRAY_UNIQUE_SYMBOL" }, { "__type": "Text", "__tag": 4046, "value": " are defined:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If neither is defined, the C-API is declared to " }, { "__type": "InlineCode", "__tag": 4051, "value": "static void **PyArray_API" }, { "__type": "Text", "__tag": 4046, "value": ", so it is only visible within the compilation unit/file using " }, { "__type": "InlineCode", "__tag": 4051, "value": "#include " }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If only " }, { "__type": "InlineCode", "__tag": 4051, "value": "PY_ARRAY_UNIQUE_SYMBOL" }, { "__type": "Text", "__tag": 4046, "value": " is defined (it could be empty) then the it is declared to a non-static " }, { "__type": "InlineCode", "__tag": 4051, "value": "void **" }, { "__type": "Text", "__tag": 4046, "value": " allowing it to be used by other files which are linked." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "NO_IMPORT_ARRAY" }, { "__type": "Text", "__tag": 4046, "value": " is defined, the table is declared as " }, { "__type": "InlineCode", "__tag": 4051, "value": "extern void **" }, { "__type": "Text", "__tag": 4046, "value": ", meaning that it must be linked to a file which does not use " }, { "__type": "InlineCode", "__tag": 4051, "value": "NO_IMPORT_ARRAY" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "PY_ARRAY_UNIQUE_SYMBOL" }, { "__type": "Text", "__tag": 4046, "value": " mechanism additionally mangles the names to avoid conflicts." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy 2.1 changed the headers to avoid sharing the table outside of a single shared object/dll (this was always the case on Windows). Please see " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_API_SYMBOL_ATTRIBUTE" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In order to make use of the C-API from another extension module, the " }, { "__type": "InlineCode", "__tag": 4051, "value": "import_array" }, { "__type": "Text", "__tag": 4046, "value": " function must be called. If the extension module is self-contained in a single .c file, then that is all that needs to be done. If, however, the extension module involves multiple files where the C-API is needed then some additional steps must be taken." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Mechanism details and dynamic linking" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Because python extensions are not used in the same way as usual libraries on most platforms, some errors cannot be automatically detected at build time or even runtime. For example, if you build an extension using a function available only for numpy >= 1.3.0, and you import the extension later with numpy 1.2, you will not get an import error (but almost certainly a segmentation fault when calling the function). That's why several functions are provided to check for numpy versions. The macros " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FEATURE_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " corresponds to the numpy version used to build the extension, whereas the versions returned by the functions " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GetNDArrayCVersion" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GetNDArrayCFeatureVersion" }, { "__type": "Text", "__tag": 4046, "value": " corresponds to the runtime numpy's version." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The rules for ABI and API compatibilities can be summarized as follows:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whenever " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " != " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GetNDArrayCVersion()" }, { "__type": "Text", "__tag": 4046, "value": ", the extension has to be recompiled (ABI incompatibility)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " == " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GetNDArrayCVersion()" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FEATURE_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " <= " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GetNDArrayCFeatureVersion()" }, { "__type": "Text", "__tag": 4046, "value": " means backward compatible changes." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "ABI incompatibility is automatically detected in every numpy's version. API incompatibility detection was added in numpy 1.4.0. If you want to supported many different numpy versions with one extension binary, you have to build your extension with the lowest " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_FEATURE_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " as possible." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Checking the API Version" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Memory management" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These macros are only meaningful if " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ALLOW_THREADS" }, { "__type": "Text", "__tag": 4046, "value": " evaluates True during compilation of the extension module. Otherwise, these macros are equivalent to whitespace. Python uses a single Global Interpreter Lock (GIL) for each Python process so that only a single thread may execute at a time (even on multi-cpu machines). When calling out to a compiled function that may take time to compute (and does not have side-effects for other threads like updated global variables), the GIL should be released so that other Python threads can run while the time-consuming calculations are performed. This can be accomplished using two groups of macros. Typically, if one macro in a group is used in a code block, all of them must be used in the same code block. " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ALLOW_THREADS" }, { "__type": "Text", "__tag": 4046, "value": " is true (defined as " }, { "__type": "InlineCode", "__tag": 4051, "value": "1" }, { "__type": "Text", "__tag": 4046, "value": ") unless the build option " }, { "__type": "InlineCode", "__tag": 4051, "value": "-Ddisable-threading" }, { "__type": "Text", "__tag": 4046, "value": " is set to " }, { "__type": "InlineCode", "__tag": 4051, "value": "true" }, { "__type": "Text", "__tag": 4046, "value": " - in which case " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_ALLOW_THREADS" }, { "__type": "Text", "__tag": 4046, "value": " is false (" }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Threading support" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This group is used to call code that may take some time but does not use any Python C-API calls. Thus, the GIL should be released during its calculation." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Group 1" } ], "level": 3, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This group is used to re-acquire the Python GIL after it has been released. For example, suppose the GIL has been released (using the previous calls), and then some path in the code (perhaps in a different subroutine) requires use of the Python C-API, then these macros are useful to acquire the GIL. These macros accomplish essentially a reverse of the previous three (acquire the LOCK saving what state it had) and then re-release it with the saved state." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "tip", "base_type": "tip", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "tip " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Never use semicolons after the threading support macros." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Group 2" } ], "level": 3, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Priority" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Default buffers" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Other constants" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Miscellaneous Macros" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Enumerated Types" } ], "level": 2, "target": null } ], "local_refs": [] }