Visitor Classes

class pyomo.core.expr.StreamBasedExpressionVisitor(**kwds)

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)

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.

class pyomo.core.expr.SimpleExpressionVisitor

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 PyUtilib SimpleVisitor class because all key methods are reimplemented.

finalize()

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)

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)

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 to None.

xbfs_yield_leaves(node)

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 to None.

class pyomo.core.expr.ExpressionValueVisitor

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 PyUtilib ValueVisitor class because all key methods are reimplemented.

dfs_postorder_stack(node)

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)

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)

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)

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). If flag is False, then the node is not a leaf and value is None. 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)

dfs_postorder_stack(expr)

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.