kernelfoundry.gui.roofline¶

Page for showing roofline charts and ALU breakdown charts for kernel performance analysis.

Functions

`fill_figure_template`(template_str, series)	Fill SVG template placeholders with data from series.
`format_bytes`(value)	Format byte values into human-readable format (B, KB, MB, GB, TB).
`render_kernel_charts_section`(label, ...[, ...])	Renders the profiler charts section for a kernel (custom or reference).
`roofline_page`([kernel_id, template_dir])	Render the roofline analysis page for a kernel with profiler data visualization.
`write_trace_and_create_traceviewer_button`(...)	Write profiler trace to file and create a viewer button for timeline analysis.

Classes

RooflineUtils()

kernelfoundry.gui.roofline.format_bytes(value) → str[source]¶: Format byte values into human-readable format (B, KB, MB, GB, TB).

kernelfoundry.gui.roofline.fill_figure_template(template_str, series: list[Series]) → str[source]¶: Fill SVG template placeholders with data from series.

class kernelfoundry.gui.roofline.RooflineUtils[source]¶

MIN_VALUE = 0.001¶

DISPLAY_NAME = {'GPU_MEMORY_BYTE_READ[bytes]': 'GMEM', 'GPU_MEMORY_BYTE_WRITE[bytes]': 'GMEM', 'SLM_BYTE_READ[bytes]': 'SLM', 'SLM_BYTE_WRITE[bytes]': 'SLM', 'XVE_INST_EXECUTED_ALU0_ALL[events]': 'ALU0', 'XVE_INST_EXECUTED_ALU1_ALL[events]': 'ALU1', 'XVE_INST_EXECUTED_ALU2_ALL[events]': 'ALU2', 'XVE_INST_EXECUTED_FP16[events]': 'FP16', 'XVE_INST_EXECUTED_FP32[events]': 'FP32', 'XVE_INST_EXECUTED_FP64[events]': 'FP64', 'XVE_INST_EXECUTED_INT16[events]': 'INT16', 'XVE_INST_EXECUTED_INT32[events]': 'INT32', 'XVE_INST_EXECUTED_INT64[events]': 'INT64', 'XVE_INST_EXECUTED_MATH[events]': 'EMATH', 'XVE_INST_EXECUTED_XMX_BF16[events]': 'XMX BF16', 'XVE_INST_EXECUTED_XMX_FP16[events]': 'XMX FP16', 'XVE_INST_EXECUTED_XMX_INT2[events]': 'XMX INT2', 'XVE_INST_EXECUTED_XMX_INT4[events]': 'XMX INT4', 'XVE_INST_EXECUTED_XMX_INT8[events]': 'XMX INT8'}¶

MEM_PAIRS = [('GPU_MEMORY_BYTE_READ[bytes]', 'GPU_MEMORY_BYTE_WRITE[bytes]'), ('SLM_BYTE_READ[bytes]', 'SLM_BYTE_WRITE[bytes]')]¶

COMPUTE_METRICS = ['XVE_INST_EXECUTED_FP16[events]', 'XVE_INST_EXECUTED_FP32[events]', 'XVE_INST_EXECUTED_FP64[events]', 'XVE_INST_EXECUTED_INT16[events]', 'XVE_INST_EXECUTED_INT32[events]', 'XVE_INST_EXECUTED_INT64[events]', 'XVE_INST_EXECUTED_MATH[events]', 'XVE_INST_EXECUTED_XMX_BF16[events]', 'XVE_INST_EXECUTED_XMX_FP16[events]', 'XVE_INST_EXECUTED_XMX_INT2[events]', 'XVE_INST_EXECUTED_XMX_INT4[events]', 'XVE_INST_EXECUTED_XMX_INT8[events]', 'XVE_INST_EXECUTED_ALU0_ALL[events]', 'XVE_INST_EXECUTED_ALU1_ALL[events]', 'XVE_INST_EXECUTED_ALU2_ALL[events]']¶

static shorten_fn_name(fn_name: str) → str[source]¶: Shorten function names by removing common namespace prefixes.

static read_metrics(profiler_data: dict) → tuple[DataFrame | None, DataFrame | None, DataFrame | None][source]¶

Reads the metrics from the profiler data dictionary. :param profiler_data: The profiler data dictionary. :type profiler_data: dict

Returns:

A tuple containing three DataFrames (or None) for different metric groups.: (ComputeBasic, MemoryProfile, VectorEngineProfile)

Return type:

tuple

static vtune_counters_to_dataframe(vtune_raw_data: dict) → DataFrame | None[source]¶

Convert VTune raw counter data to a unitrace-compatible DataFrame for roofline plotting.

