graph – Interface for the Theano graph
- Reference

graph – Interface for the Theano graph

Reference

Node classes (Apply, Variable) and expression graph algorithms.

class theano.gof.graph.Apply(op, inputs, outputs)[source]
An Apply instance is a node in an expression graph which representsthe application of an Op to some input Variable nodes, producing someoutput Variable nodes.

This class is typically instantiated by an Op’s makenode() function, whichis typically called by that Op’s _call() function.

An Apply instance serves as a simple structure with three importantattributes:

inputs : a list of Variable nodes that represent thearguments of the expression,
outputs : a list of Variable nodes that represent thevariable of the expression, and
op : an Op instance that determines the nature of theexpression being applied. The driver compile.function uses Apply’s inputs attribute together withVariable’s owner attribute to search the expression graph and determinewhich inputs are necessary to compute the function’s outputs.

A Linker uses the Apply instance’s op field to compute the variables.

Comparing with the Python language, an Apply instance is theano’s versionof a function call (or expression instance) whereas Op is theano’s versionof a function definition.

Parameters:

op (Op instance) –
inputs (list of Variable instances) –
outputs (list of Variable instances) –

Notes

The owner field of each output in the outputs list will be set to self.

If an output element has an owner that is neither None nor self, then aValueError exception will be raised.

clone()[source]
Duplicate this Apply instance with inputs = self.inputs.

Returns:A new Apply instance (or subclass instance) with new outputs.Return type:object

Notes

Tags are copied from self to the returned instance.

clonewith_new_inputs(_inputs, strict=True)[source]
Duplicate this Apply instance in a new graph.

Parameters:

- **inputs** – List of Variable instances to use as inputs.
- **strict** (_bool_) – If True, the type fields of all the inputs must be equalto the current ones (or compatible, for instance Tensor /GpuArray of the same dtype and broadcastable patterns,in which case they will be converted into current Type), andreturned outputs are guaranteed to have the same types asself.outputs. If False, then there’s no guarantee that theclone’s outputs will have the same types as self.outputs,and cloning may not even be possible (it depends on the Op).Returns:

An Apply instance with the same op but different outputs. Return type: object

default_output()[source]
Returns the default output for this node.

Returns:An element of self.outputs, typically self.outputs[0].Return type:Variable instance

Notes

May raise AttributeError self.op.default_output is out of range, or ifthere are multiple outputs and self.op.default_output does not exist.

nin[source]
Property – Number of inputs.
nout[source]
Property – Number of outputs.
out[source]
Alias for self.default_output().
params_type[source]
type to use for the params
run_params()[source]
Returns the params for the node, or NoParams if no params is set.

class theano.gof.graph.Constant(type, data, name=None)[source]
A Constant is a Variable with a value field that cannot bechanged at runtime.

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

Notes

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

WRITEME

clone()[source]
We clone this object, but we don’t clone the data to lower memoryrequirement. We suppose that the data will never change.
value[source]
read-only data access method

class theano.gof.graph.Node[source]
A Node in a theano graph.

Graphs contain two kinds of Nodes – Variable and Apply.Edges in the graph are not explicitly represented.Instead each Node keeps track of its parents viaVariable.owner / Apply.inputs and its childrenvia Variable.clients / Apply.outputs.

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

class theano.gof.graph.Variable(type, owner=None, index=None, name=None)[source]
A Variable is a node in an expression graph that represents avariable.

The inputs and outputs of every Apply (theano.gof.Apply) are Variable_instances. The input and output arguments to create a _function are alsoVariable instances. A Variable is like a strongly-typed variable insome other languages; each Variable contains a reference to a Type_instance that defines the kind of value the _Variable can take in acomputation.

A Variable is a container for four important attributes:

