fg
– Graph Container [doc TODO]¶
FunctionGraph¶
-
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.
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.
-
add_client
(var, new_client)[source]¶ Update the clients of var with new_clients.
Parameters: - 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) –
-
attach_feature
(feature)[source]¶ 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 beTrue
, whereold_var
is the current value ofnode.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)
Parameters: - 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 theself.outputs
will be used instead ofnode.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]
.
- node (theano.graph.basic.Apply or str) – The node for which an input is to be changed. If the value is
the string
-
clone
(check_integrity=True)[source]¶ 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
- 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)[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.
-
disown
()[source]¶ 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.
-
import_node
(apply_node, check=True, reason=None)[source]¶ Recursively import everything between an Apply node and the FunctionGraph’s outputs.
- apply_nodetheano.graph.basic.Apply
- The node to be imported.
- checkbool
- Check that the inputs for the imported nodes are also present in the FunctionGraph.
- reasonstr
- 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.
- variabletheano.graph.basic.Variable
- The variable to be imported.
- reasonstr
- The name of the optimization or operation in progress.
-
orderings
()[source]¶ 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.
Notes
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.
Parameters:
-
remove_feature
(feature)[source]¶ 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.
- vartheano.graph.basic.Variable
- The variable to be replaced.
- new_vartheano.graph.basic.Variable
- The variable to replace var.
- reasonstr
- The name of the optimization or operation in progress.
- verbosebool
- 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.
-
setup_node
(node)[source]¶ Set up node so it belongs to this FunctionGraph.
Parameters: node (theano.graph.basic.Apply) –
-
setup_var
(var)[source]¶ Set up a variable so it belongs to this FunctionGraph.
Parameters: var (theano.graph.basic.Variable) –
-
toposort
()[source]¶ 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.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
theano.graph.toolbox
- for common extensions.
-
on_attach
(fgraph)[source]¶ 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.
-
on_detach
(fgraph)[source]¶ 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.
-
orderings
(fgraph)[source]¶ Called by FunctionGraph.toposort. It should return a dictionary of
{node: predecessors}
wherepredecessors
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