[draft] Workflow docs

docs/1-getting-started.rst

@@ -20,6 +20,9 @@ To install this, you can use::
 
     pip install -r requirements.txt
 
-Now you are ready to look at the benchmarks and systems available in Benchpark,
-as described in :doc:`2-benchpark-list`.
+The executable is in ``benchpark/bin``, to check the version you can run:: 
 
+    ./bin/benchpark --v
+
+Now you are ready to look at the benchmarks and systems available in Benchpark, 
+and determine your workflow as described in :doc:`2-benchpark-list`.

docs/2-benchpark-list.rst

@@ -7,7 +7,10 @@
 Searching Benchpark
 ===================
 
-The user can search for available system and experiment specifications in Benchpark.
+The easiest way to get started is to run existing experiments one existing systems, or 
+to modify one that is similar. You can search through the existing experiments and benchmarks with the below commands. 
+
+Search for available system and experiment specifications in Benchpark.
 
 .. list-table:: Searching for specifications in Benchpark
    :widths: 25 25 50
@@ -39,7 +42,6 @@ The user can search for available system and experiment specifications in Benchp
      -
 
 
-Once you have decided on a ``system`` you will use, and the ``benchmark/ProgrammingModel``
-to run, you can proceed to :doc:`4-benchpark-setup`.
-
 For a complete list of options, see the help menu in :doc:`benchpark-help`.
+
+Now that you know the existing benchmarks and systems, you can determine your necessary workflow in :doc:`3-benchpark-workflow`:

docs/3-benchpark-workflow.rst

@@ -0,0 +1,70 @@
+.. 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
+
+=================================
+Benchpark Workflow
+=================================
+
+Follow the workflow diagram to determine how many new configurations are required. 
+
+.. image:: /_static/images/new-workflow.png
+
+If you are running on an existing ``system``, and the ``benchmark`` and ``experiment`` are 
+already configured, you can proceed directly to :doc:`4-benchpark-setup`.
+
+Otherwise, you will be editing one or more of the files below.
+
+Benchpark configuration files are organized as follows::
+
+  $benchpark
+  ├── var
+  |  ├── exp_repo
+  |  |  └── experiments
+  |  |     └── ${BENCHMARK1}
+  |  |        └── experiment.py
+  |  └── sys_repo
+  |     └── systems
+  |        └── ${SYSTEM1}
+  |           ├── system.py
+  |           ├── compilers
+  |           └── externals
+  └── repo
+     ├── ${BENCHMARK1}
+     │  ├── application.py
+     │  └── package.py
+     └── repo.yaml
+
+
+
+System Specification
+--------------------
+Files under ``benchpark/var/sys_repo/systems/${SYSTEM}`` provide the specification
+of the software stack on your system:
+
+* Find a similar ``system``: :doc:`identifying-similar-system`
+
+* Add or edit a ``system``: :doc:`add-a-system-config`
+
+
+Benchmark Specification
+-----------------------
+If you would like to modify a specification of your benchmark,
+you can do so by upstreaming changes to Spack and/or Ramble,
+or working on your benchmark specification in ``benchpark/repo/${BENCHMARK}``:
+
+* Add a ``benchmark``: :doc:`add-a-benchmark`
+
+
+Experiment Specification
+------------------------
+Files under ``benchpark/var/exp_repo/experiments/${BENCHMARK}/${ProgrammingModel}``
+provide the specifications for the experiments.
+If you would like to make changes to your experiments,  such as enabling
+specific tools to measure the performance of your experiments,
+you can manually edit the specifications in ``ramble.yaml``:
+
+* Add/edit an ``experiment``: :doc:`add-an-experiment`
+
+

docs/5-build-experiment.rst

@@ -33,3 +33,5 @@ Ramble will build the source code and set up the following workspace directory s
 
 If you edit any of the files, see :doc:`FAQ-what-to-rerun` to determine
 whether you need to re-do any of the previous steps.
+
+Once that is complete, you are ready for :doc:`6-run-experiment`. 

docs/6-run-experiment.rst

@@ -42,3 +42,5 @@ Further, if the benchmark has restart capability, existing output may alter the
 benchpark would run in the second run.  Generally, we would advise the user to remove the
 ``$workspace/experiments`` directory before re-running the experiments using
 ``ramble -P -D . on``.
+
+Once you have run your experiment you can try :doc:`7-analyze-experiment`.

docs/add-a-benchmark.rst

@@ -7,7 +7,10 @@
 Adding a Benchmark
 ==================
 
-The following system-independent specification is required for each ${Benchmark1}:
+Add a New Benchmark
+------------------------
+
+The following system-independent specification is required for each ${Benchmark1} in ``benchpark/repo/${Benchmark1}``:
 
 - ``package.py`` is a Spack specification that defines how to build and install ${Benchmark1}.
 - ``application.py`` is a Ramble specification that defines the ${Benchmark1} input and parameters.
@@ -20,3 +23,9 @@ By default, Benchpark will use ${Benchmark1} specifications (``package.py`` and
 provided in the Spack and Ramble repos.
 It is possible to overwrite the benchmark specifications provided in the Spack and Ramble repos;
 see :doc:`FAQ-benchpark-repo` for details.
+
+
+Validate a Benchmark (Needed?)
+------------------------
+
+Now that the benchmark has been created/updated/validated you need to configure at least one experiment, see :doc:`add-an-experiment`.