Owl APIs

owl module

Owl module: Python binding for Minerva library

The module encapsulates or directly maps some functions of Minerva’s API to python. Only system APIs are defined here. For convolution APIs, please refer to conv.py. For element-wise operations, please refer to elewise.py. For other APIs such as member functions of owl.NArray, please refer to the API document.

Note that Minerva is an dataflow system with lazy evaluation to construct dataflow graph to extract parallelism within codes. All the operations like +-*/ of owl.NArray are all lazy such that they are NOT evaluated immediatedly. Only when you try to pull the content of an NArray outside Minerva’s control (e.g. call to_numpy()) will those operations be executed concretely.

We implement two interfaces for swapping values back and forth between numpy and Minerva. They are from_numpy and to_numpy. So you could still use any existing codes on numpy such as IO and visualization.

owl.initialize(argv)[source]

Initialize Minerva System

Note

Must be called before calling any owl’s API

Parameters:argv (list str) – commandline arguments
owl.finalize()[source]

Finalize Minerva System

Returns:None
owl.wait_for_all()[source]

Wait for all evaluation to complete

Note

The user thread (python) will be blocked until all previous operations are finished.

Returns:None
owl.create_cpu_device()[source]

Create device for running on CPU cores

Note

At least one of create_cpu_device() or create_gpu_device() should be called before using any owl APIs.

Returns:A unique id for cpu device
Return type:int
owl.create_gpu_device(which)[source]

Create device for running on GPU card

Note

At least one of create_cpu_device() or create_gpu_device() should be called before using any owl APIs.

Parameters:which (int) – which GPU card the code would be run on
Returns:A unique id for the device on that GPU card
Return type:int
owl.get_gpu_device_count()[source]

Get the number of compute-capable GPU devices

Returns:Number of compute-capable GPU devices
Return type:int
owl.set_device(dev)[source]

Switch to the given device for running computations

When set_device(dev) is called, all the subsequent codes will be run on dev till another set_device is called.

Parameters:dev (int) – the id of the device (usually returned by create_xxx_device)
owl.zeros(shape)[source]

Create ndarray of zero values

Parameters:shape (list int) – shape of the ndarray to create
Returns:result ndarray
Return type:owl.NArray
owl.ones(shape)[source]

Create ndarray of one values

Parameters:shape (list int) – shape of the ndarray to create
Returns:result ndarray
Return type:owl.NArray
owl.randn(shape, mu, var)[source]

Create a random ndarray using normal distribution

Parameters:
  • shape (list int) – shape of the ndarray to create
  • mu (float) – mu
  • var (float) – variance
Returns:

result ndarray
Return type:

owl.NArray
owl.randb(shape, prob)[source]

Create a random ndarray using bernoulli distribution

Parameters:
  • shape (list int) – shape of the ndarray to create
  • prob (float) – probability for the value to be one
Returns:

result ndarray
Return type:

owl.NArray
owl.from_numpy(nparr)[source]

Create an owl.NArray from numpy.ndarray

Note

The content will be directly copied to Minerva’s memory system. However, due to the different priority when treating dimensions between numpy and Minerva. The result owl.NArray‘s dimension will be reversed.

>>> a = numpy.zeros([200, 300, 50])
>>> b = owl.from_numpy(a)
>>> print b.shape
[50, 300, 200]

See also

owl.NArray.to_numpy()

Parameters:nparr (numpy.ndarray) – numpy ndarray
Returns:Minerva’s ndarray
Return type:owl.NArray
owl.concat(narrays, concat_dim)[source]

Concatenate NArrays according to concat_dim

Parameters:
  • narrays (owl.NArray) – inputs for concatenation
  • concat_dim (int) – the dimension to concate
Returns:

result of concatenation
Return type:

owl.NArray
owl.slice(src, slice_dim, st_off, slice_count)[source]

Slice NArrays according to slice_dim

Parameters:
  • src (owl.NArray) – inputs for slice
  • slice_dim (int) – the dimension to slice
  • st_off (int) – where to start slice
  • slice_count – how many data_chunk on slice_dim
Slice_count:

int
Returns:

result of slicer
Return type:

owl.NArray
owl.print_profiler_result()[source]

Print result from execution profiler

