From 108fe27c4634954104e4b3ea867bbf952a9a2ed9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Madon?= <mael.madon@irit.fr>
Date: Wed, 19 Jun 2024 10:15:25 +0200
Subject: [PATCH] doc: update README and root of the documentation
---
README.md | 43 -------------------------------------------
README.rst | 34 ++++++++++++++++++++++++++++++++++
docs/dev/user_simu.md | 18 ++++++++++++++++++
docs/index.rst | 16 +++++++++-------
4 files changed, 61 insertions(+), 50 deletions(-)
delete mode 100644 README.md
create mode 100644 README.rst
create mode 100644 docs/dev/user_simu.md
diff --git a/README.md b/README.md
deleted file mode 100644
index 6104b9f..0000000
--- a/README.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Batmen
-
-Batmen is a plugin to the scientific simulator [Batsim].
-It allows simulating users of large-scale distributed systems.
-Batmen is originally a fork of [batsched].
-
-## How does it work?
-
-
-
-A simulation with [Batsim] consists of two processes:
-- Batsim itself, in charge of reading an input workload and **simulating the platform** (job arrival, job termination, energy consumed...)
-- a scheduler, in charge of **making the scheduling decisions**. The scheduler communicates with Batsim via a ZeroMQ socket through messages defined in [Batsim protocol](https://batsim.readthedocs.io/en/latest/protocol.html).
-
-In Batmen, we added a layer: **the simulation of users**.
-
-### User simulation
-The interaction with users happens through a "broker". The broker manages a pool of simulated users and dynamically register new jobs to submit. These jobs come on top of the input workload read by Batsim.
-
-Implementation, in the folder `src/users`:
-- class `Broker`: implement the broker, submitting the jobs on behalf of the users
-- class `DynScheduler`: superclass managing the interaction with the broker from the scheduler
-- class `User`: an individual user, submitting her jobs to the broker
-
-### Types of user
-
-For now, we have developed three types of users.
-
-- *modeled users* (class `User`): using a model to generate the jobs to submit
-- *replay users* (class `ReplayUser`): replaying a workload trace given as input
-- *feedback users* (class `FeedbackUser`): taking feedback on the status of previous jobs into account when submitting the next one
-
-
-
-
-
-
-
-
-[Nix]: https://nixos.org/nix/
-[Batsim]: https://batsim.org/
-[batsched]: https://framagit.org/batsim/batsched
-[Batmen doc]: https://batmen.readthedocs.io/en/latest/
\ No newline at end of file
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..8ac86a1
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,34 @@
+Batmen
+======
+
+Batmen is a plugin to the scientific simulator `Batsim <https://batsim.org/>`_.
+It allows the simulation of **users** (bat-men) of large-scale distributed systems.
+Batmen is originally a fork of `batsched <https://framagit.org/batsim/batsched>`_.
+
+How does is work?
+-----------------
+
+.. image:: ./batmen_diagram.svg
+ :alt: Batmen diagram
+
+A simulation with Batmen has to be launched in parallel with Batsim.
+
+* Batsim takes care of **simulating the IT platform** (job arrival, job termination, energy consumed...), thanks to the underlying simulator `SimGrid <https://simgrid.org/>`_.
+* Batmen simulates the **users of the system**, through their **job submission behavior**. It also simulates the **scheduler**.
+
+Documentation
+-------------
+For more information, refer to `Batmen documentation <https://batmen.readthedocs.io>`_.
+
+
+Aknowledgments
+--------------
+Batmen was developped mainly by Maël Madon during his PhD thesis.
+The most up-to-date description can be found in Chapter II of the `thesis manuscript <https://cloud.irit.fr/s/ZjafxKO0YnaMqpK>`_ (and more precisely in Section II.2.2).
+It was used to carry scientific experimental campains, leading to several peer-reveiwed publications:
+
+* `Europar'22 <https://doi.org/10.1007/978-3-031-12597-3_4>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Characterization of Different User Behaviors for Demand Response in Data Centers"*
+* `FGCS'24 <https://doi.org/10.1016/j.future.2024.01.024>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Replay with Feedback: How Does the Performance of HPC System Impact User Submission Behavior?"*
+* ICT4S'24: Jolyne Gatt, Maël Madon, and Georges Da Costa. *"Digital Sufficiency Behaviors to Deal with Intermittent Energy Sources in a Data Center"*
+
+If you use Batmen for your work, please cite one of these.
\ No newline at end of file
diff --git a/docs/dev/user_simu.md b/docs/dev/user_simu.md
new file mode 100644
index 0000000..1e61a43
--- /dev/null
+++ b/docs/dev/user_simu.md
@@ -0,0 +1,18 @@
+# User simulation
+The interaction with users happens through a "broker".
+The broker manages a pool of simulated users and dynamically register new jobs to submit.
+These jobs come on top of the input workload read by Batsim.
+
+Implementation, in the folder `src/users`:
+
+- class `Broker`: implement the broker, submitting the jobs on behalf of the users
+- class `DynScheduler`: superclass managing the interaction with the broker from the scheduler
+- class `User`: an individual user, submitting her jobs to the broker
+
+## Types of user
+
+For now, we have developed three types of users.
+
+- *modeled users* (class `User`): using a model to generate the jobs to submit
+- *replay users* (class `ReplayUser`): replaying a workload trace given as input
+- *feedback users* (class `FeedbackUser`): taking feedback on the status of previous jobs into account when submitting the next one
diff --git a/docs/index.rst b/docs/index.rst
index 222bb20..178c5ae 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,7 @@ Welcome to Batmen's documentation!
Batmen is a plugin to the scientific simulator `Batsim <https://batsim.org/>`_.
It allows the simulation of **users** (bat-men) of large-scale distributed systems.
+Batmen is originally a fork of `batsched <https://framagit.org/batsim/batsched>`_.
How does is work?
-----------------
@@ -21,21 +22,21 @@ A simulation with Batmen has to be launched in parallel with Batsim.
* Batmen simulates the **users of the system**, through their **job submission behavior**. It also simulates the **scheduler**.
Batmen was developped mainly by Maël Madon during his PhD thesis.
-The most up-to-date description can be found in Chapter II of the thesis manuscript (and more precisely in Section II.2.2).
+The most up-to-date description can be found in Chapter II of the `thesis manuscript <https://cloud.irit.fr/s/ZjafxKO0YnaMqpK>`_ (and more precisely in Section II.2.2).
It was used to carry scientific experimental campains, leading to several peer-reveiwed publications:
* `Europar'22 <https://doi.org/10.1007/978-3-031-12597-3_4>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Characterization of Different User Behaviors for Demand Response in Data Centers"*
* `FGCS'24 <https://doi.org/10.1016/j.future.2024.01.024>`_: Maël Madon, Georges Da Costa, and Jean-Marc Pierson. *"Replay with Feedback: How Does the Performance of HPC System Impact User Submission Behavior?"*
* ICT4S'24: Jolyne Gatt, Maël Madon, and Georges Da Costa. *"Digital Sufficiency Behaviors to Deal with Intermittent Energy Sources in a Data Center"*
-If you use it for your work, please cite one of these.
+If you use Batmen for your work, please cite one of these.
-This documentation is divided in two parts, user and developer manual:
+This present documentation is divided in two parts, user and developer manual:
.. toctree::
:maxdepth: 1
- :caption: User manual:
+ :caption: User manual
user/installation.md
user/first_simu.md
@@ -44,8 +45,9 @@ This documentation is divided in two parts, user and developer manual:
.. toctree::
:maxdepth: 1
- :caption: Developer manual:
+ :caption: Developer manual
+ dev/user_simu.md
+ dev/scheduler.md
dev/tests.md
- dev/documentation.md
- dev/scheduler.md
\ No newline at end of file
+ dev/documentation.md
\ No newline at end of file
--
GitLab