`type` – Interface for types of variables¶

Reference¶

WRITEME

Defines the Type class.

class theano.gof.type.CDataType(ctype, freefunc=None, headers=(), header_dirs=(), libraries=(), lib_dirs=(), compile_args=(), extra_support_code='', version=None)[source]¶

Represents opaque C data to be passed around. The intent is to ease passing arbitrary data between ops C code.

The constructor builds a type made to represent a C pointer in theano.

Parameters

ctype – The type of the pointer (complete with the *).
freefunc – A function to call to free the pointer. This function must have a void return and take a single pointer argument.
version – The version to use in Theano cache system.

Constant[source]¶: alias of CDataTypeConstant

c_cleanup(name, sub)[source]¶

Return C code to clean up after c_extract.

This returns C code that should deallocate whatever c_extract allocated or decrease the reference counts. Do not decrease py_%(name)s’s reference count.

WRITEME

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

c_code_cache_version()[source]¶

Return a tuple of integers indicating the version of this Type.

An empty tuple indicates an ‘unversioned’ Type that will not be cached between processes.

The cache mechanism may erase cached modules that have been superceded by newer versions. See ModuleCache for details.

c_compile_args()[source]¶

Optional: Return a list of compile args recommended to compile the code returned by other methods in this class.

Example

return [‘-ffast-math’]

Compiler arguments related to headers, libraries and search paths should be provided via the functions c_headers, c_libraries, c_header_dirs, and c_lib_dirs.

Raises: MethodNotDefined – Subclass does not implement this method.

c_declare(name, sub, check_input=True)[source]¶

Required: Return c code to declare variables that will be instantiated by c_extract.

Parameters

name (str) – The name of the PyObject * pointer that will the value for this Type
sub (dict string -> string) – a dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Notes

It is important to include the name inside of variables which are declared here, so that name collisions do not occur in the source file that is generated.

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted to create class variables for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable declaration fail? Is it even allowed to?

Raises: MethodNotDefined – Subclass does not implement this method.

Examples

c_extract(name, sub, check_input=True)[source]¶

Required: Return c code to extract a PyObject * instance.

The code returned from this function must be templated using %(name)s, representing the name that the caller wants to call this Variable. The Python object self.data is in a variable called “py_%(name)s” and this code must set the variables declared by c_declare to something representative of py_%(name)s. If the data is improper, set an appropriate exception and insert “%(fail)s”.

TODO: Point out that template filling (via sub) is now performed: by this function. –jpt

Parameters

name (str) – The name of the PyObject * pointer that will store the value for this Type.
sub (dict string -> string) – A dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Raises

MethodNotDefined – Subclass does not implement this method.

Examples

c_header_dirs()[source]¶

Optional: Return a list of header search paths required by code returned by this class.

Examples

return [‘/usr/local/include’, ‘/opt/weirdpath/src/include’]

Provides search paths for headers, in addition to those in any relevant environment variables.

Hint: for unix compilers, these are the things that get ‘-I’ prefixed in the compiler cmdline.

Raises: MethodNotDefined – Subclass does not implement this method.

c_headers()[source]¶

Optional: Return a list of header files required by code returned by this class.

Examples

return [‘<iostream>’, ‘<math.h>’, ‘/full/path/to/header.h’]

These strings will be prefixed with “#include ” and inserted at the beginning of the c source code.

Strings in this list that start neither with ‘<’ nor ‘”’ will be enclosed in double-quotes.

Raises: MethodNotDefined – Subclass does not implement this method.

c_init(name, sub)[source]¶

Required: Return c code to initialize the variables that were declared by self.c_declare().

Notes

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted in a class constructor for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable initialization fail? Is it even allowed to?

Examples

c_lib_dirs()[source]¶

Optional: Return a list of library search paths required by code returned by this class.

Examples

return [‘/usr/local/lib’, ‘/opt/weirdpath/build/libs’].

Provides search paths for libraries, in addition to those in any relevant environment variables (e.g. LD_LIBRARY_PATH).

