ppbcc — Performance Portability, Benchmarking & Code Complexity
===============================================================

.. image:: https://img.shields.io/badge/python-3.12%2B-blue
   :alt: Python 3.12+
.. image:: https://img.shields.io/badge/license-MIT-green
   :alt: MIT License

**ppbcc** is the tooling half of a performance-portability study of GPU
programming paradigms. The benchmark implementations it analyses live in the
companion repository
`performance-portability-benchmark <https://github.com/schuhmaj/performance-portability-benchmark>`__,
which implements the same four algorithms — vector addition, matrix
multiplication, an n-body simulation, and a polyhedral gravity model — across
CUDA, HIP, SYCL, Kokkos, RAJA, Alpaka, OpenMP, OpenACC, OpenCL, Vulkan,
Boost.Compute, WebGPU, Slang, Metal, and ``stdpar``.

This package provides four workflows:

* :doc:`Code complexity <usage/code_complexity>` — Halstead and LOC/SLOC
  metrics for C++ and *GPU-enriched* C++. This part is **stand-alone**: it
  needs nothing but the source files you point it at.
* :doc:`Benchmarking <usage/benchmark>` — discover and run Google Benchmark
  executables and consolidate their JSON reports into one tidy CSV.
* :doc:`Kernel profiling <usage/profiling>` — batch-run Nvidia Nsight Compute
  over the same executables and build a roofline model from the counters.
* :doc:`P3 analysis and plotting <usage/plots>` — application efficiency,
  performance portability, and five chart types that relate both to code
  complexity.

Credits
-------

The performance-portability metrics and the Cascade/Navchart layouts are
inspired by the
`P3 Analysis Library <https://github.com/P3HPC/p3-analysis-library>`__ by
Pennycook et al. If you use this tool, please also have a look at their
performance-portability analysis in published work, as this work builds upon
theirs.

``ppbcc`` rests on two bodies of work:

* **Code complexity** — Halstead's software science [Halstead1977]_, the basis
  of :doc:`usage/code_complexity`.
* **Performance portability** — the :math:`\Phi` metric and its visualizations
  [Pennycook2019]_ [Pennycook2021]_, the basis of :doc:`usage/p3analysis`.

.. toctree::
   :caption: INSTALLATION & QUICK START
   :maxdepth: 2

   quickstart/installation
   quickstart/overview
   quickstart/cli

.. toctree::
   :caption: USAGE
   :maxdepth: 2

   usage/code_complexity
   usage/benchmark
   usage/profiling
   usage/p3analysis
   usage/plots

.. toctree::
   :caption: API REFERENCE
   :maxdepth: 2

   api/code_complexity
   api/benchmark
   api/profiling
   api/performance_portability
   api/plot

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`