fg – Graph Container [doc TODO]

FunctionGraph

class theano.gof.FunctionGraph(inputs, outputs, features=None, clone=True, update_mapping=None)

A FunctionGraph represents a subgraph bound by a set of input variables and a set of output variables, ie a subgraph that specifies a theano function. The inputs list should contain all the inputs on which the outputs depend. Variables of type Constant are not counted as inputs.

The FunctionGraph supports the replace operation which allows to replace a variable in the subgraph by another, e.g. replace (x + x).out by (2 * x).out. This is the basis for optimization in theano.

This class is also responsible for verifying that a graph is valid (ie, all the dtypes and broadcast patterns are compatible with the way the the Variables are used) and for annotating the Variables with a .clients field that specifies which Apply nodes use the variable. The .clients field combined with the .owner field and the Apply nodes’ .inputs field allows the graph to be traversed in both directions.

It can also be extended with new features using FunctionGraph.attach_feature(<toolbox.Feature instance>). See toolbox.Feature for event types and documentation. Extra features allow the FunctionGraph to verify new properties of a graph as it is optimized. # TODO: are there other things features can do to the fgraph?

Historically, the FunctionGraph was called an Env. Keep this in mind while reading out-of-date documentation, e-mail support threads, etc.

The constructor creates a FunctionGraph which operates on the subgraph bound by the inputs and outputs sets.

This class keeps a pointer to the inputs and outputs, and also modifies them.

#TODO: document what variables are[not] set in the FunctionGraph when a feature is added via the constructor. How constructed is the FunctionGraph?

Parameters

• inputs – Inputs nodes of the graph, usually declared by the user.

• outputs – Outputs nodes of the graph.

• clone – If true, we will clone the graph. This is useful to remove the constant cache problem.

Notes

The intermediate nodes between ‘inputs’ and ‘outputs’ are not explicitely passed.

*TODO*

Note

FunctionGraph(inputs, outputs) clones the inputs by default. To avoid this behavior, add the parameter clone=False. This is needed as we do not want cached constants in fgraph.

attach_feature(feature)

Adds a gof.toolbox.Feature to this function_graph and triggers its on_attach callback.

change_input(node, i, new_r, reason=None)

Changes node.inputs[i] to new_r.

new_r.type == old_r.type must be True, where old_r is the current value of node.inputs[i] which we want to replace.

For each feature that has a ‘on_change_input’ method, calls: feature.on_change_input(function_graph, node, i, old_r, new_r, reason)

check_integrity()

Call this for a diagnosis if things go awry.

clients(r)

Set of all the (node, i) pairs such that node.inputs[i] is r. Told differently, a list of (node,i) such that each node have r as input at index i.

clone(check_integrity=True)

Clone the graph and get a memo( a dict )that map old node to new node

clone_get_equiv(check_integrity=True, attach_feature=True)

Clone the graph and get a dict that maps old nodes to new ones

Parameters:

check_integrity: bool

Whether to check integrity. Default is True.

attach_feature: bool

Whether to attach feature of origin graph to cloned graph. Default is True.

Returns:

e: FunctionGraph

Cloned fgraph. Every node in cloned graph is cloned.

equiv: dict

A dict that map old node to new node.

collect_callbacks(name, *args)

Collects callbacks

Returns a dictionary d such that d[feature] == getattr(feature, name)(*args) For each feature which has a method called after name.

disown()

Cleans up all of this FunctionGraph’s nodes and variables so they are not associated with this FunctionGraph anymore.

The FunctionGraph should not be used anymore after disown is called.

execute_callbacks(name, *args, **kwargs)

Execute callbacks

Calls getattr(feature, name)(*args) for each feature which has a method called after name.

orderings()

Return dict d s.t. d[node] is a list of nodes that must be evaluated before node itself can be evaluated.

This is used primarily by the destroy_handler feature to ensure that all clients of any destroyed inputs have already computed their outputs.

Notes

This only calls the orderings() fct on all features. It does not take care of computing dependencies by itself.

remove_feature(feature)

Removes the feature from the graph.

Calls feature.on_detach(function_graph) if an on_detach method is defined.

replace(r, new_r, reason=None, verbose=None)

This is the main interface to manipulate the subgraph in FunctionGraph. For every node that uses r as input, makes it use new_r instead.

replace_all(pairs, reason=None)

For every node that uses r as input, makes it use new_r instead

toposort()

Toposort

Return an ordering of the graph’s Apply nodes such that

• All the nodes of the inputs of a node are before that node.

• Satisfies the orderings provided by each feature that has an ‘orderings’ method.

If a feature has an ‘orderings’ method, it will be called with this FunctionGraph as sole argument. It should return a dictionary of {node: predecessors} where predecessors is a list of nodes that should be computed before the key node.

FunctionGraph Features

class theano.gof.toolbox.Feature

Base class for FunctionGraph extensions.

A Feature is an object with several callbacks that are triggered by various operations on FunctionGraphs. It can be used to enforce graph properties at all stages of graph optimization.

See also

theano.gof.toolbox

for common extensions.

on_attach(function_graph)

Called by FunctionGraph.attach_feature, the method that attaches the feature to the FunctionGraph. Since this is called after the FunctionGraph is initially populated, this is where you should run checks on the initial contents of the FunctionGraph.

The on_attach method may raise the AlreadyThere exception to cancel the attach operation if it detects that another Feature instance implementing the same functionality is already atttached to the FunctionGraph.

The feature has great freedom in what it can do with the function_graph: it may, for example, add methods to it dynamically.

on_change_input(function_graph, node, i, r, new_r, reason=None)

Called whenever node.inputs[i] is changed from r to new_r. At the moment the callback is done, the change has already taken place.

If you raise an exception in this function, the state of the graph might be broken for all intents and purposes.

on_detach(function_graph)

Called by remove_feature(feature). Should remove any dynamically-added functionality that it installed into the function_graph.

on_import(function_graph, node, reason)

Called whenever a node is imported into function_graph, which is just before the node is actually connected to the graph. Note: on_import is not called when the graph is created. If you want to detect the first nodes to be implemented to the graph, you should do this by implementing on_attach.

on_prune(function_graph, node, reason)

Called whenever a node is pruned (removed) from the function_graph, after it is disconnected from the graph.

orderings(function_graph)

Called by toposort. It should return a dictionary of {node: predecessors} where predecessors is a list of nodes that should be computed before the key node.

If you raise an exception in this function, the state of the graph might be broken for all intents and purposes.

FunctionGraph Feature List

• ReplaceValidate

• DestroyHandler