From 4f0cbff0fec9833679a11443e8beddee600e1391 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 31 Aug 2020 11:49:48 -0700 Subject: [PATCH 1/6] Add accuracy doc --- spec/design_topics/accuracy.md | 56 ++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 spec/design_topics/accuracy.md diff --git a/spec/design_topics/accuracy.md b/spec/design_topics/accuracy.md new file mode 100644 index 000000000..ae31391fa --- /dev/null +++ b/spec/design_topics/accuracy.md @@ -0,0 +1,56 @@ +.. _accuracy: + +# Accuracy + +## Arithmetic Operations + +The results of element-wise arithmetic operations + +- `+` +- `-` +- `*` +- `/` +- `%` + +including the corresponding element-wise array APIs defined in this standard + +- add +- subtract +- multiply +- divide + +for floating-point operands must return the nearest representable value according to IEEE 754-2019 and a supported rounding mode. By default, the rounding mode should be `roundTiesToEven` (i.e., ties rounded toward the nearest value with an even least significant bit). + +## Mathematical Functions + +This specification does **not** precisely define the behavior of the following functions + +- acos +- acosh +- asin +- asinh +- atan +- atanh +- cos +- cosh +- exp +- log +- sin +- sinh +- sqrt +- tan +- tanh + +except to require specific results for certain argument values that represent boundary cases of interest. + +For other argument values, these functions should compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. + +Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in [fdlibm](http://www.netlib.org/fdlibm), the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. + +## Statistical Functions + +(TODO) + +## Linear Algebra + +(TODO) \ No newline at end of file From 8af77f5088af3cbe5604f4fc58a16053e123429d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 31 Aug 2020 11:50:16 -0700 Subject: [PATCH 2/6] Update index --- spec/design_topics/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/design_topics/index.rst b/spec/design_topics/index.rst index c481e0d9e..fdeb13eb5 100644 --- a/spec/design_topics/index.rst +++ b/spec/design_topics/index.rst @@ -12,5 +12,6 @@ Design topics & constraints array_ducktyping data_interchange missing_data + accuracy portability C_API From 3844139affc98065edb4c4a668b2d85aebaceef1 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 01:10:06 -0700 Subject: [PATCH 3/6] Fix capitalization --- spec/design_topics/accuracy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/design_topics/accuracy.md b/spec/design_topics/accuracy.md index ae31391fa..f50bfe7f1 100644 --- a/spec/design_topics/accuracy.md +++ b/spec/design_topics/accuracy.md @@ -45,7 +45,7 @@ except to require specific results for certain argument values that represent bo For other argument values, these functions should compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. -Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in [fdlibm](http://www.netlib.org/fdlibm), the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. +Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in [FDLIBM](http://www.netlib.org/fdlibm), the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. ## Statistical Functions From 6632f932ea1f03b0f71fd02fef307feb70cfa6e6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 23 Sep 2020 23:42:52 -0700 Subject: [PATCH 4/6] Update function list --- spec/design_topics/accuracy.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/spec/design_topics/accuracy.md b/spec/design_topics/accuracy.md index f50bfe7f1..f9a154fd1 100644 --- a/spec/design_topics/accuracy.md +++ b/spec/design_topics/accuracy.md @@ -30,14 +30,19 @@ This specification does **not** precisely define the behavior of the following f - asin - asinh - atan +- atan2 - atanh - cos - cosh - exp +- expm1 - log +- log1p +- log2 +- log10 +- pow - sin - sinh -- sqrt - tan - tanh From 6f2fc441597315d878edfc2da2fce76d58a5837c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 24 Sep 2020 00:40:03 -0700 Subject: [PATCH 5/6] Update copy --- spec/design_topics/accuracy.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/spec/design_topics/accuracy.md b/spec/design_topics/accuracy.md index f9a154fd1..7590cbc49 100644 --- a/spec/design_topics/accuracy.md +++ b/spec/design_topics/accuracy.md @@ -2,6 +2,8 @@ # Accuracy +> Array API specification for minimum accuracy requirements. + ## Arithmetic Operations The results of element-wise arithmetic operations @@ -48,14 +50,26 @@ This specification does **not** precisely define the behavior of the following f except to require specific results for certain argument values that represent boundary cases of interest. +.. note:: + + To help readers identify functions lacking precisely defined accuracy behavior, this specification uses the phrase "implementation-dependent approximation" in function descriptions. + For other argument values, these functions should compute approximations to the results of respective mathematical functions; however, this specification recognizes that array libraries may be constrained by underlying hardware and/or seek to optimize performance over absolute accuracy and, thus, allows some latitude in the choice of approximation algorithms. Although the specification leaves the choice of algorithms to the implementation, this specification recommends (but does not specify) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in [FDLIBM](http://www.netlib.org/fdlibm), the freely distributable mathematical library from Sun Microsystems, or some other comparable IEEE 754-2019 compliant mathematical library. +.. note:: + + With exception of a few mathematical functions, returning results which are indistinguishable from correctly rounded infinitely precise results is difficult, if not impossible, to achieve due to the algorithms involved, the limits of finite-precision, and error propagation. However, this specification recognizes that numerical accuracy alignment among array libraries is desirable in order to ensure portability and reproducibility. Accordingly, for each mathematical function, the specification test suite includes test values which span a function's domain and reports the average and maximum deviation from either a designated standard implementation (e.g., an arbitrary precision arithmetic implementation) or an average computed across a subset of known array library implementations. Such reporting aids users who need to know how accuracy varies among libraries and developers who need to check the validity of their implementations. + ## Statistical Functions -(TODO) +This specification does not specify accuracy requirements for statistical functions; however, this specification does expect that a conforming implementation of the array API standard will make a best-effort attempt to ensure that its implementations are theoretically sound and numerically robust. + +.. note:: + + In order for an array library to pass the specification test suite, an array library's statistical function implementations must satisfy certain bare-minimum accuracy requirements (e.g., accurate summation of a small set of positive integers). Unfortunately, imposing more rigorous accuracy requirements is not possible without severely curtailing possible implementation algorithms and unduly increasing implementation complexity. ## Linear Algebra -(TODO) \ No newline at end of file +This specification does not specify accuracy requirements for linear algebra functions; however, this specification does expect that a conforming implementation of the array API standard will make a best-effort attempt to ensure that its implementations are theoretically sound and numerically robust. \ No newline at end of file From 360a97840ad6393bb97d33ec8409f3b462c006d7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 24 Sep 2020 00:50:42 -0700 Subject: [PATCH 6/6] Add note regarding accuracy requirements --- spec/API_specification/elementwise_functions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index d9e1ff6e4..754449e05 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -10,6 +10,7 @@ A conforming implementation of the array API standard must provide and support t - Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. - Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. - Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019. +- Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`.