Visitor Classes
- class pyomo.core.expr.StreamBasedExpressionVisitor(**kwds)[source]
This class implements a generic stream-based expression walker.
This visitor walks an expression tree using a depth-first strategy and generates a full event stream similar to other tree visitors (e.g., the expat XML parser). The following events are triggered through callback functions as the traversal enters and leaves nodes in the tree:
initializeWalker(expr) -> walk, result enterNode(N1) -> args, data {for N2 in args:} beforeChild(N1, N2) -> descend, child_result enterNode(N2) -> N2_args, N2_data [...] exitNode(N2, n2_data) -> child_result acceptChildResult(N1, data, child_result) -> data afterChild(N1, N2) -> None exitNode(N1, data) -> N1_result finalizeWalker(result) -> result
Individual event callbacks match the following signatures:
walk, result = initializeWalker(self, expr):
initializeWalker() is called to set the walker up and perform any preliminary processing on the root node. The method returns a flag indicating if the tree should be walked and a result. If walk is True, then result is ignored. If walk is False, then result is returned as the final result from the walker, bypassing all other callbacks (including finalizeResult).
args, data = enterNode(self, node):
enterNode() is called when the walker first enters a node (from above), and is passed the node being entered. It is expected to return a tuple of child args (as either a tuple or list) and a user-specified data structure for collecting results. If None is returned for args, the node’s args attribute is used for expression types and the empty tuple for leaf nodes. Returning None is equivalent to returning (None,None). If the callback is not defined, the default behavior is equivalent to returning (None, []).
node_result = exitNode(self, node, data):
exitNode() is called after the node is completely processed (as the walker returns up the tree to the parent node). It is passed the node and the results data structure (defined by enterNode() and possibly further modified by acceptChildResult()), and is expected to return the “result” for this node. If not specified, the default action is to return the data object from enterNode().
descend, child_result = beforeChild(self, node, child, child_idx):
beforeChild() is called by a node for every child before entering the child node. The node, child node, and child index (position in the args list from enterNode()) are passed as arguments. beforeChild should return a tuple (descend, child_result). If descend is False, the child node will not be entered and the value returned to child_result will be passed to the node’s acceptChildResult callback. Returning None is equivalent to (True, None). The default behavior if not specified is equivalent to (True, None).
data = acceptChildResult(self, node, data, child_result, child_idx):
acceptChildResult() is called for each child result being returned to a node. This callback is responsible for recording the result for later processing or passing up the tree. It is passed the node, result data structure (see enterNode()), child result, and the child index (position in args from enterNode()). The data structure (possibly modified or replaced) must be returned. If acceptChildResult is not specified, it does nothing if data is None, otherwise it calls data.append(result).
afterChild(self, node, child, child_idx):
afterChild() is called by a node for every child node immediately after processing the node is complete before control moves to the next child or up to the parent node. The node, child node, an child index (position in args from enterNode()) are passed, and nothing is returned. If afterChild is not specified, no action takes place.
finalizeResult(self, result):
finalizeResult() is called once after the entire expression tree has been walked. It is passed the result returned by the root node exitNode() callback. If finalizeResult is not specified, the walker returns the result obtained from the exitNode callback on the root node.
Clients interact with this class by either deriving from it and implementing the necessary callbacks (see above), assigning callable functions to an instance of this class, or passing the callback functions as arguments to this class’ constructor.
- walk_expression(expr)[source]
Walk an expression, calling registered callbacks.
This is the standard interface for running the visitor. It defaults to using an efficient recursive implementation of the visitor, falling back on
walk_expression_nonrecursive()
if the recursion stack gets too deep.
- class pyomo.core.expr.SimpleExpressionVisitor[source]
Note
This class is a customization of the PyUtilib
SimpleVisitor
class that is tailored to efficiently walk Pyomo expression trees. However, this class is not a subclass of the PyUtilibSimpleVisitor
class because all key methods are reimplemented.- finalize()[source]
Return the “final value” of the search.
The default implementation returns
None
, because the traditional visitor pattern does not return a value.- Returns:
The final value after the search. Default is
None
.
- visit(node)[source]
Visit a node in an expression tree and perform some operation on it.
This method should be over-written by a user that is creating a sub-class.
- Parameters:
node – a node in an expression tree
- Returns:
nothing
- xbfs(node)[source]
Breadth-first search of an expression tree, except that leaf nodes are immediately visited.
Note
This method has the same functionality as the PyUtilib
SimpleVisitor.xbfs
method. The difference is that this method is tailored to efficiently walk Pyomo expression trees.- Parameters:
node – The root node of the expression tree that is searched.
- Returns:
The return value is determined by the
finalize()
function, which may be defined by the user. Defaults toNone
.
- xbfs_yield_leaves(node)[source]
Breadth-first search of an expression tree, except that leaf nodes are immediately visited.
Note
This method has the same functionality as the PyUtilib
SimpleVisitor.xbfs_yield_leaves
method. The difference is that this method is tailored to efficiently walk Pyomo expression trees.- Parameters:
node – The root node of the expression tree that is searched.
- Returns:
The return value is determined by the
finalize()
function, which may be defined by the user. Defaults toNone
.
- class pyomo.core.expr.ExpressionValueVisitor[source]
Note
This class is a customization of the PyUtilib
ValueVisitor
class that is tailored to efficiently walk Pyomo expression trees. However, this class is not a subclass of the PyUtilibValueVisitor
class because all key methods are reimplemented.- dfs_postorder_stack(node)[source]
Perform a depth-first search in postorder using a stack implementation.
Note
This method has the same functionality as the PyUtilib
ValueVisitor.dfs_postorder_stack
method. The difference is that this method is tailored to efficiently walk Pyomo expression trees.- Parameters:
node – The root node of the expression tree that is searched.
- Returns:
The return value is determined by the
finalize()
function, which may be defined by the user.
- finalize(ans)[source]
This method defines the return value for the search methods in this class.
The default implementation returns the value of the initial node (aka the root node), because this visitor pattern computes and returns value for each node to enable the computation of this value.
- Parameters:
ans – The final value computed by the search method.
- Returns:
The final value after the search. Defaults to simply returning
ans
.
- visit(node, values)[source]
Visit a node in a tree and compute its value using the values of its children.
This method should be over-written by a user that is creating a sub-class.
- Parameters:
node – a node in a tree
values – a list of values of this node’s children
- Returns:
The value for this node, which is computed using
values
- visiting_potential_leaf(node)[source]
Visit a node and return its value if it is a leaf.
Note
This method needs to be over-written for a specific visitor application.
- Parameters:
node – a node in a tree
- Returns:
(flag, value)
. Ifflag
is False, then the node is not a leaf andvalue
isNone
. Otherwise,value
is the computed value for this node.- Return type:
A tuple
- class pyomo.core.expr.ExpressionReplacementVisitor(substitute=None, descend_into_named_expressions=True, remove_named_expressions=True)[source]
- dfs_postorder_stack(expr)[source]
DEPRECATED.
Deprecated since version 6.2: ExpressionReplacementVisitor: this walker has been ported to derive from StreamBasedExpressionVisitor. dfs_postorder_stack() has been replaced with walk_expression()
- walk_expression(expr)
Walk an expression, calling registered callbacks.
This is the standard interface for running the visitor. It defaults to using an efficient recursive implementation of the visitor, falling back on
walk_expression_nonrecursive()
if the recursion stack gets too deep.
- walk_expression_nonrecursive(expr)
Nonrecursively walk an expression, calling registered callbacks.
This routine is safer than the recursive walkers for deep (or unbalanced) trees. It is, however, slightly slower than the recursive implementations.