Skip to content

Outputs

Every entry point returns a MappingEstimate and writes a set of files under its output directory, one group_<index>/ folder per fused group. This page covers both.

The result

A MappingEstimate holds cycles, the fused groups' estimates plus the reconfiguration the hardware declares, the per-group group_cycles, and the solved context. Read the rest off the context with ctx.get(...):

Key What it is
group_latencies Per-fusion-group latency breakdown.
roofline The accelerator's roofline (a compute roof per class of compute core, a bandwidth ceiling per memory level) and each solved group on it: its operations per cycle, its intensity and attainable rate per level, what bounds it, and a diagnosis of what holds it down. Groups with the same operators, shapes, placement and cost are one point.
allocation The Allocation - the problem it solves (the steady-state workload, the candidate placements and routes, the iteration spaces), the solved mapping and iteration spaces, and its solution (placements, routes, latencies, solve statistics and metrics, reports).
workload The parsed computation graph.
accelerator The parsed hardware model.
estimate = evaluate_mapping(...)
print(estimate.cycles)
ctx = estimate.context
allocation = ctx.get("allocation")
print(allocation.solution.latency.total)

Files written to disk

  • Once per run, in the output folder: a picture of the accelerator as Stream reads it (hardware_graph.svg): each core with the memory each of its top-level instances is a view of and the operands it holds there, each memory with its capacity, views, banks, measured bandwidth and ports (their width, the operands and directions they serve, the cores reaching them), and each link and bus between the memories. python -m stream.visualization.hardware_graph <hardware.yaml> <out.svg> draws one without solving.
  • Per fused group, in its group_<index>/ folder: a picture of its tiled workload (tiled_workload.svg), the cost of each node on each core (core_cost_lut.yaml, with its core_cost_lut.pickle cache) and its allocation artifacts; under a tile search, those of the candidate it chose.

