theano.gpuarray.type – Type classes

exception theano.gpuarray.type.ContextNotDefined

class theano.gpuarray.type.GpuArrayConstant(type, data, name=None)

A constant representing a value on a certain GPU.

This supports all the operations that TensorType supports.

See also

Constant

class theano.gpuarray.type.GpuArraySharedVariable(name, type, value, strict, allow_downcast=None, container=None)

A variable representing a shared value on a certain GPU.

This supports all the operations that TensorType supports.

See also

SharedVariable

get_value(borrow=False, return_internal_type=False)

Get the non-symbolic value associated with this SharedVariable.

Parameters

• borrow (bool) – True to permit returning of an object aliased to internal memory.

• return_internal_type (bool) – True to permit the returning of an arbitrary type object used internally to store the shared variable.

• with borrow=False and return_internal_type=True does this function (Only) –

• that you actually get the internal object. (guarantee) –

• in that case, you may get different return types when using (But) –

• compute devices. (different) –

set_value(value, borrow=False)

Set the non-symbolic value associated with this SharedVariable.

Parameters

• borrow (bool) – True to use the new_value directly, potentially creating problems related to aliased memory.

• to this value will be visible to all functions using (Changes) –

• SharedVariable. (this) –

Notes

Set_value will work in-place on the GPU, if the following conditions are met:

• The destination on the GPU must be c_contiguous.

• The source is on the CPU.

• The old value must have the same dtype as the new value (which is a given for now, since only float32 is supported).

• The old and new value must have the same shape.

• The old value is being completely replaced by the new value (not partially modified, e.g. by replacing some subtensor of it).

It is also worth mentioning that, for efficient transfer to the GPU, Theano will make the new data c_contiguous. This can require an extra copy of the data on the host.

The inplace on gpu memory work when borrow is either True or False.

class theano.gpuarray.type.GpuArraySignature

class theano.gpuarray.type.GpuArrayType(dtype, broadcastable, context_name=None, name=None)

The type that represents an array on a gpu.

The dtype indicates what scalar data type the elements of variables of this type will be.

broadcastable indicates whether each dimension is broadcastable or not (to be broadcastable a dimension must always be of length 1).

The context_name is the name of the context on will values of variables of this type will be stored.

Parameters

• dtype (str) – The name of a numpy dtype

• broadcastable (tuple of bools) – A tuple that indicates both the number of dimensions (by its length) and whether those dimensions are broadcastable or not (by the boolean values).

• context_name (str) – The name of the context the that this type is attached to (default: None, which is the context specified by config.device).

• name (string, optional) – A name for the type that will be used in printouts.

dtype

Data type used for scalar elements of variables.

Type

str

broadcastable

Indicates whether the dimensions are broadcastable or not.

Type

tuple of bools

ndim

The number of dimensions

Type

int

context_name

The name of a gpu context on which variables will have their values.

Type

str

name

A string used to print the type if given.

Type

str

typecode

The gpuarray typecode for dtype

Type

int

See also

theano.gof.type.PureType

Constant

alias of GpuArrayConstant

SharedVariable

alias of GpuArraySharedVariable

Variable

alias of GpuArrayVariable

c_cleanup(name, sub)

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()

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)

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()

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)

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()

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()

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)

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_init_code()

Optional: return a list of code snippets to be inserted in module initialization.

Raises

MethodNotDefined – The subclass does not override this method.

c_lib_dirs()

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()

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_sync(name, sub)

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.

property context

The context object mapped to the type’s context_name. This is a property.

convert_variable(var)

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.

dtype_specs()

Return a tuple (python type, c type, numpy typenum) that corresponds to self.dtype.

This function is used internally as part of C code generation.

filter(data, strict=False, allow_downcast=None)

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)

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.

static values_eq(a, b, force_same_dtype=True)

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

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

static values_eq_approx(a, b, allow_remove_inf=False, allow_remove_nan=False, rtol=None, atol=None)

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.gpuarray.type.GpuArrayVariable(type, owner=None, index=None, name=None)

A variable representing a computation on a certain GPU.

This supports all the operations that TensorType supports.

See also

Variable

class theano.gpuarray.type.GpuContextType

Minimal type used for passing contexts to nodes.

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

c_cleanup(name, sub)

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()

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)

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)

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()

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()

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)

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_init_code()

Optional: return a list of code snippets to be inserted in module initialization.

Raises

MethodNotDefined – The subclass does not override this method.

filter(data, strict=False, allow_downcast=None)

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.

static values_eq(a, b)

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

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

theano.gpuarray.type.get_context(name)

Retrive the context associated with a name.

Return the context object mapped to ref that was previously register through reg_context(). Trying to get the context for an unregistered ref will raise a exception.

Parameters

name (hashable object) – Name associated with the context we want (usually a string)

theano.gpuarray.type.gpu_supported(data)

Is the following data supported on the GPU?

Currently, only complex aren’t supported.

Parameters

data (numpy.ndarray or TensorVariable) – (it must have dtype and ndim parameter)

theano.gpuarray.type.gpuarray_shared_constructor(value, name=None, strict=False, allow_downcast=None, borrow=False, broadcastable=None, target=<object object>)

SharedVariable constructor for GpuArrayType.

See theano.shared().

Target

default None The device target. As None is a valid value and we need to differentiate from the parameter notset and None, we use a notset object.

theano.gpuarray.type.list_contexts()

Return an iterable of all the registered context names.

theano.gpuarray.type.move_to_gpu(data)

Do we want to move this computation to the GPU?

Currently, we don’t move complex and scalar.

Parameters

data (numpy.ndarray or TensorVariable) – (it must have dtype and ndim parameter)

theano.gpuarray.type.reg_context(name, ctx)

Register a context by mapping it to a name.

The context must be of type GpuContext and the name can be anything hashable (but is usually a string). Only one context can be registered per name and the second registration for a given name will raise an error.

Parameters

• name (hashable object) – Name to associate the context with (usually a string)

• ctx (GpuContext) – Context instance