Template Function sequant::cache_manager(meta::eval_node_range auto const&, auto&&, size_t, FootprintOf, double)

Function Documentation

template<bool force_hash_collisions = false, typename FootprintOf = zero_footprint>
auto sequant::cache_manager(meta::eval_node_range auto const &nodes, auto &&is_volatile, size_t min_repeats = 1, FootprintOf footprint_of = {}, double max_footprint = 0.)

A node is also refused run-scope residence when it is batch-variant: its cross-occurrence lifetime mask is non-empty (!EvalExpr::mask_all_full(); this builder itself calls stamp_lifetime_masks over nodes before the DAG walk below, so the mask is always current here regardless of caller &#8212; see lifetime_mask.hpp). Such a node is sliced by some enclosing External batch mode in every occurrence, so its value differs per batch of that mode &#8212; caching it whole at run scope would serve a wrong-batch value to a deeper consumer on cache fall-through (the F1 hazard). Only an all-full node (empty mask, including every node on the off path) is admitted.

See also

CacheManager, cache_manager

Parameters:

  • nodes – the evaluation forest.

  • is_volatile – bool(TreeNode const&): true if the node is intrinsically volatile. Only its value on leaves matters in practice (volatility propagates up), but it is consulted on every node.

  • min_repeats – minimum NP repeats to cache (default 1). The table-driven ordered executor derives every life from the cell table’s exact per-cell read count, and a use-count-tracking cache that silently declines single-use nodes makes that count wrong; with 1 the cache and the table agree by construction. Pass 2 to cache only nodes reached more than once, which caches less and leaves the use counts approximate. Cost note: 1 registers every internal node, and a cached node is held in the cache map by value (a deep copy of its subtree). On the left-leaning Sum-tree binarize builds for a whole equation the spine has one node per summand, each with a strictly larger subtree, so registering all of them costs O(terms^2) nodes &#8212; fine for a residual (tens of terms), fatal for a UCC BCH energy (thousands). A forest-descent caller that does not need the ordered executor’s exact use counts should pass 2 there.

  • footprint_of – double(TreeNode const&): the materialized storage footprint of a node’s result (e.g. its element count or byte size). Consulted only when max_footprint > 0.

  • max_footprint – footprint gate: any node whose footprint_of exceeds this is NOT cached (neither as an NP repeat nor as a P frontier node), so it is recomputed by each consumer instead of being materialized whole and held. This bounds the peak/sustained footprint of huge intermediates that carry a free large-space index (e.g. a half-transformed DF integral with a free projected-AO index), at the cost of recomputation. 0 (default) disables the gate.