Using Op params

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

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

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

The params type

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

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

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

The params object

The object that you use to store your param values must be hashableand comparable for equality, because it will be stored in a dictionaryat some point. Apart from those requirements it can be anything thatmatches what you have declared as the params type.

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 yourparams object. It doesn’t have to be complete type because only thefollowing methods will be used for the type:

• filter
• eq
• hash
• values_eq

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

• c_declare
• c_init
• c_extract
• c_cleanup

You can also define other convenience methods such asc_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 classattribute params_type to an instance of your params Type.

Note

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

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

class MyOp(Op):
    params_type = Generic()

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

def get_params(self, node)

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

Note

Due to implementation restrictions, None is not allowed as aparams object and will be taken to mean that the Op doesn’t haveparameters.

Since this will change the expected signature of a few methods, itis strongly discouraged to have your get_params() methodreturn None.

Signature changes from having params

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

Warning

If you do not account for this extra parameter, the code will failat 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 thismeans that you can use your params in the c_codeand 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 asthe 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 pointweights.

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
 
    def __hash__(self):
        return hash((type(self), self.alpha, self.beta))
 
    def __eq__(self, other):
        return (type(self) == type(other) and
                self.alpha == other.alpha and
                self.beta == other.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])