Decorator cengine renamed to jit and added to docs

Author: FrancescAlted

README_DEVELOPERS.md

@@ -46,12 +46,13 @@ If you want to run the network tests, you can use the following command:
 
 ## Documentation
 
-We are using Sphinx for documentation.  You can build the documentation by executing
+We are using Sphinx for documentation.  You can build the documentation by executing:
 
 ``` bash
   cd doc
   rm -rf html _build
   python -m sphinx . html
 ```
+[You may need to install the `pandoc` package first: https://pandoc.org/installing.html]
 
 You will find the documentation in the `html` directory.

bench/ndarray/cengine-expr.py renamed to bench/ndarray/jit-expr.py

@@ -1,3 +1,13 @@
+#######################################################################
+# Copyright (c) 2019-present, Blosc Development Team <[email protected]>
+# All rights reserved.
+#
+# This source code is licensed under a BSD-style license (found in the
+# LICENSE file in the root directory of this source tree)
+#######################################################################
+
+# Compute expressions for different array sizes, using the jit decorator.
+
 from time import time
 import blosc2
 import numpy as np
@@ -44,13 +54,13 @@ def compute_expression_numpy(a, b, c):
 print(f"Time to compute with NumExpr: {t1:.5f}")
 print(f"Speedup: {tref / t1:.2f}x")
 
-@blosc2.cengine
+@blosc2.jit
 def compute_expression_nocompr(a, b, c):
     return ((a ** 3 + np.sin(a * 2)) < c) & (b > 0)
 
 print("\nUsing NumPy operands...")
 
-@blosc2.cengine(cparams=cparams_out)
+@blosc2.jit(cparams=cparams_out)
 def compute_expression_compr(a, b, c):
     return ((a ** 3 + np.sin(a * 2)) < c) & (b > 0)
 
@@ -115,7 +125,7 @@ def compute_expression_compr(a, b, c):
 # c = blosc2.asarray(nc, cparams=cparams, chunks=chunks, blocks=blocks)
 print(f"{a.chunks=}, {a.blocks=}, {a.schunk.cratio=:.2f}x")
 
-@blosc2.cengine(cparams=cparams_out)
+@blosc2.jit(cparams=cparams_out)
 def compute_expression_compr(a, b, c):
     return ((a ** 3 + np.sin(a * 2)) < c) & (b > 0)
 

bench/ndarray/cengine-reduc.py renamed to bench/ndarray/jit-reduc.py

@@ -1,7 +1,16 @@
+#######################################################################
+# Copyright (c) 2019-present, Blosc Development Team <[email protected]>
+# All rights reserved.
+#
+# This source code is licensed under a BSD-style license (found in the
+# LICENSE file in the root directory of this source tree)
+#######################################################################
+
+# Compute expressions for different array sizes, using the jit decorator.
+
 from time import time
 import blosc2
 import numpy as np
-import numexpr as ne
 
 niter = 5
 # Create some data operands
@@ -36,13 +45,13 @@ def compute_expression_numpy(a, b, c):
 tref = time() - t0
 print(f"Time to compute with NumPy engine: {tref:.5f}")
 
-@blosc2.cengine
+@blosc2.jit
 def compute_expression_nocompr(a, b, c):
     return np.sum(((a ** 3 + np.sin(a * 2)) < c) & (b > 0), axis=1)
 
 print("\nUsing NumPy operands...")
 
-@blosc2.cengine
+@blosc2.jit
 def compute_expression_compr(a, b, c, out):
     return np.sum(((a ** 3 + np.sin(a * 2)) < c) & (b > 0), axis=1, out=out)
 

doc/reference/decorators.rst

@@ -0,0 +1,8 @@
+Decorators
+----------
+
+.. toctree::
+    :maxdepth: 2
+
+
+.. autofunction:: blosc2.jit

doc/reference/index.rst

@@ -8,4 +8,5 @@ API Reference
     save_load
     storage
     array_operations
+    decorators
     low_level

src/blosc2/__init__.py

@@ -248,7 +248,7 @@ class Tuner(Enum):
     get_expr_operands,
     validate_expr,
 )
-from .proxy import Proxy, ProxySource, ProxyNDSource, ProxyNDField, SimpleProxy, cengine
+from .proxy import Proxy, ProxySource, ProxyNDSource, ProxyNDField, SimpleProxy, jit
 
 from .schunk import SChunk, open
 

src/blosc2/proxy.py

@@ -8,6 +8,7 @@
 from abc import ABC, abstractmethod
 
 import numpy as np
+from traitlets import Callable
 
 import blosc2
 
@@ -580,20 +581,22 @@ def __getitem__(self, item: slice | list[slice]) -> np.ndarray:
         return self.src[item]
 
 
-def cengine(func=None, out=None, **kwargs):  # noqa: C901
+def jit(func : Callable, out=None, **kwargs):  # noqa: C901
     """
-    Wrap a function so that it can be used with the Blosc2 compute engine.
+    Prepare a function so that it can be used with the Blosc2 compute engine.
 
-    The inputs can be any combination of NumPy/NDArray arrays and scalars.
-    The function will be called with the NumPy arrays replaced by
+    The inputs of the function can be any combination of NumPy/NDArray arrays
+    and scalars.  The function will be called with the NumPy arrays replaced by
     :ref:`SimpleProxy` objects, whereas NDArray objects will be used as is.
 
     The returned value will be a NumPy array if all arguments are NumPy arrays
     or if not kwargs are provided. Else, the return value will be a NDArray
-    created using the provided kwargs (or the default ones).
+    created using the provided kwargs.
 
     Parameters
     ----------
+    func: callable
+        The function to be prepared for the Blosc2 compute engine.
     out: np.ndarray, NDArray, optional
         The output array where the result will be stored.
     **kwargs: dict, optional
@@ -607,24 +610,15 @@ def cengine(func=None, out=None, **kwargs):  # noqa: C901
     -----
     * Although many NumPy functions are supported, some may not be implemented yet.
       If you find a function that is not supported, please open an issue.
-    * Due to implementation, the `out` and `kwargs` parameters are not supported
-      for all expressions (e.g. when using a reduction as the last function).
-      In this case, you can still use the `out` parameter of the reduction function
-      for some custom control over the output.
-
-    Parameters
-    ----------
-    func
-
-    Returns
-    -------
-    wrapper
+    * `kwargs` parameters are not supported for all expressions (e.g. when using a
+      reduction as the last function).  In this case, you can still use the `out`
+      parameter of the reduction function for some custom control over the output.
 
     Examples
     --------
     >>> import numpy as np
     >>> import blosc2
-    >>> @blosc2.cengine
+    >>> @blosc2.jit
     >>> def compute_expression(a, b, c):
     >>>     return np.sum(((a ** 3 + np.sin(a * 2)) > 2 * c) & (b > 0), axis=1)
     >>> a = np.arange(20, dtype=np.float32).reshape(4, 5)