VTune provides per-kernel aggregated counters with bandwidth in GB/s and instruction counts. This converts them into the column format expected by the roofline chart infrastructure (bytes transferred and instruction event counts).

Accepts two formats: - DB format: {‘counters’: {kernel_name: {col: val, …}}} - File format: {‘counters.json’: ‘<json string>’}

Parameters:: vtune_raw_data – The raw VTune data dict.
Returns:: A DataFrame with unitrace-compatible column names, or None if data is unavailable.

static get_median_row_for_each_kernel(df: DataFrame, column: str = 'GpuTime[ns]') → list[Series][source]¶: Returns a DataFrame with the median row for each kernel.

static compute_plot_range(mem_bandwidths: list[float], compute_limits: list[float], measured_arithmic_intensities: list[float], measured_compute: list[float])[source]¶

Computes the x and y ranges for the roofline plot. :param mem_bandwidths: List of memory bandwidths. :type mem_bandwidths: list[float] :param compute_limits: List of compute limits. :type compute_limits: list[float] :param measured_arithmic_intensities: List of measured arithmetic intensities. :type measured_arithmic_intensities: list[float] :param measured_compute: List of measured compute values. :type measured_compute: list[float]

Returns:: A tuple containing x_range and y_range.
Return type:: tuple

static get_chart_options(title: str, data: Series, mem_compute_pairs: list[tuple[tuple[str, str], str]], roofs: HardwareRoofs)[source]¶

Generates the chart options for the roofline plot. :param title: The title of the chart. :type title: str :param data: The data series containing the metrics. :type data: pd.Series :param mem_compute_pairs: List of memory-compute metric column name pairs. :type mem_compute_pairs: list[tuple[tuple[str,str], str]] :param roofs: Dictionary of roof names to their compute limits. :type roofs: HardwareRoofs

Returns:: The chart options for the roofline plot.
Return type:: dict

get_alu_breakdown_chart_options(roofs: HardwareRoofs) → dict[source]¶

Generates chart options for the ALU breakdown bar chart. :param metrics: The metrics series containing the ALU instruction counts. :type metrics: pd.Series :param roofs: The hardware roofs containing the ALU compute limits. :type roofs: HardwareRoofs

Returns:: The chart options for the ALU breakdown bar chart.
Return type:: dict

static get_vtune_alu_bar_chart_options(metrics: Series, roofs: HardwareRoofs) → dict[source]¶

Generates a simplified ALU utilization bar chart from VTune instruction counts.

VTune provides ALU0/ALU1/XMX totals rather than per-instruction-type breakdowns, so this produces a three-bar chart showing utilisation of each pipeline as a percentage of the theoretical peak.

Parameters:

metrics (pd.Series) – A row from the vtune_counters_to_dataframe() result.
roofs (HardwareRoofs) – The hardware roofs containing peak ALU compute limits.

Returns:

ECharts options for the simplified ALU utilization bar chart.

Return type:

dict

static get_chart_options_for_kernel(profiler_data: dict, worker_info: dict, profiler_key: str, shorten_fn_signatures: bool = True, figure_templates: dict | None = None) → OrderedDict[str, dict][source]¶

Generates chart options for all roofline plots for a given kernel entry :param profiler_data: The profiler data dictionary. :type profiler_data: dict :param worker_info: The worker info dictionary. :type worker_info: dict :param profiler_key: The key in the profiler data to use (e.g. ‘unitrace’, ‘vtune’). :type profiler_key: str :param shorten_fn_signatures: Whether to shorten function signatures in titles. :type shorten_fn_signatures: bool

Returns:

An ordered dictionary mapping kernel names to their chart data.: Each value contains: ‘roofline_options’, ‘mem_figure’, ‘alu_bar_chart_options’

Return type:

OrderedDict[str, dict]

kernelfoundry.gui.roofline.render_kernel_charts_section(label: str, profiler_data: dict, worker_info: dict, profiler_key: str, profiler_feedback: str | None = None, figure_templates: dict | None = None)[source]¶

Renders the profiler charts section for a kernel (custom or reference).

Parameters:

label – Section header label (e.g. “custom” or “reference”).
profiler_data – The profiler data dictionary for the kernel.
worker_info – The worker info dictionary for the kernel.
profiler_key – The key in profiler_data to use (e.g. “unitrace”).
profiler_feedback – Optional profiler feedback text to display after the charts.

kernelfoundry.gui.roofline.write_trace_and_create_traceviewer_button(kernel, kernel_id)[source]¶: Write profiler trace to file and create a viewer button for timeline analysis.

kernelfoundry.gui.roofline.roofline_page(kernel_id: int = 0, template_dir: Path | None = None)[source]¶: Render the roofline analysis page for a kernel with profiler data visualization.