Returns:None
owl.reset_profiler_result()[source]

Reset execution profiler

Returns:None
owl.print_dag_to_file(fname)[source]

Print the current generated dag into the give filename

Parameters:fname (str) – filename for printing the dag
Returns:None
owl.print_dot_dag_to_file(fname)[source]

Print the current generated dag into the give filename in dot format

Parameters:fname (str) – filename for printing the dag
Returns:None
class owl.NArray
__add__

x.__add__(y)<==>x+y

__sub__

x.__sub__(y)<==>x-y

__mul__

x.__mul__(y)<==>x*y

Note

If any of x and y is float number, it is an element-wise multiplication. Otherwise, it is a matrix multiplcation which is only allowed for 2-dimensional NArray (matrix).

__div__

x.__div__(y)<==>x/y

__iadd__

x.__add__(y)<==>x+=y

__isub__

x.__sub__(y)<==>x-=y

__imul__

x.__mul__(y)<==>x*=y

__idiv__

x.__div__(y)<==>x/=y

shape

A list of int that describes the shape of this NArray

sum(axis)

Sum up value along the given axis

Parameters:axis (int) – the axis along which to do summation
Returns:the result ndarray
Return type:owl.NArray
max(axis)

Calculate max value along the given axis

Parameters:axis (int) – the axis along which to do max
Returns:the result ndarray
Return type:owl.NArray
argmax(axis)

Calculate the index of the max value along the given axis

Parameters:axis (int) – the axis along which to do max
Returns:the result ndarray
Return type:owl.NArray
count_zero()

Return the number of zero elements in the NArray

Note

This function is a non-lazy function.

Returns:number of zero elements
Return type:int
trans()

Return the transposed NArray

Note

Only allow transpose on 2-dimension NArray (matrix)

Returns:transposed NArray
Return type:owl.NArray
reshape(shape)

Return the NArray that is of different shape but same contents.

Note

Only shape of the same volume is allowed.

Parameters:shape (list int) – the new shape of the NArray
Returns:the NArray with new shape
Return type:owl.NArray
wait_for_eval()

Put this NArray into evaluation, but do NOT wait for the finish of evaluation. The function will return immediately.

start_eval()

Put this NArray into evaluation and block the execution until this NArray is concretely evaluated.

to_numpy()

Convert this NArray to numpy::ndarray

Note

This function is a non-lazy function. Due to the different priority when treating dimensions between numpy and Minerva. The result numpy::ndarray‘s dimension will be reversed

>>> a = owl.zeros([50, 300, 200])
>>> b = a.to_numpy()
>>> print b.shape
[200, 300, 50]

See also

owl.from_numpy()

Returns:numpy’s ndarray with the same contents
Return type:numpy::ndarray

owl.conv module

This module contains operations for convolution, pooling and softmax

owl.conv.soft_op

Same enum type as cudnn’s cudnnSoftmaxMode_t. Either soft_op.instance or soft_op.channel.

alias of softmax_algo

owl.conv.pool_op

Same enum type as cudnn’s cudnnPoolingMode_t. Either pool_op.max or pool_op.avg.

alias of pooling_algo

owl.conv.softmax(x, op=owl.libowl.softmax_algo.instance)[source]

Perform softmax on the given ndarray.

Note that this function is currently only for softmax accross instances. And the last dimension of x should represent instances. If x is of four dimension, directly call the c++ routine. Otherwise, augment the number of dimension to four.

Parameters:
Returns:

the ndarray after being softmaxed and of the same shape
Return type:

owl.NArray
class owl.conv.Lrner(local_size, alpha, beta)[source]

Wrapper class for LRN.

Variables:
  • local_size (int) – the size of lrn across channel
  • alpha (float) – lrn parameters
  • beta (float) – lrn parameters

Constructor for Convolver class

Parameters:
  • local_size (int) – the size of lrn across channel
  • alpha (float) – lrn parameters
  • beta (float) – lrn parameters
ff(x, scale)[source]

Feed-forward local response norm

Parameters:
Returns:

result ndarray after forward lrn
Return type:

owl.NArray
bp(bottom_data, top_data, scale, top_diff)[source]

Backward local response norm

