Skip to content

Commit 52d7e9e

Browse files
tomwhitetomwhite
authored
Improve documentation around Array API support (#477)
* Remove `roll` from list of missing functions since it was added in #115 * Add array API version to API status page
1 parent 02d33e9 commit 52d7e9e

File tree

5 files changed

+41
-21
lines changed

5 files changed

+41
-21
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Cubed is a distributed N-dimensional array library implemented in Python using b
66

77
- Implements the [Python Array API standard](https://data-apis.org/array-api/latest/) (see [coverage status](./api_status.md))
88
- Guaranteed maximum memory usage for standard array functions
9-
- Follows [Dask Array](https://docs.dask.org/en/stable/array.html)'s chunked array API (`map_blocks`, `rechunk`, `apply_gufunc`, etc)
9+
- Follows [Dask Array](https://docs.dask.org/en/stable/array.html)'s chunked array API (`map_blocks`, `map_overlap`, `rechunk`, `apply_gufunc`, etc)
1010
- [Zarr](https://zarr.readthedocs.io/en/stable/) for persistent and intermediate storage
1111
- Multiple serverless runtimes: Python (in-process), [Lithops](https://lithops-cloud.github.io/), [Modal](https://modal.com/), [Apache Beam](https://beam.apache.org/)
1212
- Integration with [Xarray](https://xarray.dev/) via [cubed-xarray](https://github.com/xarray-contrib/cubed-xarray)

‎api_status.md

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
## Array API Coverage Implementation Status
22

3-
This table shows which parts of the the [Array API](https://data-apis.org/array-api/latest/API_specification/index.html) have been implemented in Cubed. For those that have not been implemented a rough level of difficulty is indicated (1=easy, 3=hard).
3+
Cubed supports version [2022.12](https://data-apis.org/array-api/2022.12/index.html) of the Python array API standard, with a few exceptions noted below. The [linear algebra extensions](https://data-apis.org/array-api/2022.12/extensions/linear_algebra_functions.html) and [Fourier transform functions¶](https://data-apis.org/array-api/2022.12/extensions/fourier_transform_functions.html) are *not* supported.
44

5-
| Category | Object/Function | Implemented | Difficulty | Notes |
5+
Support for version [2023.12](https://data-apis.org/array-api/2023.12/index.html) is tracked in Cubed issue [#438](https://github.com/cubed-dev/cubed/issues/438).
6+
7+
This table shows which parts of the the [Array API](https://data-apis.org/array-api/latest/API_specification/index.html) have been implemented in Cubed, and which ones are missing. The version column shows the version when the feature was added to the standard, for version 2022.12 or later.
8+
9+
| Category | Object/Function | Implemented | Version | Notes |
610
| ------------------------ | ------------------- | ------------------ | ---------- | ---------------------------- |
711
| Array object | Arithmetic Ops | :white_check_mark: | | |
812
| | Array Ops | :white_check_mark: | | |
@@ -37,10 +41,16 @@ This table shows which parts of the the [Array API](https://data-apis.org/array-
3741
| Data Types | `bool`, `int8`, ... | :white_check_mark: | | |
3842
| Elementwise Functions | `add` | :white_check_mark: | | Example of a binary function |
3943
| | `negative` | :white_check_mark: | | Example of a unary function |
40-
| | _others_ | :white_check_mark: | | |
44+
| | _others_ | :white_check_mark: | | Except 2023.12 functions in [#438](https://github.com/cubed-dev/cubed/issues/438) |
4145
| Indexing | Single-axis | :white_check_mark: | | |
4246
| | Multi-axis | :white_check_mark: | | |
43-
| | Boolean array | :x: | 3 | Shape is data dependent, [#73](https://github.com/cubed-dev/cubed/issues/73) |
47+
| | Boolean array | :x: | | Shape is data dependent, [#73](https://github.com/cubed-dev/cubed/issues/73) |
48+
| Indexing Functions | `take` | :white_check_mark: | 2022.12 | |
49+
| Inspection | `capabilities` | :x: | 2023.12 | |
50+
| | `default_device` | :x: | 2023.12 | |
51+
| | `default_dtypes` | :x: | 2023.12 | |
52+
| | `devices` | :x: | 2023.12 | |
53+
| | `dtypes` | :x: | 2023.12 | |
4454
| Linear Algebra Functions | `matmul` | :white_check_mark: | | |
4555
| | `matrix_transpose` | :white_check_mark: | | |
4656
| | `tensordot` | :white_check_mark: | | |
@@ -49,28 +59,33 @@ This table shows which parts of the the [Array API](https://data-apis.org/array-
4959
| | `broadcast_to` | :white_check_mark: | | |
5060
| | `concat` | :white_check_mark: | | |
5161
| | `expand_dims` | :white_check_mark: | | |
52-
| | `flip` | :x: | 2 | Needs indexing with step=-1, [#114](https://github.com/cubed-dev/cubed/issues/114) |
62+
| | `flip` | :x: | | Needs indexing with step=-1, [#114](https://github.com/cubed-dev/cubed/issues/114) |
5363
| | `permute_dims` | :white_check_mark: | | |
64+
| | `repeat` | :x: | 2023.12 | |
5465
| | `reshape` | :white_check_mark: | | Partial implementation |
5566
| | `roll` | :white_check_mark: | | |
5667
| | `squeeze` | :white_check_mark: | | |
5768
| | `stack` | :white_check_mark: | | |
69+
| | `tile` | :x: | 2023.12 | |
70+
| | `unstack` | :x: | 2023.12 | |
5871
| Searching Functions | `argmax` | :white_check_mark: | | |
5972
| | `argmin` | :white_check_mark: | | |
60-
| | `nonzero` | :x: | 3 | Shape is data dependent |
73+
| | `nonzero` | :x: | | Shape is data dependent |
74+
| | `searchsorted` | :x: | 2023.12 | |
6175
| | `where` | :white_check_mark: | | |
62-
| Set Functions | `unique_all` | :x: | 3 | Shape is data dependent |
63-
| | `unique_counts` | :x: | 3 | Shape is data dependent |
64-
| | `unique_inverse` | :x: | 3 | Shape is data dependent |
65-
| | `unique_values` | :x: | 3 | Shape is data dependent |
66-
| Sorting Functions | `argsort` | :x: | 3 | Not in Dask |
67-
| | `sort` | :x: | 3 | Not in Dask |
68-
| Statistical Functions | `max` | :white_check_mark: | | |
76+
| Set Functions | `unique_all` | :x: | | Shape is data dependent |
77+
| | `unique_counts` | :x: | | Shape is data dependent |
78+
| | `unique_inverse` | :x: | | Shape is data dependent |
79+
| | `unique_values` | :x: | | Shape is data dependent |
80+
| Sorting Functions | `argsort` | :x: | | Not in Dask |
81+
| | `sort` | :x: | | Not in Dask |
82+
| Statistical Functions | `cumulative_sum` | :x: | 2023.12 | |
83+
| | `max` | :white_check_mark: | | |
6984
| | `mean` | :white_check_mark: | | |
7085
| | `min` | :white_check_mark: | | |
7186
| | `prod` | :white_check_mark: | | |
72-
| | `std` | :x: | 2 | Like `mean`, [#29](https://github.com/cubed-dev/cubed/issues/29) |
87+
| | `std` | :x: | | Like `mean`, [#29](https://github.com/cubed-dev/cubed/issues/29) |
7388
| | `sum` | :white_check_mark: | | |
74-
| | `var` | :x: | 2 | Like `mean`, [#29](https://github.com/cubed-dev/cubed/issues/29) |
89+
| | `var` | :x: | | Like `mean`, [#29](https://github.com/cubed-dev/cubed/issues/29) |
7590
| Utility Functions | `all` | :white_check_mark: | | |
7691
| | `any` | :white_check_mark: | | |

‎docs/api.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,8 @@ Chunk-specific functions
5050
Non-standardised functions
5151
==========================
5252

53+
These are functions that have not (yet) been included in the Python Array API Standard.
54+
5355
.. currentmodule:: cubed
5456
.. autosummary::
5557
:nosignatures:

‎docs/array-api.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
# Python Array API
22

3-
Cubed implements the [Python Array API standard](https://data-apis.org/array-api/latest/) in `cubed.array_api`. Refer
4-
to its [API specification](https://data-apis.org/array-api/latest/API_specification/index.html) for API documentation.
3+
Cubed implements version 2022.12 of the [Python Array API standard](https://data-apis.org/array-api/2022.12/index.html) in `cubed.array_api`, with a few exceptions noted below. Refer to its [API specification](https://data-apis.org/array-api/2022.12/API_specification/index.html) for API documentation.
4+
5+
The [linear algebra extensions](https://data-apis.org/array-api/2022.12/extensions/linear_algebra_functions.html) and [Fourier transform functions¶](https://data-apis.org/array-api/2022.12/extensions/fourier_transform_functions.html) are *not* supported.
6+
7+
Support for version [2023.12](https://data-apis.org/array-api/2023.12/index.html) is tracked in Cubed issue [#438](https://github.com/cubed-dev/cubed/issues/438).
58

69
## Missing from Cubed
710

@@ -13,7 +16,6 @@ The following parts of the standard are not implemented:
1316
| Creation Functions | `from_dlpack` |
1417
| Indexing | Boolean array |
1518
| Manipulation Functions | `flip` |
16-
| | `roll` |
1719
| Searching Functions | `nonzero` |
1820
| Set Functions | `unique_all` |
1921
| | `unique_counts` |
@@ -47,4 +49,5 @@ The following [Manipulation Functions](https://data-apis.org/array-api/latest/AP
4749

4850
```{eval-rst}
4951
.. autofunction:: cubed.array_api.broadcast_to
52+
.. autofunction:: cubed.array_api.concat
5053
```

‎docs/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Cubed is a distributed N-dimensional array library implemented in Python using b
66

77
- Implements the [Python Array API standard](https://data-apis.org/array-api/latest/)
88
- Guaranteed maximum memory usage for standard array functions
9-
- Follows [Dask Array](https://docs.dask.org/en/stable/array.html)'s chunked array API (`map_blocks`, `rechunk`, etc)
9+
- Follows [Dask Array](https://docs.dask.org/en/stable/array.html)'s chunked array API (`map_blocks`, `map_overlap`, `rechunk`, `apply_gufunc`, etc)
1010
- [Zarr](https://zarr.readthedocs.io/en/stable/) for storage
1111
- Multiple serverless runtimes: Python (in-process), [Lithops](https://lithops-cloud.github.io/), [Modal](https://modal.com/), [Apache Beam](https://beam.apache.org/)
1212
- Integration with [Xarray](https://xarray.dev/) via [cubed-xarray](https://github.com/xarray-contrib/cubed-xarray)
@@ -42,4 +42,4 @@ contributing
4242

4343
[Cubed: Bounded-memory serverless array processing in xarray](https://xarray.dev/blog/cubed-xarray)
4444

45-
[Optimizing Cubed](https://medium.com/pangeo/optimizing-cubed-7a0b8f65f5b7)
45+
[Optimizing Cubed](https://medium.com/pangeo/optimizing-cubed-7a0b8f65f5b7)

0 commit comments

Comments
 (0)