Hint: for unix compilers, these are the things that get ‘-L’ prefixed in the compiler cmdline.

Raises: MethodNotDefined – Subclass does not implement this method.

c_libraries()[source]¶

Optional: Return a list of libraries required by code returned by this class.

Examples

return [‘gsl’, ‘gslcblas’, ‘m’, ‘fftw3’, ‘g2c’].

The compiler will search the directories specified by the environment variable LD_LIBRARY_PATH in addition to any returned by c_lib_dirs.

Hint: for unix compilers, these are the things that get ‘-l’ prefixed in the compiler cmdline.

Raises: MethodNotDefined – Subclass does not implement this method.

c_support_code()[source]¶

Optional: Return utility code (a string, or a list of strings) for use by a Variable or Op to be included at global scope prior to the rest of the code for this class.

QUESTION: How many times will this support code be emitted for a graph with many instances of the same type?

Raises: MethodNotDefined – Subclass does not implement this method.

c_sync(name, sub)[source]¶

Required: Return C code to pack C types back into a PyObject.

The code returned from this function must be templated using “%(name)s”, representing the name that the caller wants to call this Variable. The returned code may set “py_%(name)s” to a PyObject* and that PyObject* will be accessible from Python via variable.data. Do not forget to adjust reference counts if “py_%(name)s” is changed from its original value.

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

filter(data, strict=False, allow_downcast=None)[source]¶

Required: Return data or an appropriately wrapped/converted data.

Subclass implementation should raise a TypeError exception if the data is not of an acceptable type.

If strict is True, the data returned must be the same as the data passed as an argument. If it is False, and allow_downcast is True, filter may cast it to an appropriate type. If allow_downcast is False, filter may only upcast it, not lose precision. If allow_downcast is None (default), the behaviour can be Type-dependent, but for now it means only Python floats can be downcasted, and only to floatX scalars.

Raises: MethodNotDefined – Subclass doesn’t implement this function.

make_value(ptr)[source]¶

Make a value of this type.

Parameters: ptr (int) – Integer representation of a valid pointer value

class theano.gof.type.CDataTypeConstant(type, data, name=None)[source]¶

class theano.gof.type.CEnumType(*args, **kwargs)[source]¶

Inherit from:

EnumList

Op parameter class that allows to create enumeration of constant values that represent C-defined constants.

Constant should have same names as in C.

In Python, constants will have arbitrary-defined values. They should be used only for choices, not for its values.

In C code, the real values defined in C will be used. They could be used either for choices or for its real values.

Like EnumList, you can also define the C type and a C name for the op param. Default C type is int.

enum = CEnumType('CONSTANT_CNAME_1', 'CONSTANT_CNAME_2', 'CONSTANT_CNAME_3', ctype='long')

Like EnumList, you can also add an alias to a constant, with same syntax as in EnumList.

See test theano.gof.tests.test_types.TestEnumTypes.test_op_with_cenumtype() for a working example.

Note

Be sure C constants are available in your C code. If they come from a C header, consider implementing c_headers() and c_header_dirs() in the Op class where you use CEnumType as op parameter type.

c_code_cache_version()[source]¶

Return a tuple of integers indicating the version of this Type.

An empty tuple indicates an ‘unversioned’ Type that will not be cached between processes.

The cache mechanism may erase cached modules that have been superceded by newer versions. See ModuleCache for details.

c_extract(name, sub, check_input=True)[source]¶

Required: Return c code to extract a PyObject * instance.

The code returned from this function must be templated using %(name)s, representing the name that the caller wants to call this Variable. The Python object self.data is in a variable called “py_%(name)s” and this code must set the variables declared by c_declare to something representative of py_%(name)s. If the data is improper, set an appropriate exception and insert “%(fail)s”.

TODO: Point out that template filling (via sub) is now performed: by this function. –jpt

Parameters

name (str) – The name of the PyObject * pointer that will store the value for this Type.
sub (dict string -> string) – A dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Raises

MethodNotDefined – Subclass does not implement this method.

