Skip to content

Commit 28b1964

Browse files
committed
Add Assumptions section
Includes: - hardware and software environments - dependencies (including abstract dependency diagram) - backwards compatibility - production code & interactive use
1 parent c9d2908 commit 28b1964

File tree

2 files changed

+63
-4
lines changed

2 files changed

+63
-4
lines changed
Loading

spec/assumptions.md

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,74 @@
11
# Assumptions
22

3-
## Hardware environments
3+
## Hardware and software environments
44

5+
No assumptions on a specific hardware environment are made. It must be possible
6+
to create an array library adhering to this standard that runs (efficiently) on
7+
a variety of different hardware: CPUs with different architectures, GPUs,
8+
distributed systems and TPUs and other emerging accelerators.
59

10+
The same applies to software environments: it must be possible to create an
11+
array library adhering to this standard that runs efficiently independent of
12+
what compilers, build-time or run-time execution environment, or distribution
13+
and install method is employed. Parallel execution, JIT compilation, and
14+
delayed (lazy) evaluation must all be possible.
615

7-
## Software environments
8-
16+
The variety of hardware and software environments puts _constraints_ on choices
17+
made in the API standard. For example, JIT compilers may require output dtypes
18+
of functions to be predictable from input dtypes only rather than input values.
919

1020

1121
## Dependencies
1222

23+
The only dependency that's assumed in this standard is that on Python itself.
24+
Python >= 3.8 is assumed, motivated by the use of positional-only parameters
25+
(see [function and method signatures](API_specification/function_and_method_signatures.md)).
26+
27+
Importantly, array libraries are not assumed to be aware of each other, or of
28+
a common array-specific layer. The [use cases](use_cases.md) do not require
29+
such a dependency, and building and evolving an array library is easier without
30+
such a coupling. Facilitation support of multiple array types in downstream
31+
libraries is an important use case however, the assumed dependency structure
32+
for that is:
33+
34+
![dependency assumptions diagram](_static/images/dependency_assumption_diagram.png)
35+
36+
Array libraries may know how to interoperate with each other, for example by
37+
constructing their own array type from that of another library or by shared
38+
memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)).
39+
This can be done without a dependency though - only adherence to a protocol is
40+
enough.
41+
42+
Array-consuming libraries will have to depend on one or more array libraries.
43+
That could be a "soft dependency" though, meaning retrieving an array library
44+
namespace from array instances that are passed in, but not explicitly doing
45+
`import arraylib_name`.
46+
47+
48+
## Backwards compatibility
49+
50+
The assumption made during creation of this standard is that libraries are
51+
constrained by backwards compatibility guarantees to their users, and are
52+
likely unwilling to make significant backwards-incompatible changes for the
53+
purpose of conforming to this standard. Therefore it is assumed that the
54+
standard will be made available in a new namespace within each library, or the
55+
library will provide a way to retrieve a module or module-like object that
56+
adheres to this standard. See [How to adopt this API](purpose_and_scope.html#how-to-adopt-this-api)
57+
for more details.
58+
59+
60+
## Production code & interactive use
1361

62+
It is assumed that the primary use case is writing production code, for example
63+
in array-consuming libraries. As a consequence, making it easy to ensure that
64+
code is written as intended and has unambiguous semantics is preferred - and
65+
clear exceptions must be raised otherwise.
1466

15-
## Interactive use & production code
67+
It is also assumed that this does not significantly detract from the
68+
interactive user experience. However, in case existing libraries differ in
69+
behavior, the more strict version of that behavior is typically preferred. A
70+
good example is array inputs to functions - while NumPy accepts lists, tuples,
71+
generators, and anything else that could be turned into an array, most other
72+
libraries only accept their own array types. This standard follows the latter choice.
73+
It is likely always possible to put a thin "interactive use convenience layer"
74+
on top of a more strict behavior.

0 commit comments

Comments
 (0)