From 6c9a2cbaab59057503d455e0212fe460e135a3ae Mon Sep 17 00:00:00 2001
From: Millian Poquet <millian.poquet@irit.fr>
Date: Thu, 9 May 2024 23:33:24 +0200
Subject: [PATCH] artifact guide++
---
artifact-overview.typ | 180 +++++++++++++++++++++++++++++++-----------
1 file changed, 132 insertions(+), 48 deletions(-)
diff --git a/artifact-overview.typ b/artifact-overview.typ
index f041e80..ee7332f 100644
--- a/artifact-overview.typ
+++ b/artifact-overview.typ
@@ -11,7 +11,7 @@
)
#set heading(numbering: "1.1.")
-#let emph-overhead(x) = text(fill: rgb("ff0000"), weight: "semibold", x)
+#let emph-overhead(x) = text(fill: rgb("ff0000").darken(30%), weight: "semibold", x)
#let fullbox(content, ..args) = showybox(..args,
frame: (
@@ -45,7 +45,8 @@
}
#set par(justify: true)
-#show link: x => underline(offset: 0.5mm, stroke: .25mm, text(font: "DejaVu Sans Mono", weight: "semibold", size: 9.5pt, fill: blue, x))
+#show link: x => underline(offset: 0.5mm, stroke: .25mm, text(weight: "semibold", fill: blue, x))
+#let url(x) = link(x)[#raw(x)]
#let todo = todo.with(inline: true)
#[
@@ -62,12 +63,12 @@
#set align(left)
*Conference.* Euro-Par 2024\
*Article.* Light-weight prediction for improving energy consumption in HPC platforms\
- *Links*.
+ *Quick links*.
#set list(marker: none, body-indent: 5mm)
- - Preprint on HAL (long-term). #link("https://hal.science/hal-04566184")
- - Artifact data on Zenodo (long-term). #todo([zenodo link])
- - Artifact code on Software Heritage (long-term). #todo([software heritage link])
- - Artifact code on the author's GitLab instance. #todo([git link])
+ - Preprint PDF on HAL. #url("https://hal.science/hal-04566184")
+ - Artifact data on Zenodo. #todo([zenodo link])
+ - Artifact code on Software Heritage. #todo([software heritage link])
+ - Artifact code on a GitLab instance. #todo([git link])
#line(length:100%, stroke: .5mm)
]
@@ -116,35 +117,51 @@ As of 2024-05-07 the recommended command to install Nix (on a Linux system runni
Please note that you may need to launch a new shell, to source a file or to modify your shell configuration script as indicated by the Nix installer.
-*Test your installation.* Launching `nix-shell --version` should run and print you the Nix version installed.
+*Testing your Nix installation.*
+- Launching `nix-shell --version` should run successfully and print you the Nix version you have installed.
+- Launching `nix-build --version` should run successfully and print you the Nix version you have installed.
== Enable Nix flakes <enable-nix-flakes>
Our Nix packages rely on #link("https://nixos.wiki/wiki/Flakes")[Nix flakes], which are not enabled by default as of 2024-05-07.
Nix flakes must be enabled to use the software we have packaged.
-We recommend to use #link("https://nixos.wiki/wiki/Flakes")[up-to-date documentation on how to enable flakes], but we also explain how to install it as of 2024-05-07 below. Please note that the way to enable flakes depend on whether you are on NixOS or not.
+We recommend to use #link("https://nixos.wiki/wiki/Flakes")[up-to-date documentation on how to enable flakes].
+However for the sake of this artifact guide self-containedness, steps to enable flakes are given below.
+Please note that the way to enable flakes depend on whether you are on NixOS or not.
-#grid(
+#table(
columns: (1fr, 1fr),
- column-gutter: 5mm,
+ column-gutter: 1mm,
+ stroke: (x,y) => {
+ if x == 0 {
+ (right: 1pt+black)
+ }
+ else { none }
+ },
[
- *If you are using NixOS* and as of 2024-05-07, flakes can be enabled by setting at least the `nix-command` and `flakes` experimental settings in your system configuration file. In other words, your NixOS configuration file should have content similar to the one in the box below.
+ If *you are using NixOS*
+ flakes can be enabled by setting at least the `nix-command` and `flakes` Nix experimental settings in your Nix#underline[OS] configuration file.
+ In other words, your Nix#underline[OS] configuration file should have a content similar to the following.
+ #set align(bottom+left)
#{
- rect(stroke: (thickness: .1mm, dash: "densely-dashed"), fill: luma(97%), outset:1mm)[
+ rect(stroke: (thickness: .05mm), fill: luma(97%), outset:0mm)[
```nix
- nix.settings.experimental-features = [ "nix-command" "flakes" ];
+ nix.settings.experimental-features = [
+ "nix-command" "flakes"
+ ];
```
]
}
],
[
- If you are *not using NixOS*, as of 2024-05-07, flakes can be enabled by setting at least the `nix-command` and `flakes` `experimental-features` in your Nix configuration file.
- The Nix configuration file path is `~/.config/nix/nix.conf` on non-NixOS Linuxes.
- In other words, your Nix configuration file should have content similar to the one in the box below.
+ If you are *not using NixOS*
+ flakes can be enabled by setting at least the `nix-command` and `flakes` `experimental-features` in your #underline[Nix] configuration file.
+ The #underline[Nix] configuration file path is `~/.config/nix/nix.conf` on non-NixOS Linuxes.
+ In other words, your #underline[Nix] configuration file should have content similar to the one below.
+ #set align(bottom+right)
#{
- set align(right)
- rect(stroke: (thickness: .1mm, dash: "densely-dashed"), fill: luma(97%), outset:1mm)[
+ rect(stroke: (thickness: .05mm), fill: luma(97%), outset:0mm)[
```nix
experimental-features = nix-command flakes
```
@@ -153,7 +170,11 @@ We recommend to use #link("https://nixos.wiki/wiki/Flakes")[up-to-date documenta
]
)
-*Test your flakes configuration.* Launching `nix build 'github:nixos/nixpkgs?ref=23.11#hello'` should create a `result` symbolic link in your current directory. Then, launching `./result/bin/hello` should print `Hello, world!`.
+*Testing your Nix flakes.*
+- Launching `nix --version` should run successfully and print you the Nix version you have installed.
+- Launching `nix flake --version` should run successfully and print you the Nix version you have installed.
+- Launching `nix build 'github:nixos/nixpkgs?ref=23.11#hello'` should create a `result` symbolic link in your current directory. Then, launching `./result/bin/hello` should print `Hello, world!`.
+- Launching `nix shell 'github:nixos/nixpkgs?ref=23.11#hello' --command hello` should print `Hello, world!`.
== Configure Nix to use our binary cache
This step is completely optional but recommended for this artifact reviewers, as it enables to download precompiled versions of our software environments instead of building them on your own machine.
@@ -163,27 +184,49 @@ This step is completely optional but recommended for this artifact reviewers, as
== Version traceability
#todo[dump all envs versions]
-
-
= Step-by-Step Instructions
+All the scripts strongly related to the experiments of Article @lightpredenergy are available on #todo[git repo].
+The repository can be cloned with the following command.
+This repository might be updated, so for traceability please note that this guide expects the artifacts commit to be #todo[git repo commit].
-#todo[clone repo]
+#fullbox[
+ ```sh
+ git clone
+ cd ?????
+ git checkout ????
+ ```
+ #todo[git repo]
+]
-#todo[introduce data caches on zenodo]
+*All commands* below should be executed from the *root of the cloned Git repository*.
-#todo[introduce how commands should be run (root of cloned repo)]
+The step-by-step instructions of this document can be used in several ways depending on *your* goals.
++ You can *check* the final analyses (code + plots) done in Article @lightpredenergy by reading the provided pre-rendered notebooks.
++ You can *reproduce* the *final analyses* by first downloading the provided aggregated results the experiments, and then by running the notebooks yourself.
+ Notebooks are editable so you can freely modify the analyses done, or add your own.
++ You can *reproduce* our *experimental campaigns* by downloading the provided input files, and then by running the experiment yourself.
+ This can enable you to make sure that our experiment can be reproduced with the *exact same parameters and configuration*.
++ You can reproduce our *experimental campaigns* by downloading original traces of the Marconi100,
+ by generating the experimental campaigns parameters yourself (enabling you to hacking provided command-line parameters or provided code),
+ and then by running the experiment yourself.\
+ *Please note that this option is disk/bandwidth/computation-intensive.*
-#todo[propose paths in the graph depending on what the reproducer wants to do]
+The following instructions detail how to reproduce our work from scratch if done in order (goal 4).
-== Trace analysis??
+== Trace analysis #todo[remove section?]
== Job power prediction <sec-job-power-pred>
-*Inputs.* ???\
-*Outputs.*
-- Job power predictions for all prediction methods. #todo[cache mean/max power prediction tarballs]
+#todo[Millian to Danilo : comment regénérer les tarballs ?]
-== Modeling of the power behavior of Marconi100 nodes
-#todo[introduce this section]
+#fullbox[
+ #todo[Millian to Danilo : commandes pour regénérer les tarballs]
+ #filehashes((
+ "fdcc47998a7e998abde325162833b23e", "power_pred_users_allmethods_max.tar.gz",
+ "954f782a75c9a5b21c53a95c0218e220", "power_pred_users_allmethods_mean.tar.gz",
+ ))
+]
+
+== Analysis and modeling of the power behavior of Marconi100 nodes
=== Get power and job Marconi100 traces on your disk <sec-m100-power-job-traces>
This section downloads parts of the Marconi100 trace as archives from Zenodo, checks that the archives have the right content (via a md5 checksum), extracts the data needed by later stages of the pipeline (node power usage traces, jobs information traces), then removes unneeded extracted files and the downloaded archives.
@@ -215,8 +258,12 @@ This section downloads parts of the Marconi100 trace as archives from Zenodo, ch
))
]
-=== Aggregate power traces per node
+=== Aggregate power traces per node <sec-agg-power-traces-per-node>
The following command traverses all the Marconi100 power traces and counts how many times each node was at each power value.
+
+Required input files.
+- All parquet files outputted by @sec-m100-power-job-traces.
+
#fullbox(footer:[Disk: 1 Mo. Time: 00:03:00.])[
```sh
nix develop .#py-scripts --command \
@@ -229,7 +276,12 @@ The following command traverses all the Marconi100 power traces and counts how m
]
=== Analyze Marconi100 power traces <sec-analyze-m100-power-traces>
-#fullbox(footer:[Disk: 1.7 Mo. Time: 00:00:10])[
+The following commands runs a notebook that analyses the node power consumption of the Marconi100 trace.
+
+Required input files.
+- `m100-data/22-agg_power_total.csv` (output of @sec-agg-power-traces-per-node).
+
+#fullbox(footer:[Disk: 1.7 Mo. Time (laptop): 00:00:10])[
```sh
nix develop .#r-notebook --command \
Rscript notebooks/run-rmarkdown-notebook.R \
@@ -245,11 +297,13 @@ The following command traverses all the Marconi100 power traces and counts how m
This section shows how to reproduce Sections 6.4 and 6.5 of article @lightpredenergy.
=== Prepare all the files required to run the simulation
-==== Generate a SimGrid platform
+==== Generate a SimGrid platform <sec-gen-sg-platform>
The following command generates the SimGrid platform used for the simulations.
-This requires a power model of the Marconi100 nodes (as outputted by @sec-analyze-m100-power-traces).
-#fullbox(footer:[Time: ])[
+Required input files.
+- `m100-data/22-powermodel_total.csv`, the M100 node power model (output of @sec-analyze-m100-power-traces).
+
+#fullbox(footer:[Time: 00:00:01.])[
```sh
nix develop .#py-scripts --command \
m100-generate-sg-platform ./m100-data/22-powermodel_total.csv 100 \
@@ -260,9 +314,12 @@ This requires a power model of the Marconi100 nodes (as outputted by @sec-analyz
"b5c28261bbe6bcea017ac03b1ef97bd9", "expe-sched/m100-platform.xml",
))
]
-==== Generate simulation instances
+==== Generate simulation instances <sec-gen-simu-instances>
The following commands generate workload parameters (_i.e._, when each workload should start and end). The start points are taken randomly during the 2022 M100 trace.
+Required input files.
+- `expe-sched/m100-platform.xml` (output of @sec-gen-sg-platform).
+
#fullbox(footer:[Disk: 1.3 Mo. Time: 00:00:01.])[
```sh
nix develop .#py-scripts --command \
@@ -296,11 +353,15 @@ To make things more convenient for the generation of simulation inputs, all the
./m100-data/22-job-power-estimations.csv
rm -rf ./user-power-predictions/tmp
```
+
+ #filehashes((
+ "86a056a9d61cca59b80adf95fa8bff22", "./m100-data/22-job-power-estimations.csv",
+ ))
]
Similarly, Marconi100 job traces are also merged into a single file.
-#fullbox(footer: [Final disk used: 343 Mo. Time: 00:02:00.])[
+#fullbox(footer: [Final disk: 343 Mo. Time: 00:02:00.])[
```sh
nix develop .#py-scripts --command \
m100-agg-jobs-info ./m100-data/ ./m100-data/22-jobs.csv \
@@ -310,14 +371,17 @@ Similarly, Marconi100 job traces are also merged into a single file.
./m100-data/22-jobs.csv \
./m100-data/22-jobs-with-prediction.csv
```
+
+ #filehashes((
+ "c7d00104663b13e2992ec10749d6a162", "m100-data/22-jobs-with-prediction.csv"
+ ))
]
-==== Generate workloads
+==== Generate workloads <sec-gen-workloads>
The following command generates all the workloads needed by the simulation.
-*This step is very long!*
-#todo[zenodo]
+*This step is very long, even while using all cores of powerful computation nodes!*
-#fullbox(footer: [#emph-overhead[Time: 05:30:00.]])[
+#fullbox(footer: [#emph-overhead[Disk: 1.4 Go. Time: 05:30:00.]])[
```sh
nix develop .#py-scripts --command \
m100-generate-expe-workloads ./expe-sched/workload-params.json \
@@ -334,12 +398,19 @@ The following command generates all the workloads needed by the simulation.
]
-=== Run the simulation campaign
+=== Run the simulation campaign <sec-run-simu-campaign>
The following command runs the whole simulation campaign.
-This requires that you have generated or downloaded simulation instances: file `./expe-sched/simu-instances.json` should exist.
-This requires that you have generated or downloaded workloads: directory `/tmp/wlds` should exist and contain #box([$tilde.eq$ 1.4 Go]).
+The main results of the simulations are aggregated _in situ_ into a single file.
+Details about each simulation are stored in the `/tmp/simout` directory, one subdirectory per simulation instance --
+please refer to `expe-sched/simu-instances.json` for the mapping from unique simulation instances to the simulation parameters.
+
+Required input files.
+- `expe-sched/m100-platform.xml`, the SimGrid platform file (output of @sec-gen-sg-platform).
+- `expe-sched/simu-instances.json`, the set of simulation instances (output of @sec-gen-simu-instances).
+- The `/tmp/wlds` directory (#emph-overhead[1.4 Go]) that contains all the workload files (output of @sec-gen-workloads).\
+ #todo[zenodo workloads]
-#fullbox(footer: [Time: 00:06:00.])[
+#fullbox(footer: [#emph-overhead[Disk: 7.6 Go.] Time: 00:06:00.])[
```sh
nix develop .#simulation --command \
m100-run-batsim-instances \
@@ -349,15 +420,28 @@ This requires that you have generated or downloaded workloads: directory `/tmp/w
--output_state_file ./expe-sched/simu-campaign-exec-state.json \
--output_result_file ./expe-sched/simu-campaign-agg-result.csv
```
+
+ #filehashes((
+ "2f31cf5a3ca6b2f46a2d426c9558f351", "expe-sched/simu-campaign-agg-result.csv"
+ ))
]
=== Analyze the simulation campaign outputs
-#fullbox(footer:[Time on a low-performance laptop: 00:00:30.])[
+The following command runs a notebook that analyze the aggregated results of the simulation campaign, and outputs Figure 4 and Figure 5 of Article @lightpredenergy.
+
+Required input files.
+- `expe-sched/simu-campaign-agg-result.csv`, the simulation campaign main output of @sec-run-simu-campaign.
+
+#fullbox(footer:[Time (laptop): 00:00:30.])[
```sh
nix develop .#r-notebook --command \
Rscript notebooks/run-rmarkdown-notebook.R \
notebooks/simulation-output-analysis.Rmd
```
+
+ #filehashes((
+ "1d59a49dd3b1a1e8c10ee01aef11e644", "notebooks/simulation-output-analysis.html",
+ ))
]
#bibliography("artifact-bib.yml")
--
GitLab