Examples

c_support_code()[source]¶

Optional: Return utility code (a string, or a list of strings) for use by a Variable or Op to be included at global scope prior to the rest of the code for this class.

QUESTION: How many times will this support code be emitted for a graph with many instances of the same type?

Raises: MethodNotDefined – Subclass does not implement this method.

class theano.gof.type.CLinkerType[source]¶

Interface specification for Types that can be arguments to a CLinkerOp.

A CLinkerType instance is mainly responsible for providing the C code that interfaces python objects with a C CLinkerOp implementation.

See WRITEME for a general overview of code generation by CLinker.

c_cleanup(name, sub)[source]¶

Return C code to clean up after c_extract.

This returns C code that should deallocate whatever c_extract allocated or decrease the reference counts. Do not decrease py_%(name)s’s reference count.

WRITEME

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

c_code_cache_version()[source]¶

Return a tuple of integers indicating the version of this Type.

An empty tuple indicates an ‘unversioned’ Type that will not be cached between processes.

The cache mechanism may erase cached modules that have been superceded by newer versions. See ModuleCache for details.

c_declare(name, sub, check_input=True)[source]¶

Required: Return c code to declare variables that will be instantiated by c_extract.

Parameters

name (str) – The name of the PyObject * pointer that will the value for this Type
sub (dict string -> string) – a dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Notes

It is important to include the name inside of variables which are declared here, so that name collisions do not occur in the source file that is generated.

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted to create class variables for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable declaration fail? Is it even allowed to?

Raises: MethodNotDefined – Subclass does not implement this method.

Examples

c_element_type()[source]¶

Optional: Return the name of the primitive C type of items into variables handled by this type.

e.g:

For TensorType(dtype='int64', ...): should return "npy_int64".

For GpuArrayType(dtype='int32', ...): should return "ga_int".

c_extract(name, sub, check_input=True)[source]¶

Required: Return c code to extract a PyObject * instance.

The code returned from this function must be templated using %(name)s, representing the name that the caller wants to call this Variable. The Python object self.data is in a variable called “py_%(name)s” and this code must set the variables declared by c_declare to something representative of py_%(name)s. If the data is improper, set an appropriate exception and insert “%(fail)s”.

TODO: Point out that template filling (via sub) is now performed: by this function. –jpt

Parameters

name (str) – The name of the PyObject * pointer that will store the value for this Type.
sub (dict string -> string) – A dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Raises

MethodNotDefined – Subclass does not implement this method.

Examples

c_extract_out(name, sub, check_input=True)[source]¶

Optional: C code to extract a PyObject * instance.

Unlike c_extract, c_extract_out has to accept Py_None, meaning that the variable should be left uninitialized.

c_init(name, sub)[source]¶

Required: Return c code to initialize the variables that were declared by self.c_declare().

Notes

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted in a class constructor for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable initialization fail? Is it even allowed to?

Examples

c_is_simple()[source]¶

Optional: Return True for small or builtin C types.

A hint to tell the compiler that this type is a builtin C type or a small struct and that its memory footprint is negligible. Simple objects may be passed on the stack.

c_literal(data)[source]¶

Optional: WRITEME

Parameters: data (WRITEME) – WRITEME
Raises: MethodNotDefined – Subclass does not implement this method.

c_sync(name, sub)[source]¶

Required: Return C code to pack C types back into a PyObject.

The code returned from this function must be templated using “%(name)s”, representing the name that the caller wants to call this Variable. The returned code may set “py_%(name)s” to a PyObject* and that PyObject* will be accessible from Python via variable.data. Do not forget to adjust reference counts if “py_%(name)s” is changed from its original value.

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

class theano.gof.type.EnumList(*args, **kwargs)[source]¶

Inherit from:

EnumType

Op parameter class that allows to create enumeration of constant values. Same as EnumType, but automatically gives an unique integer value for each constant in a list of constants names (constant at index i in the list will receive value i, with i from 0 to len(constants) - 1).

Example:

