special._generate_pyx

python _generate_pyx.py

Generate Ufunc definition source files for scipy.special. Produces files ‘_ufuncs.c’ and ‘_ufuncs_cxx.c’ by first producing Cython.

This will generate both calls to PyUFunc_FromFuncAndData and the required ufunc inner loops.

The syntax in the ufunc signature list is

<line>: <ufunc_name> ‘–’ <kernels> ‘–’ <headers> <kernels>: <function> [‘,’ <function>]* <function>: <name> ‘:’ <input> ‘*’ <output>

’->’ <retval> ‘*’ <ignored_retval>

<input>: <typecode>* <output>: <typecode>* <retval>: <typecode>? <ignored_retval>: <typecode>? <headers>: <header_name> [‘,’ <header_name>]*

The input parameter types are denoted by single character type codes, according to

’f’: ‘float’ ‘d’: ‘double’ ‘g’: ‘long double’ ‘F’: ‘float complex’ ‘D’: ‘double complex’ ‘G’: ‘long double complex’ ‘i’: ‘int’ ‘l’: ‘long’ ‘v’: ‘void’

If multiple kernel functions are given for a single ufunc, the one which is used is determined by the standard ufunc mechanism. Kernel functions that are listed first are also matched first against the ufunc input types, so functions listed earlier take precedence.

In addition, versions with casted variables, such as d->f,D->F and i->d are automatically generated.

There should be either a single header that contains all of the kernel functions listed, or there should be one header for each kernel function. Cython pxd files are allowed in addition to .h files.

Cython functions may use fused types, but the names in the list should be the specialized ones, such as ‘somefunc[float]’.

Function coming from C++ should have ++ appended to the name of the header.

Floating-point exceptions inside these Ufuncs are converted to special function errors — which are separately controlled by the user, and off by default, as they are usually not especially useful for the user.

The C++ module

In addition to _ufuncs module, a second module _ufuncs_cxx is generated. This module only exports function pointers that are to be used when constructing some of the ufuncs in _ufuncs. The function pointers are exported via Cython’s standard mechanism.

This mainly avoids build issues — Python distutils has no way to figure out what to do if you want to link both C++ and Fortran code in the same shared library.

Module Contents

Classes

Func(self,name,signatures,headers) Base class for Ufunc and FusedFunc.
Ufunc(self,name,signatures,headers) Ufunc signature, restricted format suitable for special functions.
FusedFunc(self,name,signatures,headers) Generate code for a fused-type special function that can be

Functions

underscore(arg)
cast_order(c)
generate_loop(func_inputs,func_outputs,func_retval,ufunc_inputs,ufunc_outputs) Generate a UFunc loop function that calls a function given as its
generate_fused_type(codes) Generate name of and cython code for a fused type.
generate_bench(name,codes)
generate_doc(name,specs)
npy_cdouble_from_double_complex(var) Cast a cython double complex to a numpy cdouble.
double_complex_from_npy_cdouble(var) Cast a numpy cdouble to a cython double complex.
iter_variants(inputs,outputs) Generate variants of UFunc signatures, by changing variable types,
get_declaration(ufunc,c_name,c_proto,cy_proto,header,proto_h_filename) Construct a Cython declaration of a function coming either from a
generate_ufuncs(fn_prefix,cxx_fn_prefix,ufuncs)
generate_fused_funcs(modname,ufunc_fn_prefix,fused_funcs)
unique(lst) Return a list without repeated entries (first occurrence is kept),
all_newer(src_files,dst_files)
main()
underscore(arg)
cast_order(c)
generate_loop(func_inputs, func_outputs, func_retval, ufunc_inputs, ufunc_outputs)

Generate a UFunc loop function that calls a function given as its data parameter with the specified input and output arguments and return value.

This function can be passed to PyUFunc_FromFuncAndData.

func_inputs, func_outputs, func_retval : str

Signature of the function to call, given as type codes of the input, output and return value arguments. These 1-character codes are given according to the CY_TYPES and TYPE_NAMES lists above.

