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 partitioning uses ordered-packing/dependency-tail priorities and nominal movement volumes. PEFT and final evaluation use physical cost estimates. 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, and C modeled work.

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)) plus dependency traversal / O(S G²) cache
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/temporary space for Q slot visits and L producer lanes; publication maps cached
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.