stdlib-js / stdlib-js/stdlib

RFC: strided array function interfaces

Offen
#364 27 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Feature Needs Discussion RFC
Vorherrschende Sprache
JavaScript
Sterne
6k
Forks
1.3k
Ø Merge
1 T. 3 Std.
Gemergte PRs (30 T.)
611

Beschreibung

I’ve got a proof-of-concept strided array interface supporting multiple dispatch (i.e., an interface which delegates to a type-aware implementation) for computing the absolute value, with N-API support. See https://github.com/stdlib-js/stdlib/tree/62cb2f0ea67ad09deb990d6e86e236785c848856/lib/node_modules/%40stdlib/strided/math/special/abs.

**What does this mean?** This is part of an effort to bring something comparable to NumPy’s ufuncs ("universal functions"; a.k.a., element-wise functions).

**What would this allow?** This would allow us to provided strided interfaces to all of our base mathematical functions (all `~160` of them) and any other applicable numerical API (including distributions). And would allow us to be another step closer to something resembling NumPy capabilities.

**What is needed?** Would be great to get initial design feedback from @Planeshifter and @rreusser (and anyone else for that matter) so we can figure out the best approach for ensuring that strided interfaces can be added to `stdlib` with as little work as possible and for ensuring that we can minimize the possibility of future refactoring. Once we begin rolling out strided array interfaces, it may become significantly harder to make changes due to the need to update many packages. So would be good to have confidence that we’ve nailed down the design now, rather having to do a large refactor later.

I am particularly interested in feedback on the JavaScript side of things: https://github.com/stdlib-js/stdlib/tree/62cb2f0ea67ad09deb990d6e86e236785c848856/lib/node_modules/%40stdlib/strided/math/special/abs/lib

…and on the C side of things: https://github.com/stdlib-js/stdlib/tree/62cb2f0ea67ad09deb990d6e86e236785c848856/lib/node_modules/%40stdlib/strided/math/special/abs/src/addon.cpp

On the C side of things, one thing I’d like to achieve is that a strided interface need only create the `StridedFunctionObject`. The add-on `namespace` could be hidden away in a macro/interface which an author would include at the very end, similar to how N-API works for performing module initialization.

> **Update**: I've implemented a macro which allows add-on authors to omit any N-API logic.

On the JavaScript side of things, I am not sure how we get around needing several files with source documentation. All the files are fairly short. The only "real" code is that which wraps the native add-on interfaces, which is necessary for calling into C when we’ve been provided generic arrays. Source code documentation is useful for JSDoc documentation. Having the interface types in `types.json` is convenient for dynamically generating tests and benchmarks (i.e., having the ability to require the `types.json` file and then dynamically creating arrays satisfying the type requirements).

We may want some way for a user to query what types are supported by a given strided API. What would this look like? In NumPy, you can do `np.sin.types` which returns a list of supported input types.

> **Update**: I've added support for querying strided array function meta data (e.g., `nargs`, `nin`, `nout`, and `types`), similar to NumPy's ufuncs.

One thing to note is that I’ve not included support for automatic casting and/or detection of overlapping buffers. My sense is that these behaviors, if desired, can be supported by wrapping these "lower-level" interfaces and performing the casting and/or copies there.

> **Update**: decided to punt these concerns to userland. A user can avoid overlapping buffer issues by manipulating the array strides (e.g., reversing them) depending on the direction of overlap.

Thoughts on all the above?

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.