Using Op params

The Op params is a facility to pass some runtime parameters to the code of an op without modifying it. It can enable a single instance of C code to serve different needs and therefore reduce compilation.

The code enables you to pass a single object, but it can be a struct or python object with multiple values if you have more than one value to pass.

We will first introduce the parts involved in actually using this functionality and then present a simple working example.

The params type

You can either reuse an existing type such as Generic or create your own.

Using a python object for your op parameters (Generic) can be annoying to access from C code since you would have to go through the Python-C API for all accesses.

Making a purpose-built class may require more upfront work, but can pay off if you reuse the type for a lot of Ops, by not having to re-do all of the python manipulation.

Defining a params type

Note

This section is only relevant if you decide to create your own type.

The first thing you need to do is to define a Theano Type for your params object. It doesn’t have to be complete type because only the following methods will be used for the type:

Additionaly if you want to use your params with C code, you need the following methods:

You can also define other convenience methods such as c_headers if you need any special things.

Registering the params with your Op

To declare that your Op uses params you have to set the class attribute params_type to an instance of your params Type.

Note

If you want to have multiple parameters you have to bundle those inside a single object and use that as the params type.

For example if we decide to use an int as the params the following would be appropriate:

class MyOp(Op):
    params_type = Generic()

After that you need to define a get_params() method on your class with the following signature:

def get_params(self, node)

This method must return a valid object for your Type (an object that passes filter()). The node parameter is the Apply node for which we want the params. Therefore the params object can depend on the inputs and outputs of the node.

Note

Due to implementation restrictions, None is not allowed as a params object and will be taken to mean that the Op doesn’t have parameters.

Since this will change the expected signature of a few methods, it is strongly discouraged to have your get_params() method return None.

Signature changes from having params

Having declared a params for your Op will affect the expected signature of perform(). The new expected signature will have an extra parameter at the end which corresponds to the params object.

Warning

If you do not account for this extra parameter, the code will fail at runtime if it tries to run the python version.

Also, for the C code, the sub dictionary will contain an extra entry ‘params’ which will map to the variable name of the params object. This is true for all methods that recieve a sub parameter, so this means that you can use your params in the c_code and c_init_code_struct method.

A simple example

This is a simple example which uses a params object to pass a value. This Op will multiply a scalar input by a fixed floating point value.

Since the value in this case is a python float, we chose Generic as the params type.

from theano import Op
from theano.gof.type import Generic
from theano.scalar import as_scalar

class MulOp(Op):
    params_type = Generic()
    __props__ = ('mul',)

    def __init__(self, mul):
        self.mul = float(mul)

    def get_params(self, node):
        return self.mul

    def make_node(self, inp):
        inp = as_scalar(inp)
        return Apply(self, [inp], [inp.type()]

    def perform(self, node, inputs, output_storage, params):
        # Here params is a python float so this is ok
        output_storage[0][0] = inputs[0] * params

    def c_code(self, node, name, inputs, outputs, sub):
        return ("%(z)s = %(x)s * PyFloat_AsDouble(%(p)s);" %
                dict(z=outputs[0], x=inputs[0], p=sub['params']))

A more complex example

This is a more complex example which actually passes multiple values. It does a linear combination of two values using floating point weights.

from theano import Op
from theano.gof.type import Generic
from theano.scalar import as_scalar

class ab(object):
    def __init__(self, alpha, beta):
        self.alpha = alpha
        self.beta = beta


class Mix(Op):
    params_type = Generic()
    __props__ = ('alpha', 'beta')

    def __init__(self, alpha, beta):
        self.alpha = alpha
        self.beta = beta

    def get_params(self, node):
        return ab(alpha=self.alpha, beta=self.beta)

    def make_node(self, x, y):
        x = as_scalar(x)
        y = as_scalar(y)
        return Apply(self, [x, y], [x.type()]

    def c_support_code_struct(self, node, name):
        return """
        double alpha_%(name)s;
        double beta_%(name)s;
        """ % dict(name=name)

    def c_init_code_struct(self, node, name, sub):
        return """{
        PyObject *tmp;
        tmp = PyObject_GetAttrString(%(p)s, "alpha");
        if (tmp == NULL)
          %(fail)s
        alpha_%(name)s = PyFloat_AsDouble(tmp);
        Py_DECREF(%(tmp)s);
        if (PyErr_Occurred())
          %(fail)s
        tmp = PyObject_GetAttrString(%(p)s, "beta");
        if (tmp == NULL)
          %(fail)s
        beta_%(name)s = PyFloat_AsDouble(tmp);
        Py_DECREF(tmp);
        if (PyErr_Occurred())
          %(fail)s
        }""" % dict(name=name, p=sub['params'], fail=sub['fail'])

    def c_code(self, node, name, inputs, outputs, sub):
        return """
        %(z)s = alpha_%(name)s * %(x)s + beta_%(name)s * %(y)s;
        """ % dict(name=name, z=outputs[0], x=inputs[0], y=inputs[1])