From f87e5645280151d126a1a2950cd91380fdf1a472 Mon Sep 17 00:00:00 2001
From: Guillaume Raffy <guillaume.raffy@univ-rennes1.fr>
Date: Fri, 10 Jun 2022 08:39:22 +0200
Subject: [PATCH] reorganized files and documented

---
 .ipr/readme.md                                |  1 -
 README.md                                     | 24 +++++++++++++++++++
 .ipr/starbench.py => starbench.py             |  0
 {.ipr => usecases/ipr}/hibench-on-physix.sh   |  4 ++--
 usecases/ipr/readme.md                        | 15 ++++++++++++
 {.ipr => usecases/ipr}/starbench-template.job |  0
 6 files changed, 41 insertions(+), 3 deletions(-)
 delete mode 100644 .ipr/readme.md
 rename .ipr/starbench.py => starbench.py (100%)
 rename {.ipr => usecases/ipr}/hibench-on-physix.sh (97%)
 create mode 100644 usecases/ipr/readme.md
 rename {.ipr => usecases/ipr}/starbench-template.job (100%)

diff --git a/.ipr/readme.md b/.ipr/readme.md
deleted file mode 100644
index 27e876d..0000000
--- a/.ipr/readme.md
+++ /dev/null
@@ -1 +0,0 @@
-This directory contains scripts for hibridon that are specific to IPR (Institut de Physique de Rennes)
diff --git a/README.md b/README.md
index b2df71e..9655f37 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,26 @@
 # starbench
 a tool to benchmark a git cmake application using embarassingly parallel runs
+
+`starbench` is a tool designed to build and test the performance of an application versioned in a `git` repository and using the `cmake` build system.
+
+In order to measure the performance of the code in *hpc* (high performance computing) environment, `starbench` is designed to make all the cores busy. For this, it uses the same technique as in `hpl`'s `stardgemm` test (that's where the 'star' prefix comes from): the same code is run on each `CPU` core. This way, we performances measures are expected to be more realistic, as the cores won't benefit from the unrealistic boost provided by the memory cache of unued cores.
+
+If the user provides:
+- the `url` of the repository
+- the commit number of the version to test
+- the number of cores the benchmark should use (usually the number of cores of the machine that executes the benchmark)
+- the benchmark command to use
+
+then `starbench` will do the rest:
+1. clone the repository to a temporary location
+2. checkout the requested version
+3. configure the build
+4. build the code
+5. run the becnhmark command for each core
+6. output the average duration of the benchmark
+
+## example
+
+```sh
+starbench.py --git-repos-url https://github.com/hibridon/hibridon --code-version a3bed1c3ccfbca572003020d3e3d3b1ff3934fad --git-user g-raffy --git-pass-file "$HOME/.github/personal_access_tokens/bench.hibridon.cluster.ipr.univ-rennes1.fr.pat" --num-cores 2 --output-dir=/tmp/hibench --cmake-path=/opt/cmake/cmake-3.23.0/bin/cmake --cmake-option=-DCMAKE_BUILD_TYPE=Release --cmake-option=-DBUILD_TESTING=ON --benchmark-command='ctest --output-on-failure -L ^arch4_quick$'
+```
diff --git a/.ipr/starbench.py b/starbench.py
similarity index 100%
rename from .ipr/starbench.py
rename to starbench.py
diff --git a/.ipr/hibench-on-physix.sh b/usecases/ipr/hibench-on-physix.sh
similarity index 97%
rename from .ipr/hibench-on-physix.sh
rename to usecases/ipr/hibench-on-physix.sh
index ff1e8e4..af0a3fc 100755
--- a/.ipr/hibench-on-physix.sh
+++ b/usecases/ipr/hibench-on-physix.sh
@@ -19,8 +19,8 @@ then
 fi
 
 HIBRIDON_VERSION="$1"  # the version of hibridon to test, in the form of a valid commit number eg 'a3bed1c3ccfbca572003020d3e3d3b1ff3934fad'
-# 'a3bed1c3ccfbca572003020d3e3d3b1ff3934fad'  # latest from branch master as of 01/06/2022 12:52
-# code_version='775048db02dfb317d5eaddb6d6db520be71a2fdf'  # latest from branch graffy-issue51 as of 01/06/
+# '53894da48505892bfa05693a52312bacb12c70c9'  # latest from branch master as of 10/06/2022 00:30
+# code_version='dd0f413b85cf0f727a5a4e88b2b02d75a28b377f'  # latest from branch graffy-issue51 as of 10/06/2022 00:30
 
 SCRIPT_DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]:-$0}"; )" &> /dev/null && pwd 2> /dev/null; )";
 
diff --git a/usecases/ipr/readme.md b/usecases/ipr/readme.md
new file mode 100644
index 0000000..a5650d8
--- /dev/null
+++ b/usecases/ipr/readme.md
@@ -0,0 +1,15 @@
+This example illustrates how `starbench` is used at IPR (Institut de Physique de Rennes) to measure the performance of [hibridon](https://github.com/hibridon/hibridon) on IPR's cluster (`physix`)
+
+usage:
+
+```sh
+graffy@physix-frontal:/opt/ipr/cluster/work.global/graffy/starbench$ ./hibench-on-physix.sh 53894da48505892bfa05693a52312bacb12c70c9
+```
+
+`hibench-on-physix.sh` script launches two `sge` jobs for each machine type in `physix` cluster:
+- one job that performs a benchmark of hibridon with `gfortran` compiler
+- one job that performs a benchmark of hibridon with `ifort` compiler
+
+When the job successfully completes, it puts the results of the benchmark on `physix`'s global work directory (eg `/opt/ipr/cluster/work.global/graffy/hibridon/benchmarks/starbench/53894da48505892bfa05693a52312bacb12c70c9/nh3h2_qma_long/intel_xeon_x5550/gfortran`)
+
+
diff --git a/.ipr/starbench-template.job b/usecases/ipr/starbench-template.job
similarity index 100%
rename from .ipr/starbench-template.job
rename to usecases/ipr/starbench-template.job