enum = EnumList('CONSTANT_1', 'CONSTANT_2', 'CONSTANT_3', 'CONSTANT_4', 'CONSTANT_5')
print (enum.CONSTANT_1, enum.CONSTANT_2, enum.CONSTANT_3, enum.CONSTANT_4, enum.CONSTANT_5)
# will print: 0 1 2 3 4

Like EnumType, you can also define the C type and a C name for the op param. Default C type is int:

enum = EnumList('CONSTANT_1', 'CONSTANT_2', 'CONSTANT_3', 'CONSTANT_4', ctype='unsigned int')

Like EnumType, you can also add an alias to a constant, by replacing the only constant name (e.g. 'CONSTANT_NAME') by a couple with constant name first and constant alias second (e.g. ('CONSTANT_NAME', 'constant_alias')).

enum = EnumList(('A', 'alpha'), ('B', 'beta'), 'C', 'D', 'E', 'F', ('G', 'gamma'))

See test class theano.gof.tests.test_types.TestOpEnumList for a working example.

class theano.gof.type.EnumType(**kwargs)[source]¶

Main subclasses:

EnumList
CEnumType

Op parameter class that allows to create enumerations of constant values.

Constants are available as object attributes in Python code and as macro-defined constants in C code.

Constants can be floating values, integers, or booleans (automatically converted to integers).

Constants name must start with a capital letter and contain capital letters, underscores or digits.

A constant can have an alias, and then be available through both constant name and constant alias.

Example

enum = EnumType(CONSTANT_1=1, CONSTANT_2=2.5, CONSTANT_3=False, CONSTANT_4=True)
print (enum.CONSTANT_1, enum.CONSTANT_2, enum.CONSTANT_3, enum.CONSTANT_4)
# will print 1 2.5 0 1

In C code:

int constant_1 = CONSTANT_1;
double constant_2 = CONSTANT_2;
int constant_3 = CONSTANT_3; // constant_3 == 0
int constant_4 = CONSTANT_4; // constant_4 == 1

You can also specify a C type for the op param. Default C type is double.

enum = EnumType(CONSTANT_1=0, CONSTANT_2=1, CONSTANT_3=2, ctype='size_t')
# In C code, the Op param will then be a ``size_t``.

Note

You can also specify a C name (cname) or the current enumeration. This C name may be used to name functions related to that specific enumeration, e.g. for debugging purposes. Default C name is the C type (with any sequence of spaces replaced with an underscore). If you want to debug and your C type is quite generic (e.g. int or double), we recommend you specify a C name.

C name must be a valid C identifier.

enum = EnumType(CONSTANT_1=0, CONSTANT_2=1, CONSTANT_3=2,
                ctype='size_t', cname='MyEnumName')

Example with aliases

When creating an enum, you can give some aliases to specific constants while keeping other constants without aliases. An alias must be a string, and there is currently no string format constraints.

To give an alias to a constant in the EnumType constructor, use the following key-value syntax:

constant_name=(constant_alias, constant_value)

You can then retrieve a constant from an alias with method EnumType.fromalias().

Aliases are intended to be used in Python code only (only constants names are available in C code). Especially, an alias will be recognized by Enumtype.filter() method with non-strict filtering, allowing a maximum flexibility for converting strings to numeric constants available in Python and C code.

from theano.gof import EnumType

# You can remark that constant 'C' does not have an alias.
enum = EnumType(A=('alpha', 1), B=('beta', 2), C=3, D=('delta', 4))

# Constants are all directly available by name.
print(enum.A, enum.B, enum.C, enum.D)

# But we can also now get some constants by alias.
a = enum.fromalias('alpha')
b = enum.fromalias('beta')
d = enum.fromalias('delta')

# If method fromalias() receives an unknown alias,
# it will looks for a constant with this alias
# as exact constant name.
c = enum.fromalias('C') # will get enum.C

# An alias defined in an EnumType will be correctly converted with non-strict filtering.
value = enum.filter('delta', strict=False)
# value now contaisn enum.D, ie. 4.

