API — ppbcc.benchmark

API — ppbcc.benchmark#

Module Overview#

Benchmark discovery, execution, and report consolidation.

Discovery and Execution#

Discover and execute Google Benchmark targets.

ppbcc.benchmark.runner.find_files(search_dirs, patterns, require_executable=False, exclude=None)[source]#

Recursively search search_dirs for files whose path matches any of the given regular expressions.

Parameters:

  • search_dirs (list[Path]) – Directories to search recursively.

  • patterns (list[str]) – Regular expression patterns. A file is kept if any pattern matches (re.search) against its path.

  • require_executable (bool) – If True, only keep files with the executable bit set (used to locate benchmark binaries).

  • exclude (list[str] | None) – Regular expression patterns. A file is dropped if any of these matches (re.search) against its path, even if it matched a include pattern (e.g. ".*cpp.*").

Returns:

A sorted, de-duplicated list of resolved matching file paths.

Return type:

list[Path]

ppbcc.benchmark.runner.print_found_files(files, base, are_reports)[source]#

Pretty-print the discovered files as a boxed, numbered table (dry run).

Parameters:
Return type:

None

ppbcc.benchmark.runner.run_benchmarks(executables, force=False, json_prefix='', stream_output=False)[source]#

Run each benchmark executable, producing a <prefix><name>.json Google-Benchmark report in the current working directory.

Parameters:

  • executables (list[Path]) – Benchmark binaries to run.

  • force (bool) – Re-run even if a report already exists (otherwise it is reused).

  • json_prefix (str) – String prepended to each report file name (e.g. "intel_").

  • stream_output (bool) – If True, forward each executable’s stdout/stderr to the logger at TRACE level (enabled at -vv); otherwise it is discarded.

Returns:

The list of report files that exist after the run.

Return type:

list[Path]

Report Consolidation#

Normalize Google Benchmark JSON reports into tidy tables.

ppbcc.benchmark.reports.load_reports(report_files, hardware='')[source]#

Load and normalize a list of Google-Benchmark JSON reports.

Parameters:

  • report_files (list[Path]) – Paths to JSON report files.

  • hardware (str) – Free-form hardware identifier stored in the Hardware column (e.g. "RTX5080").

Returns:

A single tidy DataFrame (one row per benchmark run).

Return type:

DataFrame

Command Line Interface#

Command-line interface for benchmark execution and consolidation.

ppbcc.benchmark.cli.build_parser()[source]#

Build the benchmark command parser.

Returns:

Configured argument parser.

Return type:

ArgumentParser

ppbcc.benchmark.cli.main(argv=None)[source]#

Run the benchmark command.

Parameters:

argv (list[str] | None) – Command-line arguments, or None to read sys.argv.

Returns:

Process exit status.

Return type:

int