stdlib-js / stdlib-js/stdlib

RFC: strided array function interfaces

オープン
#364 コメント 27 件 リアクション 0 件 担当者 0 名 GitHub で見る
Feature Needs Discussion RFC
主要言語
JavaScript
スター
6k
フォーク
1.3k
平均マージ
1日 3時間
マージ済み PR(30日)
611

説明

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?

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Start with the proof-of-concept at lib/node_modules/@stdlib/strided/math/special/abs, especially its JavaScript implementation and src/addon.cpp. Read the issue discussion and the linked revision to understand the proposed multiple-dispatch, metadata, and N-API interfaces. Done means reaching agreement on a stable design for adding strided interfaces, rather than implementing a narrowly defined change.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
cpp, javascript, nodejs
領域
api, backend-api-design, data
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
説明が足りない
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。