Note

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

c_cleanup(name, sub)[source]¶

Return C code to clean up after c_extract.

This returns C code that should deallocate whatever c_extract allocated or decrease the reference counts. Do not decrease py_%(name)s’s reference count.

WRITEME

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

c_code_cache_version()[source]¶

Return a tuple of integers indicating the version of this Type.

An empty tuple indicates an ‘unversioned’ Type that will not be cached between processes.

The cache mechanism may erase cached modules that have been superceded by newer versions. See ModuleCache for details.

c_declare(name, sub, check_input=True)[source]¶

Required: Return c code to declare variables that will be instantiated by c_extract.

Parameters

name (str) – The name of the PyObject * pointer that will the value for this Type
sub (dict string -> string) – a dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Notes

It is important to include the name inside of variables which are declared here, so that name collisions do not occur in the source file that is generated.

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted to create class variables for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable declaration fail? Is it even allowed to?

Raises: MethodNotDefined – Subclass does not implement this method.

Examples

c_extract(name, sub, check_input=True)[source]¶

Required: Return c code to extract a PyObject * instance.

The code returned from this function must be templated using %(name)s, representing the name that the caller wants to call this Variable. The Python object self.data is in a variable called “py_%(name)s” and this code must set the variables declared by c_declare to something representative of py_%(name)s. If the data is improper, set an appropriate exception and insert “%(fail)s”.

TODO: Point out that template filling (via sub) is now performed: by this function. –jpt

Parameters

name (str) – The name of the PyObject * pointer that will store the value for this Type.
sub (dict string -> string) – A dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Raises

MethodNotDefined – Subclass does not implement this method.

Examples

c_init(name, sub)[source]¶

Required: Return c code to initialize the variables that were declared by self.c_declare().

Notes

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted in a class constructor for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable initialization fail? Is it even allowed to?

Examples

c_support_code()[source]¶

Optional: Return utility code (a string, or a list of strings) for use by a Variable or Op to be included at global scope prior to the rest of the code for this class.

QUESTION: How many times will this support code be emitted for a graph with many instances of the same type?

Raises: MethodNotDefined – Subclass does not implement this method.

c_to_string()[source]¶

Return code for a C function that will convert an enumeration value to a string representation. The function prototype is:

int theano_enum_to_string_<cname>(<ctype> value, char* output_string);

Where ctype and cname are the C type and the C name of current Theano enumeration.

output_string should be large enough to contain the longest name in this enumeration.

If given value is unknown, the C function sets a Python ValueError exception and returns a non-zero.

This C function may be useful to retrieve some runtime informations. It is available in C code when theano flag config.cmodule.debug is set to True.

filter(data, strict=False, allow_downcast=None)[source]¶

Required: Return data or an appropriately wrapped/converted data.

Subclass implementation should raise a TypeError exception if the data is not of an acceptable type.

If strict is True, the data returned must be the same as the data passed as an argument. If it is False, and allow_downcast is True, filter may cast it to an appropriate type. If allow_downcast is False, filter may only upcast it, not lose precision. If allow_downcast is None (default), the behaviour can be Type-dependent, but for now it means only Python floats can be downcasted, and only to floatX scalars.

Raises: MethodNotDefined – Subclass doesn’t implement this function.

fromalias(alias)[source]¶: Get a constant value by its alias. If there is not such alias in this enum, look for a constant with this alias as constant name.

get_aliases()[source]¶: Return the sorted tuple of all aliases in this enumeration.

has_alias(alias)[source]¶: return True if and only if this enum has this alias.

values_eq(a, b)[source]¶

Return True if a and b can be considered exactly equal.

a and b are assumed to be valid values of this Type.

values_eq_approx(a, b)[source]¶

Return True if a and b can be considered approximately equal.

This function is used by theano debugging tools to decide whether two values are equivalent, admitting a certain amount of numerical instability. For example, for floating-point numbers this function should be an approximate comparison.

By default, this does an exact comparison.

Parameters

