Raptor/docs/compiler/scheduling.md

Spatial scheduling

ScheduleAndRealizeSpatial constructs a shared ComputeGraph, then selects latency PEFT or pipeline scheduling. Pipeline mode does not run PEFT.

See implementation notes for fragment-view eligibility, receive forwarding, transfer rounding, cost-model boundaries, and recovery limits.

Ownership

Responsibility	Owner
Instances, dependencies, execution/transfer costs, resident weights	ComputeGraph, ComputeInstanceUtils
Target resources and physical link costs	Compiler target adapter via SchedulingTarget
Latency priorities, reservations, placement, per-core order	PeftScheduler
Capacity-driven workload splitting	PipelineWorkloadPreparation
Groups, stage partitioning, core budgets	buildPipelineGroups, partitionPipelineGroups, assignPipelineStages
Topology clustering and stage-local packing	PipelineCoreLayout, packPipelineStages, IndexedResidentWeights
Timing evaluation and publication equivalence	evaluateSchedule, populateScheduleEquivalenceClasses
Selected execution order and homogeneous runs	Scheduled compute planning/materialization
Routing, forwarding, blocking communication order	Deferred transfer planning and communication scheduling
READY/FREE counts, registers, overwrite/restart boundaries	Deferred boundary planning/realization

Both strategies produce MergeScheduleResult: core assignments, contiguous per-core slots, estimated starts, last-task markers, equivalence classes, and cost summaries. Pipeline results also assign each core a stage. Materialization uses verified slots for execution order and merges only consecutive compatible instances. Graph/class lane identity does not imply core identity or execution order.

Dependencies and transfer costs share getGraphBatchPublicationMap. Statically proven physical-slot projections support many-to-many edges; unproven projections retain complete producer dependencies, including region captures. Malformed publication metadata fails graph construction.

Normative contracts: graph fragments, pipeline stages, target boundary, synchronization, and performance.

Costs and interpretation

Execution and fixed transfer costs use integer nanoseconds, converted from target cycles. Bytes, elements, flits, weight slots, and lanes remain resource quantities. Memory work is rounded at its actual fragment/run granularity; runtime-free views cost zero. Transposes charge memory traffic and strided vector work; concatenation charges per-input blocks per outer row. Direct receives into assembly storage avoid duplicate endpoint-memory charges. Sub-byte storage is analyzable in Spatial but rejected by byte-addressed PIM communication lowering.

The evaluator separates serial work, per-core work, dependency critical path, summed transfer work, single-inference completion, and stage spans. Dependency paths exclude core-order constraints; completion includes them. Stage spans exclude cross-stage routing, restart/host synchronization, and contention. Simulator latency and measured throughput remain the performance gates.

Pipeline scheduling retains the original ordered-packing/dependency-tail heuristic using nominal movement volumes. A second search uses execution estimates and aggregate serialized shared-memory service, minimizing their maximum. Its DP keeps at most eight compute/memory trade-offs per state; four final alternatives and the initial partition undergo the existing core allocation, topology placement, and capacity verification. The phase-1 winner remains a fallback. A second bounded search accounts for shared publications. Selection retains the fallback unless the modeled bottleneck improves. Selection also requires that shared-memory service plus maximum stage span does not increase. The same check applies to shared-memory service plus maximum per-core compute work. These guards limit compute imbalance; their sums do not predict simulator periods. Sharing-aware alternatives must also preserve maximum stage span, because placement-dependent baseline loads remain approximate. PEFT is unchanged.

ComputeGraph retains physical publication and consumer identities separately from aggregated dependency edges. Cross-stage demands charge one store per shared physical publication and one load per consumer transfer. Publication identity includes the immutable result generation, exact payload type, and physical source fragment. Scalar projections retain separate stores conservatively. Same-stage local/direct transfers incur no host traffic. Function inputs, constants, and outputs supply a separate baseline estimate. The target adapter supplies access width and read/write service times; request rounding precedes aggregation. Serialized service is shared by all stages and is not added to individual stage spans. Baseline loads remain approximate before placement, bufferization, aliasing, and load folding. Scalar publication stores round each contiguous source run separately. Consumer load counts can remain conservative before load folding. The scheduler evaluates boundary demand again after physical placement. Full graph fragments resolve to unique physical producers, so their sharing does not depend on reader placement. Deferred planning uses the same identity rule and retains separate loads, including repeated loads on one reader core. Placement ranks maximum per-core compute/incident-transfer demand, then stage completion and compute load; within 1% demand, stage span breaks the tie. These are placement heuristics, not a steady-state timing model.

Capacity and recovery

Distinct-weight union / per-core capacity is a lower bound; an oversized task is infeasible. Ordered pack counts estimate budgets, and failed heuristic packing does not prove infeasibility. Exhausted budgets restart from lower bounds and constructive packing establishes feasibility.

Latency reservations try load/communication-aware placement, then largest-weight-first and shared reuse-first best fit on failure. Pipeline packing compares arrival/load-aware candidates and uses constructive recovery. The shared constructor retries in reverse order, then at most 16 single-choice deviations within 65,536 core-candidate checks. Successful placements are preserved. Exhausted search produces a bounded diagnostic, not a claim of proved hardware infeasibility.

Complexity and limits

Let T be tasks, E dependencies, P cores, G groups, S stages, R weight references, W distinct weights, C modeled work, F physical fragment/consumer demands, and bounded frontier size K = 8.

Analysis	Time / storage
Schedule evaluation	O((T + E) log T + P) / O(T + E + P)
Weight indexing	Up to O(R W) equality comparisons
Weight lower bounds	O(R + W) / O(W) bits
Constructive best fit	O(T log T + P R + P W) / O(P W) bits plus O(T + P); bounded retries only on failure
Partition DP	Up to O(S G² ((T + R) log C + W + K³)) plus dependency traversal / O(S G² + S G K); at most five additional physical placements per memory objective
Cut memory service	Expected O(F + G) time / O(F + G) scratch and retained demands
Topology clustering / cached PEFT distances	O(P²) time
Concat cost extraction	O(A D) for A inputs of rank D; constant auxiliary space
Cached pipeline priorities	O(T + D) time / O(T + G) space for D template-body operations
Exact projections	O(Q + L) time for Q slot visits and L producer lanes; repeated demands aggregate by projection and fragment
Conservative producer tracing	Linear in the input projection DAG, including captures

Latency insertion-gap searches can remain quadratic. Issue overhead, eliminated assembly copies, contention, and pipeline synchronization remain cost approximations. Changes require matched execution measurements. Loop-invariant projections use trip-count multiplication. Loop-invariant resident weights are collected once. Loop-dependent projections and weights can still require iteration visits; retained projection demands scale with distinct physical fragments instead of repeated visits.