ADDFUNCS.rst

Functions and Function signatures

Adding functions

In order to add new functions to numexpr, currently it is necessary to edit several files. Consider adding a function out_type myfunc(arg_type).

• numexpr/expressions.py

Add 'myfunc': func(numpy.myfunc, out_dtype), to the dict of functions, functions = {.... If the return type of the function is bool, add the function to the list if opcode in ("isnan", "isfinite"): in the __init__ function of the FuncNode class. In the future it might be nice to refactor this function since it sets the output type based on the type of the inputs in general.

• numexpr/necompiler.py

Add "myfunc" to the list of functions:

"floor",
"isnan",
"isfinite",
"myfunc"
]

• numexpr/functions.hpp

Find the correct function signature FUNC_OA where O is the return type, and A the argument type(s). For example, if the function is double myfunc(double), one should edit within the FUNC_DD clause. If you cannot find your function signature you will have to add it, following the template of the other functions. Most likely, you will want to add support for several function signatures (e.g. double -> bool and float -> bool) and so you will have to add the function in two clauses. If your function has a float input, you will see that there are 5 arguments in the FUNC_OA macro, and you will have to add myfunc2 here is order to compile on MSVC machines (i.e. Windows, see following). Example:

 #ifndef FUNC_DD
 #define ELIDE_FUNC_DD
 #define FUNC_DD(...)
 #endif
 ...
 FUNC_DD(FUNC_MYFUNC_DD, "myfunc_dd", myfunc, vdMyfunc)
 FUNC_DD(FUNC_DD_LAST,    NULL,          NULL,  NULL)
 #ifdef ELIDE_FUNC_DD
 #undef ELIDE_FUNC_DD
 #undef FUNC_DD
 #endif

 ...

 #ifndef FUNC_FF
 #define ELIDE_FUNC_FF
 #define FUNC_FF(...)
 #endif
 ...
 FUNC_FF(FUNC_MYFUNC_FF, "myfunc_ff", myfuncf, myfuncf2, vsMyfunc)
 FUNC_FF(FUNC_FF_LAST,    NULL,       NULL,    NULL,     NULL)
 #ifdef ELIDE_FUNC_FF
 #undef ELIDE_FUNC_FF
 #undef FUNC_FF
 #endif

• numexpr/msvc_function_stubs.hpp

In order to support float arguments, due to oddities of MSVC, you have to provide explicit support for your function in this file. Add #define myfuncf(x) ((float)floor((double)(x))) (if your function is float -> float) to the #if clause at the top of the file which is for old versions of MSVC which did not have support for single precision fucntions. Then in the body, add an inline function

inline float myfuncf2(float x) {
    return myfuncf(x);
}

This is the function that appears as the f_win32 parameter in functions.hpp.

• numexpr/tests/test_numexpr.py

Don't forget to add a test for your function!

Adding function signatures

It may so happen that you cannot find your desired function signature in functions.hpp. This means you will have to add it yourself! This involves editing a few more files. In addition, there may be certain bespoke changes, specific to the function signature that you may have to make (see Notes, below)

• numexpr/functions.hpp

Firstly, add clause(s) for your function signature. For example, if the function signature is bool(double) and bool(float), add FUNC_BD and FUNC_BF clauses (in the latter case you will need the macro to take 5 arguments for MSVC-compatibility.)

#ifndef FUNC_BD
#define ELIDE_FUNC_BD
#define FUNC_BD(...)
#endif
...
FUNC_BD(FUNC_BD_LAST,    NULL,          NULL,  NULL)
#ifdef ELIDE_FUNC_BD
#undef ELIDE_FUNC_BD
#undef FUNC_BD
#endif

#ifndef FUNC_BF
#define ELIDE_FUNC_BF
#define FUNC_BF(...)
#endif
...
FUNC_BF(FUNC_BF_LAST,    NULL,     NULL,     NULL,  NULL)
#ifdef ELIDE_FUNC_BF
#undef ELIDE_FUNC_BF
#undef FUNC_BF
#endif

The ultimate source of the functions in the macro FUNC_BF(...) are the headers included in numexpr/interpreter.cpp (in particular numexpr/numexpr_config.hpp, which can be used to overwrite <math.h> functions), so the functions should be available from there.

• numexpr/interp_body.cpp

Add case support for OPCODES associated to your new function signatures via e.g. case OP_FUNC_BFN and case OP_FUNC_BDN, following the framework suggested by the other functions:

case OP_FUNC_BFN:
#ifdef USE_VML
            VEC_ARG1_VML(functions_bf_vml[arg2](BLOCK_SIZE,
                                                (float*)x1, (bool*)dest));
