Core functionality

Classes necessary to create computations and transformations are exposed from the core module.

Computation signatures

class reikna.core.Type(dtype, shape=None, strides=None, offset=0, nbytes=None)

Represents an array or, as a degenerate case, scalar type of a computation parameter.

shape

A tuple of integers. Scalars are represented by an empty tuple.

dtype

A numpy.dtype instance.

ctype

A string with the name of C type corresponding to dtype, or a module if it is a struct type.

strides

Tuple of bytes to step in each dimension when traversing an array.

offset

The initial offset (in bytes).

nbytes

The total size of the memory buffer (in bytes)

__call__(val)

Casts the given value to this type.

classmethod from_value(val)

Creates a Type object corresponding to the given value.

classmethod padded(dtype, shape, pad=0)

Creates a Type object corresponding to an array padded from all dimensions by pad elements.

class reikna.core.Annotation(type_, role=None, constant=False)

Computation parameter annotation, in the same sense as it is used for functions in the standard library.

Parameters:
  • type – a Type object.
  • role – any of 'i' (input), 'o' (output), 'io' (input/output), 's' (scalar). Defaults to 's' for scalars, 'io' for regular arrays and 'i' for constant arrays.
  • constant – if True, corresponds to a constant (cached) array.
class reikna.core.Parameter(name, annotation, default=<class 'funcsigs._empty'>)

Computation parameter, in the same sense as it is used for functions in the standard library. In its terms, all computation parameters have kind POSITIONAL_OR_KEYWORD.

Parameters:
  • name – parameter name.
  • annotation – an Annotation object.
  • default – default value for the parameter, can only be specified for scalars.
rename(new_name)

Creates a new Parameter object with the new name and the same annotation and default value.

class reikna.core.Signature(parameters)

Computation signature, in the same sense as it is used for functions in the standard library.

Parameters:parameters – a list of Parameter objects.
parameters

An OrderedDict with Parameter objects indexed by their names.

bind_with_defaults(args, kwds, cast=False)

Binds passed positional and keyword arguments to parameters in the signature and returns the resulting BoundArguments object.

Core classes

class reikna.core.Computation(root_parameters)

A base class for computations, intended to be subclassed.

Parameters:root_parameters – a list of Parameter objects.
signature

A Signature object representing current computation signature (taking into account connected transformations).

parameter

A named tuple of ComputationParameter objects corresponding to parameters from the current signature.

_build_plan(plan_factory, device_params, *args)

Derived classes override this method. It is called by compile() and supposed to return a ComputationPlan object.

Parameters:
  • plan_factory – a callable returning a new ComputationPlan object.
  • device_params – a DeviceParameters object corresponding to the thread the computation is being compiled for.
  • args – KernelArgument objects, corresponding to parameters specified during the creation of this computation object.
_update_attributes()

Updates signature and parameter attributes. Called by the methods that change the signature.

compile(thread, fast_math=False, compiler_options=None, keep=False)

Compiles the computation with the given Thread object and returns a ComputationCallable object. If fast_math is enabled, the compilation of all kernels is performed using the compiler options for fast and imprecise mathematical functions. compiler_options can be used to pass a list of strings as arguments to the backend compiler. If keep is True, the generated kernels and binaries will be preserved in temporary directories.

connect(_comp_connector, _trf, _tr_connector, **tr_from_comp)

Connect a transformation to the computation.

Parameters:
  • _comp_connector – connection target — a ComputationParameter object belonging to this computation object, or a string with its name.
  • _trf – a Transformation object.
  • _tr_connector – connector on the side of the transformation — a TransformationParameter object belonging to tr, or a string with its name.
  • tr_from_comp – a dictionary with the names of new or old computation parameters as keys, and TransformationParameter objects (or their names) as values. The keys of tr_from_comp cannot include the name of the connection target.
Returns:

this computation object (modified).

Note

The resulting parameter order is determined by traversing the graph of connections depth-first (starting from the initial computation parameters), with the additional condition: the nodes do not change their order in the same branching level (i.e. in the list of computation or transformation parameters, both of which are ordered).

