boundlab.expr.Expr

class boundlab.expr.Expr

Bases: object

Abstract base class for all symbolic expressions in BoundLab.

Each expression represents a node in a directed acyclic graph (DAG) of computations. Expressions are immutable after construction, and each instance is assigned a unique time-ordered UUID to enable deterministic topological ordering during bound propagation.

Subclasses must implement shape, children, and backward() to define the expression’s semantics.

Methods

__init__
all_subnodes	Return a list of all sub-expressions in the DAG rooted at this expression, in topological order.
backward	Perform backward-mode bound propagation through this expression.
bound_width	Compute the width of the bounds for this expression.
bound_width_reasons_breakdown	Compute the breakdown of the bound width by reason.
center	Compute the center of the bounds for this expression.
diag
expand
expand_on
flatten
flip
gather
get_const	Return the concrete tensor if self is a pure constant expression, else None.
is_symmetric_to_0	Return True if this expression is symmetric about zero, else False.
lb	Compute a lower bound for this expression.
max_bound_width	Compute the maximum width across all output dimensions.
mean
narrow
permute
repeat
replace_subnode_once	Return a new expression with the same structure but sub-expressions replaced by replace_fn.
reshape
roll
scatter
simplify_ops_	Recursively compute simplified ops for affine expressions.
split_const	Decompose this expression into a constant part and a zero-constant part.
squeeze
sum
tile
to_string	Return string representation with child strings substituted.
transpose
ub	Compute an upper bound for this expression.
ublb	Compute both an upper bound and a lower bound for this expression.
uncertainty_reasons	Compute the breakdown of the bound width by reason, aggregated to total contributions.
unflatten
unsqueeze
with_children	Return a new expression with the same type and flags but new children.
zeros_set

__init__(flags=<ExprFlags.NONE: 0>)

id: int

Unique identifier for the expression, used for topological sorting.

flags: ExprFlags

Flags indicating expression properties for optimization.

with_children(*new_children)

Return a new expression with the same type and flags but new children.

property shape: torch.Size

The shape of the output(s) produced by this expression.

property children: tuple[Expr, ...]

The child expressions that serve as inputs to this expression.

backward(weights, direction='==')

Perform backward-mode bound propagation through this expression.

Given an accumulated weight weights (usually a EinsumOp) from the output back to this node, backward propagation derives child weights and a bias:

\[\mathbf{w}^\top f(x_1, \ldots, x_n) \;\square\; b + \sum_i \mathbf{w}_i^\top x_i\]

Parameters:

• weights (LinearOp) – A EinsumOp accumulated weight from the root expression to this node.

• direction (Literal['>=', '<=', '==']) – Bound direction — ">=" (lower), "<=" (upper), or "==" (exact).

Returns:

A tuple (bias, child_weights) where bias is a torch.Tensor or 0, and child_weights is a list of EinsumOp (one per child). Returns None if this expression cannot contribute to the bound in the given direction.

Return type:

tuple[torch.Tensor, list[LinearOp]] | None

to_string(*children_str)

Return string representation with child strings substituted.

__add__(other)

__mul__(other)

Element-wise multiplication (no broadcast).

reshape(*shape)

permute(*dims)

transpose(dim0, dim1)

property T: Expr

Convenience for transpose of the last two dimensions.

flatten(start_dim=0, end_dim=-1)

unflatten(dim, sizes)

squeeze(dim=None)

unsqueeze(dim)

narrow(dim, start, length)

expand(*sizes)

expand_on(dim, size)

repeat(*sizes)

tile(*sizes)

flip(dims)

roll(shifts, dims)

diag(diagonal=0)

zeros_set(output_shape)

scatter(indices, output_shape)

gather(indices, dim=0)

sum(dim=None, keepdim=False)

mean(dim=None, keepdim=False)

ub()

Compute an upper bound for this expression.

lb()

Compute a lower bound for this expression.

ublb()

Compute both an upper bound and a lower bound for this expression.

center()

Compute the center of the bounds for this expression.

bound_width()

Compute the width of the bounds for this expression.

max_bound_width()

Compute the maximum width across all output dimensions.

bound_width_reasons_breakdown()

Compute the breakdown of the bound width by reason.

uncertainty_reasons()

Compute the breakdown of the bound width by reason, aggregated to total contributions.

get_const()

Return the concrete tensor if self is a pure constant expression, else None.

Works for ConstVal and any AffineSum that has no symbolic children.

simplify_ops_()

Recursively compute simplified ops for affine expressions.

is_symmetric_to_0()

Return True if this expression is symmetric about zero, else False.

split_const()

Decompose this expression into a constant part and a zero-constant part.

If the expression is symmetric about zero, the constant part is zero. If the expression is a pure constant, the zero-constant part is zero.

Returns:

A tuple (non_const_part, const_part) where exactly one of the two is zero.

Return type:

tuple[Expr | 0, Expr | 0]

all_subnodes()

Return a list of all sub-expressions in the DAG rooted at this expression, in topological order.

replace_subnode_once(replace_fn)

Return a new expression with the same structure but sub-expressions replaced by replace_fn.