a – A potential value for a Variable of this Type.
b – A potential value for a Variable of this Type.

Returns

Return type

bool

class theano.gof.type.Generic[source]¶

Represents a generic Python object.

This class implements the PureType and CLinkerType interfaces for generic PyObject instances.

EXAMPLE of what this means, or when you would use this type.

WRITEME

c_cleanup(name, sub)[source]¶

Return C code to clean up after c_extract.

This returns C code that should deallocate whatever c_extract allocated or decrease the reference counts. Do not decrease py_%(name)s’s reference count.

WRITEME

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

c_code_cache_version()[source]¶

Return a tuple of integers indicating the version of this Type.

An empty tuple indicates an ‘unversioned’ Type that will not be cached between processes.

The cache mechanism may erase cached modules that have been superceded by newer versions. See ModuleCache for details.

c_declare(name, sub, check_input=True)[source]¶

Required: Return c code to declare variables that will be instantiated by c_extract.

Parameters

name (str) – The name of the PyObject * pointer that will the value for this Type
sub (dict string -> string) – a dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Notes

It is important to include the name inside of variables which are declared here, so that name collisions do not occur in the source file that is generated.

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted to create class variables for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable declaration fail? Is it even allowed to?

Raises: MethodNotDefined – Subclass does not implement this method.

Examples

c_extract(name, sub, check_input=True)[source]¶

Required: Return c code to extract a PyObject * instance.

The code returned from this function must be templated using %(name)s, representing the name that the caller wants to call this Variable. The Python object self.data is in a variable called “py_%(name)s” and this code must set the variables declared by c_declare to something representative of py_%(name)s. If the data is improper, set an appropriate exception and insert “%(fail)s”.

TODO: Point out that template filling (via sub) is now performed: by this function. –jpt

Parameters

name (str) – The name of the PyObject * pointer that will store the value for this Type.
sub (dict string -> string) – A dictionary of special codes. Most importantly sub[‘fail’]. See CLinker for more info on sub and fail.

Raises

MethodNotDefined – Subclass does not implement this method.

Examples

c_init(name, sub)[source]¶

Required: Return c code to initialize the variables that were declared by self.c_declare().

Notes

The variable called name is not necessarily defined yet where this code is inserted. This code might be inserted in a class constructor for example, whereas the variable name might only exist inside certain functions in that class.

TODO: Why should variable initialization fail? Is it even allowed to?

Examples

c_sync(name, sub)[source]¶

Required: Return C code to pack C types back into a PyObject.

The code returned from this function must be templated using “%(name)s”, representing the name that the caller wants to call this Variable. The returned code may set “py_%(name)s” to a PyObject* and that PyObject* will be accessible from Python via variable.data. Do not forget to adjust reference counts if “py_%(name)s” is changed from its original value.

Parameters

name (WRITEME) – WRITEME
sub (WRITEME) – WRITEME

Raises

MethodNotDefined – Subclass does not implement this method.

filter(data, strict=False, allow_downcast=None)[source]¶

Required: Return data or an appropriately wrapped/converted data.

Subclass implementation should raise a TypeError exception if the data is not of an acceptable type.

If strict is True, the data returned must be the same as the data passed as an argument. If it is False, and allow_downcast is True, filter may cast it to an appropriate type. If allow_downcast is False, filter may only upcast it, not lose precision. If allow_downcast is None (default), the behaviour can be Type-dependent, but for now it means only Python floats can be downcasted, and only to floatX scalars.

Raises: MethodNotDefined – Subclass doesn’t implement this function.

is_valid_value(a)[source]¶: Required: Return True for any python object a that would be a legal value for a Variable of this Type.

class theano.gof.type.PureType[source]¶

Interface specification for variable type instances.

A Type instance is mainly responsible for two things:

creating Variable instances (conventionally, __call__ does this), and
filtering a value assigned to a Variable so that the value conforms to restrictions imposed by the type (also known as casting, this is done by filter).

class Constant(type, data, name=None)[source]¶

