Expression Utilities¶
A series of utilities are provided to work with expressions in a more convenient way.
Functions¶
- blosc2.evaluate(ex: str, local_dict: dict | None = None, global_dict: dict | None = None, out: ndarray | NDArray = None, **kwargs: Any) ndarray | NDArray[source]¶
Evaluate a string expression using the Blosc2 compute engine.
This is a drop-in replacement for numexpr.evaluate(), but using the Blosc2 compute engine. This allows for:
Use more functionality (e.g. reductions) than numexpr.
Follow casting rules of NumPy more closely.
Use both NumPy arrays and Blosc2 NDArrays in the same expression.
As NDArrays can be on-disk, the expression can be evaluated without loading the whole array into memory (i.e. using an out-of-core approach).
- Parameters:
ex¶ (str) – The expression to evaluate.
local_dict¶ (dict, optional) – The local dictionary to use when looking for operands in the expression. If not provided, the local dictionary of the caller will be used.
global_dict¶ (dict, optional) – The global dictionary to use when looking for operands in the expression. If not provided, the global dictionary of the caller will be used.
out¶ (NDArray or np.ndarray, optional) – The output array where the result will be stored. If not provided, a new NumPy array will be created and returned.
kwargs¶ (Any, optional) – Additional arguments to be passed to numexpr.evaluate() function.
- Returns:
out – The result of the expression evaluation. If out is provided, the result will be stored in out and returned at the same time.
- Return type:
NumPy or NDArray
Examples
>>> import blosc2 >>> import numpy as np >>> dtype = np.float64 >>> shape = [3, 3] >>> size = shape[0] * shape[1] >>> a = np.linspace(0, 5, num=size, dtype=dtype).reshape(shape) >>> b = blosc2.linspace(0, 5, num=size, dtype=dtype, shape=shape) >>> expr = 'a * b + 2' >>> out = blosc2.evaluate(expr) >>> out [[ 2. 2.390625 3.5625 ] [ 5.515625 8.25 11.765625] [16.0625 21.140625 27. ]]
Decorators¶
- blosc2.jit(func=None, *, out=None, disable=False, **kwargs)[source]¶
Prepare a function so that it can be used with the Blosc2 compute engine.
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 SimpleProxy objects, whereas NDArray objects will be used as is.
The returned value will be a NDArray if appropriate kwargs are provided (e.g. cparams=). Else, the return value will be a NumPy array (if the function returns a NumPy array). If out is provided, the result will be computed and stored in the out array
- 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.
disable¶ (bool, optional) – If True, the decorator is disabled and the original function is returned unchanged. Default is False.
**kwargs¶ (dict, optional) – Additional keyword arguments supported by the
empty()constructor.
- Return type:
wrapper
Notes
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.
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.
Examples
>>> import numpy as np >>> import blosc2 >>> @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) >>> b = np.arange(20).reshape(4, 5) >>> c = np.arange(5) >>> compute_expression(a, b, c) [5 5 5 5]