fg – Graph Container [doc TODO]


class theano.graph.fg.FunctionGraph(inputs, outputs, features=None, clone=True, update_mapping=None)[source]

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. Variable`s 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 Variable`s are used) and for tracking the `Variable`s with a `clients field that specifies which Apply nodes use the Variable. The clients field combined with the Variable.owner field and the Apply nodes’ Apply.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.

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.

  • 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.


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



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.

add_client(var, new_client)[source]

Update the clients of var with new_clients.

  • var (Variable.) –
  • new_client ((Apply, int)) – A (node, i) pair such that node.inputs[i] is var.
add_input(var, check=True)[source]

Add a new variable as an input to this FunctionGraph.

Parameters:var (theano.graph.basic.Variable) –

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

change_input(node, i, new_var, reason=None)[source]

Change node.inputs[i] to new_var.

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

For each feature that has an on_change_input method, this method calls: feature.on_change_input(function_graph, node, i, old_var, new_var, reason)

  • node (theano.graph.basic.Apply or str) – The node for which an input is to be changed. If the value is the string "output" then the self.outputs will be used instead of node.inputs.
  • i (int) – The index in node.inputs that we want to change.
  • new_var (theano.graph.basic.Variable) – The new variable to take the place of node.inputs[i].

Call this for a diagnosis if things go awry.


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)[source]

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

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.
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)[source]

Collects callbacks

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


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)[source]

Execute callbacks

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


Return a list of all the (node, i) pairs such that node.inputs[i] is var.

import_node(apply_node, check=True, reason=None)[source]

Recursively import everything between an Apply node and the FunctionGraph’s outputs.

The node to be imported.
Check that the inputs for the imported nodes are also present in the FunctionGraph.
The name of the optimization or operation in progress.
import_var(var, reason)[source]

Import variables into this FunctionGraph.

This will also import the variable’s Apply node.

The variable to be imported.
The name of the optimization or operation in progress.

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 the clients of any destroyed inputs have already computed their outputs.


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

remove_client(var, client_to_remove, reason=None)[source]

Recursively removes clients of a variable.

This is the main method to remove variables or Apply nodes from a FunctionGraph.

This will remove var from the FunctionGraph if it doesn’t have any clients remaining. If it has an owner and all the outputs of the owner have no clients, it will also be removed.

  • var (Variable) – The clients of var that will be removed.
  • client_to_remove (pair of (Apply, int)) – A (node, i) pair such that node.inputs[i] will no longer be var in this FunctionGraph.

Removes the feature from the graph.

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

replace(var, new_var, reason=None, verbose=None)[source]

Replace a variable in the FunctionGraph.

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

The variable to be replaced.
The variable to replace var.
The name of the optimization or operation in progress.
Print reason, var, and new_var.
replace_all(pairs, reason=None)[source]

Replace variables in the FunctionGraph according to (var, new_var) pairs in a list.


Set up node so it belongs to this FunctionGraph.

Parameters:node (theano.graph.basic.Apply) –

Set up a variable so it belongs to this FunctionGraph.

Parameters:var (theano.graph.basic.Variable) –


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.graph.toolbox.Feature[source]

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

for common extensions.

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 attached to the FunctionGraph.

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

on_change_input(fgraph, node, i, var, new_var, reason=None)[source]

Called whenever node.inputs[i] is changed from var to new_var. 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.


Called by FunctionGraph.remove_feature. Should remove any dynamically-added functionality that it installed into the fgraph.

on_import(fgraph, node, reason)[source]

Called whenever a node is imported into fgraph, which is just before the node is actually connected to the graph.

Note: this 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(fgraph, node, reason)[source]

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


Called by FunctionGraph.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