reorganized files and documented

.ipr/readme.md

@@ -1 +0,0 @@
-This directory contains scripts for hibridon that are specific to IPR (Institut de Physique de Rennes)

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$'
+```

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; )";
 

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`)
+
+