NumPy rank-typing tracker

numpy-rank-typing-tracker.md

Rank-typing coverage of the public NumPy API.

numpy

Function	Progress	Effort	Limit	Uses (x1000)
array	●			20,218
arange	●			10,060
zeros1	●			9,716
ones1	●			6,676
asarray	●			6,619
mean/nanmean	●			5,494
sum/nansum	●			4,684
concatenate/concat	●			4,557
linspace2	●			4,022
empty1	●			3,826
max/amax/nanmax	●			3,193
where3	◐	XL		3,047
all	●			2,626
dot	●			2,576
zeros_like	●			2,179
full1	●			2,097
min/amin/nanmin	●			2,024
unique	●			1,860
clip	●			1,843
eye	●			1,843
vstack	●			1,686
argmax/nanargmax	●			1,683
std/nanstd	●			1,521
load4	-			1,499
argsort	●			1,450
any	●			1,446
round/around	●			1,316
hstack	●			1,307
sort	●			1,276
stack	●			1,196
repeat	●			1,182
prod/nanprod	●			1,098
diff	●			1,071
tile	●			1,067
diag	●			991
reshape1	●			985
transpose/permute_dims	●			954
expand_dims	●			944
cumsum/nancumsum	●			932
ones_like	●			911
nonzero	●			850
meshgrid	●			831
percentile/nanpercentile5	○	L		797
median/nanmedian	◐	L		790
append	●			767
argmin/nanargmin	●			722
copy6	●			707
column_stack	●			646
empty_like	●			594
broadcast_to1	●			587
isclose	●			549
squeeze	○	M	value	529
atleast_1d	◐	M	var	520
shape	●			517
bincount	●			511
atleast_2d	◐	M	var	493
outer	●			492
loadtxt	○	M		488
var/nanvar	●			477
moveaxis	●			476
ascontiguousarray	◐	S		474
frombuffer	●			461
count_nonzero5	○	M		445
ndim	-			428
einsum7	○	XL	lit	425
asanyarray	◐	S		424
delete	●			421
ravel	●			417
average	◐	L		412
searchsorted	●			384
pad	◐	S		361
take	○	L		360
real8	◐	S		352
size	-			351
logspace2	●			347
interp	●			332
identity	●			323
flatnonzero	●			306
full_like	●			294
roll	●			283
corrcoef	●			278
split	●			278
unravel_index	○	M	var	272
convolve	●			266
isin	●			263
apply_along_axis	○	XL	var	263
cov	○	M		253
broadcast_arrays	○	M	var	248
polyfit	○	M		246
cross	○	M		244
argwhere	●			238
insert	●			237
trace	○	L		236
quantile/nanquantile5	○	L		225
histogram	●			214
nan_to_num	◐	S		212
swapaxes	◐	S		206
asfortranarray	◐	S		199
inner	●			194
flip	◐	S		191
cumprod/nancumprod	●			191
angle	●			190
tensordot	○	XL	var	189
imag8	◐	S		186
lexsort	○	M	var	185
indices	●			182
ptp	◐	L		179
triu	◐	S		179
resize1	●			178
flipud	◐	S		168
dstack	○	M		165
fromiter	●			164
ix_	●			163
fromfile	●			155
genfromtxt	○	M		154
kron	○	M		154
polyval	○	S		148
array_split	●			143
fliplr	◐	S		141
fromstring	●			139
tril	◐	S		136
diagonal	◐	M		135
ravel_multi_index	○	M		134
isposinf	○	S		127
setdiff1d	●			117
block	○	XL	var	116
take_along_axis	○	M		111
rollaxis	●			109
rot90	●			109
argpartition	●			109
geomspace2	●			108
correlate	●			106
gradient	●			104
compress	○	M		103
isneginf	○	S		100
digitize	●			100
choose	○	S		100
broadcast_shapes	○	M	var	96
intersect1d	●			94
histogram2d	●			91
fix	○	S		87
isreal	○	S		83
vdot	-			82
vander	●			80
require8	◐	S		80
partition	◐	S		79
polydiv	○	M		78
unpackbits	●			76
unwrap	●			76
ediff1d	●			74
diag_indices	●			73
packbits	●			73
triu_indices	●			71
tri	●			69
polymul	○	M		68
roots	○	M		66
hanning	●			65
astype	●			60
select	●			59
histogramdd	○	M	var	59
diag_indices_from	●			57
atleast_3d	◐	M	var	56
asarray_chkfinite	◐	S		56
histogram_bin_edges	●			56
poly	○	M		55
diagflat	●			54
datetime_as_string	○	S		53
polyder	○	M		53
extract	●			52
sinc	●			51
busday_offset	○	M		50
polyint	○	M		50
fromregex	●			49
put_along_axis	-			45
trim_zeros9	○	S		45
union1d	●			44
tril_indices	●			44
polyadd	○	M		43
hamming	●			43
polysub	○	M		42
fromfunction	○	XL	var	40
piecewise	●			40
blackman	●			39
busday_count	○	M		39
is_busday	○	M		39
kaiser	●			38
vsplit	●			36
sort_complex8	◐	S		36
triu_indices_from	●			36
bartlett	●			35
from_dlpack10	○	S		34
i0	●			34
iscomplex	○	S		33
hsplit	●			33
real_if_close8	◐	S		32
mask_indices	●			31
trapezoid11	○ !	M		31
tril_indices_from	●			26
setxor1d	●			25
dsplit	●			22
unique_values	●			21
unique_all	◐	M		21
unique_counts	◐	M		21
unique_inverse	◐	M		21
cumulative_prod	●			20
cumulative_sum	●			20
apply_over_axes	○	XL	var	18
unstack	○	M		18
matrix_transpose	●			12

