From 8b4e2f2c837437b31dd519808b937c1b8ff8735c Mon Sep 17 00:00:00 2001 From: Andreas Kloeckner <inform@tiker.net> Date: Sat, 1 Oct 2022 12:38:06 -0500 Subject: [PATCH] Add some design guidelines to docs --- doc/index.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/index.rst b/doc/index.rst index 1a8cf4d..48fd25b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,6 +15,39 @@ implementations for: :mod:`arraycontext` started life as an array abstraction for use with the :mod:`meshmode` unstrucuted discretization package. +Design Guidelines +----------------- + +Here are some of the guidelines we aim to follow in :mod:`arraycontext`. There +exist numerous other, related efforts, such as the `Python array API standard +<https://data-apis.org/array-api/latest/purpose_and_scope.html>`__. These +points may aid in clarifying and differentiating our objectives. + +- The array context is about exposing the common subset of operations + available in immutable and mutable arrays. As a result, the interface + does *not* seek to support interfaces that provide, enable, or are typically + used only with in-place mutation. + + For example: The equivalents of :func:`numpy.empty` were deprecated + and will eventually be removed. + +- Each array context offers a specific subset of of :mod:`numpy` under + :attr:`arraycontext.ArrayContext.np`. Functions under this namespace + must be unconditionally :mod:`numpy`-compatible, that is, they may not + offer an interface beyond what numpy offers. Functions that are + incompatible, for example by supporting tag metadata + (cf. :meth:`arraycontext.ArrayContext.einsum`) should live under the + :class:`~arraycontext.ArrayContext` directly. + +- Similarly, we strive to minimize redundancy between attributes of + :class:`~arraycontext.ArrayContext` and :attr:`arraycontext.ArrayContext.np`. + + For example: ``ArrayContext.empty_like`` was deprecated. + +- Array containers are data structures that may contain arrays. + See :mod:`arraycontext.container`. We strive to support these, where sensible, + in :class:`~arraycontext.ArrayContext` and :attr:`arraycontext.ArrayContext.np`. + Contents -------- -- GitLab