StreamBasedExpressionVisitor

(class from pyomo.core.expr.visitor)

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

Bases: object

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.

__init__(**kwds)

Methods

__init__(**kwds)
walk_expression(expr)	Walk an expression, calling registered callbacks.
walk_expression_nonrecursive(expr)	Nonrecursively walk an expression, calling registered callbacks.

Attributes

client_methods

Member Documentation

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.