tatami_python Namespace Reference

tatami bindings for arbitrary Python matrices. More...

Classes
class	UnknownMatrix
	Unknown matrix-like object in Python. More...
struct	UnknownMatrixOptions
	Options for data extraction from an UnknownMatrix. More...

Functions
template<class Function_ , class Index_ >
int	parallelize (const Function_ fun, const Index_ tasks, int workers)
template<typename Function_ >
void	lock (Function_ fun)
template<typename Value_ , typename Index_ , class Function_ >
void	parse_Sparse2darray (const pybind11::object &matrix, Value_ *const vbuffer, Index_ *const ibuffer, Function_ fun)

Detailed Description

tatami bindings for arbitrary Python matrices.

Function Documentation

lock()

template<typename Function_ >

void tatami_python::lock

(

Function_

fun

)

This function is only available if TATAMI_PYTHON_PARALLELIZE_UNKNOWN is defined. Applications can override this by defining a TATAMI_PYTHON_SERIALIZE function-like macro, which should accept a function object and execute it in some serial context.

Template Parameters

Function_

Function that accepts no arguments.

Parameters

fun	Function to be evaluated after the GIL is acquired. This typically involves calls to the Python interpreter or API.

parallelize()

template<class Function_ , class Index_ >

int tatami_python::parallelize	(	const Function_	fun,
		const Index_	tasks,
		int	workers )

Replacement for tatami::parallelize() that applies a function to a set of tasks in parallel, usually for iterating over a dimension of a Matrix. This releases the Python GIL so that it can be re-acquired by UnknownMatrix extractors in each individual worker.

Template Parameters

Function_

Function to be applied to a contiguous range of tasks. This should accept three arguments: worker, the worker ID executing this task range. This will be passed as an int in [0, workers). task_start, the start index of the task range. This will be passed as an Index_ in [0, tasks). task_length, the number of tasks in the task range. This will be passed as an Index_ in (0, tasks), i.e., it is always positive.

Index_

Integer type for the number of tasks.

Parameters

fun	Function that executes a contiguous range of tasks. This will be called no more than once in each worker with a different non-overlapping range, where the union of all ranges will cover [0, tasks).
tasks	Number of tasks. This should be non-negative.
workers	Number of workers. This should be positive.

Returns

The number of workers (K) that were actually used. K is guaranteed to be no greater than workers (or 1, if workers is not positive). fun() will have been called once for each of the worker IDs [0, ..., K - 1].

parse_Sparse2darray()

template<typename Value_ , typename Index_ , class Function_ >

void tatami_python::parse_Sparse2darray	(	const pybind11::object &	matrix,
		Value_ *const	vbuffer,
		Index_ *const	ibuffer,
		Function_	fun )

Parse the contents of a 2-dimensional SparseNdArray from the delayedarray package.

Template Parameters

Value_	Numeric type of the matrix value.
Index_	Integer type of the matrix indices.
Function_	Function to be applied at each leaf node.

Parameters

matrix	The SparseNdarray object.
vbuffer	Pointer to an array of length greater than or equal to the number of rows of matrix, in which to store the values of the structural non-zero elements. This may also be NULL in which case no values are extracted. On input, the contents of the array are ignored by this function.
ibuffer	Pointer to an array of length greater than or equal to the number of rows of matrix, in which to store the indices of the structural non-zero elements. This may also be NULL in which case no values are extracted. On input, the contents of the array are ignored by this function.
fun	Function to apply to each leaf node, accepting two arguments: c, an Index_ specifying the index of the leaf node, i.e., the column index. n, an Index_ specifying the number of structural non-zero elements for c. The first n entries of vbuffer and ibuffer will be filled with the values and indices of these non-zero elements, respectively, if they are not NULL. The return value of this function is ignored. Note that fun may not be called for all c - if leaf nodes do not contain any data, they will be skipped.