SolveOptions(artifacts=False) writes none of these pictures (nor the ONNX parser's workload_graph.svg), and none of the allocation artifacts below.

Allocation artifacts

Each allocation solve writes into group_<index>/allocation/:

  • reports/ - the solver's metrics (optimization_metrics.yaml) and, for Gurobi, its progress (optimization_trace.yaml), and where each slot's latency goes (slot_latency_breakdown.yaml).
  • traces/ - the allocation as Perfetto JSON traces (steady_state_trace.json and steady_state_trace_compact.json); open them at https://ui.perfetto.dev to inspect each core's timeline and the inter-core transfers.
  • figures/ - the solver's progress for Gurobi (optimization_progress.png) and a picture of the solved steady-state workload (steady_state_workload_final.svg).

A sweep that only needs the estimates turns these off, and the pictures with them, with SolveOptions(artifacts=False). A solve that has no solution writes its model for diagnosis instead, whatever artifacts says: Gurobi's irreducible infeasible subsystem as allocation/model.ilp, OR-Tools' whole model as allocation/model.mps.

YAML reference

Every key of every YAML file a solve writes, one table per file. A nested key is a dotted path, an item of a list is [], and a key that names something of the solve (a memory, a metadata entry) is in angle brackets. A test solves a small mapping and checks that these are exactly the keys the files hold. The mapping.yaml the generic mapping generator writes is a mapping in the input format, described in Mapping.

core_cost_lut.yaml

The cost of each computation node on each core it may run on, next to the core_cost_lut.pickle cache it summarises.

Key Meaning Unit
nodes the computation nodes the cost LUT holds
nodes[].node the node's name
nodes[].cores the cores the node has a cost on
nodes[].cores[].core_id the core's id
nodes[].cores[].core_type the core's namespaced type, such as aie2.compute
nodes[].cores[].latency_cycles the node's latency on the core, memory stalls included cycles
nodes[].cores[].ideal_cycles the latency at full use of the core's MAC units cycles
nodes[].cores[].ideal_temporal_cycles the latency without memory stalls, under the spatial unrolling the mapping gives the core cycles
nodes[].cores[].energy_pj the node's energy on the core; 0 where the backend estimates none pJ
nodes[].cores[].metadata what the core-cost backend records about the estimate
nodes[].cores[].metadata.backend the backend that estimated it: zigzag, ideal-cycle (ZigZag could not cost the pair) or aie
nodes[].cores[].metadata.<key> a further fact the backend records; aie records computed_fraction (the share of the core's steps that compute anything), and family (the kernel family whose rate priced it) or measured_symbol (the kernel whose measured call did)

allocation/reports/optimization_metrics.yaml

The outcome of the allocation solve, on every backend, and the size of its model, which only Gurobi reports; a value the backend does not report is null.

Key Meaning Unit
status how the solve ended, such as OPTIMAL or TIME_LIMIT
backend the solver backend, such as GUROBI or ORTOOLS_GSCIP
solver the solver behind it, such as gurobi or gscip
search how much the solver searched
search.nodes_explored branch-and-bound nodes explored count
search.simplex_iterations simplex iterations count
solution what the solver found
solution.objective_value the objective of the best solution; for Stream's lexicographic objective, its highest level, the latency objective
solution.mip_gap the relative gap between that objective and the best bound; null with Gurobi, whose multi-objective solve defines none per level ratio
effort what the solve cost
effort.runtime_s the solver's runtime over every level of the objective s
model the size of the model
model.variables its variables
model.variables.total all variables count
model.variables.integer integer variables, binaries included count
model.variables.binary binary variables count
model.constraints its constraints
model.constraints.linear linear constraints count
model.constraints.general general constraints (min, max, indicator, ...) count
model.nonzeros nonzero coefficients of the constraint matrix count

allocation/reports/optimization_trace.yaml

Every point a Gurobi solve's progress callback reported, in time order; other backends write no trace. A key a point's callback does not report is null.

Key Meaning Unit
trace the points, in time order
trace[].time_s the solver's runtime at the point s
trace[].event the callback that reported it: PRESOLVE (presolve progress), MIP (search progress) or MIPSOL (a new incumbent)
trace[].incumbent_objective the objective of the best solution so far, null before the first; a lexicographic solve optimizes its levels in turn, so the values restart at each level objective
trace[].objective_bound the best bound so far, null before the first objective
trace[].mip_gap the relative gap between the two, null while either is ratio
trace[].nodes_explored branch-and-bound nodes explored so far count
trace[].nodes_left branch-and-bound nodes still open (MIP) count
trace[].simplex_iterations simplex iterations so far (MIP) count
trace[].cuts_applied cutting planes applied so far (MIP) count
trace[].work_units Gurobi's deterministic work measure so far work units
trace[].rows_removed constraints presolve removed so far (PRESOLVE) count
trace[].columns_removed variables presolve removed so far (PRESOLVE) count
trace[].bound_changes variable bounds presolve changed so far (PRESOLVE) count
trace[].coefficient_changes coefficients presolve changed so far (PRESOLVE) count

allocation/reports/slot_latency_breakdown.yaml

Where the latency of one steady-state iteration goes: its totals, each resource's slack, each tensor's reuse, and what sets each slot's latency.

Key Meaning Unit
totals the latency of the schedule
totals.iteration_latency_cycles one iteration, the sum of its slot latencies cycles
totals.overlap_cycles how much of an iteration the next one overlaps cycles
totals.initiation_interval_cycles the time between the starts of two iterations, the iteration latency less the overlap cycles
totals.total_latency_cycles the latency of every iteration together, fill included cycles
totals.fill_cycles what the run adds to its overlapped iterations: loading single-buffered windows and the first tiles' warm-up before them, the drain and the epilogue after them, and the wait for absent nodes cycles
totals.absent_wait_cycles of the fill, the wait for computation nodes absent from a fused loop that a neighbour varies on cycles
totals.epilogue_cycles of the fill, the calls and firings that run once, after the last iteration and drain cycles
totals.shared_busy_cycles per memory with a measured bandwidth, the time it spends on one iteration's transfers
totals.shared_busy_cycles.<memory> that time for the memory of this name; it bounds the initiation interval from below cycles
resource_slack per core and link, least first, its idle time within one iteration; the overlap is at most the least of them
resource_slack[].resource the core or link
resource_slack[].kind core or link
resource_slack[].slack_cycles its idle time cycles
tensor_reuse per tensor, largest first, the reuse the solve chose
tensor_reuse[].tensor the tensor's name
tensor_reuse[].size_bits its size bits
tensor_reuse[].reuse_factor the iterations one fetch serves, absent loops included; 1 is fetched every iteration iterations
tensor_reuse[].reuse_stop_level the loop level its reuse stops at
tensor_reuse[].on_chip_tiles the tiles it takes on chip at that level count
tensor_reuse[].loop_nest_out_to_in its loop nest, outermost first
slots the slots of one iteration, in order
slots[].slot the slot's index
slots[].slot_latency_cycles its latency, that of the slowest node or transfer in it cycles
slots[].compute_contributors the computation nodes in the slot
slots[].compute_contributors[].node the node's name
slots[].compute_contributors[].cost_lut_core_count the cores the cost LUT prices it on count
slots[].compute_contributors[].lut_latency_cycles its latency on the slowest of them cycles
slots[].compute_contributors[].active_fraction the share of the iterations it is not idle on a loop it is absent from ratio
slots[].compute_contributors[].active_latency_cycles its LUT latency times its active fraction cycles
slots[].transfer_contributors the transfers in the slot, on the routes the solve chose
slots[].transfer_contributors[].transfer the transfer's name
slots[].transfer_contributors[].tensor_bits the size of the tensor it moves, only the indices its readers read bits
slots[].transfer_contributors[].min_link_bandwidth_bits_per_cycle the bandwidth of the narrowest link on its route bits/cycle
slots[].transfer_contributors[].path_cycles the time its route takes to move the tensor cycles
slots[].transfer_contributors[].active_latency_cycles the route time times its active fraction cycles
slots[].transfer_contributors[].reuse_factor the iterations one firing of its most often firing copy serves, absent loops included iterations
slots[].transfer_contributors[].latency_contribution_cycles what it adds to the slot's latency cycles

Typed IR (for tools and agents)

For structured, JSON-serializable output, convert the context's objects into the typed IR models. These are the same models the MCP server returns:

from stream.ir import WorkloadIR, AcceleratorIR, AllocationIR

workload_ir    = WorkloadIR.from_internal(ctx.get("workload"))
accelerator_ir = AcceleratorIR.from_internal(ctx.get("accelerator"))
allocation_ir  = AllocationIR.from_internal(ctx.get("allocation"))

allocation_data = allocation_ir.model_dump()      # JSON-compatible dict

AllocationIR exposes persona views - .algorithmic_view(), .hardware_view(), .compiler_view() - each shaping the same result for a different consumer. The performance view surfaces bottleneck (compute- vs transfer-bound) cycles and per-node utilization, and, under layouts, every transfer on its chosen route: the tile it moves, the memories it reads and writes, the axis orders of both copies (source_order, target_order, outermost first), whether it converts the layout, its contiguous bytes per run on each side, and per side the strides, the steps the DMA takes along each axis, its size and stride loops and the memory banks it lands in (see Data layout). Its energy gives the run's energy in pJ, per iteration split into the nodes and the transfers, and over every iteration, and under components where one iteration's energy is spent: each node's MAC array and memory levels on the cores it runs on, and each transfer's memory ports and links. steady_state is the solved steady state per core: its iterations and axes, where each tensor is placed and how it is buffered, and per tiled node its cores, tiles and runs (the times it runs), or for a transfer its route, the window and moved tile of each target, its halos and the demand each source serves at each target per firing (sent, by kind: moved, in_place, filled or partial) and the bits each link carries per firing (link_bits). copy_moved_bits and copy_reuse_factors give each copy's bits and reuse; where copies slide along fused loops, a firing's bits are the average over the firings. Partial sums are held at the accumulator precision and exchanged between cores at their reduction format; a sum kept below the top memory reaches it once (see Hardware). fill includes the epilogue: what a copy kept along a loop in which its producer still computes, and the calls after it, add after the last iteration. roofline is the group's point on the accelerator's roofline. Under memory_ports, bits_per_iteration, real_cycle and utilization are what the solver paces per iteration, and once_per_run_bits what moves once per run: a resource moves iterations x bits_per_iteration + once_per_run_bits. edge_placements and edge_tensors give where each input and output of the group is held, off chip or placed on chip, and its whole tensor, and offchip_holdings the bits of each of those tensors each off-chip memory holds, the group's off-chip footprint, keyed by the tensor names edge_tensors gives so that a tensor several groups hold counts once (see Placement of inputs and outputs). See Using Stream with an AI agent for details.