numpy.ndarray

Checked on a 3-D array. .T, .mT, .real, .imag, .flat are ● and not listed. Uses is ".foo(" "import numpy" NOT "import pandas" NOT "import torch"¹².

Function	Progress	Effort	Limit	Uses (x1000)
ndarray.astype	●			6,815
ndarray.reshape1	●			6,381
ndarray.copy	●			5,914
ndarray.sum	●			5,513
ndarray.mean	●			5,054
ndarray.max	●			4,644
ndarray.all	●			3,444
ndarray.dot	●			2,891
ndarray.min	●			2,772
ndarray.any	●			2,330
ndarray.sort	-			2,056
ndarray.tolist13	●			2,039
ndarray.ravel	●			1,994
ndarray.argmax	●			1,896
ndarray.transpose	●			1,769
ndarray.flatten	●			1,576
ndarray.clip	●			1,511
ndarray.std	●			1,396
ndarray.argsort	●			1,331
ndarray.view14	●			1,314
ndarray.dumps	-			1,062
ndarray.resize	-			1,058
ndarray.prod	●			1,034
ndarray.squeeze	●		value	1,026
ndarray.repeat	●			1,024
ndarray.dump	-			1,009
ndarray.nonzero	●			970
ndarray.round	●			964
ndarray.cumsum	●			894
ndarray.item	-			864
ndarray.take15	◐	L		781
ndarray.argmin	●			753
ndarray.fill	-			728
ndarray.var	●			685
ndarray.conj	●			668
ndarray.tobytes	-			466
ndarray.searchsorted15	◐	M		411
ndarray.diagonal	●			398
ndarray.swapaxes	●			366
ndarray.conjugate	●			329
ndarray.trace	○	L		308
ndarray.put	-			295
ndarray.partition	-			280
ndarray.compress	●			241
ndarray.cumprod	●			222
ndarray.setflags	-			218
ndarray.byteswap	●			201
ndarray.choose	○	L		166
ndarray.tofile	-			157
ndarray.argpartition	●			148
ndarray.getfield	●			71
ndarray.setfield	-			66
ndarray.to_device	●			31

numpy.ndarray operators

A row marked &c. stands for a group of dunders — reflected forms are always included, and the footnote names the rest. Uses here is not comparable with the table above¹⁶; __matmul__ is the exception¹⁷. Treat the column as an order of magnitude.

Operator	Progress	Effort	Limit	Uses (x1000)
ndarray.__getitem__18	○	XL		50,000
ndarray.__add__ &c.19	◐	L		49,000
ndarray.__eq__ &c.20	○	L		33,000
ndarray.__setitem__	-			23,000
ndarray.__lt__ &c.21	●			8,300
ndarray.__iter__22	●			6,800
ndarray.__neg__ &c.23	●			5,200
ndarray.__iadd__ &c.24	●			2,600
ndarray.__matmul__ &c.17	●			1,650
ndarray.__and__ &c.25	●			1,600
ndarray.__divmod__ &c.	◐	L		180
ndarray.__array__ &c.26	-