The corresponding C function signature to be called is:

retval func(intype1 iv1, intype2 iv2, …, outtype1 *ov1, …);

If len(ufunc_outputs) == len(func_outputs)+1, the return value is treated as the first output argument. Otherwise, the return value is ignored.

ufunc_inputs, ufunc_outputs : str

Ufunc input and output signature.

This does not have to exactly match the function signature, as long as the type casts work out on the C level.

loop_name
Name of the generated loop function.
loop_body
Generated C code for the loop.
generate_fused_type(codes)

Generate name of and cython code for a fused type.

typecodes : str
Valid inputs to CY_TYPES (i.e. f, d, g, …).
generate_bench(name, codes)
generate_doc(name, specs)
npy_cdouble_from_double_complex(var)

Cast a cython double complex to a numpy cdouble.

double_complex_from_npy_cdouble(var)

Cast a numpy cdouble to a cython double complex.

iter_variants(inputs, outputs)

Generate variants of UFunc signatures, by changing variable types, within the limitation that the corresponding C types casts still work out.

This does not generate all possibilities, just the ones required for the ufunc to work properly with the most common data types.

inputs, outputs : str
UFunc input and output signature strings
new_input, new_output : str
Modified input and output strings. Also the original input/output pair is yielded.
class Func(name, signatures, headers)

Base class for Ufunc and FusedFunc.

__init__(name, signatures, headers)
_parse_signatures(sigs_str, headers_str)
_parse_signature(sig)
get_prototypes(nptypes_for_h=False)
cython_func_name(c_name, specialized=False, prefix="_func_", override=True)
parse_all(ufunc_str)
class Ufunc(name, signatures, headers)

Ufunc signature, restricted format suitable for special functions.

name
Name of the ufunc to create
signature

String of form ‘func: fff*ff->f, func2: ddd->*i’ describing the C-level functions and types of their input arguments and return values.

The syntax is ‘function_name: inputparams*outputparams->output_retval*ignored_retval’

name : str
Python name for the Ufunc
signatures : list of (func_name, inarg_spec, outarg_spec, ret_spec, header_name)
List of parsed signatures
doc : str
Docstring, obtained from add_newdocs
function_name_overrides : dict of str->str
Overrides for the function names in signatures
__init__(name, signatures, headers)
_get_signatures_and_loops(all_loops)
generate(all_loops)
class FusedFunc(name, signatures, headers)

Generate code for a fused-type special function that can be cimported in cython.

__init__(name, signatures, headers)
_get_codes()
_get_types(codes)
_get_vars()
_get_conditional(types, codes, adverb)

Generate an if/elif/else clause that selects a specialization of fused types.

_get_incallvars(intypes, c)

Generate pure input variables to a specialization, i.e. variables that aren’t used to return a value.

_get_outcallvars(outtypes, c)

Generate output variables to a specialization, i.e. pointers that are used to return values.

_get_nan_decs()

Set all variables to nan for specializations of fused types for which don’t have signatures.

_get_tmp_decs(all_tmpvars)

Generate the declarations of any necessary temporary variables.

_get_python_wrap()

Generate a python wrapper for functions which pass their arguments as pointers.

_get_common(signum, sig)

Generate code common to all the _generate_* methods.

_generate_from_return_and_no_outargs()
_generate_from_outargs_and_no_return()
_generate_from_outargs_and_return()
generate()
get_declaration(ufunc, c_name, c_proto, cy_proto, header, proto_h_filename)

Construct a Cython declaration of a function coming either from a pxd or a header file. Do sufficient tricks to enable compile-time type checking against the signature expected by the ufunc.

generate_ufuncs(fn_prefix, cxx_fn_prefix, ufuncs)
generate_fused_funcs(modname, ufunc_fn_prefix, fused_funcs)
unique(lst)

Return a list without repeated entries (first occurrence is kept), preserving order.

all_newer(src_files, dst_files)
main()