Add Scope section

Author: rgommers

spec/_static/images/scope_of_array_API.png

@@ -3,13 +3,151 @@
 ## Introduction
 
 
+### This API standard
+
 
 ## History
 
 
 
 ## Scope (includes out-of-scope / non-goals)
 
+This section outlines what is in scope and out of scope for this API standard.
+
+### In scope
+
+The scope of the array API standard includes:
+
+- Functionality which needs to be included in an array library for it to adhere
+  to this standard.
+- Names of functions, methods, classes and other objects.
+- Function signatures, including type annotations.
+- Semantics of functions and methods. I.e. expected outputs including precision
+  for and dtypes of numerical results.
+- Semantics in the presence of `nan`'s, `inf`'s, empty arrays (i.e. arrays
+  including one or more dimensions of size `0`).
+- Casting rules, broadcasting, indexing
+- Data interchange. I.e. protocols to convert one type of array into another
+  type, potentially sharing memory.
+
+Furthermore, meta-topics included in this standard include:
+
+- Use cases for the API standard and assumptions made in it
+- API standard adoption
+- API standard versioning
+- Future API standard evolution
+- Array library and API standard versioning
+- Verification of API standard conformance
+
+The concrete set of functionality that is in scope for this version of the
+standard is shown in this diagram (_TODO: update after deciding on how optional
+extensions are dealt with_):
+
+![Scope of array API](_static/images/scope_of_array_API.png)
+
+
+**Goals** for the API standard include:
+
+- Make it possible for array-consuming libraries to start using multiple types
+  of arrays as inputs.
+- Enable more sharing and reuse of code built on top of the core functionality
+  in the API standard.
+- For authors of new array libraries, provide a concrete API that can be
+  adopted as is, rather than each author having to decide what to borrow from
+  where and where to deviate.
+- Make the learning curve for users less steep when they switch from one array
+  library to another one.
+
+
+### Out of scope
+
+1. Implementations of the standard are out of scope.
+
+   _Rationale: the standard will consist of a document and an accompanying test
+   suite with which the conformance of an implementation can be verified. Actual
+   implementations will live in array libraries; no reference implementation is
+   planned._
+
+2. Execution semantics are out of scope. This includes single-threaded vs.
+   parallel execution, task scheduling and synchronization, eager vs. delayed
+   evaluation, performance characteristics of a particular implementation of the
+   standard, and other such topics.
+
+   _Rationale: execution is the domain of implementations. Attempting to specify
+   execution behavior in a standard is likely to require much more fine-grained
+   coordination between developers of implementations, and hence is likely to
+   become an obstable to adoption._
+
+3. Non-Python API standardization (e.g., Cython or NumPy C APIs)
+
+   _Rationale: this is an important topic for some array-consuming libraries,
+   but there is no widely shared C/Cython API and hence it doesn't make sense at
+   this point in time to standardize anything. See
+   [the C API section](design_topics/C_API.md) for more details._
+
+4. Standardization of these dtypes is out of scope: bfloat16, complex, extended
+   precision floating point, datetime, string, object and void dtypes.
+
+   _Rationale: these dtypes aren't uniformly supported, and their inclusion at
+   this point in time could put a significant implementation burden on
+   libraries. It is expected that some of these dtypes - in particular
+   `bfloat16`, `complex64`, and `complex128` - will be included in a future
+   version of the standard._
+
+5. The following topics are out of scope: I/O, polynomials, error handling,
+   testing routines, building and packaging related functionality, methods of
+   binding compiled code (e.g., `cffi`, `ctypes`), subclassing of an array
+   class, masked arrays, and missing data.
+
+   _Rationale: these topics are not core functionality for an array library,
+   and/or are too tied to implementation details._
+
+6. NumPy (generalized) universal functions, i.e. ufuncs and gufuncs.
+
+   _Rationale: these are NumPy-specific concepts, and are mostly just a
+   particular way of building regular functions with a few extra
+   methods/properties._
+
+
+**Non-goals** for the API standard include:
+
+- Making array libraries identical so they can be merged.
+
+  _Each library will keep having its own particular strength, whether it's
+  offering functionality beyond what's in the standard, performance advantages
+  for a given use case, specific hardware or software environment support, or
+  more._
+
+- Implement a backend or runtime switching system to be able to switch from one
+  array library to another with a single setting or line of code.
+
+  _This may be feasible, however it's assumed that when an array-consuming
+  library switches from one array type to another, some testing and possibly
+  code adjustment for performance or other reasons may be needed._
+
+
+### TBD whether or not in scope, or for a later version
+
+- Device support (related to array creation on a specific device).
+
+  _This can be important, however there's no uniform syntax for it currently
+  and it may not make sense to add such syntax to libraries that only support a
+  single device type._
+
+- Random number generation, Fourier transforms, and miscellaneous functionality
+  like a padding function.
+
+  _This will be decided later, depending on whether "optional extensions" will
+  be added to the standard._
+
+
+### Implications of in/out of scope
+
+If something is out of scope and therefore will not be part of (the current
+version of) the API standard, that means that there are no guarantees that that
+functionality works the same way, or even exists at all, across the set of
+array libraries that conform to the standard. It does _not_ imply that this
+functionality is less important or should not be used.
 
 
 ## Stakeholders
@@ -104,9 +242,19 @@ For guidance on how to read and understand the type annotations included in this
 
 ## Conformance
 
-A conforming implementation of the array API standard must provide and support all the functions, arguments, data types, syntax, and semantics described in this specification.
+A conforming implementation of the array API standard must provide and support
+all the functions, arguments, data types, syntax, and semantics described in
+this specification.
+
+A conforming implementation of the array API standard may provide additional
+values, objects, properties, data types, and functions beyond those described
+in this specification.
+
+Libraries which aim to provide a conforming implementation but haven't yet
+completed such an implementation may, and are encouraged to, provide details on
+the level of (non-)conformance. For details on how to do this, see
+[Verification - measuring conformance](verification_test_suite.md).
 
-A conforming implementation of the array API standard may provide additional values, objects, properties, data types, and functions beyond those described in this specification.
 
 * * *
 

spec/purpose_and_scope.md

@@ -1,2 +1,8 @@
 # Verification - test suite
 
+
+
+## Measuring conformance
+
+TODO: explain how to use the test suite to measure and report on the level of
+(non-)conformance.