Multimode batched evaluation of factorized CC (cost model + placement + dry-run)

CMakeLists.txt

@@ -438,6 +438,7 @@ set(SeQuant_eval_src
         SeQuant/core/eval/eval_expr.hpp
         SeQuant/core/eval/eval_node.hpp
         SeQuant/core/eval/eval_node_compare.hpp
+        SeQuant/core/eval/node_batch_annotation.hpp
         SeQuant/core/eval/result.cpp
         SeQuant/core/eval/result.hpp
         SeQuant/core/eval/fwd.hpp

SeQuant/core/batch_policy.hpp

@@ -3,16 +3,64 @@
 
 #include <cstddef>
 #include <functional>
+#include <limits>
 
 namespace sequant {
 
 class Index;
 class Tensor;
 
+/// The three RUNTIME EXECUTION MODELS for batched evaluation (Task 6 of the
+/// whole-scope batched DAG execution design, `doc/dev/specs/2026-08-10-
+/// whole-scope-batched-dag-execution-design.md`, plus its SP3 follow-on
+/// `doc/dev/specs/2026-08-05-dryrun-wetrun-schedule-equivalence-design.md`,
+/// the ordered-scope batched-eval design):
+///   - \c forest_descent (default): one tree at a time,
+///     `sequant::evaluate(Nodes const&, ...)`, unchanged.
+///   - \c whole_scope: one fused scope-tree walk over the whole forest,
+///     `sequant::eval::evaluate_whole_scope`, so a value shared across trees
+///     is built once per home block and reused, rather than rebuilt per tree.
+///   - \c ordered: driven by the SP2 `eval::OrderedSchedule` IR rather than
+///     the narrow `ScopeSchedule` scope tree,
+///     `sequant::eval::evaluate_ordered_schedule`.
+enum class BatchScheduler { forest_descent, whole_scope, ordered };
+
 /// One batchability policy shared by the single-term optimizer and the runtime
 /// batched evaluator (make_evaluator, Task A3). All predicates default empty.
 struct BatchPolicy {
-  std::function<bool(Index const&)> is_batchable_index = {};
+  /// Spaces batchable in the CONTRACTED role: a mode of such a space is
+  /// batchable where it is summed. Companion to \ref
+  /// is_batchable_external_index (the EXTERNAL role). Splitting batchability by
+  /// role lets a caller admit a space only where batching it is meaningful --
+  /// e.g. a space batchable only as an external spectator contributes none of
+  /// its contracted occurrences to the optimizer's 2^m search. Building block;
+  /// the derived "batchable in any role" query is \ref is_batchable_index().
+  /// Defaults to decline every index; a caller opts spaces in explicitly.
+  std::function<bool(Index const&)> is_batchable_contracted_index =
+      [](Index const&) { return false; };
+  /// Spaces batchable in the EXTERNAL role: a mode of such a space is batchable
+  /// where it is open on the term root (a spectator carried to the result), not
+  /// where it is contracted. Building block; declared adjacent to its
+  /// contracted companion. Defaults to decline every index; a caller that wants
+  /// external batching sets this predicate explicitly (there is no fallback to
+  /// the contracted role).
+  std::function<bool(Index const&)> is_batchable_external_index =
+      [](Index const&) { return false; };
+
+  /// Derived "batchable in ANY role": the union of the two building-block
+  /// predicates. This is NEVER a settable field -- it is computed from
+  /// \ref is_batchable_contracted_index and \ref is_batchable_external_index.
+  /// The runtime batched evaluator's accept predicate is this union (a mode is
+  /// accepted at runtime if it is batchable in either role); the factorizer's
+  /// role filters instead consume the individual building blocks. The building
+  /// blocks default-decline, so both are always callable here.
+  std::function<bool(Index const&)> is_batchable_index() const {
+    auto contracted = is_batchable_contracted_index;
+    auto external = is_batchable_external_index;
+    return [contracted, external](Index const& ix) {
+      return contracted(ix) || external(ix);
+    };
+  }
   /// Per-index per-batch slice size (in elements) for a batchable index -- an
   /// UPPER BOUND, not a goal. Both the single-term optimizer and the runtime
   /// batched evaluator treat it as a ceiling: the realized whole-tile batch is
@@ -21,6 +69,41 @@ struct BatchPolicy {
   std::function<std::size_t(Index const&)> batch_target_size = {};
   std::function<bool(Tensor const&)> is_volatile_leaf = {};
 
+  /// If true, an external/spectator index -- open on the whole network's result
+  /// yet contracted at no node -- is eligible for batching; its per-slice size
+  /// comes from \c batch_target_size(ix) like any batchable index. Default
+  /// false = no spectator batching (byte-identical to non-spectator behavior).
+  /// Necessary but not sufficient: spectator axes are emitted only under a
+  /// TIME-FIRST objective (DenseTimeSpaceBatched) and only when the selected
+  /// root's modeled peak exceeds \c peak_threshold. Spectator batching is
+  /// therefore currently unavailable under the space-first objectives.
+  bool batch_spectator_indices = false;
+
+  /// Enable the order-aware multilevel recompute cost model (resident-scan peak
+  /// + ordered-key flops recompute). SELECTION knob ONLY: it makes the DP
+  /// charge recompute realistically and thus pick a different (better-batching)
+  /// factorization. It does NOT control external-mode EMISSION -- that is the
+  /// independent \ref node_level_placement. Consulted only by the batched
+  /// objectives (threaded via CostParams). Default TRUE: the recompute-aware
+  /// model is the more realistic cost for selection. This is SAFE precisely
+  /// because it is now selection-only -- the node-level emission it used to
+  /// force is separately gated by \ref node_level_placement (default off), so
+  /// the emission stays the correct, cheap root-level forest seed. (Before the
+  /// decouple, defaulting this true forced the node-level runtime regression.)
+  bool order_aware_recompute = true;
+
+  /// Emission-placement knob for external (spectator) modes, INDEPENDENT of the
+  /// order-aware cost model. Only meaningful with \ref batch_spectator_indices.
+  /// If true, the emit uses node-level placement (per-node External stamps); if
+  /// false (default) it uses the root-level forest seed (one global spectator
+  /// loop). Node-level placement is currently a net runtime REGRESSION -- ~6x
+  /// wall time and ~8x batch scopes on water-8, and it produces a wrong
+  /// residual on water-20 -- because it nests a batch scope at every carrying
+  /// node and the batched evaluator replays each. It stays OFF by default until
+  /// that is fixed; the root-seed emission is correct and cheap regardless of
+  /// order_aware_recompute.
+  bool node_level_placement = false;
+
   /// If true, restrict batching to persistent (amplitude-independent) subtrees,
   /// declining to batch any subtree that contains a volatile leaf. If false
   /// (the default), batch ACROSS THE BOARD: slicing the batch axis shrinks any
@@ -40,6 +123,36 @@ struct BatchPolicy {
   /// accumulator + contribution co-residency of a node that contracts a
   /// batchable index.
   double accumulation_factor = 0.0;
+
+  /// Selects among the three runtime execution models (\ref BatchScheduler
+  /// above). Consulted by the
+  /// `sequant::evaluate(Nodes const&, BatchPolicy const&, ...)` driver
+  /// overload (`scope_executor.hpp`) to select the driver, and by
+  /// `sequant::eval::dryrun::cost_profile()` to select the matching peak
+  /// model: the co-residency oracle (`peak_profile_sweep` over `home_modes`)
+  /// for \c whole_scope, since that model is what predicts the whole-scope
+  /// realized peak, vs the batched-scratch replay high-watermark (models
+  /// forest descent) for \c forest_descent. Default \c forest_descent
+  /// reproduces today's behavior on every existing call site byte-for-byte.
+  BatchScheduler scheduler = BatchScheduler::forest_descent;
+
+  /// Peak-memory budget in BYTES for the batched objectives. Its meaning
+  /// DIFFERS between them:
+  ///
+  /// - SPACE-FIRST (DenseSpaceTimeBatched): a hard feasibility gate. The
+  ///   single-term optimizer minimizes flops among schedules whose modeled peak
+  ///   is <= peak_threshold, falling back to min-peak (best effort) when none
+  ///   fit. Default +infinity => every schedule feasible => min flops => no
+  ///   batching, i.e. here a finite value is the *enable* trigger for batching.
+  ///
+  /// - TIME-FIRST (DenseTimeSpaceBatched): NOT a feasibility gate. Root
+  ///   selection ignores it entirely (peak breaks exact flop ties only), so it
+  ///   can neither constrain the schedule's peak nor enable CONTRACTED-axis
+  ///   batching (which is emitted regardless). Its ONLY effect is to trigger
+  ///   EXTERNAL (spectator) axis emission, together with
+  ///   \c batch_spectator_indices: axes are emitted iff the selected root's
+  ///   modeled peak exceeds this threshold.
+  double peak_threshold = std::numeric_limits<double>::infinity();
 };
 
 }  // namespace sequant

SeQuant/core/binary_node.hpp

@@ -463,11 +463,23 @@ class FullBinaryNode {
   /// \return Size of the tree rooted at this node
   ///
   [[nodiscard]] std::size_t size() const {
-    if (leaf()) {
-      return 1;
+    // Iterative (explicit stack) node count: recursing left().size() +
+    // right().size() would descend to the tree's depth and overflow the C++
+    // call stack on a deep tree -- e.g. the left-folded Sum-tree binarize
+    // builds for a Sum with thousands of summands (mirrors the iterative
+    // destructor / deep_copy above; the recursive form also made this an
+    // O(N)-deep call on every use, e.g. each equality comparison's size check).
+    std::size_t n = 0;
+    std::vector<FullBinaryNode const*> stk;
+    stk.push_back(this);
+    while (!stk.empty()) {
+      FullBinaryNode const* cur = stk.back();
+      stk.pop_back();
+      ++n;
+      if (cur->left_) stk.push_back(cur->left_.get());
+      if (cur->right_) stk.push_back(cur->right_.get());
     }
-
-    return left().size() + right().size() + 1;
+    return n;
   }
 
   ///

SeQuant/core/eval/backend_array_ops.hpp

@@ -0,0 +1,56 @@
+#ifndef SEQUANT_EVAL_BACKEND_ARRAY_OPS_HPP
+#define SEQUANT_EVAL_BACKEND_ARRAY_OPS_HPP
+
+#include <SeQuant/core/container.hpp>
+#include <SeQuant/core/eval/result.hpp>
+#include <SeQuant/core/index.hpp>
+
+#include <cstddef>
+#include <functional>
+#include <utility>
+
+namespace sequant {
+
+/// \brief Backend-provided realizations of the two operations external-axis
+/// batching needs but that are backend-specific: constructing a zero
+/// destination array and chunking an axis into batches.
+///
+/// \details The neutral eval layer names only INDICES (which carry their
+/// spaces); the backend (the "user", e.g. mpqc) supplies these closures, so no
+/// backend artifact -- a TiledArray tiling has no meaning for, say, an on-disk
+/// backend -- ever leaks into the eval layer.
+///
+/// This replaces the old "carrier" model, in which the batched executor
+/// borrowed an axis's tiling from whichever array in the DAG happened to carry
+/// it (\c Result::pre_sized_zeros_over_mode / \c Result::mode_batches) and then
+/// had to reconcile that array's Result TYPE and mode ordinal against the
+/// scatter destination's. Tiling is a property of the space, not of any one
+/// array, so it is sourced once, backend-side, from the index alone.
+struct BackendArrayOps {
+  /// Construct a sufficiently-initialized ZERO result shaped by \p descriptor
+  /// -- a FULL (unsliced) index list, e.g. a node's \c canon_indices(). The
+  /// backend maps each index's space to its own artifact and applies its own
+  /// outer/inner split for proto-bearing (nested) indices, so flat-vs-nested
+  /// is decided by the descriptor, not by any type reconciliation here.
+  /// "Sufficiently initialized" is backend-defined (TA: a World + TiledRange,
+  /// zero-filled; a nested result gets empty inner tiles, filled by the
+  /// subsequent scatter writes).
+  std::function<ResultPtr(container::vector<Index> const& descriptor)>
+      make_zeros;
+
+  /// Enumerate the half-open [lo,hi) element ranges chunking \p axis at
+  /// ~\p target_batch_size. The backend owns the chunking rule (TA lands on
+  /// tile boundaries). Per-space: two indices of one space chunk identically.
+  std::function<container::svector<std::pair<std::size_t, std::size_t>>(
+      Index const& axis, std::size_t target_batch_size)>
+      axis_batches;
+
+  /// True iff both closures are installed (a batched run requires them).
+  explicit operator bool() const noexcept {
+    return static_cast<bool>(make_zeros) && static_cast<bool>(axis_batches);
+  }
+};
+
+}  // namespace sequant
+
+#endif  // SEQUANT_EVAL_BACKEND_ARRAY_OPS_HPP

SeQuant/core/eval/backends/btas/result.hpp

@@ -379,6 +379,12 @@ class ResultTensorBTAS final : public Result {
     return eval_result<ResultTensorBTAS<T>>(std::move(pre));
   }
 
+  /// Deep copy: the backing tensor type owns its elements, so its copy
+  /// constructor already produces an independently owned buffer.
+  [[nodiscard]] ResultPtr clone() const override {
+    return eval_result<ResultTensorBTAS<T>>(get<T>());
+  }
+
   [[nodiscard]] ResultPtr permute(
       std::array<std::any, 2> const& ann) const override {
     auto const pre_annot = std::any_cast<annot_t>(ann[0]);