multiarray_api.txt
1 2 =========== 3 NumPy C-API 4 =========== 5 :: 6 7 unsigned int 8 PyArray_GetNDArrayCVersion(void ) 9 10 11 Included at the very first so not auto-grabbed and thus not labeled. 12 13 :: 14 15 int 16 PyArray_SetNumericOps(PyObject *dict) 17 18 Set internal structure with number functions that all arrays will use 19 20 :: 21 22 PyObject * 23 PyArray_GetNumericOps(void ) 24 25 Get dictionary showing number functions that all arrays will use 26 27 :: 28 29 int 30 PyArray_INCREF(PyArrayObject *mp) 31 32 For object arrays, increment all internal references. 33 34 :: 35 36 int 37 PyArray_XDECREF(PyArrayObject *mp) 38 39 Decrement all internal references for object arrays. 40 (or arrays with object fields) 41 42 :: 43 44 void 45 PyArray_SetStringFunction(PyObject *op, int repr) 46 47 Set the array print function to be a Python function. 48 49 :: 50 51 PyArray_Descr * 52 PyArray_DescrFromType(int type) 53 54 Get the PyArray_Descr structure for a type. 55 56 :: 57 58 PyObject * 59 PyArray_TypeObjectFromType(int type) 60 61 Get a typeobject from a type-number -- can return NULL. 62 63 New reference 64 65 :: 66 67 char * 68 PyArray_Zero(PyArrayObject *arr) 69 70 Get pointer to zero of correct type for array. 71 72 :: 73 74 char * 75 PyArray_One(PyArrayObject *arr) 76 77 Get pointer to one of correct type for array 78 79 :: 80 81 PyObject * 82 PyArray_CastToType(PyArrayObject *arr, PyArray_Descr *dtype, int 83 is_f_order) 84 85 For backward compatibility 86 87 Cast an array using typecode structure. 88 steals reference to dtype --- cannot be NULL 89 90 This function always makes a copy of arr, even if the dtype 91 doesn't change. 92 93 :: 94 95 int 96 PyArray_CastTo(PyArrayObject *out, PyArrayObject *mp) 97 98 Cast to an already created array. 99 100 :: 101 102 int 103 PyArray_CastAnyTo(PyArrayObject *out, PyArrayObject *mp) 104 105 Cast to an already created array. Arrays don't have to be "broadcastable" 106 Only requirement is they have the same number of elements. 107 108 :: 109 110 int 111 PyArray_CanCastSafely(int fromtype, int totype) 112 113 Check the type coercion rules. 114 115 :: 116 117 npy_bool 118 PyArray_CanCastTo(PyArray_Descr *from, PyArray_Descr *to) 119 120 leaves reference count alone --- cannot be NULL 121 122 PyArray_CanCastTypeTo is equivalent to this, but adds a 'casting' 123 parameter. 124 125 :: 126 127 int 128 PyArray_ObjectType(PyObject *op, int minimum_type) 129 130 Return the typecode of the array a Python object would be converted to 131 132 Returns the type number the result should have, or NPY_NOTYPE on error. 133 134 :: 135 136 PyArray_Descr * 137 PyArray_DescrFromObject(PyObject *op, PyArray_Descr *mintype) 138 139 new reference -- accepts NULL for mintype 140 141 :: 142 143 PyArrayObject ** 144 PyArray_ConvertToCommonType(PyObject *op, int *retn) 145 146 147 This function is only used in one place within NumPy and should 148 generally be avoided. It is provided mainly for backward compatibility. 149 150 The user of the function has to free the returned array with PyDataMem_FREE. 151 152 :: 153 154 PyArray_Descr * 155 PyArray_DescrFromScalar(PyObject *sc) 156 157 Return descr object from array scalar. 158 159 New reference 160 161 :: 162 163 PyArray_Descr * 164 PyArray_DescrFromTypeObject(PyObject *type) 165 166 167 :: 168 169 npy_intp 170 PyArray_Size(PyObject *op) 171 172 Compute the size of an array (in number of items) 173 174 :: 175 176 PyObject * 177 PyArray_Scalar(void *data, PyArray_Descr *descr, PyObject *base) 178 179 Get scalar-equivalent to a region of memory described by a descriptor. 180 181 :: 182 183 PyObject * 184 PyArray_FromScalar(PyObject *scalar, PyArray_Descr *outcode) 185 186 Get 0-dim array from scalar 187 188 0-dim array from array-scalar object 189 always contains a copy of the data 190 unless outcode is NULL, it is of void type and the referrer does 191 not own it either. 192 193 steals reference to outcode 194 195 :: 196 197 void 198 PyArray_ScalarAsCtype(PyObject *scalar, void *ctypeptr) 199 200 Convert to c-type 201 202 no error checking is performed -- ctypeptr must be same type as scalar 203 in case of flexible type, the data is not copied 204 into ctypeptr which is expected to be a pointer to pointer 205 206 :: 207 208 int 209 PyArray_CastScalarToCtype(PyObject *scalar, void 210 *ctypeptr, PyArray_Descr *outcode) 211 212 Cast Scalar to c-type 213 214 The output buffer must be large-enough to receive the value 215 Even for flexible types which is different from ScalarAsCtype 216 where only a reference for flexible types is returned 217 218 This may not work right on narrow builds for NumPy unicode scalars. 219 220 :: 221 222 int 223 PyArray_CastScalarDirect(PyObject *scalar, PyArray_Descr 224 *indescr, void *ctypeptr, int outtype) 225 226 Cast Scalar to c-type 227 228 :: 229 230 PyObject * 231 PyArray_ScalarFromObject(PyObject *object) 232 233 Get an Array Scalar From a Python Object 234 235 Returns NULL if unsuccessful but error is only set if another error occurred. 236 Currently only Numeric-like object supported. 237 238 :: 239 240 PyArray_VectorUnaryFunc * 241 PyArray_GetCastFunc(PyArray_Descr *descr, int type_num) 242 243 Get a cast function to cast from the input descriptor to the 244 output type_number (must be a registered data-type). 245 Returns NULL if un-successful. 246 247 :: 248 249 PyObject * 250 PyArray_FromDims(int NPY_UNUSED(nd) , int *NPY_UNUSED(d) , int 251 NPY_UNUSED(type) ) 252 253 Deprecated, use PyArray_SimpleNew instead. 254 255 :: 256 257 PyObject * 258 PyArray_FromDimsAndDataAndDescr(int NPY_UNUSED(nd) , int 259 *NPY_UNUSED(d) , PyArray_Descr 260 *descr, char *NPY_UNUSED(data) ) 261 262 Deprecated, use PyArray_NewFromDescr instead. 263 264 :: 265 266 PyObject * 267 PyArray_FromAny(PyObject *op, PyArray_Descr *newtype, int 268 min_depth, int max_depth, int flags, PyObject 269 *context) 270 271 Does not check for NPY_ARRAY_ENSURECOPY and NPY_ARRAY_NOTSWAPPED in flags 272 Steals a reference to newtype --- which can be NULL 273 274 :: 275 276 PyObject * 277 PyArray_EnsureArray(PyObject *op) 278 279 This is a quick wrapper around 280 PyArray_FromAny(op, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY, NULL) 281 that special cases Arrays and PyArray_Scalars up front 282 It *steals a reference* to the object 283 It also guarantees that the result is PyArray_Type 284 Because it decrefs op if any conversion needs to take place 285 so it can be used like PyArray_EnsureArray(some_function(...)) 286 287 :: 288 289 PyObject * 290 PyArray_EnsureAnyArray(PyObject *op) 291 292 293 :: 294 295 PyObject * 296 PyArray_FromFile(FILE *fp, PyArray_Descr *dtype, npy_intp num, char 297 *sep) 298 299 300 Given a ``FILE *`` pointer ``fp``, and a ``PyArray_Descr``, return an 301 array corresponding to the data encoded in that file. 302 303 The reference to `dtype` is stolen (it is possible that the passed in 304 dtype is not held on to). 305 306 The number of elements to read is given as ``num``; if it is < 0, then 307 then as many as possible are read. 308 309 If ``sep`` is NULL or empty, then binary data is assumed, else 310 text data, with ``sep`` as the separator between elements. Whitespace in 311 the separator matches any length of whitespace in the text, and a match 312 for whitespace around the separator is added. 313 314 For memory-mapped files, use the buffer interface. No more data than 315 necessary is read by this routine. 316 317 :: 318 319 PyObject * 320 PyArray_FromString(char *data, npy_intp slen, PyArray_Descr 321 *dtype, npy_intp num, char *sep) 322 323 324 Given a pointer to a string ``data``, a string length ``slen``, and 325 a ``PyArray_Descr``, return an array corresponding to the data 326 encoded in that string. 327 328 If the dtype is NULL, the default array type is used (double). 329 If non-null, the reference is stolen. 330 331 If ``slen`` is < 0, then the end of string is used for text data. 332 It is an error for ``slen`` to be < 0 for binary data (since embedded NULLs 333 would be the norm). 334 335 The number of elements to read is given as ``num``; if it is < 0, then 336 then as many as possible are read. 337 338 If ``sep`` is NULL or empty, then binary data is assumed, else 339 text data, with ``sep`` as the separator between elements. Whitespace in 340 the separator matches any length of whitespace in the text, and a match 341 for whitespace around the separator is added. 342 343 :: 344 345 PyObject * 346 PyArray_FromBuffer(PyObject *buf, PyArray_Descr *type, npy_intp 347 count, npy_intp offset) 348 349 350 :: 351 352 PyObject * 353 PyArray_FromIter(PyObject *obj, PyArray_Descr *dtype, npy_intp count) 354 355 356 steals a reference to dtype (which cannot be NULL) 357 358 :: 359 360 PyObject * 361 PyArray_Return(PyArrayObject *mp) 362 363 364 Return either an array or the appropriate Python object if the array 365 is 0d and matches a Python type. 366 steals reference to mp 367 368 :: 369 370 PyObject * 371 PyArray_GetField(PyArrayObject *self, PyArray_Descr *typed, int 372 offset) 373 374 Get a subset of bytes from each element of the array 375 steals reference to typed, must not be NULL 376 377 :: 378 379 int 380 PyArray_SetField(PyArrayObject *self, PyArray_Descr *dtype, int 381 offset, PyObject *val) 382 383 Set a subset of bytes from each element of the array 384 steals reference to dtype, must not be NULL 385 386 :: 387 388 PyObject * 389 PyArray_Byteswap(PyArrayObject *self, npy_bool inplace) 390 391 392 :: 393 394 PyObject * 395 PyArray_Resize(PyArrayObject *self, PyArray_Dims *newshape, int 396 refcheck, NPY_ORDER NPY_UNUSED(order) ) 397 398 Resize (reallocate data). Only works if nothing else is referencing this 399 array and it is contiguous. If refcheck is 0, then the reference count is 400 not checked and assumed to be 1. You still must own this data and have no 401 weak-references and no base object. 402 403 :: 404 405 int 406 PyArray_MoveInto(PyArrayObject *dst, PyArrayObject *src) 407 408 Move the memory of one array into another, allowing for overlapping data. 409 410 Returns 0 on success, negative on failure. 411 412 :: 413 414 int 415 PyArray_CopyInto(PyArrayObject *dst, PyArrayObject *src) 416 417 Copy an Array into another array. 418 Broadcast to the destination shape if necessary. 419 420 Returns 0 on success, -1 on failure. 421 422 :: 423 424 int 425 PyArray_CopyAnyInto(PyArrayObject *dst, PyArrayObject *src) 426 427 Copy an Array into another array -- memory must not overlap 428 Does not require src and dest to have "broadcastable" shapes 429 (only the same number of elements). 430 431 TODO: For NumPy 2.0, this could accept an order parameter which 432 only allows NPY_CORDER and NPY_FORDER. Could also rename 433 this to CopyAsFlat to make the name more intuitive. 434 435 Returns 0 on success, -1 on error. 436 437 :: 438 439 int 440 PyArray_CopyObject(PyArrayObject *dest, PyObject *src_object) 441 442 443 :: 444 445 PyObject * 446 PyArray_NewCopy(PyArrayObject *obj, NPY_ORDER order) 447 448 Copy an array. 449 450 :: 451 452 PyObject * 453 PyArray_ToList(PyArrayObject *self) 454 455 To List 456 457 :: 458 459 PyObject * 460 PyArray_ToString(PyArrayObject *self, NPY_ORDER order) 461 462 463 :: 464 465 int 466 PyArray_ToFile(PyArrayObject *self, FILE *fp, char *sep, char *format) 467 468 To File 469 470 :: 471 472 int 473 PyArray_Dump(PyObject *self, PyObject *file, int protocol) 474 475 476 :: 477 478 PyObject * 479 PyArray_Dumps(PyObject *self, int protocol) 480 481 482 :: 483 484 int 485 PyArray_ValidType(int type) 486 487 Is the typenum valid? 488 489 :: 490 491 void 492 PyArray_UpdateFlags(PyArrayObject *ret, int flagmask) 493 494 Update Several Flags at once. 495 496 :: 497 498 PyObject * 499 PyArray_New(PyTypeObject *subtype, int nd, npy_intp const *dims, int 500 type_num, npy_intp const *strides, void *data, int 501 itemsize, int flags, PyObject *obj) 502 503 Generic new array creation routine. 504 505 :: 506 507 PyObject * 508 PyArray_NewFromDescr(PyTypeObject *subtype, PyArray_Descr *descr, int 509 nd, npy_intp const *dims, npy_intp const 510 *strides, void *data, int flags, PyObject *obj) 511 512 Generic new array creation routine. 513 514 steals a reference to descr. On failure or when dtype->subarray is 515 true, dtype will be decrefed. 516 517 :: 518 519 PyArray_Descr * 520 PyArray_DescrNew(PyArray_Descr *base) 521 522 base cannot be NULL 523 524 :: 525 526 PyArray_Descr * 527 PyArray_DescrNewFromType(int type_num) 528 529 530 :: 531 532 double 533 PyArray_GetPriority(PyObject *obj, double default_) 534 535 Get Priority from object 536 537 :: 538 539 PyObject * 540 PyArray_IterNew(PyObject *obj) 541 542 Get Iterator. 543 544 :: 545 546 PyObject* 547 PyArray_MultiIterNew(int n, ... ) 548 549 Get MultiIterator, 550 551 :: 552 553 int 554 PyArray_PyIntAsInt(PyObject *o) 555 556 557 :: 558 559 npy_intp 560 PyArray_PyIntAsIntp(PyObject *o) 561 562 563 :: 564 565 int 566 PyArray_Broadcast(PyArrayMultiIterObject *mit) 567 568 569 :: 570 571 void 572 PyArray_FillObjectArray(PyArrayObject *arr, PyObject *obj) 573 574 Assumes contiguous 575 576 :: 577 578 int 579 PyArray_FillWithScalar(PyArrayObject *arr, PyObject *obj) 580 581 582 :: 583 584 npy_bool 585 PyArray_CheckStrides(int elsize, int nd, npy_intp numbytes, npy_intp 586 offset, npy_intp const *dims, npy_intp const 587 *newstrides) 588 589 590 :: 591 592 PyArray_Descr * 593 PyArray_DescrNewByteorder(PyArray_Descr *self, char newendian) 594 595 596 returns a copy of the PyArray_Descr structure with the byteorder 597 altered: 598 no arguments: The byteorder is swapped (in all subfields as well) 599 single argument: The byteorder is forced to the given state 600 (in all subfields as well) 601 602 Valid states: ('big', '>') or ('little' or '<') 603 ('native', or '=') 604 605 If a descr structure with | is encountered it's own 606 byte-order is not changed but any fields are: 607 608 609 Deep bytorder change of a data-type descriptor 610 Leaves reference count of self unchanged --- does not DECREF self *** 611 612 :: 613 614 PyObject * 615 PyArray_IterAllButAxis(PyObject *obj, int *inaxis) 616 617 Get Iterator that iterates over all but one axis (don't use this with 618 PyArray_ITER_GOTO1D). The axis will be over-written if negative 619 with the axis having the smallest stride. 620 621 :: 622 623 PyObject * 624 PyArray_CheckFromAny(PyObject *op, PyArray_Descr *descr, int 625 min_depth, int max_depth, int requires, PyObject 626 *context) 627 628 steals a reference to descr -- accepts NULL 629 630 :: 631 632 PyObject * 633 PyArray_FromArray(PyArrayObject *arr, PyArray_Descr *newtype, int 634 flags) 635 636 steals reference to newtype --- acc. NULL 637 638 :: 639 640 PyObject * 641 PyArray_FromInterface(PyObject *origin) 642 643 644 :: 645 646 PyObject * 647 PyArray_FromStructInterface(PyObject *input) 648 649 650 :: 651 652 PyObject * 653 PyArray_FromArrayAttr(PyObject *op, PyArray_Descr *typecode, PyObject 654 *context) 655 656 657 :: 658 659 NPY_SCALARKIND 660 PyArray_ScalarKind(int typenum, PyArrayObject **arr) 661 662 ScalarKind 663 664 Returns the scalar kind of a type number, with an 665 optional tweak based on the scalar value itself. 666 If no scalar is provided, it returns INTPOS_SCALAR 667 for both signed and unsigned integers, otherwise 668 it checks the sign of any signed integer to choose 669 INTNEG_SCALAR when appropriate. 670 671 :: 672 673 int 674 PyArray_CanCoerceScalar(int thistype, int neededtype, NPY_SCALARKIND 675 scalar) 676 677 678 Determines whether the data type 'thistype', with 679 scalar kind 'scalar', can be coerced into 'neededtype'. 680 681 :: 682 683 PyObject * 684 PyArray_NewFlagsObject(PyObject *obj) 685 686 687 Get New ArrayFlagsObject 688 689 :: 690 691 npy_bool 692 PyArray_CanCastScalar(PyTypeObject *from, PyTypeObject *to) 693 694 See if array scalars can be cast. 695 696 TODO: For NumPy 2.0, add a NPY_CASTING parameter. 697 698 :: 699 700 int 701 PyArray_CompareUCS4(npy_ucs4 const *s1, npy_ucs4 const *s2, size_t 702 len) 703 704 705 :: 706 707 int 708 PyArray_RemoveSmallest(PyArrayMultiIterObject *multi) 709 710 Adjusts previously broadcasted iterators so that the axis with 711 the smallest sum of iterator strides is not iterated over. 712 Returns dimension which is smallest in the range [0,multi->nd). 713 A -1 is returned if multi->nd == 0. 714 715 don't use with PyArray_ITER_GOTO1D because factors are not adjusted 716 717 :: 718 719 int 720 PyArray_ElementStrides(PyObject *obj) 721 722 723 :: 724 725 void 726 PyArray_Item_INCREF(char *data, PyArray_Descr *descr) 727 728 XINCREF all objects in a single array item. This is complicated for 729 structured datatypes where the position of objects needs to be extracted. 730 The function is execute recursively for each nested field or subarrays dtype 731 such as as `np.dtype([("field1", "O"), ("field2", "f,O", (3,2))])` 732 733 :: 734 735 void 736 PyArray_Item_XDECREF(char *data, PyArray_Descr *descr) 737 738 739 XDECREF all objects in a single array item. This is complicated for 740 structured datatypes where the position of objects needs to be extracted. 741 The function is execute recursively for each nested field or subarrays dtype 742 such as as `np.dtype([("field1", "O"), ("field2", "f,O", (3,2))])` 743 744 :: 745 746 PyObject * 747 PyArray_FieldNames(PyObject *fields) 748 749 Return the tuple of ordered field names from a dictionary. 750 751 :: 752 753 PyObject * 754 PyArray_Transpose(PyArrayObject *ap, PyArray_Dims *permute) 755 756 Return Transpose. 757 758 :: 759 760 PyObject * 761 PyArray_TakeFrom(PyArrayObject *self0, PyObject *indices0, int 762 axis, PyArrayObject *out, NPY_CLIPMODE clipmode) 763 764 Take 765 766 :: 767 768 PyObject * 769 PyArray_PutTo(PyArrayObject *self, PyObject*values0, PyObject 770 *indices0, NPY_CLIPMODE clipmode) 771 772 Put values into an array 773 774 :: 775 776 PyObject * 777 PyArray_PutMask(PyArrayObject *self, PyObject*values0, PyObject*mask0) 778 779 Put values into an array according to a mask. 780 781 :: 782 783 PyObject * 784 PyArray_Repeat(PyArrayObject *aop, PyObject *op, int axis) 785 786 Repeat the array. 787 788 :: 789 790 PyObject * 791 PyArray_Choose(PyArrayObject *ip, PyObject *op, PyArrayObject 792 *out, NPY_CLIPMODE clipmode) 793 794 795 :: 796 797 int 798 PyArray_Sort(PyArrayObject *op, int axis, NPY_SORTKIND which) 799 800 Sort an array in-place 801 802 :: 803 804 PyObject * 805 PyArray_ArgSort(PyArrayObject *op, int axis, NPY_SORTKIND which) 806 807 ArgSort an array 808 809 :: 810 811 PyObject * 812 PyArray_SearchSorted(PyArrayObject *op1, PyObject *op2, NPY_SEARCHSIDE 813 side, PyObject *perm) 814 815 816 Search the sorted array op1 for the location of the items in op2. The 817 result is an array of indexes, one for each element in op2, such that if 818 the item were to be inserted in op1 just before that index the array 819 would still be in sorted order. 820 821 Parameters 822 ---------- 823 op1 : PyArrayObject * 824 Array to be searched, must be 1-D. 825 op2 : PyObject * 826 Array of items whose insertion indexes in op1 are wanted 827 side : {NPY_SEARCHLEFT, NPY_SEARCHRIGHT} 828 If NPY_SEARCHLEFT, return first valid insertion indexes 829 If NPY_SEARCHRIGHT, return last valid insertion indexes 830 perm : PyObject * 831 Permutation array that sorts op1 (optional) 832 833 Returns 834 ------- 835 ret : PyObject * 836 New reference to npy_intp array containing indexes where items in op2 837 could be validly inserted into op1. NULL on error. 838 839 Notes 840 ----- 841 Binary search is used to find the indexes. 842 843 :: 844 845 PyObject * 846 PyArray_ArgMax(PyArrayObject *op, int axis, PyArrayObject *out) 847 848 ArgMax 849 850 :: 851 852 PyObject * 853 PyArray_ArgMin(PyArrayObject *op, int axis, PyArrayObject *out) 854 855 ArgMin 856 857 :: 858 859 PyObject * 860 PyArray_Reshape(PyArrayObject *self, PyObject *shape) 861 862 Reshape 863 864 :: 865 866 PyObject * 867 PyArray_Newshape(PyArrayObject *self, PyArray_Dims *newdims, NPY_ORDER 868 order) 869 870 New shape for an array 871 872 :: 873 874 PyObject * 875 PyArray_Squeeze(PyArrayObject *self) 876 877 878 return a new view of the array object with all of its unit-length 879 dimensions squeezed out if needed, otherwise 880 return the same array. 881 882 :: 883 884 PyObject * 885 PyArray_View(PyArrayObject *self, PyArray_Descr *type, PyTypeObject 886 *pytype) 887 888 View 889 steals a reference to type -- accepts NULL 890 891 :: 892 893 PyObject * 894 PyArray_SwapAxes(PyArrayObject *ap, int a1, int a2) 895 896 SwapAxes 897 898 :: 899 900 PyObject * 901 PyArray_Max(PyArrayObject *ap, int axis, PyArrayObject *out) 902 903 Max 904 905 :: 906 907 PyObject * 908 PyArray_Min(PyArrayObject *ap, int axis, PyArrayObject *out) 909 910 Min 911 912 :: 913 914 PyObject * 915 PyArray_Ptp(PyArrayObject *ap, int axis, PyArrayObject *out) 916 917 Ptp 918 919 :: 920 921 PyObject * 922 PyArray_Mean(PyArrayObject *self, int axis, int rtype, PyArrayObject 923 *out) 924 925 Mean 926 927 :: 928 929 PyObject * 930 PyArray_Trace(PyArrayObject *self, int offset, int axis1, int 931 axis2, int rtype, PyArrayObject *out) 932 933 Trace 934 935 :: 936 937 PyObject * 938 PyArray_Diagonal(PyArrayObject *self, int offset, int axis1, int 939 axis2) 940 941 Diagonal 942 943 In NumPy versions prior to 1.7, this function always returned a copy of 944 the diagonal array. In 1.7, the code has been updated to compute a view 945 onto 'self', but it still copies this array before returning, as well as 946 setting the internal WARN_ON_WRITE flag. In a future version, it will 947 simply return a view onto self. 948 949 :: 950 951 PyObject * 952 PyArray_Clip(PyArrayObject *self, PyObject *min, PyObject 953 *max, PyArrayObject *out) 954 955 Clip 956 957 :: 958 959 PyObject * 960 PyArray_Conjugate(PyArrayObject *self, PyArrayObject *out) 961 962 Conjugate 963 964 :: 965 966 PyObject * 967 PyArray_Nonzero(PyArrayObject *self) 968 969 Nonzero 970 971 TODO: In NumPy 2.0, should make the iteration order a parameter. 972 973 :: 974 975 PyObject * 976 PyArray_Std(PyArrayObject *self, int axis, int rtype, PyArrayObject 977 *out, int variance) 978 979 Set variance to 1 to by-pass square-root calculation and return variance 980 Std 981 982 :: 983 984 PyObject * 985 PyArray_Sum(PyArrayObject *self, int axis, int rtype, PyArrayObject 986 *out) 987 988 Sum 989 990 :: 991 992 PyObject * 993 PyArray_CumSum(PyArrayObject *self, int axis, int rtype, PyArrayObject 994 *out) 995 996 CumSum 997 998 :: 999 1000 PyObject * 1001 PyArray_Prod(PyArrayObject *self, int axis, int rtype, PyArrayObject 1002 *out) 1003 1004 Prod 1005 1006 :: 1007 1008 PyObject * 1009 PyArray_CumProd(PyArrayObject *self, int axis, int 1010 rtype, PyArrayObject *out) 1011 1012 CumProd 1013 1014 :: 1015 1016 PyObject * 1017 PyArray_All(PyArrayObject *self, int axis, PyArrayObject *out) 1018 1019 All 1020 1021 :: 1022 1023 PyObject * 1024 PyArray_Any(PyArrayObject *self, int axis, PyArrayObject *out) 1025 1026 Any 1027 1028 :: 1029 1030 PyObject * 1031 PyArray_Compress(PyArrayObject *self, PyObject *condition, int 1032 axis, PyArrayObject *out) 1033 1034 Compress 1035 1036 :: 1037 1038 PyObject * 1039 PyArray_Flatten(PyArrayObject *a, NPY_ORDER order) 1040 1041 Flatten 1042 1043 :: 1044 1045 PyObject * 1046 PyArray_Ravel(PyArrayObject *arr, NPY_ORDER order) 1047 1048 Ravel 1049 Returns a contiguous array 1050 1051 :: 1052 1053 npy_intp 1054 PyArray_MultiplyList(npy_intp const *l1, int n) 1055 1056 Multiply a List 1057 1058 :: 1059 1060 int 1061 PyArray_MultiplyIntList(int const *l1, int n) 1062 1063 Multiply a List of ints 1064 1065 :: 1066 1067 void * 1068 PyArray_GetPtr(PyArrayObject *obj, npy_intp const*ind) 1069 1070 Produce a pointer into array 1071 1072 :: 1073 1074 int 1075 PyArray_CompareLists(npy_intp const *l1, npy_intp const *l2, int n) 1076 1077 Compare Lists 1078 1079 :: 1080 1081 int 1082 PyArray_AsCArray(PyObject **op, void *ptr, npy_intp *dims, int 1083 nd, PyArray_Descr*typedescr) 1084 1085 Simulate a C-array 1086 steals a reference to typedescr -- can be NULL 1087 1088 :: 1089 1090 int 1091 PyArray_As1D(PyObject **NPY_UNUSED(op) , char **NPY_UNUSED(ptr) , int 1092 *NPY_UNUSED(d1) , int NPY_UNUSED(typecode) ) 1093 1094 Convert to a 1D C-array 1095 1096 :: 1097 1098 int 1099 PyArray_As2D(PyObject **NPY_UNUSED(op) , char ***NPY_UNUSED(ptr) , int 1100 *NPY_UNUSED(d1) , int *NPY_UNUSED(d2) , int 1101 NPY_UNUSED(typecode) ) 1102 1103 Convert to a 2D C-array 1104 1105 :: 1106 1107 int 1108 PyArray_Free(PyObject *op, void *ptr) 1109 1110 Free pointers created if As2D is called 1111 1112 :: 1113 1114 int 1115 PyArray_Converter(PyObject *object, PyObject **address) 1116 1117 1118 Useful to pass as converter function for O& processing in PyArgs_ParseTuple. 1119 1120 This conversion function can be used with the "O&" argument for 1121 PyArg_ParseTuple. It will immediately return an object of array type 1122 or will convert to a NPY_ARRAY_CARRAY any other object. 1123 1124 If you use PyArray_Converter, you must DECREF the array when finished 1125 as you get a new reference to it. 1126 1127 :: 1128 1129 int 1130 PyArray_IntpFromSequence(PyObject *seq, npy_intp *vals, int maxvals) 1131 1132 PyArray_IntpFromSequence 1133 Returns the number of integers converted or -1 if an error occurred. 1134 vals must be large enough to hold maxvals 1135 1136 :: 1137 1138 PyObject * 1139 PyArray_Concatenate(PyObject *op, int axis) 1140 1141 Concatenate 1142 1143 Concatenate an arbitrary Python sequence into an array. 1144 op is a python object supporting the sequence interface. 1145 Its elements will be concatenated together to form a single 1146 multidimensional array. If axis is NPY_MAXDIMS or bigger, then 1147 each sequence object will be flattened before concatenation 1148 1149 :: 1150 1151 PyObject * 1152 PyArray_InnerProduct(PyObject *op1, PyObject *op2) 1153 1154 Numeric.innerproduct(a,v) 1155 1156 :: 1157 1158 PyObject * 1159 PyArray_MatrixProduct(PyObject *op1, PyObject *op2) 1160 1161 Numeric.matrixproduct(a,v) 1162 just like inner product but does the swapaxes stuff on the fly 1163 1164 :: 1165 1166 PyObject * 1167 PyArray_CopyAndTranspose(PyObject *op) 1168 1169 Copy and Transpose 1170 1171 Could deprecate this function, as there isn't a speed benefit over 1172 calling Transpose and then Copy. 1173 1174 :: 1175 1176 PyObject * 1177 PyArray_Correlate(PyObject *op1, PyObject *op2, int mode) 1178 1179 Numeric.correlate(a1,a2,mode) 1180 1181 :: 1182 1183 int 1184 PyArray_TypestrConvert(int itemsize, int gentype) 1185 1186 Typestr converter 1187 1188 :: 1189 1190 int 1191 PyArray_DescrConverter(PyObject *obj, PyArray_Descr **at) 1192 1193 Get typenum from an object -- None goes to NPY_DEFAULT_TYPE 1194 This function takes a Python object representing a type and converts it 1195 to a the correct PyArray_Descr * structure to describe the type. 1196 1197 Many objects can be used to represent a data-type which in NumPy is 1198 quite a flexible concept. 1199 1200 This is the central code that converts Python objects to 1201 Type-descriptor objects that are used throughout numpy. 1202 1203 Returns a new reference in *at, but the returned should not be 1204 modified as it may be one of the canonical immutable objects or 1205 a reference to the input obj. 1206 1207 :: 1208 1209 int 1210 PyArray_DescrConverter2(PyObject *obj, PyArray_Descr **at) 1211 1212 Get typenum from an object -- None goes to NULL 1213 1214 :: 1215 1216 int 1217 PyArray_IntpConverter(PyObject *obj, PyArray_Dims *seq) 1218 1219 Get intp chunk from sequence 1220 1221 This function takes a Python sequence object and allocates and 1222 fills in an intp array with the converted values. 1223 1224 Remember to free the pointer seq.ptr when done using 1225 PyDimMem_FREE(seq.ptr)** 1226 1227 :: 1228 1229 int 1230 PyArray_BufferConverter(PyObject *obj, PyArray_Chunk *buf) 1231 1232 Get buffer chunk from object 1233 1234 this function takes a Python object which exposes the (single-segment) 1235 buffer interface and returns a pointer to the data segment 1236 1237 You should increment the reference count by one of buf->base 1238 if you will hang on to a reference 1239 1240 You only get a borrowed reference to the object. Do not free the 1241 memory... 1242 1243 :: 1244 1245 int 1246 PyArray_AxisConverter(PyObject *obj, int *axis) 1247 1248 Get axis from an object (possibly None) -- a converter function, 1249 1250 See also PyArray_ConvertMultiAxis, which also handles a tuple of axes. 1251 1252 :: 1253 1254 int 1255 PyArray_BoolConverter(PyObject *object, npy_bool *val) 1256 1257 Convert an object to true / false 1258 1259 :: 1260 1261 int 1262 PyArray_ByteorderConverter(PyObject *obj, char *endian) 1263 1264 Convert object to endian 1265 1266 :: 1267 1268 int 1269 PyArray_OrderConverter(PyObject *object, NPY_ORDER *val) 1270 1271 Convert an object to FORTRAN / C / ANY / KEEP 1272 1273 :: 1274 1275 unsigned char 1276 PyArray_EquivTypes(PyArray_Descr *type1, PyArray_Descr *type2) 1277 1278 1279 This function returns true if the two typecodes are 1280 equivalent (same basic kind and same itemsize). 1281 1282 :: 1283 1284 PyObject * 1285 PyArray_Zeros(int nd, npy_intp const *dims, PyArray_Descr *type, int 1286 is_f_order) 1287 1288 Zeros 1289 1290 steals a reference to type. On failure or when dtype->subarray is 1291 true, dtype will be decrefed. 1292 accepts NULL type 1293 1294 :: 1295 1296 PyObject * 1297 PyArray_Empty(int nd, npy_intp const *dims, PyArray_Descr *type, int 1298 is_f_order) 1299 1300 Empty 1301 1302 accepts NULL type 1303 steals a reference to type 1304 1305 :: 1306 1307 PyObject * 1308 PyArray_Where(PyObject *condition, PyObject *x, PyObject *y) 1309 1310 Where 1311 1312 :: 1313 1314 PyObject * 1315 PyArray_Arange(double start, double stop, double step, int type_num) 1316 1317 Arange, 1318 1319 :: 1320 1321 PyObject * 1322 PyArray_ArangeObj(PyObject *start, PyObject *stop, PyObject 1323 *step, PyArray_Descr *dtype) 1324 1325 1326 ArangeObj, 1327 1328 this doesn't change the references 1329 1330 :: 1331 1332 int 1333 PyArray_SortkindConverter(PyObject *obj, NPY_SORTKIND *sortkind) 1334 1335 Convert object to sort kind 1336 1337 :: 1338 1339 PyObject * 1340 PyArray_LexSort(PyObject *sort_keys, int axis) 1341 1342 LexSort an array providing indices that will sort a collection of arrays 1343 lexicographically. The first key is sorted on first, followed by the second key 1344 -- requires that arg"merge"sort is available for each sort_key 1345 1346 Returns an index array that shows the indexes for the lexicographic sort along 1347 the given axis. 1348 1349 :: 1350 1351 PyObject * 1352 PyArray_Round(PyArrayObject *a, int decimals, PyArrayObject *out) 1353 1354 Round 1355 1356 :: 1357 1358 unsigned char 1359 PyArray_EquivTypenums(int typenum1, int typenum2) 1360 1361 1362 :: 1363 1364 int 1365 PyArray_RegisterDataType(PyArray_Descr *descr) 1366 1367 Register Data type 1368 Does not change the reference count of descr 1369 1370 :: 1371 1372 int 1373 PyArray_RegisterCastFunc(PyArray_Descr *descr, int 1374 totype, PyArray_VectorUnaryFunc *castfunc) 1375 1376 Register Casting Function 1377 Replaces any function currently stored. 1378 1379 :: 1380 1381 int 1382 PyArray_RegisterCanCast(PyArray_Descr *descr, int 1383 totype, NPY_SCALARKIND scalar) 1384 1385 Register a type number indicating that a descriptor can be cast 1386 to it safely 1387 1388 :: 1389 1390 void 1391 PyArray_InitArrFuncs(PyArray_ArrFuncs *f) 1392 1393 Initialize arrfuncs to NULL 1394 1395 :: 1396 1397 PyObject * 1398 PyArray_IntTupleFromIntp(int len, npy_intp const *vals) 1399 1400 PyArray_IntTupleFromIntp 1401 1402 :: 1403 1404 int 1405 PyArray_TypeNumFromName(char const *str) 1406 1407 1408 :: 1409 1410 int 1411 PyArray_ClipmodeConverter(PyObject *object, NPY_CLIPMODE *val) 1412 1413 Convert an object to NPY_RAISE / NPY_CLIP / NPY_WRAP 1414 1415 :: 1416 1417 int 1418 PyArray_OutputConverter(PyObject *object, PyArrayObject **address) 1419 1420 Useful to pass as converter function for O& processing in 1421 PyArgs_ParseTuple for output arrays 1422 1423 :: 1424 1425 PyObject * 1426 PyArray_BroadcastToShape(PyObject *obj, npy_intp *dims, int nd) 1427 1428 Get Iterator broadcast to a particular shape 1429 1430 :: 1431 1432 void 1433 _PyArray_SigintHandler(int signum) 1434 1435 1436 :: 1437 1438 void* 1439 _PyArray_GetSigintBuf(void ) 1440 1441 1442 :: 1443 1444 int 1445 PyArray_DescrAlignConverter(PyObject *obj, PyArray_Descr **at) 1446 1447 1448 Get type-descriptor from an object forcing alignment if possible 1449 None goes to DEFAULT type. 1450 1451 any object with the .fields attribute and/or .itemsize attribute (if the 1452 .fields attribute does not give the total size -- i.e. a partial record 1453 naming). If itemsize is given it must be >= size computed from fields 1454 1455 The .fields attribute must return a convertible dictionary if present. 1456 Result inherits from NPY_VOID. 1457 1458 :: 1459 1460 int 1461 PyArray_DescrAlignConverter2(PyObject *obj, PyArray_Descr **at) 1462 1463 1464 Get type-descriptor from an object forcing alignment if possible 1465 None goes to NULL. 1466 1467 :: 1468 1469 int 1470 PyArray_SearchsideConverter(PyObject *obj, void *addr) 1471 1472 Convert object to searchsorted side 1473 1474 :: 1475 1476 PyObject * 1477 PyArray_CheckAxis(PyArrayObject *arr, int *axis, int flags) 1478 1479 PyArray_CheckAxis 1480 1481 check that axis is valid 1482 convert 0-d arrays to 1-d arrays 1483 1484 :: 1485 1486 npy_intp 1487 PyArray_OverflowMultiplyList(npy_intp const *l1, int n) 1488 1489 Multiply a List of Non-negative numbers with over-flow detection. 1490 1491 :: 1492 1493 int 1494 PyArray_CompareString(const char *s1, const char *s2, size_t len) 1495 1496 1497 :: 1498 1499 PyObject* 1500 PyArray_MultiIterFromObjects(PyObject **mps, int n, int nadd, ... ) 1501 1502 Get MultiIterator from array of Python objects and any additional 1503 1504 PyObject **mps - array of PyObjects 1505 int n - number of PyObjects in the array 1506 int nadd - number of additional arrays to include in the iterator. 1507 1508 Returns a multi-iterator object. 1509 1510 :: 1511 1512 int 1513 PyArray_GetEndianness(void ) 1514 1515 1516 :: 1517 1518 unsigned int 1519 PyArray_GetNDArrayCFeatureVersion(void ) 1520 1521 Returns the built-in (at compilation time) C API version 1522 1523 :: 1524 1525 PyObject * 1526 PyArray_Correlate2(PyObject *op1, PyObject *op2, int mode) 1527 1528 correlate(a1,a2,mode) 1529 1530 This function computes the usual correlation (correlate(a1, a2) != 1531 correlate(a2, a1), and conjugate the second argument for complex inputs 1532 1533 :: 1534 1535 PyObject* 1536 PyArray_NeighborhoodIterNew(PyArrayIterObject *x, const npy_intp 1537 *bounds, int mode, PyArrayObject*fill) 1538 1539 A Neighborhood Iterator object. 1540 1541 :: 1542 1543 void 1544 PyArray_SetDatetimeParseFunction(PyObject *NPY_UNUSED(op) ) 1545 1546 This function is scheduled to be removed 1547 1548 TO BE REMOVED - NOT USED INTERNALLY. 1549 1550 :: 1551 1552 void 1553 PyArray_DatetimeToDatetimeStruct(npy_datetime NPY_UNUSED(val) 1554 , NPY_DATETIMEUNIT NPY_UNUSED(fr) 1555 , npy_datetimestruct *result) 1556 1557 Fill the datetime struct from the value and resolution unit. 1558 1559 TO BE REMOVED - NOT USED INTERNALLY. 1560 1561 :: 1562 1563 void 1564 PyArray_TimedeltaToTimedeltaStruct(npy_timedelta NPY_UNUSED(val) 1565 , NPY_DATETIMEUNIT NPY_UNUSED(fr) 1566 , npy_timedeltastruct *result) 1567 1568 Fill the timedelta struct from the timedelta value and resolution unit. 1569 1570 TO BE REMOVED - NOT USED INTERNALLY. 1571 1572 :: 1573 1574 npy_datetime 1575 PyArray_DatetimeStructToDatetime(NPY_DATETIMEUNIT NPY_UNUSED(fr) 1576 , npy_datetimestruct *NPY_UNUSED(d) ) 1577 1578 Create a datetime value from a filled datetime struct and resolution unit. 1579 1580 TO BE REMOVED - NOT USED INTERNALLY. 1581 1582 :: 1583 1584 npy_datetime 1585 PyArray_TimedeltaStructToTimedelta(NPY_DATETIMEUNIT NPY_UNUSED(fr) 1586 , npy_timedeltastruct 1587 *NPY_UNUSED(d) ) 1588 1589 Create a timedelta value from a filled timedelta struct and resolution unit. 1590 1591 TO BE REMOVED - NOT USED INTERNALLY. 1592 1593 :: 1594 1595 NpyIter * 1596 NpyIter_New(PyArrayObject *op, npy_uint32 flags, NPY_ORDER 1597 order, NPY_CASTING casting, PyArray_Descr*dtype) 1598 1599 Allocate a new iterator for one array object. 1600 1601 :: 1602 1603 NpyIter * 1604 NpyIter_MultiNew(int nop, PyArrayObject **op_in, npy_uint32 1605 flags, NPY_ORDER order, NPY_CASTING 1606 casting, npy_uint32 *op_flags, PyArray_Descr 1607 **op_request_dtypes) 1608 1609 Allocate a new iterator for more than one array object, using 1610 standard NumPy broadcasting rules and the default buffer size. 1611 1612 :: 1613 1614 NpyIter * 1615 NpyIter_AdvancedNew(int nop, PyArrayObject **op_in, npy_uint32 1616 flags, NPY_ORDER order, NPY_CASTING 1617 casting, npy_uint32 *op_flags, PyArray_Descr 1618 **op_request_dtypes, int oa_ndim, int 1619 **op_axes, npy_intp *itershape, npy_intp 1620 buffersize) 1621 1622 Allocate a new iterator for multiple array objects, and advanced 1623 options for controlling the broadcasting, shape, and buffer size. 1624 1625 :: 1626 1627 NpyIter * 1628 NpyIter_Copy(NpyIter *iter) 1629 1630 Makes a copy of the iterator 1631 1632 :: 1633 1634 int 1635 NpyIter_Deallocate(NpyIter *iter) 1636 1637 Deallocate an iterator. 1638 1639 To correctly work when an error is in progress, we have to check 1640 `PyErr_Occurred()`. This is necessary when buffers are not finalized 1641 or WritebackIfCopy is used. We could avoid that check by exposing a new 1642 function which is passed in whether or not a Python error is already set. 1643 1644 :: 1645 1646 npy_bool 1647 NpyIter_HasDelayedBufAlloc(NpyIter *iter) 1648 1649 Whether the buffer allocation is being delayed 1650 1651 :: 1652 1653 npy_bool 1654 NpyIter_HasExternalLoop(NpyIter *iter) 1655 1656 Whether the iterator handles the inner loop 1657 1658 :: 1659 1660 int 1661 NpyIter_EnableExternalLoop(NpyIter *iter) 1662 1663 Removes the inner loop handling (so HasExternalLoop returns true) 1664 1665 :: 1666 1667 npy_intp * 1668 NpyIter_GetInnerStrideArray(NpyIter *iter) 1669 1670 Get the array of strides for the inner loop (when HasExternalLoop is true) 1671 1672 This function may be safely called without holding the Python GIL. 1673 1674 :: 1675 1676 npy_intp * 1677 NpyIter_GetInnerLoopSizePtr(NpyIter *iter) 1678 1679 Get a pointer to the size of the inner loop (when HasExternalLoop is true) 1680 1681 This function may be safely called without holding the Python GIL. 1682 1683 :: 1684 1685 int 1686 NpyIter_Reset(NpyIter *iter, char **errmsg) 1687 1688 Resets the iterator to its initial state 1689 1690 The use of errmsg is discouraged, it cannot be guaranteed that the GIL 1691 will not be grabbed on casting errors even when this is passed. 1692 1693 If errmsg is non-NULL, it should point to a variable which will 1694 receive the error message, and no Python exception will be set. 1695 This is so that the function can be called from code not holding 1696 the GIL. Note that cast errors may still lead to the GIL being 1697 grabbed temporarily. 1698 1699 :: 1700 1701 int 1702 NpyIter_ResetBasePointers(NpyIter *iter, char **baseptrs, char 1703 **errmsg) 1704 1705 Resets the iterator to its initial state, with new base data pointers. 1706 This function requires great caution. 1707 1708 If errmsg is non-NULL, it should point to a variable which will 1709 receive the error message, and no Python exception will be set. 1710 This is so that the function can be called from code not holding 1711 the GIL. Note that cast errors may still lead to the GIL being 1712 grabbed temporarily. 1713 1714 :: 1715 1716 int 1717 NpyIter_ResetToIterIndexRange(NpyIter *iter, npy_intp istart, npy_intp 1718 iend, char **errmsg) 1719 1720 Resets the iterator to a new iterator index range 1721 1722 If errmsg is non-NULL, it should point to a variable which will 1723 receive the error message, and no Python exception will be set. 1724 This is so that the function can be called from code not holding 1725 the GIL. Note that cast errors may still lead to the GIL being 1726 grabbed temporarily. 1727 1728 :: 1729 1730 int 1731 NpyIter_GetNDim(NpyIter *iter) 1732 1733 Gets the number of dimensions being iterated 1734 1735 :: 1736 1737 int 1738 NpyIter_GetNOp(NpyIter *iter) 1739 1740 Gets the number of operands being iterated 1741 1742 :: 1743 1744 NpyIter_IterNextFunc * 1745 NpyIter_GetIterNext(NpyIter *iter, char **errmsg) 1746 1747 Compute the specialized iteration function for an iterator 1748 1749 If errmsg is non-NULL, it should point to a variable which will 1750 receive the error message, and no Python exception will be set. 1751 This is so that the function can be called from code not holding 1752 the GIL. 1753 1754 :: 1755 1756 npy_intp 1757 NpyIter_GetIterSize(NpyIter *iter) 1758 1759 Gets the number of elements being iterated 1760 1761 :: 1762 1763 void 1764 NpyIter_GetIterIndexRange(NpyIter *iter, npy_intp *istart, npy_intp 1765 *iend) 1766 1767 Gets the range of iteration indices being iterated 1768 1769 :: 1770 1771 npy_intp 1772 NpyIter_GetIterIndex(NpyIter *iter) 1773 1774 Gets the current iteration index 1775 1776 :: 1777 1778 int 1779 NpyIter_GotoIterIndex(NpyIter *iter, npy_intp iterindex) 1780 1781 Sets the iterator position to the specified iterindex, 1782 which matches the iteration order of the iterator. 1783 1784 Returns NPY_SUCCEED on success, NPY_FAIL on failure. 1785 1786 :: 1787 1788 npy_bool 1789 NpyIter_HasMultiIndex(NpyIter *iter) 1790 1791 Whether the iterator is tracking a multi-index 1792 1793 :: 1794 1795 int 1796 NpyIter_GetShape(NpyIter *iter, npy_intp *outshape) 1797 1798 Gets the broadcast shape if a multi-index is being tracked by the iterator, 1799 otherwise gets the shape of the iteration as Fortran-order 1800 (fastest-changing index first). 1801 1802 The reason Fortran-order is returned when a multi-index 1803 is not enabled is that this is providing a direct view into how 1804 the iterator traverses the n-dimensional space. The iterator organizes 1805 its memory from fastest index to slowest index, and when 1806 a multi-index is enabled, it uses a permutation to recover the original 1807 order. 1808 1809 Returns NPY_SUCCEED or NPY_FAIL. 1810 1811 :: 1812 1813 NpyIter_GetMultiIndexFunc * 1814 NpyIter_GetGetMultiIndex(NpyIter *iter, char **errmsg) 1815 1816 Compute a specialized get_multi_index function for the iterator 1817 1818 If errmsg is non-NULL, it should point to a variable which will 1819 receive the error message, and no Python exception will be set. 1820 This is so that the function can be called from code not holding 1821 the GIL. 1822 1823 :: 1824 1825 int 1826 NpyIter_GotoMultiIndex(NpyIter *iter, npy_intp const *multi_index) 1827 1828 Sets the iterator to the specified multi-index, which must have the 1829 correct number of entries for 'ndim'. It is only valid 1830 when NPY_ITER_MULTI_INDEX was passed to the constructor. This operation 1831 fails if the multi-index is out of bounds. 1832 1833 Returns NPY_SUCCEED on success, NPY_FAIL on failure. 1834 1835 :: 1836 1837 int 1838 NpyIter_RemoveMultiIndex(NpyIter *iter) 1839 1840 Removes multi-index support from an iterator. 1841 1842 Returns NPY_SUCCEED or NPY_FAIL. 1843 1844 :: 1845 1846 npy_bool 1847 NpyIter_HasIndex(NpyIter *iter) 1848 1849 Whether the iterator is tracking an index 1850 1851 :: 1852 1853 npy_bool 1854 NpyIter_IsBuffered(NpyIter *iter) 1855 1856 Whether the iterator is buffered 1857 1858 :: 1859 1860 npy_bool 1861 NpyIter_IsGrowInner(NpyIter *iter) 1862 1863 Whether the inner loop can grow if buffering is unneeded 1864 1865 :: 1866 1867 npy_intp 1868 NpyIter_GetBufferSize(NpyIter *iter) 1869 1870 Gets the size of the buffer, or 0 if buffering is not enabled 1871 1872 :: 1873 1874 npy_intp * 1875 NpyIter_GetIndexPtr(NpyIter *iter) 1876 1877 Get a pointer to the index, if it is being tracked 1878 1879 :: 1880 1881 int 1882 NpyIter_GotoIndex(NpyIter *iter, npy_intp flat_index) 1883 1884 If the iterator is tracking an index, sets the iterator 1885 to the specified index. 1886 1887 Returns NPY_SUCCEED on success, NPY_FAIL on failure. 1888 1889 :: 1890 1891 char ** 1892 NpyIter_GetDataPtrArray(NpyIter *iter) 1893 1894 Get the array of data pointers (1 per object being iterated) 1895 1896 This function may be safely called without holding the Python GIL. 1897 1898 :: 1899 1900 PyArray_Descr ** 1901 NpyIter_GetDescrArray(NpyIter *iter) 1902 1903 Get the array of data type pointers (1 per object being iterated) 1904 1905 :: 1906 1907 PyArrayObject ** 1908 NpyIter_GetOperandArray(NpyIter *iter) 1909 1910 Get the array of objects being iterated 1911 1912 :: 1913 1914 PyArrayObject * 1915 NpyIter_GetIterView(NpyIter *iter, npy_intp i) 1916 1917 Returns a view to the i-th object with the iterator's internal axes 1918 1919 :: 1920 1921 void 1922 NpyIter_GetReadFlags(NpyIter *iter, char *outreadflags) 1923 1924 Gets an array of read flags (1 per object being iterated) 1925 1926 :: 1927 1928 void 1929 NpyIter_GetWriteFlags(NpyIter *iter, char *outwriteflags) 1930 1931 Gets an array of write flags (1 per object being iterated) 1932 1933 :: 1934 1935 void 1936 NpyIter_DebugPrint(NpyIter *iter) 1937 1938 For debugging 1939 1940 :: 1941 1942 npy_bool 1943 NpyIter_IterationNeedsAPI(NpyIter *iter) 1944 1945 Whether the iteration loop, and in particular the iternext() 1946 function, needs API access. If this is true, the GIL must 1947 be retained while iterating. 1948 1949 NOTE: Internally (currently), `NpyIter_GetTransferFlags` will 1950 additionally provide information on whether floating point errors 1951 may be given during casts. The flags only require the API use 1952 necessary for buffering though. So an iterate which does not require 1953 buffering may indicate `NpyIter_IterationNeedsAPI`, but not include 1954 the flag in `NpyIter_GetTransferFlags`. 1955 1956 :: 1957 1958 void 1959 NpyIter_GetInnerFixedStrideArray(NpyIter *iter, npy_intp *out_strides) 1960 1961 Get an array of strides which are fixed. Any strides which may 1962 change during iteration receive the value NPY_MAX_INTP. Once 1963 the iterator is ready to iterate, call this to get the strides 1964 which will always be fixed in the inner loop, then choose optimized 1965 inner loop functions which take advantage of those fixed strides. 1966 1967 This function may be safely called without holding the Python GIL. 1968 1969 :: 1970 1971 int 1972 NpyIter_RemoveAxis(NpyIter *iter, int axis) 1973 1974 Removes an axis from iteration. This requires that NPY_ITER_MULTI_INDEX 1975 was set for iterator creation, and does not work if buffering is 1976 enabled. This function also resets the iterator to its initial state. 1977 1978 Returns NPY_SUCCEED or NPY_FAIL. 1979 1980 :: 1981 1982 npy_intp * 1983 NpyIter_GetAxisStrideArray(NpyIter *iter, int axis) 1984 1985 Gets the array of strides for the specified axis. 1986 If the iterator is tracking a multi-index, gets the strides 1987 for the axis specified, otherwise gets the strides for 1988 the iteration axis as Fortran order (fastest-changing axis first). 1989 1990 Returns NULL if an error occurs. 1991 1992 :: 1993 1994 npy_bool 1995 NpyIter_RequiresBuffering(NpyIter *iter) 1996 1997 Whether the iteration could be done with no buffering. 1998 1999 :: 2000 2001 char ** 2002 NpyIter_GetInitialDataPtrArray(NpyIter *iter) 2003 2004 Get the array of data pointers (1 per object being iterated), 2005 directly into the arrays (never pointing to a buffer), for starting 2006 unbuffered iteration. This always returns the addresses for the 2007 iterator position as reset to iterator index 0. 2008 2009 These pointers are different from the pointers accepted by 2010 NpyIter_ResetBasePointers, because the direction along some 2011 axes may have been reversed, requiring base offsets. 2012 2013 This function may be safely called without holding the Python GIL. 2014 2015 :: 2016 2017 int 2018 NpyIter_CreateCompatibleStrides(NpyIter *iter, npy_intp 2019 itemsize, npy_intp *outstrides) 2020 2021 Builds a set of strides which are the same as the strides of an 2022 output array created using the NPY_ITER_ALLOCATE flag, where NULL 2023 was passed for op_axes. This is for data packed contiguously, 2024 but not necessarily in C or Fortran order. This should be used 2025 together with NpyIter_GetShape and NpyIter_GetNDim. 2026 2027 A use case for this function is to match the shape and layout of 2028 the iterator and tack on one or more dimensions. For example, 2029 in order to generate a vector per input value for a numerical gradient, 2030 you pass in ndim*itemsize for itemsize, then add another dimension to 2031 the end with size ndim and stride itemsize. To do the Hessian matrix, 2032 you do the same thing but add two dimensions, or take advantage of 2033 the symmetry and pack it into 1 dimension with a particular encoding. 2034 2035 This function may only be called if the iterator is tracking a multi-index 2036 and if NPY_ITER_DONT_NEGATE_STRIDES was used to prevent an axis from 2037 being iterated in reverse order. 2038 2039 If an array is created with this method, simply adding 'itemsize' 2040 for each iteration will traverse the new array matching the 2041 iterator. 2042 2043 Returns NPY_SUCCEED or NPY_FAIL. 2044 2045 :: 2046 2047 int 2048 PyArray_CastingConverter(PyObject *obj, NPY_CASTING *casting) 2049 2050 Convert any Python object, *obj*, to an NPY_CASTING enum. 2051 2052 :: 2053 2054 npy_intp 2055 PyArray_CountNonzero(PyArrayObject *self) 2056 2057 Counts the number of non-zero elements in the array. 2058 2059 Returns -1 on error. 2060 2061 :: 2062 2063 PyArray_Descr * 2064 PyArray_PromoteTypes(PyArray_Descr *type1, PyArray_Descr *type2) 2065 2066 Produces the smallest size and lowest kind type to which both 2067 input types can be cast. 2068 2069 :: 2070 2071 PyArray_Descr * 2072 PyArray_MinScalarType(PyArrayObject *arr) 2073 2074 If arr is a scalar (has 0 dimensions) with a built-in number data type, 2075 finds the smallest type size/kind which can still represent its data. 2076 Otherwise, returns the array's data type. 2077 2078 2079 :: 2080 2081 PyArray_Descr * 2082 PyArray_ResultType(npy_intp narrs, PyArrayObject *arrs[] , npy_intp 2083 ndtypes, PyArray_Descr *descrs[] ) 2084 2085 2086 Produces the result type of a bunch of inputs, using the same rules 2087 as `np.result_type`. 2088 2089 NOTE: This function is expected to through a transitional period or 2090 change behaviour. DTypes should always be strictly enforced for 2091 0-D arrays, while "weak DTypes" will be used to represent Python 2092 integers, floats, and complex in all cases. 2093 (Within this function, these are currently flagged on the array 2094 object to work through `np.result_type`, this may change.) 2095 2096 Until a time where this transition is complete, we probably cannot 2097 add new "weak DTypes" or allow users to create their own. 2098 2099 :: 2100 2101 npy_bool 2102 PyArray_CanCastArrayTo(PyArrayObject *arr, PyArray_Descr 2103 *to, NPY_CASTING casting) 2104 2105 Returns 1 if the array object may be cast to the given data type using 2106 the casting rule, 0 otherwise. This differs from PyArray_CanCastTo in 2107 that it handles scalar arrays (0 dimensions) specially, by checking 2108 their value. 2109 2110 :: 2111 2112 npy_bool 2113 PyArray_CanCastTypeTo(PyArray_Descr *from, PyArray_Descr 2114 *to, NPY_CASTING casting) 2115 2116 Returns true if data of type 'from' may be cast to data of type 2117 'to' according to the rule 'casting'. 2118 2119 :: 2120 2121 PyArrayObject * 2122 PyArray_EinsteinSum(char *subscripts, npy_intp nop, PyArrayObject 2123 **op_in, PyArray_Descr *dtype, NPY_ORDER 2124 order, NPY_CASTING casting, PyArrayObject *out) 2125 2126 This function provides summation of array elements according to 2127 the Einstein summation convention. For example: 2128 - trace(a) -> einsum("ii", a) 2129 - transpose(a) -> einsum("ji", a) 2130 - multiply(a,b) -> einsum(",", a, b) 2131 - inner(a,b) -> einsum("i,i", a, b) 2132 - outer(a,b) -> einsum("i,j", a, b) 2133 - matvec(a,b) -> einsum("ij,j", a, b) 2134 - matmat(a,b) -> einsum("ij,jk", a, b) 2135 2136 subscripts: The string of subscripts for einstein summation. 2137 nop: The number of operands 2138 op_in: The array of operands 2139 dtype: Either NULL, or the data type to force the calculation as. 2140 order: The order for the calculation/the output axes. 2141 casting: What kind of casts should be permitted. 2142 out: Either NULL, or an array into which the output should be placed. 2143 2144 By default, the labels get placed in alphabetical order 2145 at the end of the output. So, if c = einsum("i,j", a, b) 2146 then c[i,j] == a[i]*b[j], but if c = einsum("j,i", a, b) 2147 then c[i,j] = a[j]*b[i]. 2148 2149 Alternatively, you can control the output order or prevent 2150 an axis from being summed/force an axis to be summed by providing 2151 indices for the output. This allows us to turn 'trace' into 2152 'diag', for example. 2153 - diag(a) -> einsum("ii->i", a) 2154 - sum(a, axis=0) -> einsum("i...->", a) 2155 2156 Subscripts at the beginning and end may be specified by 2157 putting an ellipsis "..." in the middle. For example, 2158 the function einsum("i...i", a) takes the diagonal of 2159 the first and last dimensions of the operand, and 2160 einsum("ij...,jk...->ik...") takes the matrix product using 2161 the first two indices of each operand instead of the last two. 2162 2163 When there is only one operand, no axes being summed, and 2164 no output parameter, this function returns a view 2165 into the operand instead of making a copy. 2166 2167 :: 2168 2169 PyObject * 2170 PyArray_NewLikeArray(PyArrayObject *prototype, NPY_ORDER 2171 order, PyArray_Descr *dtype, int subok) 2172 2173 Creates a new array with the same shape as the provided one, 2174 with possible memory layout order and data type changes. 2175 2176 prototype - The array the new one should be like. 2177 order - NPY_CORDER - C-contiguous result. 2178 NPY_FORTRANORDER - Fortran-contiguous result. 2179 NPY_ANYORDER - Fortran if prototype is Fortran, C otherwise. 2180 NPY_KEEPORDER - Keeps the axis ordering of prototype. 2181 dtype - If not NULL, overrides the data type of the result. 2182 subok - If 1, use the prototype's array subtype, otherwise 2183 always create a base-class array. 2184 2185 NOTE: If dtype is not NULL, steals the dtype reference. On failure or when 2186 dtype->subarray is true, dtype will be decrefed. 2187 2188 :: 2189 2190 int 2191 PyArray_GetArrayParamsFromObject(PyObject *NPY_UNUSED(op) 2192 , PyArray_Descr 2193 *NPY_UNUSED(requested_dtype) 2194 , npy_bool NPY_UNUSED(writeable) 2195 , PyArray_Descr 2196 **NPY_UNUSED(out_dtype) , int 2197 *NPY_UNUSED(out_ndim) , npy_intp 2198 *NPY_UNUSED(out_dims) , PyArrayObject 2199 **NPY_UNUSED(out_arr) , PyObject 2200 *NPY_UNUSED(context) ) 2201 2202 2203 :: 2204 2205 int 2206 PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE 2207 *modes, int n) 2208 2209 Convert an object to an array of n NPY_CLIPMODE values. 2210 This is intended to be used in functions where a different mode 2211 could be applied to each axis, like in ravel_multi_index. 2212 2213 :: 2214 2215 PyObject * 2216 PyArray_MatrixProduct2(PyObject *op1, PyObject 2217 *op2, PyArrayObject*out) 2218 2219 Numeric.matrixproduct2(a,v,out) 2220 just like inner product but does the swapaxes stuff on the fly 2221 2222 :: 2223 2224 npy_bool 2225 NpyIter_IsFirstVisit(NpyIter *iter, int iop) 2226 2227 Checks to see whether this is the first time the elements 2228 of the specified reduction operand which the iterator points at are 2229 being seen for the first time. The function returns 2230 a reasonable answer for reduction operands and when buffering is 2231 disabled. The answer may be incorrect for buffered non-reduction 2232 operands. 2233 2234 This function is intended to be used in EXTERNAL_LOOP mode only, 2235 and will produce some wrong answers when that mode is not enabled. 2236 2237 If this function returns true, the caller should also 2238 check the inner loop stride of the operand, because if 2239 that stride is 0, then only the first element of the innermost 2240 external loop is being visited for the first time. 2241 2242 WARNING: For performance reasons, 'iop' is not bounds-checked, 2243 it is not confirmed that 'iop' is actually a reduction 2244 operand, and it is not confirmed that EXTERNAL_LOOP 2245 mode is enabled. These checks are the responsibility of 2246 the caller, and should be done outside of any inner loops. 2247 2248 :: 2249 2250 int 2251 PyArray_SetBaseObject(PyArrayObject *arr, PyObject *obj) 2252 2253 Sets the 'base' attribute of the array. This steals a reference 2254 to 'obj'. 2255 2256 Returns 0 on success, -1 on failure. 2257 2258 :: 2259 2260 void 2261 PyArray_CreateSortedStridePerm(int ndim, npy_intp const 2262 *strides, npy_stride_sort_item 2263 *out_strideperm) 2264 2265 2266 This function populates the first ndim elements 2267 of strideperm with sorted descending by their absolute values. 2268 For example, the stride array (4, -2, 12) becomes 2269 [(2, 12), (0, 4), (1, -2)]. 2270 2271 :: 2272 2273 void 2274 PyArray_RemoveAxesInPlace(PyArrayObject *arr, const npy_bool *flags) 2275 2276 2277 Removes the axes flagged as True from the array, 2278 modifying it in place. If an axis flagged for removal 2279 has a shape entry bigger than one, this effectively selects 2280 index zero for that axis. 2281 2282 WARNING: If an axis flagged for removal has a shape equal to zero, 2283 the array will point to invalid memory. The caller must 2284 validate this! 2285 If an axis flagged for removal has a shape larger than one, 2286 the aligned flag (and in the future the contiguous flags), 2287 may need explicit update. 2288 2289 For example, this can be used to remove the reduction axes 2290 from a reduction result once its computation is complete. 2291 2292 :: 2293 2294 void 2295 PyArray_DebugPrint(PyArrayObject *obj) 2296 2297 Prints the raw data of the ndarray in a form useful for debugging 2298 low-level C issues. 2299 2300 :: 2301 2302 int 2303 PyArray_FailUnlessWriteable(PyArrayObject *obj, const char *name) 2304 2305 2306 This function does nothing and returns 0 if *obj* is writeable. 2307 It raises an exception and returns -1 if *obj* is not writeable. 2308 It may also do other house-keeping, such as issuing warnings on 2309 arrays which are transitioning to become views. Always call this 2310 function at some point before writing to an array. 2311 2312 name* is a name for the array, used to give better error messages. 2313 It can be something like "assignment destination", "output array", 2314 or even just "array". 2315 2316 :: 2317 2318 int 2319 PyArray_SetUpdateIfCopyBase(PyArrayObject *arr, PyArrayObject *base) 2320 2321 2322 :: 2323 2324 void * 2325 PyDataMem_NEW(size_t size) 2326 2327 Allocates memory for array data. 2328 2329 :: 2330 2331 void 2332 PyDataMem_FREE(void *ptr) 2333 2334 Free memory for array data. 2335 2336 :: 2337 2338 void * 2339 PyDataMem_RENEW(void *ptr, size_t size) 2340 2341 Reallocate/resize memory for array data. 2342 2343 :: 2344 2345 PyDataMem_EventHookFunc * 2346 PyDataMem_SetEventHook(PyDataMem_EventHookFunc *newhook, void 2347 *user_data, void **old_data) 2348 2349 Sets the allocation event hook for numpy array data. 2350 Takes a PyDataMem_EventHookFunc *, which has the signature: 2351 void hook(void *old, void *new, size_t size, void *user_data). 2352 Also takes a void *user_data, and void **old_data. 2353 2354 Returns a pointer to the previous hook or NULL. If old_data is 2355 non-NULL, the previous user_data pointer will be copied to it. 2356 2357 If not NULL, hook will be called at the end of each PyDataMem_NEW/FREE/RENEW: 2358 result = PyDataMem_NEW(size) -> (*hook)(NULL, result, size, user_data) 2359 PyDataMem_FREE(ptr) -> (*hook)(ptr, NULL, 0, user_data) 2360 result = PyDataMem_RENEW(ptr, size) -> (*hook)(ptr, result, size, user_data) 2361 2362 When the hook is called, the GIL will be held by the calling 2363 thread. The hook should be written to be reentrant, if it performs 2364 operations that might cause new allocation events (such as the 2365 creation/destruction numpy objects, or creating/destroying Python 2366 objects which might cause a gc) 2367 2368 Deprecated in 1.23 2369 2370 :: 2371 2372 void 2373 PyArray_MapIterSwapAxes(PyArrayMapIterObject *mit, PyArrayObject 2374 **ret, int getmap) 2375 2376 2377 Swap the axes to or from their inserted form. MapIter always puts the 2378 advanced (array) indices first in the iteration. But if they are 2379 consecutive, will insert/transpose them back before returning. 2380 This is stored as `mit->consec != 0` (the place where they are inserted) 2381 For assignments, the opposite happens: The values to be assigned are 2382 transposed (getmap=1 instead of getmap=0). `getmap=0` and `getmap=1` 2383 undo the other operation. 2384 2385 :: 2386 2387 PyObject * 2388 PyArray_MapIterArray(PyArrayObject *a, PyObject *index) 2389 2390 2391 Use advanced indexing to iterate an array. 2392 2393 :: 2394 2395 void 2396 PyArray_MapIterNext(PyArrayMapIterObject *mit) 2397 2398 This function needs to update the state of the map iterator 2399 and point mit->dataptr to the memory-location of the next object 2400 2401 Note that this function never handles an extra operand but provides 2402 compatibility for an old (exposed) API. 2403 2404 :: 2405 2406 int 2407 PyArray_Partition(PyArrayObject *op, PyArrayObject *ktharray, int 2408 axis, NPY_SELECTKIND which) 2409 2410 Partition an array in-place 2411 2412 :: 2413 2414 PyObject * 2415 PyArray_ArgPartition(PyArrayObject *op, PyArrayObject *ktharray, int 2416 axis, NPY_SELECTKIND which) 2417 2418 ArgPartition an array 2419 2420 :: 2421 2422 int 2423 PyArray_SelectkindConverter(PyObject *obj, NPY_SELECTKIND *selectkind) 2424 2425 Convert object to select kind 2426 2427 :: 2428 2429 void * 2430 PyDataMem_NEW_ZEROED(size_t nmemb, size_t size) 2431 2432 Allocates zeroed memory for array data. 2433 2434 :: 2435 2436 int 2437 PyArray_CheckAnyScalarExact(PyObject *obj) 2438 2439 return 1 if an object is exactly a numpy scalar 2440 2441 :: 2442 2443 PyObject * 2444 PyArray_MapIterArrayCopyIfOverlap(PyArrayObject *a, PyObject 2445 *index, int 2446 copy_if_overlap, PyArrayObject 2447 *extra_op) 2448 2449 2450 Same as PyArray_MapIterArray, but: 2451 2452 If copy_if_overlap != 0, check if `a` has memory overlap with any of the 2453 arrays in `index` and with `extra_op`. If yes, make copies as appropriate 2454 to avoid problems if `a` is modified during the iteration. 2455 `iter->array` may contain a copied array (WRITEBACKIFCOPY set). 2456 2457 :: 2458 2459 int 2460 PyArray_ResolveWritebackIfCopy(PyArrayObject *self) 2461 2462 2463 If WRITEBACKIFCOPY and self has data, reset the base WRITEABLE flag, 2464 copy the local data to base, release the local data, and set flags 2465 appropriately. Return 0 if not relevant, 1 if success, < 0 on failure 2466 2467 :: 2468 2469 int 2470 PyArray_SetWritebackIfCopyBase(PyArrayObject *arr, PyArrayObject 2471 *base) 2472 2473 2474 Precondition: 'arr' is a copy of 'base' (though possibly with different 2475 strides, ordering, etc.). This function sets the WRITEBACKIFCOPY flag and the 2476 ->base pointer on 'arr', call PyArray_ResolveWritebackIfCopy to copy any 2477 changes back to 'base' before deallocating the array. 2478 2479 Steals a reference to 'base'. 2480 2481 Returns 0 on success, -1 on failure. 2482 2483 :: 2484 2485 PyObject * 2486 PyDataMem_SetHandler(PyObject *handler) 2487 2488 Set a new allocation policy. If the input value is NULL, will reset 2489 the policy to the default. Return the previous policy, or 2490 return NULL if an error has occurred. We wrap the user-provided 2491 functions so they will still call the python and numpy 2492 memory management callback hooks. 2493 2494 :: 2495 2496 PyObject * 2497 PyDataMem_GetHandler() 2498 2499 Return the policy that will be used to allocate data 2500 for the next PyArrayObject. On failure, return NULL. 2501