From caf39d6b8c3fdb6241e16de77140cf0e2196c9ae Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Mon, 14 Jun 2021 22:47:52 -0500
Subject: [PATCH] Improve actx.compile docs
---
arraycontext/context.py | 20 +++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)
diff --git a/arraycontext/context.py b/arraycontext/context.py
index 80e32b8..de4aa69 100644
--- a/arraycontext/context.py
+++ b/arraycontext/context.py
@@ -354,13 +354,23 @@ class ArrayContext(ABC):
def compile(self, f: Callable[[Any], Any],
inputs_like: Tuple[Union[Number, np.ndarray], ...]) -> Callable[
..., Any]:
- """Compiles a function for use on this array context. Might perform some
- optimizations (such as kernel fusion) during compilation.
+ """Compiles *f* for repeated use on this array context. *f* is expected
+ to be a `pure function <https://en.wikipedia.org/wiki/Pure_function>`__
+ performing an array computation.
- :arg f: the function to compile.
- :arg inputs_like: the input arguments to the function.
+ Control flow statements (``if``, ``while``) that might take different
+ paths depending on the data lead to undefined behavior and are illegal.
+ Any data-dependent control flow must be expressed via array functions,
+ such as ``actx.np.where``.
+
+ *f* may be called on placeholder data, to obtain a representation
+ of the computation performed, or it may be called as part of the actual
+ computation, on actual data. If *f* is called on placeholder data,
+ it may be called only once (or a few times).
- :return: the compiled function.
+ :arg f: the function executing the computation.
+ :arg inputs_like: the input arguments to the function.
+ :return: a function with the same signature as *f*.
"""
return f
--
GitLab