NumExpr API

Core module

Numexpr is a fast numerical expression evaluator for NumPy. With it, expressions that operate on arrays (like “3*a+4*b”) are accelerated and use less memory than doing the same calculation in Python.

See:

https://github.com/pydata/numexpr

for more info about it.

numexpr3.evaluate(expr, name=None, lib=0, local_dict=None, global_dict=None, out=None, order='K', casting=0, optimization=0, library=0, checks=0, stackDepth=1)

Evaluate a mutliline expression element-wise, using the a NumPy.iter

expr is a string forming an expression, like

“c = 2*a + 3*b”

The values for “a” and “b” will by default be taken from the calling function’s frame (through use of sys._getframe()). Alternatively, they can be specifed using the ‘local_dict’ argument.

Multi-line statements, or semi-colon seperated statements, are supported.

Parameters:

name : DEPRECATED

use wisdom functions instead.

local_dict : dictionary, optional

A dictionary that replaces the local operands in current frame. This is generally required in Cython, as Cython does not populate the calling frame variables according to Python standards.

global_dict : DEPRECATED

A dictionary that replaces the global operands in current frame. Setting to {} can speed operations if you do not call globals. global_dict was deprecated as there is little reason for the user to maintain two dictionaries of arrays.

out : DEPRECATED

use assignment in expr (i.e. ‘out=a*b’) instead.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

Currently only ‘K’ is supported in NumExpr3.

Controls the iteration order for operands. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. For efficient computations, typically ‘K’eep order (the default) is desired.

casting : {CAST_SAFE, CAST_NO, CAST_EQUIV, CAST_SAME_KIND, CAST_UNSAFE},

optional (NumPy string repr also accepted)

Currently only ‘safe’ is supported in NumExpr3.

Controls what kind of data casting may occur when making a copy or buffering. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

• ‘no’ means the data types should not be cast at all.
• ‘equiv’ means only byte-order changes are allowed.
• ‘safe’ means only casts which can preserve values are allowed.
• ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
• ‘unsafe’ means any data conversions may be done.

optimization: {OPT_MODERATE}, optional

Controls what level of optimization the compiler will attempt to perform on the expression to speed its execution. This optimization is performed both by python.compile and numexpr3

• OPT_MODERATE performs simple optimizations, such as minimizing the number of temporary arrays

library: {LIB_STD}, optional

Indicates which library to use for calculations. The library must have been linked during the C-extension compilation, such that the associated operations are found in the opTable.

• LIB_STD is the standard C math.h / cmath.h library

Falls-back to LIB_STD if the other library is not available.

class numexpr3.NumExpr(expr, lib=0, casting=0, local_dict=None, stackDepth=1)

The self.program attribute is a bytes object and consists of operations followed by registers with the form,

opcode + return_reg + arg1_reg + arg2_reg + arg3_reg

Currently opcode is a uint16 and the register numbers are uint8. However, note that numpy.iter limits the maximum number of arguments to 32.

Register tuples have the format:

(regCode, object, dchar, KIND, name, <max_itemsize>)

where

regCode: a single byte indicating the register number object: the actual object reference, is None for temporaries. dchar: the object.dtype.char, or for temporaries the expected value KIND: indicates ndarray, scalar, temporary name: the original name of the array. It is not required for the

input arguments to run have the same names, just that they be in the same order and dtypes.

max_itemsize: the largest dtype used in temporary arrays, optional

Methods

assemble()

NumExpr.assemble() can be used in the context of having a pool of NumExpr objects; it is always called by __init__().

run(stackDepth=None, verify=False, **kwargs)

run() is called with keyword arguments as the order of args is based on the Abstract Syntax Tree parse and may be non-intuitive.

e.g. self.run( a=a1, b=b1, out=out_new )

where {a,b,out} were the original names in the expression. The disassemble() method can be used to see the original expression names.

Additional keyword arguments are:

stackDepth {None}: Tells the function how

many stacks up it was called from. Generally not altered unless one is using functional programming.

verify {False}: Resamples the calling frame to grab arrays.

There is some overhead associated with grabbing the frames so if inside a loop and using run on the same arrays repeatedly then operate without arguments.

numexpr3.__version__

The version of NumExpr.

numexpr3.ncores

The number of (virtual) cores detected.

Utility functions