..
    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

#############################
 Build and Run an Experiment
#############################

**Glossary terms:** :ref:`Benchmark <beginner-tutorial-glossary-benchmark>`,
:ref:`Experiment <beginner-tutorial-glossary-experiment>`, :ref:`System
<beginner-tutorial-glossary-system>`

Before initializing the system, open ``experiments/hpl/experiment.py`` and configure the
``exec_mode=test`` branch to use one MPI rank and a problem size of 1,000:

.. code-block:: python

    if self.spec.satisfies("exec_mode=test"):
        self.add_experiment_variable("n_ranks", 1, True)
        self.add_experiment_variable("Ns", 1000, True)

Initialize the AWS tutorial system and the HPL experiment. The explicit instance type
matches the `Benchpark tutorial infrastructure
<https://github.com/llnl/benchpark-tutorial>`_:

.. code-block:: console

    $ benchpark system init --dest=aws-tutorial aws-tutorial instance_type=c7i.12xlarge
    $ benchpark experiment init --dest=hpl aws-tutorial hpl+strong caliper=time,mpi

Create the experiment workspace:

.. code-block:: console

    $ benchpark setup aws-tutorial/hpl workspace

The ``setup.sh`` script generated by ``benchpark setup`` activates Benchpark's Spack and
Ramble environments:

.. code-block:: console

    $ . workspace/setup.sh

Set up the Ramble workspace to build HPL and generate each experiment instance, then run
the experiments:

.. code-block:: console

    $ ramble --workspace-dir workspace/aws-tutorial/hpl/workspace workspace setup
    $ ramble --workspace-dir workspace/aws-tutorial/hpl/workspace on

For workspace structure and additional build options, see :doc:`/build-experiment`. For
individual experiment instances, rerunning experiments, and combining workspaces into
one allocation, see :doc:`/run-experiment`.

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

.. tutorialcontainer:: tutorial-next-steps

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

        :ref:`I have run an experiment someone gave me on the same system. I want to
        start another workflow by searching what is available in Benchpark.
        <search-benchpark>`

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

        :doc:`I want to analyze the performance of an experiment on my system by
        generating preconfigured performance figures. <benchpark-analyze>`

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

        :doc:`I want to generate raw performance data to make my own figures.
        <benchpark-query>`