..
    Copyright 2023 Lawrence Livermore National Security, LLC and other
    Benchpark Project Developers. See the top-level COPYRIGHT file for details.

    SPDX-License-Identifier: Apache-2.0

#########################
 Analyze a Scaling Study
#########################

**Glossary terms:** :ref:`Benchmark <beginner-tutorial-glossary-benchmark>`,
:ref:`Experiment <beginner-tutorial-glossary-experiment>`, :ref:`System
<beginner-tutorial-glossary-system>`, :ref:`Modifier
<beginner-tutorial-glossary-modifier>`, :ref:`Scaling Study
<beginner-tutorial-glossary-scaling-study>`

.. tutorialcontainer:: tutorial-prerequisite-links

    .. tutorialcontainer:: tutorial-prerequisite-link tutorial-prerequisite-experiment

        :doc:`Prerequisite: Build and Run an Experiment <build-and-run-experiment>`

Install the analysis dependencies once from the Benchpark repository:

.. code-block:: console

    $ pip install .[analyze]

Analyze the completed HPL scaling study from :doc:`build-and-run-experiment`:

****************
 Strong Scaling
****************

The default stacked area chart shows the exclusive average time per rank for each
instrumented region. The x-axis records the node and MPI-rank counts varied in the
strong-scaling study.

.. code-block:: console

    $ benchpark analyze --workspace-dir workspace/aws-tutorial/hpl/workspace

.. figure:: /_static/images/hpl_mpi_strong_raw_exc.png
    :width: 800
    :align: center

    Strong-scaling area chart.

************
 Percentage
************

The percentage chart expresses each region's metric relative to the sum for all regions.
This makes each region's share of total time easier to compare.

.. code-block:: console

    $ benchpark analyze --workspace-dir workspace/aws-tutorial/hpl/workspace --chart-type percentage

.. figure:: /_static/images/hpl_mpi_strong_percentage_exc.png
    :width: 800
    :align: center

    Strong-scaling data shown as a percentage of total time.

*******************
 Inclusive Metrics
*******************

The inclusive chart uses ``Avg time/rank`` instead of ``Avg time/rank (exc)``.

.. code-block:: console

    $ benchpark analyze --workspace-dir workspace/aws-tutorial/hpl/workspace --yaxis-metric "Avg time/rank"

.. figure:: /_static/images/hpl_mpi_strong_raw.png
    :width: 800
    :align: center

    Strong-scaling data using an inclusive metric.

******************
 Region Filtering
******************

This figure combines regions that have the same name, then retains the regions with the
highest metric values. The filtered view emphasizes the regions that contribute most to
the measured time.

.. code-block:: console

    $ benchpark analyze --workspace-dir workspace/aws-tutorial/hpl/workspace --group-regions-name --top-n-regions 10

.. figure:: /_static/images/hpl_mpi_strong_raw_exc_region.png
    :width: 800
    :align: center

    Strong-scaling data after filtering regions.

For additional chart types and filtering options, see :doc:`/benchpark-analyze`.

***********************
 Choose Your Next Step
***********************

.. tutorialcontainer:: tutorial-next-steps

    .. tutorialcontainer:: tutorial-next-step tutorial-goal-search

        :ref:`I have generated preconfigured performance figures for an experiment on
        my system. I want to begin another workflow by searching what is available in
        Benchpark. <search-benchpark>`