numpy.linalg

Checked against both a 2-D and a stacked (n, m, m) input.

Function	Progress	Effort	Limit	Uses (x1000)
linalg.norm	●			1,909
linalg.inv	●			502
linalg.solve	○	M		257
linalg.svd	○	M		217
linalg.det	◐	M		213
linalg.lstsq	●			164
linalg.eigh	●			148
linalg.matrix_rank	●			135
linalg.pinv	●			131
linalg.cholesky	●			118
linalg.eig	●			106
linalg.qr	○	M		103
linalg.eigvalsh	●			89
linalg.slogdet	◐	M		77
linalg.eigvals	●			74
linalg.matrix_power	○	S		55
linalg.tensorsolve	○	M		53
linalg.cond	◐	M		46
linalg.multi_dot	○	L		43
linalg.tensorinv	●			40
linalg.matmul	○	L		25
linalg.cross	○	M		25
linalg.outer	●			25
linalg.vector_norm	●			16
linalg.matrix_norm	◐	M		16
linalg.trace	●			14
linalg.diagonal	●			13
linalg.tensordot	○	XL	var	9
linalg.svdvals	●			8
linalg.matrix_transpose	●			7
linalg.vecdot27	◐	M		5

numpy.fft

Function	Progress	Effort	Limit	Uses (x1000)
fft.fft	●			140
fft.rfft	●			108
fft.fftshift	●			93
fft.fftfreq	●			91
fft.fft2	●			77
fft.ifft	●			71
fft.ifft2	●			67
fft.irfft	●			63
fft.ifftshift	●			52
fft.rfftfreq	●			49
fft.fftn	●			40
fft.ifftn	●			40
fft.irfftn	●			37
fft.rfftn	●			37
fft.hfft	●			36
fft.ihfft	●			35
fft.rfft2	●			34
fft.irfft2	●			33

numpy.strings

Function	Progress	Effort	Limit	Uses (x1000)
strings.replace	○	L		36
strings.strip	○	L		34
strings.count	○	L		27
strings.endswith	○	L		27
strings.find	○	L		27
strings.rstrip	○	L		27
strings.index	○	L		27
strings.lstrip	○	L		27
strings.rindex	○	L		27
strings.rfind	○	L		27
strings.startswith	○	L		26
strings.partition	○	L		26
strings.rpartition	○	L		26
strings.center	○	L		25
strings.multiply	○	L		25
strings.decode	○	M		22
strings.encode	○	M		22
strings.rjust	○	L		21
strings.ljust	○	L		21
strings.expandtabs	○	L		19
strings.zfill	○	L		18
strings.capitalize	○	M		14
strings.swapcase	○	M		14
strings.title	○	M		14
strings.upper	○	M		14
strings.mod28	○	L		13
strings.lower	○	M		12
strings.slice	○	L		7
strings.translate	○	M		5

numpy.random

Generator methods; the legacy random.* functions and RandomState mirror these and are out of scope. size= can follow the zeros pattern.

Function	Progress	Effort	Limit	Uses (x1000)
Generator.random	●			1,463
Generator.choice	●			1,424
Generator.uniform	●			1,389
Generator.normal	●			1,367
Generator.shuffle	-			676
Generator.permutation	●			490
Generator.standard_normal	●			400
Generator.integers	●			313
Generator.multivariate_normal	●			133
Generator.binomial	●			106
Generator.exponential	●			97
Generator.beta	●			96
Generator.poisson	●			85
Generator.lognormal	●			76
Generator.dirichlet	●			57
Generator.multinomial	●			48
Generator.gamma	●			36
Generator.pareto	●			34
Generator.chisquare	●			31
Generator.negative_binomial	●			28
Generator.hypergeometric	●			25
Generator.logseries	●			24
Generator.laplace	●			24
Generator.zipf	●			20
Generator.geometric	●			20
Generator.rayleigh	●			18
Generator.triangular	●			17
Generator.standard_cauchy	●			17
Generator.weibull	●			17
Generator.standard_t	●			16
Generator.gumbel	●			16
Generator.logistic	●			15
Generator.vonmises	●			14
Generator.standard_gamma	●			14
Generator.noncentral_chisquare	●			13
Generator.power	●			13
Generator.wald	●			13
Generator.standard_exponential	●			13
Generator.f	●			13
Generator.noncentral_f	●			13
Generator.permuted	●			10
Generator.multivariate_hypergeometric	●