A Constant is a Variable with a value field that cannot be changed at runtime.

Constant nodes make eligible numerous optimizations: constant inlining in C code, constant folding, etc.

Notes

The data field is filtered by what is provided in the constructor for the Constant’s type field.

WRITEME

clone()[source]¶: We clone this object, but we don’t clone the data to lower memory requirement. We suppose that the data will never change.

property value[source]¶: read-only data access method

class Variable(type, owner=None, index=None, name=None)[source]¶

A Variable is a node in an expression graph that represents a variable.

The inputs and outputs of every Apply (theano.gof.Apply) are Variable instances. The input and output arguments to create a function are also Variable instances. A Variable is like a strongly-typed variable in some other languages; each Variable contains a reference to a Type instance that defines the kind of value the Variable can take in a computation.

A Variable is a container for four important attributes:

type a Type instance defining the kind of value this Variable can have,
owner either None (for graph roots) or the Apply instance of which self is an output,
index the integer such that owner.outputs[index] is this_variable (ignored if owner is None),
name a string to use in pretty-printing and debugging.

There are a few kinds of Variables to be aware of: A Variable which is the output of a symbolic computation has a reference to the Apply instance to which it belongs (property: owner) and the position of itself in the owner’s output list (property: index).

Variable (this base type) is typically the output of a symbolic computation.
Constant (a subclass) which adds a default and un-replaceable value, and requires that owner is None.
TensorVariable subclass of Variable that represents a numpy.ndarray
object.
TensorSharedVariable Shared version of TensorVariable.
SparseVariable subclass of Variable that represents a scipy.sparse.{csc,csr}_matrix object.
GpuArrayVariable subclass of Variable that represents our object on the GPU that is a subset of numpy.ndarray.
RandomVariable.

A Variable which is the output of a symbolic computation will have an owner not equal to None.

Using the Variables’ owner field and the Apply nodes’ inputs fields, one can navigate a graph from an output all the way to the inputs. The opposite direction is not possible until a FunctionGraph has annotated the Variables with the clients field, ie, before the compilation process has begun a Variable does not know which Apply nodes take it as input.

Parameters

type (a Type instance) – The type governs the kind of data that can be associated with this variable.
owner (None or Apply instance) – The Apply instance which computes the value for this variable.
index (None or int) – The position of this Variable in owner.outputs.
name (None or str) – A string for pretty-printing and debugging.

Examples

import theano
from theano import tensor

a = tensor.constant(1.5)        # declare a symbolic constant
b = tensor.fscalar()            # declare a symbolic floating-point scalar

c = a + b                       # create a simple expression

f = theano.function([b], [c])   # this works because a has a value associated with it already

assert 4.0 == f(2.5)            # bind 2.5 to an internal copy of b and evaluate an internal c

theano.function([a], [c])       # compilation error because b (required by c) is undefined

theano.function([a,b], [c])     # compilation error because a is constant, it can't be an input

d = tensor.value(1.5)           # create a value similar to the constant 'a'
e = d + b
theano.function([d,b], [e])     # this works.  d's default value of 1.5 is ignored.

The python variables a,b,c all refer to instances of type Variable. The Variable referred to by a is also an instance of Constant.

compile.function uses each Apply instance’s inputs attribute together with each Variable’s owner field to determine which inputs are necessary to compute the function’s outputs.

clone()[source]¶

Return a new Variable like self.

Returns: A new Variable instance (or subclass instance) with no owner or index.
Return type: Variable instance

Notes

Tags are copied to the returned instance.

Name is copied to the returned instance.

eval(inputs_to_values=None)[source]¶

Evaluates this variable.

Parameters: inputs_to_values – A dictionary mapping theano Variables to values.

Examples

>>> import numpy as np
>>> import theano.tensor as T
>>> x = T.dscalar('x')
>>> y = T.dscalar('y')
>>> z = x + y
>>> np.allclose(z.eval({x : 16.3, y : 12.1}), 28.4)
True

