NumPy rank-typing tracker

numpy-rank-typing-tracker.md

Rank-typing coverage of the public NumPy API.

numpy

Two things that cut across many rows. The nan* functions are stub aliases of their non-nan counterparts and are fixed together. For the reductions, axis=None and keepdims=True already give a known rank and axis=int is the gap, except where marked otherwise.

Function	Progress	Effort	Limit	Uses (x1000)
np.array1	◐	M		20,218
np.arange	●			10,060
np.zeros2	●			9,716
np.ones2	●			6,676
np.asarray1	◐	M		6,619
np.mean	◐	L		5,243
np.sum	◐	L		4,571
np.concatenate	●			4,547
np.linspace3	●			4,022
np.empty2	●			3,826
np.where4	◐	L		3,047
np.max5	◐	L		2,662
np.all	◐	L		2,626
np.dot	●			2,576
np.zeros_like	●			2,179
np.full2	●			2,097
np.unique	●			1,860
np.clip	●			1,843
np.eye	●			1,843
np.vstack	○	M		1,686
np.argmax	◐	L		1,642
np.min5	◐	L		1,610
np.load6	-			1,499
np.argsort7	◐	S		1,450
np.any	◐	L		1,446
np.std	◐	L		1,430
np.hstack	○	M		1,307
np.sort	◐	S		1,276
np.stack	○	M		1,196
np.repeat	●			1,182
np.prod	◐	L		1,079
np.round5	◐	S		1,075
np.diff	●			1,071
np.tile	○	M		1,067
np.diag	●			991
np.reshape2	●			985
np.transpose	◐	S		954
np.expand_dims	◐	M		944
np.ones_like	●			911
np.cumsum	●			899
np.nonzero	●			850
np.meshgrid	●			831
np.append	●			767
np.percentile8	○	L		729
np.copy9	●			707
np.median	◐	L		702
np.argmin	◐	L		692
np.column_stack	○	M		646
np.empty_like	●			594
np.broadcast_to2	○	S		587
np.isclose	●			549
np.squeeze	○	M	value	529
np.atleast_1d	◐	M	var	520
np.shape	●			517
np.bincount	●			511
np.atleast_2d	◐	M	var	493
np.outer	●			492
np.loadtxt	○	M		488
np.moveaxis	●			476
np.ascontiguousarray	◐	S		474
np.frombuffer	●			461
np.count_nonzero8	○	M		445
np.var	◐	L		442
np.ndim	-			428
np.einsum10	○	XL	lit	425
np.asanyarray	◐	S		424
np.delete	●			421
np.ravel	●			417
np.average	◐	L		412
np.searchsorted	○	S		384
np.pad	◐	S		361
np.take	○	L		360
np.real7	◐	S		352
np.size	-			351
np.logspace3	●			347
np.interp	●			332
np.identity	●			323
np.amax	◐	L		306
np.flatnonzero	●			306
np.full_like	●			294
np.roll	●			283
np.corrcoef	●			278
np.split	●			278
np.unravel_index	○	M	var	272
np.convolve	●			266
np.isin	○	S		263
np.apply_along_axis	○	XL	var	263
np.cov	○	M		253
np.nanmean	◐	L		251
np.broadcast_arrays	○	M	var	248
np.polyfit	○	M		246
np.cross	○	M		244
np.around	◐	S		241
np.argwhere	●			238
np.insert	●			237
np.trace	○	L		236
np.nanmax	◐	L		225
np.nanmin	◐	L		216
np.histogram	●			214
np.nan_to_num	◐	S		212
np.swapaxes	◐	S		206
np.asfortranarray	◐	S		199
np.amin	◐	L		198
np.inner	●			194
np.flip	◐	S		191
np.angle	●			190
np.tensordot	○	XL	var	189
np.quantile8	○	L		188
np.imag7	◐	S		186
np.lexsort	○	M	var	185
np.indices	●			182
np.ptp	◐	L		179
np.triu	◐	S		179
np.resize2	●			178
np.flipud	◐	S		168
np.dstack	○	M		165
np.fromiter	●			164
np.ix_	●			163
np.cumprod	●			160
np.fromfile	●			155
np.genfromtxt	○	M		154
np.kron	○	M		154
np.polyval	○	S		148
np.array_split	●			143
np.fliplr	◐	S		141
np.fromstring	●			139
np.tril	◐	S		136
np.diagonal	◐	M		135
np.ravel_multi_index	○	M		134
np.isposinf	○	S		127
np.setdiff1d	●			117
np.block	○	XL	var	116
np.nansum	◐	L		113
np.take_along_axis	○	M		111
np.rollaxis	●			109
np.rot90	●			109
np.argpartition	●			109
np.geomspace3	●			108
np.correlate	●			106
np.gradient	●			104
np.compress	○	M		103
np.isneginf	○	S		100
np.digitize	●			100
np.choose	○	S		100
np.broadcast_shapes	○	M	var	96
np.intersect1d	●			94
np.nanstd	◐	L		91
np.histogram2d	●			91
np.nanmedian	◐	L		88
np.fix	○	S		87
np.isreal	○	S		83
np.vdot	-			82
np.vander	●			80
np.require7	◐	S		80
np.partition	◐	S		79
np.polydiv	○	M		78
np.unpackbits	●			76
np.unwrap	●			76
np.ediff1d	●			74
np.diag_indices	●			73
np.packbits	●			73
np.triu_indices	●			71
np.tri	●			69
np.polymul5	○	M		68
np.nanpercentile8	○	L		68
np.roots	○	M		66
np.hanning	●			65
np.astype	●			60
np.select	●			59
np.histogramdd	○	M	var	59
np.diag_indices_from	●			57
np.atleast_3d	◐	M	var	56
np.asarray_chkfinite	◐	S		56
np.histogram_bin_edges	●			56
np.poly	○	M		55
np.diagflat	●			54
np.datetime_as_string	○	S		53
np.polyder	○	M		53
np.extract	●			52
np.sinc	●			51
np.busday_offset	○	M		50
np.polyint	○	M		50
np.fromregex	●			49
np.put_along_axis	-			45
np.trim_zeros11	○	S		45
np.union1d	●			44
np.tril_indices	●			44
np.polyadd	○	M		43
np.hamming	●			43
np.polysub	○	M		42
np.nanargmax	◐	L		41
np.fromfunction	○	XL	var	40
np.piecewise	●			40
np.blackman	●			39
np.busday_count	○	M		39
np.is_busday	○	M		39
np.kaiser	●			38
np.nanquantile8	○	L		37
np.vsplit	●			36
np.sort_complex7	◐	S		36
np.triu_indices_from	●			36
np.bartlett	●			35
np.nanvar	◐	L		35
np.from_dlpack12	○	S		34
np.i0	●			34
np.iscomplex	○	S		33
np.nancumsum	●			33
np.hsplit	●			33
np.real_if_close7	◐	S		32
np.nancumprod	●			31
np.mask_indices	●			31
np.trapezoid13	○ !	M		31
np.nanargmin	◐	L		30
np.tril_indices_from	●			26
np.setxor1d	●			25
np.dsplit	●			22
np.unique_values	●			21
np.unique_all	◐	M		21
np.unique_counts	◐	M		21
np.unique_inverse	◐	M		21
np.cumulative_prod	●			20
np.cumulative_sum	●			20
np.nanprod	◐	L		19
np.apply_over_axes	○	XL	var	18
np.unstack	○	M		18
np.matrix_transpose	●			12
np.concat5	○	M		10
np.permute_dims5	●			0

numpy.linalg

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

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

numpy.fft

n= / s= never change the rank, so these are pure passthrough.

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

numpy.strings

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

numpy.random

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

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

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 · 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. nesting is resolved only 2 deep, so a list[list[list[float]]] loses the rank ↩ ↩²

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

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

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

5. stub alias, shares overloads with the base function ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

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

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

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

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

10. needs literal-string subscript parsing ↩

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

12. stubbed inline in numpy/__init__.pyi ↩

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

14. np.linalg.vecdot re-exports the np.vecdot ufunc ↩

15. np.strings.mod is stubbed in _core/defchararray.pyi ↩