Command Line Interface

Everything is reachable through the single ppbcc executable:

ppbcc <command> [options]

ppbcc code-complexity SOURCES...   # Halstead / LOC metrics
ppbcc benchmark -r REGEX...        # run and consolidate benchmarks
ppbcc profile -r REGEX...          # profile kernels (ncu or likwid), roofline model
ppbcc p2analysis PLOT CSV...       # efficiency and portability plots
ppbcc p3analysis PLOT COMPLEXITY_CSV CSV...  # portability over code complexity

The package can also be run as a module:

python -m ppbcc code-complexity src/ -o report.csv

Tip

The tables below list the options you reach for most often, not every option. Run ppbcc <command> --help (or -h) for the exhaustive, always-current list.

ppbcc code-complexity

Halstead complexity and LOC/SLOC metrics for C++ and GPU-enriched C++.

Option	Meaning
sources	Files and/or directories; directories are searched recursively for known source extensions
-d, --dialect	auto (default, per-file detection), cpp (baseline only), or names like kokkos,openmp
-m, --metrics	Metric selection, e.g. halstead, loc, sloc, dialect (default: all)
--diff	Add baseline_*/delta_* columns: metrics with all dialect tokens removed, and the delta
--aggregate	Append a TOTAL row; operator/operand sets are merged before recomputing
-o, --output	Write the table to this CSV file
--list-dialects	List all known dialects and their aliases, then exit

Details and examples: Code Complexity.

ppbcc benchmark

Run Google Benchmark targets and consolidate their JSON reports into one CSV.

Option	Meaning
-b, --build-dir	Build folder used as the working directory for the whole pipeline
-p, --path	Directories searched recursively, relative to --build-dir
-r, --regex	Required. Pattern(s) matched against file paths to select executables (or JSON reports)
-x, --exclude	Pattern(s) excluding matched paths, e.g. '.*_cpp'
-s, --skip-benchmark	Do not run anything; locate existing JSON reports and only consolidate them
-n, --dry-run	List the matched executables (or reports) and exit
-H, --hardware	Value stored in the Hardware column, e.g. "NVIDIA RTX5080"
-o, --output	Base name of the consolidated CSV (defaults to a timestamped name)

Details and examples: Benchmarking.

ppbcc profile

Batch-profile GPU kernels and draw a roofline model. Expects executables built with -DPPB_PROFILING=ON. --profiler picks the backend: ncu (default, one row per kernel launch) or likwid (one row per marked region, needs -DPPB_ENABLE_LIKWID=ON too).

Option	Meaning
-b, --build-dir	Build folder used as the working directory for the whole pipeline
-p, --path / -r, --regex / -x, --exclude	Executable discovery, exactly as for ppbcc benchmark (--regex is required)
-d, --report-dir	Where the profiler artefacts are written (default: profiling)
--profiler	ncu (default), nsys, ngfx or likwid
--profiler-path	Path to that backend’s CLI; found automatically otherwise
-O, --option	NAME=VALUE setting of the selected backend; --help lists the names
--from-csv	Skip profiling and plot from consolidated CSVs, merging several backends
-s, --skip-profile	Run nothing; only re-parse the artefacts already in --report-dir
--timeout	Wall-clock limit per executable; a run that hits it is skipped
-m, --memory-level	Level the arithmetic intensity refers to: dram (default), l2, l1
--precision	auto (default, follows the build), fp32, fp64, fp16
--region	Plot only the regions matching a pattern, e.g. --region evaluate
--all-kernels	Keep the launches outside every named region (dropped by default)
-a, --aggregate	sum (default), dominant, or none — how launches become plot points
--roofline [PATH]	Render the roofline chart, optionally to a given path
-l, --no-legend	Leave the paradigm legend out of the roofline chart
--no-csv	Skip the consolidated CSV (for a pure collection run)
--peak-performance / --peak-bandwidth	Roofline ceilings for the backends without peak_sustained counters
--analytic-flop	REGEX=FLOP work model for nsys/ngfx
-H, --hardware / -o, --output	Hardware label and base name of the consolidated CSV

Details and examples: Kernel Profiling & Roofline.

ppbcc p2analysis / ppbcc p3analysis

Application efficiency, performance portability, and plots from benchmark CSVs. p2analysis renders the charts that need benchmark results only, p3analysis those that also need code complexity.

ppbcc p2analysis PLOT CSV [CSV ...] [options]
ppbcc p3analysis PLOT COMPLEXITY_CSV CSV [CSV ...] [options]

Option	Meaning
PLOT	p2analysis: cascade, heatmap, double-heatmap, boxplot, time-barplot; p3analysis: navchart, combined, complexity-comparison, rank-correlation
COMPLEXITY_CSV	p3analysis only: code-complexity CSV with one row per implementation
CSV	One or more CSVs produced by ppbcc benchmark
-n, --name	Benchmark problem to plot; exact case-insensitive match preferred, unique substring okay. May be omitted when the CSVs contain exactly one problem. rank-correlation takes a comma-separated list and defaults to every problem in the CSVs
-c, --complexity-metric	p3analysis only: SLOC, Halstead vocabulary/length/volume/difficulty/effort (default: halstead-difficulty)
--complexity-metric-absolute	p3analysis only: plot absolute values instead of a percentage of the plain-C++ score
--compare-metric	x-axis metric of complexity-comparison (default: sloc); -c is its y axis
--log-complexity	p3analysis only: logarithmic complexity axes
--correlation	rank-correlation only: the variable whose paradigm ordering is correlated — pp (default) or a complexity metric such as halstead-difficulty or sloc
-s, --size	all (default), an exact size, or avg/best/worst
--average-over	With -s avg: average \(\Phi\) over sizes (pp, default) or compute \(\Phi\) from size-averaged efficiencies (efficiency)
--non-zero-pp	Compute \(\Phi\) over supported platforms only
-x, --exclude / -i, --include	Regex filters on the Description column
-H, --hardware	p2analysis only: restrict a boxplot or time-barplot to one platform
-t, --time	time-barplot only: wall-clock (default), kernel, force-update, neighbor-search
--normalize-time-to-peak	time-barplot only: multiply runtimes by the platform’s published peak FLOP/s
--remove-description	Drop bracketed labels such as [Naive]; efficiency charts combine variants by paradigm
-l, --legend	Save the legend as a separate PDF (add --legend--vertical for a single column)
-e, --export-to-csv	Also export efficiency and portability data as CSV; p3analysis adds every complexity metric
-o, --output	Output path; defaults to <problem>_<chart>.pdf, or .csv for rank-correlation

Details and examples: P3 Analysis and Available Plots.

Option compatibility

Not every option applies to every chart, and the CLI rejects invalid combinations rather than silently ignoring them:

Option	Valid for
--complexity-metric-absolute	navchart, combined; complexity-comparison always compares percentages of the plain-C++ baseline and rejects it
--compare-metric	complexity-comparison only
--correlation	rank-correlation only
-l, --legend / --remove-description / --log-complexity	every chart except rank-correlation, which writes a CSV table instead of a figure and always ranks paradigms
-H, --hardware	boxplot, time-barplot
-t, --time / --normalize-time-to-peak	time-barplot only
-s avg/best/worst	every chart except boxplot (needs all or a numeric size) and time-barplot (needs a numeric size; all means the largest)

Logging

All commands log through loguru at INFO by default. -v raises the level to DEBUG, -vv to TRACE.