theano.gof.params_type – Wrapper class for op params

Reference

Module for wrapping many Op parameters into one object available in both Python and C code.

The module provides the main public class ParamsType that allows to bundle many Theano typesinto one parameter type, and an internal convenient class Params which will be automaticallyused to create a Params object that is compatible with the ParamsType defined.

The Params object will be available in both Python code (as a standard Python object) and C code(as a specific struct with parameters as struct fields). To be fully-available in C code, Theanotypes wrapped into a ParamsType must provide a C interface (e.g. TensorType, Scalar, GpuArrayType,or your own type. See Using Op params for more details).

Example of usage

Importation:

  1. # Import ParamsType class.
  2. from theano.gof import ParamsType
  3.  
  4. # If you want to use a tensor and a scalar as parameters,
  5. # you should import required Theano types.
  6. from theano.tensor import TensorType
  7. from theano.scalar import Scalar

In your Op sub-class:

  1. params_type = ParamsType(attr1=TensorType('int32', (False, False)), attr2=Scalar('float64'))

If your op contains attributes attr1 and attr2, the default op.get_params()implementation will automatically try to look for it and generate an appropriate Params object.Attributes must be compatible with the corresponding types defined into the ParamsType(we will try to convert and downcast if needed). In this example, your_op.attr1should be a matrix of integers, and your_op.attr2should be a real number (integer or floating value).

  1. def __init__(value_attr1, value_attr2):
  2.     self.attr1 = value_attr1
  3.     self.attr2 = value_attr2

In perform() implementation (with params named param):

  1. matrix_param = param.attr1
  2. number_param = param.attr2

In c_code() implementation (with param = sub['params']):

  1. PyArrayObject* matrix = param->attr1;
  2. npy_float64    number = param->attr2;
  3. /* You won't need to free them or whatever else. */

See QuadraticOpFunc and QuadraticCOpFunc in theano/gof/tests/test_params_type.pyfor complete working examples.

Combining ParamsType with Theano enumeration types

Theano provide some enumeration types that allow to create constant primitive values (integer and floating values)available in both Python and C code. See theano.gof.type.EnumType and its subclasses for more details.

If your ParamsType contains Theano enumeration types, then constants defined inside theseenumerations will be directly available as ParamsType attributes.

Example:

  1. from theano.gof import ParamsType, EnumType, EnumList
  2.  
  3. wrapper = ParamsType(enum1=EnumList('CONSTANT_1', 'CONSTANT_2', 'CONSTANT_3'),
  4.                      enum2=EnumType(PI=3.14, EPSILON=0.001))
  5.  
  6. # Each enum constant is available as a wrapper attribute:
  7. print(wrapper.CONSTANT_1, wrapper.CONSTANT_2, wrapper.CONSTANT_3,
  8.       wrapper.PI, wrapper.EPSILON)
  9.  
  10. # For convenience, you can also look for a constant by name with
  11. # ``ParamsType.get_enum()`` method.
  12. pi = wrapper.get_enum('PI')
  13. epsilon = wrapper.get_enum('EPSILON')
  14. constant_2 = wrapper.get_enum('CONSTANT_2')
  15. print(pi, epsilon, constant_2)

This implies that a ParamsType cannot contain different enum types with common enum names:

  1. # Following line will raise an error,
  2. # as there is a "CONSTANT_1" defined both in enum1 and enum2.
  3. wrapper = ParamsType(enum1=EnumList('CONSTANT_1', 'CONSTANT_2'),
  4.                      enum2=EnumType(CONSTANT_1=0, CONSTANT_3=5))

If your enum types contain constant aliases, you can retrive them from ParamsTypewith ParamsType.enum_from_alias(alias) method (see theano.gof.type.EnumTypefor more info about enumeration aliases).

  1. wrapper = ParamsType(enum1=EnumList('A', ('B', 'beta'), 'C'),
  2.                      enum2=EnumList(('D', 'delta'), 'E', 'F'))
  3. b1 = wrapper.B
  4. b2 = wrapper.get_enum('B')
  5. b3 = wrapper.enum_from_alias('beta')
  6. assert b1 == b2 == b3
  • class theano.gof.paramstype.Params(_params_type, **kwargs)[source]
  • Internal convenient class to wrap many Python objects into one(this class is not safe as the hash method does not check if values are effectively hashable).

Example:

  1. from theano.gof import ParamsType, Params
  2. from theano.scalar import Scalar
  3. # You must create a ParamsType first:
  4. params_type = ParamsType(attr1=Scalar('int32'),
  5.                          key2=Scalar('float32'),
  6.                          field3=Scalar('int64'))
  7. # Then you can create a Params object with
  8. # the params type defined above and values for attributes.
  9. params = Params(params_type, attr1=1, key2=2.0, field3=3)
  10. print(params.attr1, params.key2, params.field3)
  11. d = dict(attr1=1, key2=2.5, field3=-1)
  12. params2 = Params(params_type, **d)
  13. print(params2.attr1, params2.key2, params2.field3)
  • class theano.gof.paramstype.ParamsType(**kwargs_)[source]
  • This class can create a struct of Theano types (like TensorType, GpuArrayType, etc.)to be used as a convenience op parameter wrapping many data.