Parameters:
  • bottom_data (owl.NArray) – activation before lrn
  • top_data (owl.NArray) – activation after lrn
  • scale (owl.NArray) – auxiliary matrix to help computing
  • top_diff (owl.NArray) – error derivative
Returns:

result ndarray after backward lrn
Return type:

owl.NArray
class owl.conv.Convolver(pad_h, pad_w, stride_v, stride_h)[source]

Wrapper class for convolution.

Variables:param (libowl.ConvInfo) – convolution parameters

Constructor for Convolver class

Parameters:
  • pad_h (int) – padding height
  • pad_w (int) – padding width
  • stride_v (int) – vertical stride length
  • stride_h (int) – horizontal stride length
ff(x, w, b)[source]

Feed-forward convolution

Parameters:
Returns:

result ndarray after forward convolution
Return type:

owl.NArray
bp(y, x, w)[source]

Backward convolution

Parameters:
Returns:

result ndarray after backward convolution
Return type:

owl.NArray
weight_grad(y, x, w)[source]

Compute the gradient of filters

Parameters:
  • y (owl.NArray) – error (sensitivity) passed by higher layer
  • x (owl.NArray) – input (activation) of lower layer
  • w (owl.NArray) – weight (used to get the filter dimension)
Returns:

the gradient of filters
Return type:

owl.NArray
bias_grad(y)[source]

Compute the gradient of bias

Parameters:y (owl.NArray) – error (sensitivity) passed by higher layer
Returns:the gradient of bias
Return type:owl.NArray
class owl.conv.Pooler(h, w, stride_v, stride_h, pad_h=0, pad_w=0, op=owl.libowl.pooling_algo.max)[source]

Wrapper class for pooling operations

Variables:param (libowl.PoolingInfo) – pooling parameters

Constructor for Pooler class

Parameters:
  • h (int) – pooling height
  • w (int) – pooling width
  • stride_v (int) – vertical stride length
  • stride_h (int) – horizontal stride length
  • pad_h (int) – padding height
  • pad_w (int) – padding width
  • op (owl.conv.pool_op) – pooling type
ff(x)[source]

Forward propagation for pooling

Parameters:x (owl.NArray) – input ndarray of pooling
Returns:output ndarray after forward pooling
Return type:owl.NArray
bp(y, ff_y, ff_x)[source]

Backward propagation for pooling

Parameters:
  • y (owl.NArray) – error (sensitivity) from higher-layer
  • ff_y (owl.NArray) – value after forward pooling
  • ff_x (owl.NArray) – value before forward pooling
Returns:

output after backward pooling
Return type:

owl.NArray

owl.elewise module

This module contains element-wise operations on ndarray

owl.elewise.mult(x, y)[source]

Element-wise multiplication

Parameters:
Returns:

result after element-wise multiplication
Return type:

owl.NArray
owl.elewise.exp(x)[source]

Exponential function

Parameters:x (owl.NArray) – input
Returns:result ndarray
Return type:owl.NArray
owl.elewise.ln(x)[source]

Ln function

Parameters:x (owl.NArray) – input
Returns:result ndarray
Return type:owl.NArray
owl.elewise.sigm(x)[source]

Sigmoid function: 1 / (1 + exp(-x))

Parameters:x (owl.NArray) – input
Returns:result ndarray
Return type:owl.NArray
owl.elewise.relu(x)[source]

REctified Linear Unit: y = x if x >= 0; y = 0 if x < 0;

Parameters:x (owl.NArray) – input
Returns:result ndarray
Return type:owl.NArray
owl.elewise.tanh(x)[source]

Hyperbolic tangent function

Parameters:x (owl.NArray) – input
Returns:result ndarray
Return type:owl.NArray
owl.elewise.sigm_back(y)[source]

Derivative of sigmoid function: y * (1 - y)

Parameters:y (owl.NArray) – error from higher layer
Returns:result ndarray
Return type:owl.NArray
owl.elewise.relu_back(y, x)[source]

Derivative of RELU function

Parameters:
Returns:

result ndarray
Return type:

owl.NArray
owl.elewise.tanh_back(y)[source]

Derivative of tanh function: sech^2(y)

Parameters:y (owl.NArray) – error from higher layer
Returns:result ndarray
Return type:owl.NArray