We passed eval() a dictionary mapping symbolic theano variables to the values to substitute for them, and it returned the numerical value of the expression.

Notes

eval will be slow the first time you call it on a variable – it needs to call function() to compile the expression behind the scenes. Subsequent calls to eval() on that same variable will be fast, because the variable caches the compiled function.

This way of computing has more overhead than a normal Theano function, so don’t use it too much in real scripts.

get_parents()[source]¶: Return a list of the parents of this node. Should return a copy–i.e., modifying the return value should not modify the graph structure.

convert_variable(var)[source]¶

Patch variable so that its type will match self, if possible.

If the variable can’t be converted, this should return None.

The conversion can only happen if the following implication is true for all possible val.

self.is_valid_value(val) => var.type.is_valid_value(val)

For the majority of types this means that you can only have non-broadcastable dimensions become broadcastable and not the inverse.

The default is to not convert anything which is always safe.

filter(data, strict=False, allow_downcast=None)[source]¶

Required: Return data or an appropriately wrapped/converted data.

Subclass implementation should raise a TypeError exception if the data is not of an acceptable type.

If strict is True, the data returned must be the same as the data passed as an argument. If it is False, and allow_downcast is True, filter may cast it to an appropriate type. If allow_downcast is False, filter may only upcast it, not lose precision. If allow_downcast is None (default), the behaviour can be Type-dependent, but for now it means only Python floats can be downcasted, and only to floatX scalars.

Raises: MethodNotDefined – Subclass doesn’t implement this function.

filter_variable(other, allow_convert=True)[source]¶

Convert a symbolic variable into this Type, if compatible.

For the moment, the only Types compatible with one another are TensorType and GpuArrayType, provided they have the same number of dimensions, same broadcasting pattern, and same dtype.

If Types are not compatible, a TypeError should be raised.

is_valid_value(a)[source]¶: Required: Return True for any python object a that would be a legal value for a Variable of this Type.

make_variable(name=None)[source]¶

Return a new Variable instance of Type self.

Parameters: name (None or str) – A pretty string for printing and debugging.

value_validity_msg(a)[source]¶: Optional: Return a message explaining the output of is_valid_value.

values_eq(a, b)[source]¶

Return True if a and b can be considered exactly equal.

a and b are assumed to be valid values of this Type.

values_eq_approx(a, b)[source]¶

Return True if a and b can be considered approximately equal.

This function is used by theano debugging tools to decide whether two values are equivalent, admitting a certain amount of numerical instability. For example, for floating-point numbers this function should be an approximate comparison.

By default, this does an exact comparison.

Parameters

a – A potential value for a Variable of this Type.
b – A potential value for a Variable of this Type.

Returns

Return type

bool

class theano.gof.type.SingletonType[source]¶

Convenient Base class for a Type subclass with no attributes.

It saves having to implement __eq__ and __hash__.

class theano.gof.type.Type[source]¶

Convenience wrapper combining PureType and CLinkerType.

Theano comes with several subclasses of such as:

Generic: for any python type
TensorType: for numpy.ndarray
SparseType: for scipy.sparse

But you are encouraged to write your own, as described in WRITEME.

The following code illustrates the use of a Type instance, here tensor.fvector:

# Declare a symbolic floating-point vector using __call__
b = tensor.fvector()

# Create a second Variable with the same Type instance
c = tensor.fvector()

Whenever you create a symbolic variable in theano (technically, Variable) it will contain a reference to a Type instance. That reference is typically constant during the lifetime of the Variable. Many variables can refer to a single Type instance, as do b and c above. The Type instance defines the kind of value which might end up in that variable when executing a Function. In this sense, theano is like a strongly-typed language because the types are included in the graph before the values. In our example above, b is a Variable which is guaranteed to correspond to a numpy.ndarray of rank 1 when we try to do some computations with it.

Many Op instances will raise an exception if they are applied to inputs with incorrect types. Type references are also useful to do type-checking in pattern-based optimizations.

type – Interface for types of variables¶

Reference¶

`type` – Interface for types of variables¶