type a Type instance defining the kind of value thisVariable can have,
owner either None (for graph roots) or the Apply instanceof which self is an output,
index the integer such that owner.outputs[index] is thisvariable (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 theoutput of a symbolic computation has a reference to the Apply instance towhich it belongs (property: owner) and the position of itself in the owner’soutput list (property: index).
Variable (this base type) is typically the output of a symboliccomputation.
Constant (a subclass) which adds a default and un-replaceablevalue, 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 representsa scipy.sparse.{csc,csr}_matrix object.
GpuArrayVariable subclass of Variable that represents our object onthe GPU that is a subset of numpy.ndarray.
RandomVariable.

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

Using the Variables’ owner field and the Apply nodes’ inputs fields, one cannavigate a graph from an output all the way to the inputs. The oppositedirection is not possible until a FunctionGraph has annotated the Variableswith the clients field, ie, before the compilation process has begun aVariable 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 thisvariable.
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 typeVariable. The Variable refered to by a is also an instance ofConstant.

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

clone()[source]
Return a new Variable like self.

Returns:A new Variable instance (or subclass instance) with no owner orindex.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 theanovariables to the values to substitute for them, and it returnedthe 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 behindthe scenes. Subsequent calls to eval() on that same variablewill be fast, because the variable caches the compiled function.

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

theano.gof.graph.ancestors(variable_list, blockers=None)[source]
Return the variables that contribute to those in variable_list (inclusive).

Parameters:variable_list (list of Variable instances) – Output Variable instances from which to search backward throughowners.Returns:All input nodes, in the order found by a left-recursive depth-firstsearch started at the nodes in variable_list.Return type:list of Variable instances

theano.gof.graph.asstring(_i, o, leaf_formatter=, node_formatter=)[source]
Returns a string representation of the subgraph between i and o

Parameters:

i (list) – Input Variable s.
o (list) – Output Variable s.
leaf_formatter (callable) – Takes a Variable and returns a string to describe it.
node_formatter (callable) – Takes an Op and the list of strings corresponding to its argumentsand returns a string to describe it.Returns: Returns a string representation of the subgraph between i and o. If thesame op is used by several other ops, the first occurrence will bemarked as n -> description and all subsequent occurrenceswill be marked as n, where n is an id number (ids areattributed in an unspecified order and only exist for viewingconvenience). Return type: str

theano.gof.graph.clone(i, o, copy_inputs=True, copy_orphans=None)[source]
Copies the subgraph contained between i and o.

Parameters:

i (list) – Input Variables.
o (list) – Output Variables.
copy_inputs (bool) – If True, the inputs will be copied (defaults to True).
copy_orphans – When None, use the copy_inputs value,When True, new orphans nodes are created.When False, original orphans nodes are reused in the new graph.Returns: The inputs and outputs of that copy. Return type: object

Note

A constant, if in the i list is not an orpha. So it will becopied depending of the copy_inputs parameter. Otherwise itwill be copied depending of the copy_orphans parameter.

theano.gof.graph.cloneget_equiv(_inputs, outputs, copy_inputs=True, copy_orphans=True, memo=None)[source]
Return a dictionary that maps from Variable and Apply nodes in theoriginal graph to a new node (a clone) in a new graph.

This function works by recursively cloning inputs… rebuilding a directedgraph from the inputs up to eventually building new outputs.

Parameters:

inputs (a list of Variables) –
outputs (a list of Variables) –
copy_inputs (bool) – True means to create the cloned graph from new inputnodes (the bottom of a feed-upward graph).False means to clone a graph that is rooted at the original inputnodes.
copy_orphans – When True, new constant nodes are created. When False, originalconstant nodes are reused in the new graph.
memo (None or dict) – Optionally start with a partly-filled dictionary for the return value.If a dictionary is passed, this function will work in-place on thatdictionary and return it.

theano.gof.graph.generaltoposort(_outputs, deps, debug_print=False, compute_deps_cache=None, deps_cache=None, clients=None)[source]
WRITEME

Parameters:

deps – A python function that takes a node as input and returns its dependence.
compute_deps_cache (optional) – If provided deps_cache should also be provided. This is a function likedeps, but that also cache its results in a dict passed as deps_cache.
deps_cache (dict) – Must be used with compute_deps_cache.
clients (dict) – If a dict is passed it will be filled with a mapping of node-> clients for each node in the subgraph.

Notes

deps(i) should behave like a pure function (no funny business withinternal state).

deps(i) will be cached by this function (to be fast).

The order of the return value list is determined by the order of nodesreturned by the deps() function.

deps should be provided or can be None and the caller providescompute_deps_cache and deps_cache. The second option removes a Pythonfunction call, and allows for more specialized code, so it can befaster.

theano.gof.graph.inputs(variable_list, blockers=None)[source]
Return the inputs required to compute the given Variables.

Parameters:variable_list (list of Variable instances) – Output Variable instances from which to search backward throughowners.Returns:Input nodes with no owner, in the order found by a left-recursivedepth-first search started at the nodes in variable_list.Return type:list of Variable instances

theano.gof.graph.ioconnection_pattern(_inputs, outputs)[source]
Returns the connection pattern of a subgraph defined by giveninputs and outputs.

theano.gof.graph.iotoposort(_inputs, outputs, orderings=None, clients=None)[source]
Perform topological sort from input and output nodes

Parameters:

inputs (list or tuple of Variable instances) –
outputs (list or tuple of Apply instances) –
orderings (dict) – Key: Apply instance. Value: list of Apply instance.It is important that the value be a container with a deterministiciteration order. No sets allowed!
clients (dict) – If a dict is provided it will be filled with mappings ofnode->clients for each node in the subgraph that is sorted

theano.gof.graph.isin_ancestors(_l_node, f_node)[source]
Goes up in the graph and returns True if the apply node f_node is found.

Use a stack implementation as the vm algo.We suppose all nodes are not lazy(i.e. for IfElse we suppose all inputs are computed)

theano.gof.graph.issame_graph(_var1, var2, givens=None, debug=False)[source]
Return True iff Variables var1 and var2 perform the same computation.

By ‘performing the same computation’, we mean that they must share the samegraph, so that for instance this function will return False when comparing(x (y z)) with ((x y) z).

The current implementation is not efficient since, when possible, itverifies equality by calling two different functions that are expected toreturn the same output. The goal is to verify this assumption, toeventually get rid of one of them in the future.

Parameters:

var1 – The first Variable to compare.
var2 – The second Variable to compare.
givens – Similar to the givens argument of theano.function, it can be usedto perform substitutions in the computational graph of var1 andvar2. This argument is associated to neither var1 nor var2:substitutions may affect both graphs if the substituted variableis present in both.
debug (bool) – If True, then an exception is raised when we are in a situation wherethe equal_computations implementation cannot be called.This parameter is intended to be used in tests only, to make sure weproperly test both implementations.

Examples

var1var2givensoutputx + 1x + 1{}Truex + 1y + 1{}Falsex + 1y + 1{x: y}True

theano.gof.graph.listof_nodes(_inputs, outputs)[source]
Return the apply nodes of the graph between inputs and outputs.

theano.gof.graph.nodesconstructed(args, *kwds_)[source]
A contextmanager that is used in inherit_stack_trace and keeps trackof all the newly created varaible nodes inside an optimization. A listof new_nodes is instantiated but will be filled in a lazy manner (whenVariable.notify_construction_observers is called).

observer is the entity that updates the new_nodes list.construction_observers is a list inside Variable class and containsa list of observer functions. The observer functions insideconstruction_observers are only called when a variable node isinstantiated (where Variable.notify_construction_observers is called).When the observer function is called, a new variable node is added tothe new_nodes list.

Parameters:

new_nodes – A list of all the variable nodes that are created inside the optimization.
yields – new_nodes list.

theano.gof.graph.opas_string(_i, op, leaf_formatter=, node_formatter=)[source]
Op to return a string representation of the subgraphbetween i and o

theano.gof.graph.ops(i, o)[source]
Set of Ops contained within the subgraph between i and o

Parameters:

i (list) – Input variables.
o (list) – Output variables.Returns: The set of ops that are contained within the subgraph that liesbetween i and o, including the owners of the variables in o andintermediary ops between i and o, but not the owners of the variablesin i. Return type: object

theano.gof.graph.orphans(i, o)[source]
Extracts list of variables within input and output nodesvia dfs travesal and returns the orphans among them

Parameters:

i (list) – Input Variables.
o (list) – Output Variables.Returns: The set of Variables which one or more Variables in o depend on but areneither in i nor in the subgraph that lies between i and o. Return type: object

Examples

orphans([x], [(x+y).out]) => [y]

theano.gof.graph.stacksearch(_start, expand, mode='bfs', build_inv=False)[source]
Search through a graph, either breadth- or depth-first.

Parameters:

start (deque) – Search from these nodes.
expand (callable) – When we get to a node, add expand(node) to the list of nodes to visit.This function should return a list, or None.
mode (string) – ‘bfs’ or ‘dfs’ for breath first search or depth first search.Returns: The list of nodes in order of traversal. Return type: list of Variable or Apply instances (depends on expend)

Notes

A node will appear at most once in the return value, even if itappears multiple times in the start parameter.

Postcondition:every element of start is transferred to the returned list.Postcondition:start is empty.

theano.gof.graph.variables(i, o)[source]
Extracts list of variables within input and output nodes via dfs travesal

Parameters:

i (list) – Input variables.
o (list) – Output variables.Returns: The set of Variables that are involved in the subgraph that liesbetween i and o. This includes i, o, orphans(i, o) and all values ofall intermediary steps from i to o. Return type: object

theano.gof.graph.variablesand_orphans(_i, o)[source]
Extract list of variables between i and o nodes viadfs traversal and chooses the orphans among them

Parameters:

i (list) – Input variables.
o (list) – Output variables.

theano.gof.graph.viewroots(_r)[source]
Utility function that returns the leaves of a search throughconsecutive view_map()s.

WRITEME