NumPy API surface : plan/prioritize the coverage

ev-br commented 1 year ago

EDIT: the relevant list for an MVP is https://github.com/Quansight-Labs/numpy_pytorch_interop/issues/87#issuecomment-1478036400. The rest is maybe-some-day-if-need-arises.

Splitting it off gh-86, here's the difference in API surfaces of NumPy and this wrapper. We can edit the order to reflect priorities:

>>> import numpy as np
>>> import torch_np as tnp
>>> npset = set(x for x in dir(np) if not x.startswith('_') and not inspect.ismodule(x) and not x[0].isupper())
>>> tnpset = set(dir(tnp))
>>> for name in sorted(npset - tnpset):
...        print("-[ ]", name)

EDIT: now lightly edited:

[x] append
[ ] apply_along_axis
[ ] apply_over_axes
[ ] argpartition
[ ] asanyarray
[ ] asarray_chkfinite
[x] ascontiguousarray
[ ] asfortranarray
[x] bartlett
[x] bitwise_not -- gh-88
[x] blackman
[ ] block
[ ] bmat
[ ] c_
[x] cfloat -- gh-88
[x] choose
[x] complex_ -- gh-88
[ ] compress
[x] convolve
[x] copyto
[x] correlate
[x] cross
[ ] delete
[ ] digitize
[x] e
[ ] ediff1d
[x] einsum
[ ] einsum_path
[ ] euler_gamma
[ ] extract
[ ] find_common_type
[x] fix -- gh-88
[ ] frexp
[x] from_dlpack
[x] gradient
[x] hamming
[x] hanning
[x] histogram
[x] histogram2d
[ ] histogram_bin_edges
[x] histogramdd
[ ] in1d
[ ] infty
[ ] insert
[ ] interp
[ ] isfortran
[ ] isin
[x] issubclass_
[ ] ix_
[x] kaiser
[ ] mgrid
[x] min_scalar_type
[x] mod -- gh-88
[x] nbytes
[ ] ogrid
[x] pad
[ ] partition
[ ] piecewise
[ ] place
[ ] promote_types
[x] put
[ ] putmask
[ ] r_
[x] resize
[ ] roots
[ ] select
[x] singlecomplex -- gh-88
[x] take
[x] tensordot
[x] true_divide -- gh-88
[ ] typename
[ ] unwrap

Lower prio:

memmap ndenumerate ndindex nditer nested_iters setxor1d setdiff1d vectorize trapz trim_zeros version sort_complex flatiter union1d unpackbits packbits

Low prio if at all:

array2string array_repr array_str busday_count busday_offset busdaycalendar bytebounds bytes cast ctypeslib deprecate deprecate_with_doc format_float_positional format_float_scientific format_parser get_array_wrap get_include get_printoptions getbufsize geterr geterrcall geterrobj obj2sctype poly poly1d polyadd polyder polydiv polyfit polyint polymul polynomial polysub polyval sctype2char sctypeDict seterr seterrcall seterrobj set_numeric_ops set_printoptions set_string_function setbufsize shares_memory source tracemalloc_domain (?) test testing use_hugepage who save savetxt savez savez_compressed show_config show_runtime frombuffer fromfile fromfunction fromiter frompyfunc fromregex fromstring genfromtxt base_repr binary_repr may_share_memory broadcast printoptions issctype issubsctype require lookfor load loadtxt mask_indices kernel_version lexsort little_endian maximum_sctype intersect1d

Definitely not (no pytorch equivalents):

add_docstring add_newdoc add_newdoc_ufunc asmatrix char character chararray clongdouble clongfloat complex256 compare_chararrays datetime64 datetime_as_string datetime_data flexible float128 isnat isbusday longcomplex longdouble longfloat matrix rec recarray recfromcsv recfromtxt record ushort uint uint16 uint32 uint64 uintc uintp ulonglong unicode void spacing str string timedelta64 safeeval numarray oldnumeric object fastCopyAndTranspose (deprecated in numpy) msort (deprecated in numpy) disp info iterable

ev-br commented 1 year ago

>>> for name in sorted(set(dir(np.ndarray)) - set(dir(tnp.ndarray))):
 ...     print("- [ ]", name)

