NumExpr API

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.

numexpr.evaluate(ex, local_dict=None, global_dict=None, out=None, order='K', casting='safe', **kwargs)[source]

Evaluate a simple array expression element-wise, using the new iterator.

ex is a string forming an expression, like “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’ or ‘global_dict’ arguments.

Parameters:
local_dict : dictionary, optional

A dictionary that replaces the local operands in current frame.

global_dict : dictionary, optional

A dictionary that replaces the global operands in current frame.

out : NumPy array, optional

An existing array where the outcome is going to be stored. Care is required so that this array has the same shape and type than the actual outcome of the computation. Useful for avoiding unnecessary new array allocations.

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

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 : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

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.
numexpr.re_evaluate(local_dict=None)[source]

Re-evaluate the previous executed array expression without any check.

This is meant for accelerating loops that are re-evaluating the same expression repeatedly without changing anything else than the operands. If unsure, use evaluate() which is safer.

Parameters:
local_dict : dictionary, optional

A dictionary that replaces the local operands in current frame.

numexpr.disassemble(nex)[source]

Given a NumExpr object, return a list which is the program disassembled.

numexpr.NumExpr(ex, signature=(), **kwargs)[source]

Compile an expression built using E.<variable> variables to a function.

ex can also be specified as a string “2*a+3*b”.

The order of the input variables and their types can be specified using the signature parameter, which is a list of (name, type) pairs.

Returns a NumExpr object containing the compiled function.

numexpr.get_vml_version()[source]

Get the VML/MKL library version.

numexpr.set_vml_accuracy_mode(mode)[source]

Set the accuracy mode for VML operations.

The mode parameter can take the values: - ‘high’: high accuracy mode (HA), <1 least significant bit - ‘low’: low accuracy mode (LA), typically 1-2 least significant bits - ‘fast’: enhanced performance mode (EP) - None: mode settings are ignored

This call is equivalent to the vmlSetMode() in the VML library. See:

http://www.intel.com/software/products/mkl/docs/webhelp/vml/vml_DataTypesAccuracyModes.html

for more info on the accuracy modes.

Returns old accuracy settings.

numexpr.set_vml_num_threads(nthreads)[source]

Suggests a maximum number of threads to be used in VML operations.

This function is equivalent to the call mkl_domain_set_num_threads(nthreads, MKL_DOMAIN_VML) in the MKL library. See:

http://www.intel.com/software/products/mkl/docs/webhelp/support/functn_mkl_domain_set_num_threads.html

for more info about it.

numexpr.set_num_threads(nthreads)[source]

Sets a number of threads to be used in operations.

Returns the previous setting for the number of threads.

During initialization time Numexpr sets this number to the number of detected cores in the system (see detect_number_of_cores()).

If you are using Intel’s VML, you may want to use set_vml_num_threads(nthreads) to perform the parallel job with VML instead. However, you should get very similar performance with VML-optimized functions, and VML’s parallelizer cannot deal with common expresions like (x+1)*(x-2), while Numexpr’s one can.

numexpr.detect_number_of_cores()[source]

Detects the number of cores on a system. Cribbed from pp.

numexpr.detect_number_of_threads()[source]

If this is modified, please update the note in: https://github.com/pydata/numexpr/wiki/Numexpr-Users-Guide

numexpr.ncores

The number of (virtual) cores detected.

numexpr.nthreads

The number of threads currently in-use.

numexpr.MAX_THREADS

The maximum number of threads, as set by the environment variable NUMEXPR_MAX_THREADS

numexpr.version

The version of NumExpr.

Tests submodule

numexpr.tests.test(verbosity=1)[source]

Run all the tests in the test suite.

numexpr.tests.print_versions()[source]

Print the versions of software that numexpr relies on.