For example, consider a computation with parameters (a, b, c, d). If you connect a transformation (a', c) -> a, the resulting computation will have the signature (a', b, c, d) (as opposed to (a', c, b, d) it would have for the pure depth-first traversal).

class reikna.core.Transformation(parameters, code, render_kwds=None, connectors=None)

A class containing a pure parallel transformation of arrays. Some restrictions apply:

  • it cannot use local memory;
  • it cannot use global/local id getters (and depends only on externally passed indices);
  • it cannot have 'io' arguments;
  • it has at least one argument that uses load_same or store_same, and does it only once.
Parameters:
  • parameters – a list of Parameter objects.
  • code – a source template for the transformation. Will be wrapped in a template def with positional arguments with the names of objects in parameters.
  • render_kwds – a dictionary with render keywords that will be passed to the snippet.
  • connectors – a list of parameter names suitable for connection. Defaults to all non-scalar parameters.

Result and attribute classes

class reikna.core.Indices(shape)

Encapsulates the information about index variables available for the snippet.

__getitem__(dim)

Returns the name of the index varibale for the dimension dim.

all()

Returns the comma-separated list of all index variable names (useful for passing the guiding indices verbatim in a load or store call).

class reikna.core.computation.ComputationCallable(thread, parameters, kernel_calls, internal_args, temp_buffers)

A result of calling compile() on a computation. Represents a callable opaque GPGPU computation.

thread

A Thread object used to compile the computation.

signature

A Signature object.

parameter

A named tuple of Type objects corresponding to the callable’s parameters.

__call__(*args, **kwds)

Execute the computation. In case of the OpenCL backend, returns a list of pyopencl.Event objects from nested kernel calls.

class reikna.core.computation.ComputationParameter(computation, name, type_)

Bases: Type

Represents a typed computation parameter. Can be used as a substitute of an array for functions which are only interested in array metadata.

connect(_trf, _tr_connector, **tr_from_comp)

Shortcut for connect() with this parameter as a first argument.

class reikna.core.computation.KernelArgument(name, type_)

Bases: Type

Represents an argument suitable to pass to planned kernel or computation call.

class reikna.core.computation.ComputationPlan(tr_tree, translator, thread, fast_math, compiler_options, keep)

Computation plan recorder.

computation_call(computation, *args, **kwds)

Adds a nested computation call. The computation value must be a Computation object. args and kwds are values to be passed to the computation.

constant_array(arr)

Adds a constant GPU array to the plan, and returns the corresponding KernelArgument.

kernel_call(template_def, args, global_size, local_size=None, render_kwds=None, kernel_name='_kernel_func')

Adds a kernel call to the plan.

Parameters:
  • template_def – Mako template def for the kernel.
  • args – a list consisting of KernelArgument objects, or scalar values wrapped in numpy.ndarray, that are going to be passed to the kernel during execution.
  • global_size – global size to use for the call, in row-major order.
  • local_size – local size to use for the call, in row-major order. If None, the local size will be picked automatically.
  • render_kwds – dictionary with additional values used to render the template.
  • kernel_name – the name of the kernel function.
persistent_array(arr)

Adds a persistent GPU array to the plan, and returns the corresponding KernelArgument.

temp_array(shape, dtype, strides=None, offset=0, nbytes=None)

Adds a temporary GPU array to the plan, and returns the corresponding KernelArgument. See array() for the information about the parameters.

Temporary arrays can share physical memory, but in such a way that their contents is guaranteed to persist between the first and the last use in a kernel during the execution of the plan.

temp_array_like(arr)

Same as temp_array(), taking the array properties from array or array-like object arr.

Warning

Note that pycuda.GPUArray objects do not have the offset attribute.

class reikna.core.transformation.TransformationParameter(trf, name, type_)

Bases: Type

Represents a typed transformation parameter. Can be used as a substitute of an array for functions which are only interested in array metadata.

class reikna.core.transformation.KernelParameter(name, type_, load_idx=None, store_idx=None, load_same=None, store_same=None, load_combined_idx=None, store_combined_idx=None)

Providing an interface for accessing kernel arguments in a template. Depending on the parameter type, and whether it is used inside a computation or a transformation template, can have different load/store attributes available.

name

Parameter name

shape
dtype
ctype
strides
offset

Same as in Type.

__str__()

Returns the C kernel parameter name corresponding to this parameter. It is the only method available for scalar parameters.

load_idx

A module providing a macro with the signature (idx0, idx1, ...), returning the corresponding element of the array.

store_idx

A module providing a macro with the signature (idx0, idx1, ..., val), saving val into the specified position.

load_combined_idx(slices)

A module providing a macro with the signature (cidx0, cidx1, ...), returning the element of the array corresponding to the new slicing of indices (e.g. an array with shape (2, 3, 4, 5, 6) sliced as slices=(2, 2, 1) is indexed as an array with shape (6, 20, 6)).

store_combined_idx(slices)

A module providing a macro with the signature (cidx0, cidx1, ..., val), saving val into the specified position corresponding to the new slicing of indices.

load_same

A module providing a macro that returns the element of the array corresponding to the indices used by the caller of the transformation.

store_same

A module providing a macro with the signature (val) that stores val using the indices used by the caller of the transformation.