[ ] __copy__
[ ] __deepcopy__
[ ] __delitem__
[x] __dlpack__
[x] __dlpack_device__
[x] __imatmul__
[x] __matmul__
[x] __rdivmod__
[x] __rmatmul__
[ ] __setstate__
[ ] argpartition
[x] choose
[ ] compress
[x] data
[ ] dump
[ ] dumps
[x] fill
[x] item
[x] nbytes
[ ] partition
[x] put
[x] resize
[x] take
[x] view

Later if at all:

[ ] __contains__
[ ] __iter__

base byteswap newbyteorder flat getfield setfield setflags itemset tostring [deprecated since numpy 1.19] tobytes tofile ctypes __array__ __array_finalize__ __array_function__ __array_interface__ __array_prepare__ __array_priority__ __array_struct__ __array_ufunc__ __array_wrap__ __class_getitem__

ev-br commented 1 year ago

For tnp.random:

>>> for name in sorted(dir(tnp.random)):
...     print("- [x]", name)

[x] ArrayLike
[x] NDArray
[x] Optional
[x] array_or_scalar
[x] choice
[x] normal
[x] normalizer
[x] rand
[x] randint
[x] randn
[x] random
[x] random_sample
[x] sample
[x] seed
[x] shuffle
[x] sqrt
[x] torch
[x] uniform

>>> for name in sorted(set(dir(np.random)) - set(dir(tnp.random))):
...     print(name)

BitGenerator Generator MT19937 PCG64 PCG64DXSM Philox RandomState SFC64 SeedSequence __RandomState_ctor __path__ _bounded_integers _common _generator _mt19937 _pcg64 _philox _pickle _sfc64 beta binomial bit_generator bytes chisquare default_rng dirichlet exponential f gamma geometric get_bit_generator get_state gumbel hypergeometric laplace logistic lognormal logseries mtrand multinomial multivariate_normal negative_binomial noncentral_chisquare noncentral_f pareto permutation poisson power random_integers ranf rayleigh set_bit_generator set_state standard_cauchy standard_exponential standard_gamma standard_normal standard_t test triangular vonmises wald weibull zipf

ev-br commented 1 year ago

And linalg:

>>> for name in [x for x in dir(np.linalg) if not x.startswith("_")]:
 ...     print("- [ ]", name)

[x] LinAlgError
[x] cholesky
[x] cond
[x] det
[x] eig
[x] eigh
[x] eigvals
[x] eigvalsh
[x] inv
[x] lstsq
[x] matrix_power
[x] matrix_rank
[x] multi_dot
[x] norm
[x] pinv
[x] qr
[x] slogdet
[x] solve
[x] svd
[x] tensorinv
[x] tensorsolve

rgommers commented 1 year ago

This looks quite good, thanks @ev-br. Here's where I would start:

All of linalg can be implemented I believe, except for test. That seems important, and hopefully relatively straightforward
From the main namespace I'd take the functions that are pretty heavily used and can be mapped to equivalent pytorch functionality: pad, take, convolve, einsum, gradient, cross, tensordot, histogram, `from_dlpack, ...

ev-br commented 1 year ago

For random, we can rather easily mock up RandomState and default_rng. Might make it easier for scikit-learn and others who frown on np.random.random usage.

lezcano commented 1 year ago

I agree with the list from Ralf. Here's a slightly more comprehensive list of things that either have PyTorch equivs or are close to trivial to implement.

These could go into a PR, as most of them should have a very simple implementation. After these, I think we can declare victory on the coverage end and we should spend some time finishing the refactorisation and doing general cleanups across the codebase (without spending too much time on this) and then move on to the testing part of the project, where we show that what we built, in fact, works.

[x] append (we don't have an equiv, but should be easy to implement via advance indexing)
[x] barlett
[x] blackman
[x] choose (didn't we have this one already?)
[x] copyto (funnily enough this is the function we want to use to implement the out kwarg)
[x] convolve
[x] cross
[x] e
[x] einsum
[x] fft
[x] from_dlpack
[x] gradient
[x] hamming
[x] histogram
[x] histogram2d (dispatch to histogram2d)
[x] histogramdd
[x] kaiser
[x] min_scalar_type (trivial to implement or just vendor)
[x] nbytes (this is a property of Tensor in PyTorch)
[x] pad
[x] put
[x] resize
[x] take
[x] tensordot
[x] np.linalg

rgommers commented 1 year ago

That list seems reasonable, minus infty - I'm going to deprecate that one in NumPy soon, so would prefer to leave it out here.

Quansight-Labs / numpy_pytorch_interop