Struct OptimizeOptions

Struct Documentation

struct OptimizeOptions

Options that control behavior of sequant::optimize.

Public Members

ObjectiveFunction objective_function = ObjectiveFunction::DenseFLOPs

Objective function to minimize.

ReorderSum reorder = ReorderSum::Reorder

Whether to reorder summands so terms with shared intermediates appear closer to each other.

CSEOptions CSE = {}

Common-subexpression-elimination options. All disabled by default; enabling can reduce op counts at the cost of additional optimization time.

index_to_extent_t idx_to_extent = {}

Caller-supplied Index to extent provider. If empty, defaults to IndexSpace::approximate_size().

std::function<bool(Tensor const&)> is_volatile_leaf = {}

Marks a LEAF tensor as volatile: its value changes between replays of the network, so any contraction depending on it is re-evaluated on every replay. Empty (default) ⇒ no tensor is volatile ⇒ cost weighting is disabled and volatile_weight is ignored (behavior identical to before this feature). CC callers pass label==volatile_label, the same classification the runtime eval cache uses, so the optimizer’s cost model and the cache agree.

double volatile_weight = 1.0

Real-valued weight on the cost of each volatile contraction (re-evaluated on every replay of the network), while persistent (volatile-independent) contractions are counted once. Conceptually the expected number of replays. Default 1.0 (no change). Only consulted when is_volatile_leaf is non-empty and objective_function == ObjectiveFunction::DenseFLOPs.

double footprint_weight = 0.0

Per-intermediate memory-footprint penalty added to the single-term optimization cost. For every binary contraction, the storage footprint of its RESULT intermediate (the product of the extents of the result’s indices, i.e. its element count) is multiplied by this weight and added to the contraction cost. Unlike the FLOPs cost, this penalty is NOT scaled by volatile_weight (peak footprint is a one-time materialization cost, not a per-replay one). 0 (default) disables the penalty, recovering the pure FLOPs/Size behavior.

Rationale: the FLOPs cost is blind to the storage size of the intermediates it materializes, so it will happily pick an order (and thus expose, as a shareable subtree, a common subexpression) that carries a free large-space index — e.g. a half-transformed DF integral that still carries a free projected-AO (PAO) index — because forming it once is FLOPs-cheap. Such an intermediate can be enormous. A nonzero footprint_weight biases single-term optimization toward orders that defer or avoid materializing such large intermediates (e.g. transforming both large legs before exposing a shared subtree), trading a controlled amount of extra FLOPs for a lower peak footprint. Only consulted when objective_function == ObjectiveFunction::DenseFLOPs; the units are FLOPs-per-element, so a useful magnitude is on the order of the contracted-index extent that the offending intermediate would otherwise leave free.