ParamsType constructor takes key-value args.Key will be the name of the attribute in the struct.Value is the Theano type of this attribute, ie. an instance of (a subclass of) Type(eg. TensorType('int64', (False,))).

In a Python code any attribute named key will be available via:

  1. structObject.key

In a C code, any attribute named key will be available via:

  1. structObject->key;

Note

This Type is not complete and should never be used for regular graph operations.

  • hastype(_theano_type)[source]

  • Return True if current ParamsType contains the specified Theano type.

  • gettype(_field_name)[source]

  • Return the Theano type associated to the given field namein the current ParamsType.

  • getfield(_theano_type)[source]

  • Return the name (string) of the first field associated tothe given Theano type. Fields are sorted in lexicographicorder. Raise an exception if this Theano type is notin the current ParamsType.

This method is intended to be used to retrieve a field namewhen we know that current ParamsType contains the givenTheano type only once.

  • getenum(_key)[source]
  • Look for a constant named key in the Theano enumeration typeswrapped into current ParamsType. Return value of the constant found,or raise an exception if either the constant is not found orcurrent wrapper does not contain any Theano enumeration type.

Example:

  1. from theano.gof import ParamsType, EnumType, EnumList
  2. from theano.scalar import Scalar
  3.  
  4. wrapper = ParamsType(scalar=Scalar('int32'),
  5.                      letters=EnumType(A=1, B=2, C=3),
  6.                      digits=EnumList('ZERO', 'ONE', 'TWO'))
  7. print(wrapper.get_enum('C'))  # 3
  8. print(wrapper.get_enum('TWO'))  # 2
  9.  
  10. # You can also directly do:
  11. print(wrapper.C)
  12. print(wrapper.TWO)
  • enumfrom_alias(_alias)[source]

  • Look for a constant that has alias alias in the Theano enumeration typeswrapped into current ParamsType. Return value of the constant found,or raise an exception if either

    • there is no constant with this alias,
    • there is no constant which name is this alias, or
    • current wrapper does not contain any Theano enumeration type. Example:
  1. from theano.gof import ParamsType, EnumType, EnumList
  2. from theano.scalar import Scalar
  3.  
  4. wrapper = ParamsType(scalar=Scalar('int32'),
  5.                      letters=EnumType(A=(1, 'alpha'), B=(2, 'beta'), C=3),
  6.                      digits=EnumList(('ZERO', 'nothing'), ('ONE', 'unit'), ('TWO', 'couple')))
  7. print(wrapper.get_enum('C'))  # 3
  8. print(wrapper.get_enum('TWO'))  # 2
  9. print(wrapper.enum_from_alias('alpha')) # 1
  10. print(wrapper.enum_from_alias('nothing')) # 0
  11.  
  12. # For the following, alias 'C' is not defined, so the method looks for
  13. # a constant named 'C', and finds it.
  14. print(wrapper.enum_from_alias('C')) # 3

Note

Unlike with constant names, you can NOT access constants values directly with aliases throughParamsType (ie. you can’t write wrapper.alpha). You must use wrapper.enum_from_alias()method to do that.

  • getparams(objects, *kwargs_)[source]
  • Convenient method to extract fields values from a list of Python objects and key-value args,and wrap them into a Params object compatible with current ParamsType.

For each field defined in the current ParamsType, a value for this fieldis looked for in the given objects attributes (looking for attributes with this field name)and key-values args (looking for a key equal to this field name), from left to right(first object, then, …, then last object, then key-value args), replacing a previousfield value found with any value found in next step, so that only the last field valuefound is retained.

Fields values given in objects and kwargs must be compatible with typesassociated to corresponding fields in current ParamsType.

Example:

  1. import numpy
  2. from theano.gof import ParamsType
  3. from theano.tensor import dmatrix
  4. from theano.scalar import Scalar
  5.  
  6. class MyObject:
  7.     def __init__(self):
  8.         self.a = 10
  9.         self.b = numpy.asarray([[1, 2, 3], [4, 5, 6]])
  10.  
  11. params_type = ParamsType(a=Scalar('int32'), b=dmatrix, c=Scalar('bool'))
  12.  
  13. o = MyObject()
  14. value_for_c = False
  15.  
  16. # Value for c can't be retrieved from o, so we add a value for that field in kwargs.
  17. params = params_type.get_params(o, c=value_for_c)
  18. # params.a contains 10
  19. # params.b contains [[1, 2, 3], [4, 5, 6]]
  20. # params.c contains value_for_c
  21. print(params)
  • extended(**kwargs)[source]
  • Return a copy of current ParamsTypeextended with attributes given in kwargs.New attributes must follow same rules as inParamsType constructor.