#else
            VEC_ARG1(b_dest = functions_bf[arg2](f1));
#endif

Note that it is important that the out variable matches the output type of the function (i.e. b_dest for bool, f_dest for float etc.)

• numexpr/interpreter.hpp

Add clauses to read the functions.hpp macros correctly

enum FuncBFCodes {
#define FUNC_BF(fop, ...) fop,
#include "functions.hpp"
#undef FUNC_BF
};

• numexpr/interpreter.cpp

Add clauses to generate the FUNC_CODES from the functions.hpp header, making sure to include clauses for _WIN32 and VML as necessary accoridng to the framework suggested by the other functions.

typedef bool (*FuncBFPtr)(float);
#ifdef _WIN32
FuncBFPtr functions_bf[] = {
#define FUNC_BF(fop, s, f, f_win32, ...) f_win32,
#include "functions.hpp"
#undef FUNC_BF
};
#else
FuncBFPtr functions_bf[] = {
#define FUNC_BF(fop, s, f, ...) f,
#include "functions.hpp"
#undef FUNC_BF
};
#endif

#ifdef USE_VML
typedef void (*FuncBFPtr_vml)(MKL_INT, const float*, bool*);
FuncBFPtr_vml functions_bf_vml[] = {
#define FUNC_BF(fop, s, f, f_win32, f_vml) f_vml,
#include "functions.hpp"
#undef FUNC_BF
};
#endif

Some functions (e.g. fmod, isnan) are not available in MKL, and so must be hard-coded in bespoke_functions.hpp as well:

#ifdef USE_VML
/* no isnan, isfinite or isinf in VML */
static void vdIsfinite(MKL_INT n, const double* x1, bool* dest)
{
    MKL_INT j;
    for (j=0; j<n; j++) {
        dest[j] = isfinited(x1[j]);
    };
};
#endif

The complex case is slightly different (see other examples in the same file).

Add case handling to the check_program function

else if (op == OP_FUNC_BDN) {
    if (arg < 0 || arg >= FUNC_BD_LAST) {
        PyErr_Format(PyExc_RuntimeError, "invalid program: funccode out of range (%i) at %i", arg, argloc);
        return -1;
    }
}
else if (op == OP_FUNC_BFN) {
    if (arg < 0 || arg >= FUNC_BF_LAST) {
        PyErr_Format(PyExc_RuntimeError, "invalid program: funccode out of range (%i) at %i", arg, argloc);
        return -1;
    }
}

• numexpr/module.cpp

Add code here to define the FUNC_OA macros you require

#define FUNC_BF(name, sname, ...)  add_func(name, sname);
#define FUNC_BD(name, sname, ...)  add_func(name, sname);
...
#include "functions.hpp"
...
#undef FUNC_BD
#undef FUNC_BF

• numexpr/opcodes.hpp

Finally, add the OP_FUNC_BDN etc. codes here. It is necessary for the OPCODES in the file to be in (ascending order) with NOOP as 0 and OP_LAST as the largest number. Secondly, all reduction OPCODES must appear last. Hence, after adding your function signatures (just before the reduction OPCODES) it is necessary to increment all succeeding OPCODES.

OPCODE(106, OP_FUNC_BDN, "func_bdn", Tb, Td, Tn, T0)
OPCODE(107, OP_FUNC_BFN, "func_bfn", Tb, Tf, Tn, T0)

Notes

In many cases this process will not be very smooth since one relies on the internal C/C++ standard functions (which can be fussy, to varying degrees on different platforms). Some common gotchas are then:

• OPCODES are currently only supported up to 255 - if it becomes necessary to increment further, one will have to change the latin_1 encoding used in quadrupleToString in necompiler.py. In addition, since the OPCDE table is assumed to be of type unsigned char the get_return_sig function in numexpr/interpreter.cpp may have to be changed (possibly other changes too).
• Depending on the new function signature (above all if the out type is different to the input types), one may have to edit the __init__ function in the FuncNode class in expressions.py.
• Functions which accept and/or return complex arguments must be added to the complex_functions.hpp file (take care when adding them in interpreter.cpp and interp_body.cpp, since their signatures are usually a bit different).
• Depending on MSVC support, namespace clashes, casting problems, it may be necessary to make various changes to numexpr/numexpr_config.hpp and numexpr/msvc_function_stubs.hpp. For example, in PR #523, non-clashing wrappers were introduced for isnan and isfinite since the float versions isnanf, isfinitef were inconsistently defined (and output ints) - depending on how strict the platform interpreter is, the implicit cast from int to bool was acceptable or not for example. In addition, the base functions were in different namespaces or had different names across platforms.