accelforge.plotting package#
Submodules#
accelforge.plotting.accesstrace module#
Plot which tensor elements a LoopTree mapping touches at each timestep.
The x-axis is the timestep (one iteration of the innermost temporal loop) and the y-axis is the tensor element being accessed, so the shape of the scatter is the mapping’s data movement: horizontal streaks are elements held across many timesteps, diagonal sweeps are streaming accesses, and repeated blocks are refetches.
Passing memory_level= additionally shades, behind the points, the tile that level
holds at each timestep, which turns the same picture into a read on that level’s
capacity: a wide block is a long-lived tile, and a tall one is a large tile. Blocks show
live residency, i.e. they stop at the tile’s last use rather than running to the end of
whatever the mapping reserved.
- accelforge.plotting.accesstrace.plot_access_trace(trace, workload=None, tensors=None, color_by='einsum', rank=None, memory_level=None, level_color=_TILE_COLOR, marker_size=None, ncols=1, ax=None, figsize=None, **trace_kwargs)[source]#
Plot timestep (x) against accessed tensor element (y) for a LoopTree mapping.
One subplot is drawn per tensor, sharing the timestep axis, so that fusion and reuse across tensors line up vertically.
- Parameters:
trace – An
AccessTrace, or anythingtrace_accesses()accepts (aSpec, a mapper result, or aMapping).workload – The workload, required only when
traceis a bareMapping.tensors (
Iterable[str] |None) – Which tensors to plot, and in what order. Defaults to every traced tensor.color_by (
str) –"einsum"colors accesses by which Einsum made them;"access"colors by read vs. write. Use"access"when many Einsums share one tensor.rank (
str|None) – Plot the coordinate along this tensor rank on the y-axis instead of the flattened element index. Only applies to tensors that have this rank.memory_level (
str|None) – Shade, in a background block, the tile of each tensor that is resident in this memory level (a storage component of the architecture, e.g."GlobalBuffer"). One block covers one tile: its width is how long the tile is live – from its first touch to its last, not the whole span the mapping reserves for it – and its height is which elements it holds, so the blocks show directly what a level is holding while the points show what is being touched. Tensors that this level never holds are left unshaded.level_color (
str) – The background color of thememory_levelblocks.marker_size (
float|None) – Marker size in points. Chosen from the data density if not given.ncols (
int) – Number of subplot columns.ax – Draw into this existing axes instead of making a figure. Only valid when a single tensor is being plotted.
figsize – Figure size. Scaled to the number of subplots if not given.
**trace_kwargs – Passed to
trace_accesses()whentraceis not already anAccessTrace(e.g.max_timesteps=,einsums=,max_points=).
- Returns:
The figure and a list of the axes drawn into.
- Return type:
(fig, axes)
accelforge.plotting.latency module#
Latency timelines showing how per-component latency overlaps across Einsums.
- accelforge.plotting.latency.plot_latency(spec, mappings=None, ax=None)[source]#
Plots a latency timeline. Time is on the X axis, and component on the Y axis. Component latencies may be divided across multiple shared loop levels, and shared latencies may overlap across Einsums. Private latencies do not get a loop level.
- Parameters:
spec – The spec to plot.
mappings (
Mappings) – The mapping to plot. Must hold exactly one mapping. If not given, uses spec.mapping.ax (
Axes) – The axes to plot on. If not given, creates a new figure and axes.
- Return type:
tuple[Figure,Axes]- Returns:
fig – The figure containing the plot.
ax – The axes containing the plot.
accelforge.plotting.mappings module#
accelforge.plotting.roofline module#
Roofline (2D and (3D) plots generated from an architecture description.
The 3D roofline Gerogiannis et al., “DECA: A Near-Core LLM Decompression Accelerator Grounded on a 3D Roofline Model” (MICRO ‘25).
In 3D roofline, throughput is bounded by three rates: the memory, a secondary compute unit (e.g., vector hardware), and a primary compute unit (e.g., matrix hardware):
primary computes/s = min(BW * CI_mem, SECONDARY * CI_secondary, PRIMARY)
where CI_mem is computes per byte moved to/from memory and CI_secondary is primary computes per secondary compute.
Sets of Einsums may be plotted as points. Each set is treated as fused, only the set’s input and output tensors (not tensors produced and consumed inside the set) contribute to data movement, and each tensor is moved once.
- accelforge.plotting.roofline.plot_roofline(spec, einsum_sets=None, labels=None, memory=None, compute=None, ax=None, log_scale=True)[source]#
Plot a 2D roofline for the architecture in spec, optionally with one point per fused set of Einsums.
- Parameters:
spec (
Spec) – The specification. Its architecture sets the memory bandwidth and peak compute throughput. If einsum_sets is given, it must also include a workload.einsum_sets (
Iterable[str|Iterable[str]]) – Sets of Einsum names. Each set is treated as fused: only its input and output tensors contribute to data movement. A bare Einsum name is a set of one. All computes in the set are counted against compute.labels (
Iterable[str]) – Labels for each set. Defaults to the Einsum names joined by “+”.memory (
str) – Name of the memory whose bandwidth bounds performance. Defaults to the outermost memory.compute (
str) – Name of the compute unit whose throughput bounds performance. Defaults to the compute unit with the highest peak throughput.ax – A matplotlib Axes to use. A new one is created by default.
log_scale (
bool) – Whether to use log-scaled axes.
- Return type:
fig, ax
- accelforge.plotting.roofline.plot_roofline_3d(spec, einsum_sets=None, labels=None, memory=None, primary_compute=None, secondary_compute=None, einsum_to_compute=None, ax=None, resolution=60, x_max=None, y_max=None)[source]#
Plot a 3D roofline (DECA, Section 4.1) for the architecture in spec, optionally with one point per fused set of Einsums.
The x axis is primary computes per byte moved to/from memory, the y axis is primary computes per secondary compute, and the z axis is attainable primary computes per second. The surface is colored by the bounding factor.
- Parameters:
spec (
Spec) – The specification. Its architecture must have at least two compute units. If einsum_sets is given, it must also include a workload.einsum_sets (
Iterable[str|Iterable[str]]) – Sets of Einsum names. Each set is treated as fused: only its input and output tensors contribute to data movement. A bare Einsum name is a set of one. A set with no secondary computes is drawn at the top of the y axis.labels (
Iterable[str]) – Labels for each set. Defaults to the Einsum names joined by “+”.memory (
str) – Name of the memory whose bandwidth bounds performance. Defaults to the outermost memory.primary_compute (
str) – Name of the primary (e.g., matrix) compute unit. Defaults to the compute unit with the highest peak throughput.secondary_compute (
str) – Name of the secondary (e.g., vector) compute unit. Defaults to the other compute unit if the architecture has exactly two.einsum_to_compute (
Mapping[str,str]) – Maps Einsum names to the compute unit (primary_compute or secondary_compute) that runs them. Einsums not listed run on whichever of the two is enabled for them, preferring primary_compute if both are.ax – A matplotlib 3D Axes to use. A new one is created by default.
resolution (
int) – Number of grid points along each of the x and y axes for the surface.x_max (
Number) – Upper limits of the x and y axes. By default, twice the ridge point or enough to include every point. Set these to compare plots on the same axes.y_max (
Number) – Upper limits of the x and y axes. By default, twice the ridge point or enough to include every point. Set these to compare plots on the same axes.
- Return type:
fig, ax
accelforge.plotting.skislope module#
accelforge.plotting.specs module#
Module contents#
- accelforge.plotting.plot_access_trace(trace, workload=None, tensors=None, color_by='einsum', rank=None, memory_level=None, level_color=_TILE_COLOR, marker_size=None, ncols=1, ax=None, figsize=None, **trace_kwargs)[source]#
Plot timestep (x) against accessed tensor element (y) for a LoopTree mapping.
One subplot is drawn per tensor, sharing the timestep axis, so that fusion and reuse across tensors line up vertically.
- Parameters:
trace – An
AccessTrace, or anythingtrace_accesses()accepts (aSpec, a mapper result, or aMapping).workload – The workload, required only when
traceis a bareMapping.tensors (
Iterable[str] |None) – Which tensors to plot, and in what order. Defaults to every traced tensor.color_by (
str) –"einsum"colors accesses by which Einsum made them;"access"colors by read vs. write. Use"access"when many Einsums share one tensor.rank (
str|None) – Plot the coordinate along this tensor rank on the y-axis instead of the flattened element index. Only applies to tensors that have this rank.memory_level (
str|None) – Shade, in a background block, the tile of each tensor that is resident in this memory level (a storage component of the architecture, e.g."GlobalBuffer"). One block covers one tile: its width is how long the tile is live – from its first touch to its last, not the whole span the mapping reserves for it – and its height is which elements it holds, so the blocks show directly what a level is holding while the points show what is being touched. Tensors that this level never holds are left unshaded.level_color (
str) – The background color of thememory_levelblocks.marker_size (
float|None) – Marker size in points. Chosen from the data density if not given.ncols (
int) – Number of subplot columns.ax – Draw into this existing axes instead of making a figure. Only valid when a single tensor is being plotted.
figsize – Figure size. Scaled to the number of subplots if not given.
**trace_kwargs – Passed to
trace_accesses()whentraceis not already anAccessTrace(e.g.max_timesteps=,einsums=,max_points=).
- Returns:
The figure and a list of the axes drawn into.
- Return type:
(fig, axes)