scope_profiler.summary

Shared per-region summary table.

One renderer, used by ProfileManager.finalize(), :meth:ProfilingResults.print_summary and scope-profiler inspect, so the three agree on columns, units and formatting.

Everything here works off duck-typed results/region objects, so this module has no scope-profiler imports and cannot introduce an import cycle.

Attributes

Name	Description
DEFAULT_REGION_TABLE_COLUMNS	No description.
REGION_TABLE_COLUMNS	No description.
REGION_TABLE_COLUMN_NAMES	No description.
SORT_KEYS	No description.

Functions

Name	Description
format_region_table	Format :func:region_rows output as displayed by the region table.
gpu_timing_warnings	Explain CPU enqueue timings when device totals exceed them by over 2x.
likwid_tables	Build one LIKWID counter table per (rank, event group).
normalize_region_table_columns	Return validated (row_key, header) pairs for a region table.
perf_event_tables	Build one built-in perf-event counter table per rank.
print_likwid_table	Print one LIKWID counter table from :func:likwid_tables.
print_likwid_tables	Print every LIKWID counter table a result set exposes.
print_perf_event_tables	Print every built-in Linux perf-event counter table in results.
print_region_table	Print the aligned per-region statistics table.
region_row	Collect the summary statistics shown for one region.
region_rows	Build the summary rows for every region a result set exposes.

DEFAULT_REGION_TABLE_COLUMNSattributemodule attribute#

View source

DEFAULT_REGION_TABLE_COLUMNS = ('region', 'percent', 'total')

REGION_TABLE_COLUMNSattributemodule attribute#

View source

REGION_TABLE_COLUMNS = ('region', *REGION_TABLE_COLUMN_NAMES[1:])

REGION_TABLE_COLUMN_NAMESattributemodule attribute#

View source

REGION_TABLE_COLUMN_NAMES = tuple((key for key, _ in _COLUMNS))

SORT_KEYSattributemodule attribute#

View source

SORT_KEYS = (
  'start',
  'total',
  'calls',
  'avg',
  'min',
  'max',
  'first',
  'last',
  'std',
  'p50',
  'p95',
  'p99',
  'imbalance',
  'name'
)

Show moreShow less

format_region_tablefunction#

View source

def format_region_table(rows, columns=None, percentage_mode: str = 'coverage')

Format :func:region_rows output as displayed by the region table.

Shared by the terminal table and the HTML report so both show the same columns, tree indentation, inline call counts and (own) rows.

Returns

selected_columns : tuple of (key, header) The columns to display, in order. display_rows : list of (row, display, is_own) display maps every column key to its cell text. row is the source row; for an (own) row (is_own true) it is the parent region whose time excluding children the row shows.

gpu_timing_warningsfunction#

View source

def gpu_timing_warnings(rows) -> list[str]

Explain CPU enqueue timings when device totals exceed them by over 2x.

likwid_tablesfunction#

View source

def likwid_tables(results, include=None, exclude=None, ranks=None) -> list

Build one LIKWID counter table per (rank, event group).

Regions become columns and counters become rows: a run typically has a handful of regions but a few dozen counters, so this orientation stays readable where the transpose would not. Splitting per event group keeps every column of a table comparable, since a group fixes which events and metrics exist.

Columns are ordered by descending LIKWID runtime (ties alphabetically), so the costliest regions lead, as in the region table.

Parameters

results : ProfilingResults Source of the LIKWID results. include, exclude : list of str or str, optional Regex patterns selecting which regions to report, matched as for the region table. ranks : list of int, optional Restrict to these ranks (default: all).

Returns

list of dict One entry per table, each with rank, group, columns (the region labels) and sections ((title, rows) pairs, where a row is (name, values)). Empty when the file holds no LIKWID data.

normalize_region_table_columnsfunction#

View source

def normalize_region_table_columns(columns=None) -> tuple[tuple[str, str], ...]

Return validated (row_key, header) pairs for a region table.

perf_event_tablesfunction#

View source

def perf_event_tables(results, include=None, exclude=None, ranks=None) -> list

Build one built-in perf-event counter table per rank.

These counters are already summed across calls by the collector, so each region occupies one row and calls/events occupy columns. Missing events use - rather than being treated as zero.

print_likwid_tablefunction#

View source

def print_likwid_table(table, title=None, stream=None) -> None

Print one LIKWID counter table from :func:likwid_tables.

print_likwid_tablesfunction#

View source

def print_likwid_tables(results, include=None, exclude=None, ranks=None, stream=None)

Print every LIKWID counter table a result set exposes.

A no-op for files recorded without LIKWID, so callers can invoke it unconditionally.

print_perf_event_tablesfunction#

View source

def print_perf_event_tables(results, include=None, exclude=None, ranks=None, stream=None)

Print every built-in Linux perf-event counter table in results.

print_region_tablefunction#

View source

def print_region_table(rows, title=None, stream=None, suppress_notes: bool = False, total_time: float | None = None, columns=None, percentage_mode: str = 'coverage', file_path=None) -> None

Print the aligned per-region statistics table.

Parameters

rows : list of dict Rows from :func:region_rows. title : str, optional Heading printed above the table. stream : file-like, optional Where to write (default: stdout). suppress_notes : bool, optional Don’t print the explanatory notes below the table (default: False). total_time : float, optional Accepted for compatibility. Session elapsed time is shown in the scope_profiler.session row. columns : list of str or str, optional Region summary columns to print. Defaults to region, percent and total. An indented (own) row shows time excluding children for each parent region. Call counts other than one appear after region names unless a separate calls column is explicitly selected. The percentage is relative to scope_profiler.session. The public name for the first column is region; name is accepted as an alias for Python callers. percentage_mode : {“coverage”, “exclusive”}, optional Quantity used for the % session column. Wall-clock coverage is the default; exclusive time can be selected for attribution-focused tables. file_path : str or Path, optional File represented by the table, used for the help hints in the info box.

region_rowfunction#

View source

def region_row(region, ranks=None, *, include_exclusive: bool = False) -> dict

Collect the summary statistics shown for one region.

Duration entries are None when the region has no recorded calls for the selected ranks, which the table renders as a dash.

region_rowsfunction#

View source

def region_rows(results, include=None, exclude=None, ranks=None, sort: str = 'start', percentage_mode: str = 'coverage') -> list

Build the summary rows for every region a result set exposes.

Parameters

results : ProfilingResults Source of the regions; loaded from a file or built in memory alike. include, exclude : list of str or str, optional Regex patterns selecting which regions to summarize. ranks : list of int, optional Restrict the statistics to these ranks (default: all). sort : str, optional One of :data:SORT_KEYS: start (default), total, calls, avg, min, max and std sort descending, name alphabetically. percentage_mode : {“coverage”, “exclusive”}, optional Quantity used for the % session column. Wall-clock coverage is the default; exclusive time can be selected for attribution-focused tables.