Legend

Progress: ● done · ◐ partial · ○ none (tuple[Any, ...]) · - n/a

! = the annotation is wrong, not just incomplete: it asserts a rank numpy does not produce. Only the checked call forms, so there may be more.

Effort: S passthrough or shape argument · M rank ladder · L rank ladder times an existing dtype matrix · XL new machinery

Limit, why ● is out of reach (blank = only overloads are needed):

Limit	Not expressible because
value	the output rank depends on runtime values
var	the output rank or arity depends on a variadic argument list
lit	it needs literal-string dependence

Method

Progress from reveal_type per row, via mypy and cross-checked with basedpyright. ! from comparing the runtime .ndim to the declared rank. Effort and Limit are hand-assigned. Uses is GitHub code search for "np.foo(", including archived and unstarred repos. Compiled by Claude Opus 5.

Notes

Footnotes

1. a tuple shape gives the rank; a list shape has no static length, so it cannot ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

2. array start/stop insert an axis at axis= ↩ ↩² ↩³

3. the 1-arg form is nonzero and has a known rank; the 3-arg form does not ↩

4. returns Any (.npy / .npz / pickle union) ↩

5. unlike the other reductions, keepdims=True is tuple[Any, ...] here too ↩ ↩² ↩³

6. subok defaults to False, so the passthrough overload is not reached ↩

7. needs literal-string subscript parsing ↩

8. a list argument gives tuple[Any, ...] ↩ ↩² ↩³ ↩⁴ ↩⁵

9. the passthrough only fires for list input; an ndarray gives Any ↩

10. stubbed inline in numpy/__init__.pyi ↩

11. typed as a scalar, but it reduces one axis, so the result has rank n-1 ↩

12. a ranking, not a measurement: the search cannot pin the receiver, so dict.copy() in a numpy file still counts ↩

13. returns nested lists whose depth is the rank ↩

14. the dtype form keeps the rank, the type[ndarray] form does not ↩

15. a scalar argument gives a scalar; an array argument gives tuple[Any, ...] ↩ ↩²

16. an AST count of operators with an array-valued operand across numpy, pandas and xarray, scaled to the method table by counting its rows the same way ↩

17. from a " @ " code search, not the AST count — the AST corpus does almost no linear algebra, so it undercounted @ by four orders of magnitude ↩ ↩²

18. the rank is type-determined, not value-determined — slices and ... preserve it, each integer index drops one, None adds one, a boolean mask always gives 1-d, and an integer-array index gives rank(idx) + rank(a) - 1; XL is the combinatorics, not a limit. a[:] and a[...] are the cheap sub-case ↩

19. stands for the 7 arithmetic dunders (+ - * / // % **) and their reflected forms; a scalar operand keeps the rank today only when it is an int ↩

20. __eq__ and __ne__, declared once on _ArrayOrScalarCommon returning Any — the dtype needs designing too, not just the rank ↩

21. __lt__, __le__, __gt__ and __ge__, 7 overloads each already returning NDArray[bool_], so only the rank is missing ↩

22. 1-d already yields the scalar type; only the >=2-d overload collapses to tuple[Any, ...] instead of rank-1 ↩

23. stands for __neg__, __pos__, __abs__ and __invert__ ↩

24. stands for the augmented-assignment dunders ↩

25. stands for &, |, ^, <<, >> and their reflected forms ↩

26. __array__, __array_ufunc__, __array_function__, __array_wrap__, __array_finalize__, __buffer__, __class_getitem__, __complex__, __contains__, __dlpack__, __dlpack_device__, __index__, __len__ and __new__ — no rank to express, or already ● ↩

27. linalg.vecdot re-exports the vecdot ufunc ↩

28. strings.mod is stubbed in _core/defchararray.pyi ↩