X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e474b7f1374fa1ec39d4c5fc32a47baf4db3ded4..d546cc6688c4ec0100b9fbd30382c235876bf33a:/docs/source/Tutorial_Algorithms.rst diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst index 1b3f38b1d5..1c28510845 100644 --- a/docs/source/Tutorial_Algorithms.rst +++ b/docs/source/Tutorial_Algorithms.rst @@ -4,8 +4,8 @@ Simulating Algorithms ===================== SimGrid was conceived as a tool to study distributed algorithms. Its -modern :ref:`S4U interface ` makes it easy to assess Cloud, -P2P, HPC, IoT, and similar settings. +:ref:`S4U interface ` makes it easy to assess Cloud, +P2P, HPC, IoT, and other similar settings (:ref:`more info `). A typical SimGrid simulation is composed of several |Actors|_, that execute user-provided functions. The actors have to explicitly use the @@ -18,7 +18,7 @@ completion of these activities. Each actor executes a user-provided function on a simulated |Host|_ with which it can interact. Communications are not directly sent to -actors, but posted onto a |Mailbox|_ that serves as a rendezvous point +actors, but posted onto a |Mailbox|_ that serves as a rendez-vous point between communicating actors. .. |Actors| replace:: **Actors** @@ -62,8 +62,8 @@ fully-functioning example of SimGrid simulation: the Master/Workers application. We will detail each part of the code and the necessary configuration to make it work. After this tour, several exercises are proposed to let you discover some of the SimGrid features, hands -on the keyboard. This practical session will be given in C++, which you -are supposed to know beforehand. +on the keyboard. This practical session will be given in C++ or Python, +which you are supposed to know beforehand. Discover the Master/Workers @@ -93,7 +93,7 @@ host on which a worker is waiting for something to compute. Then, the tasks are sent one after the other, each on a mailbox named after the worker's hosts. On the other side, a given worker (which -code is given below) waits for incoming tasks on its +code is given below) waits for incoming tasks on its mailbox. @@ -201,7 +201,7 @@ This time, we have all parts: once the program is compiled, we can execute it as follows. Note how the XBT_INFO() requests turned into informative messages. -.. "WARNING: Over dedent has detected" is expected here as we remove the $ marker this way +.. "WARNING: non-whitespace stripped by dedent" is expected here as we remove the $ marker this way .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh :language: shell @@ -308,10 +308,10 @@ The easiest way to take the tutorial is to use the dedicated Docker image. Once you `installed Docker itself `_, simply do the following: -.. code-block:: shell +.. code-block:: console - docker pull simgrid/tuto-s4u - docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash + $ docker pull simgrid/tuto-s4u + $ docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash This will start a new container with all you need to take this tutorial, and create a ``simgrid-tutorial`` directory in your home on @@ -334,34 +334,38 @@ The code template is available under ``/source/simgrid-template-s4u.git`` in the image. You should copy it to your working directory and recompile it when you first log in: -.. code-block:: shell +.. code-block:: console - cp -r /source/simgrid-template-s4u.git/* /source/tutorial - cd /source/tutorial - cmake . - make + $ cp -r /source/simgrid-template-s4u.git/* /source/tutorial + $ cd /source/tutorial + $ cmake . + $ make Using your Computer Natively ............................ -To take the tutorial on your machine, you first need to :ref:`install +To take the tutorial on your machine, you first need to :ref:`install a recent version of SimGrid `, a C++ compiler, and also ``pajeng`` to visualize the traces. You may want to install `Vite `_ to get a first glance at the traces. The provided code template requires CMake to compile. On Debian and Ubuntu for example, you can get them as follows: -.. code-block:: shell +.. code-block:: console - sudo apt install simgrid pajeng cmake g++ vite + $ sudo apt install simgrid pajeng cmake g++ vite For R analysis of the produced traces, you may want to install R and the `pajengr `_ package. -.. code-block:: shell +.. code-block:: console - sudo apt install r-base r-cran-devtools cmake flex bison - Rscript -e "library(devtools); install_github('schnorr/pajengr');" + # install R and necessary packages + $ sudo apt install r-base r-cran-devtools r-cran-tidyverse + # install pajengr dependencies + $ sudo apt install git cmake flex bison + # install the pajengr R package + $ Rscript -e "library(devtools); install_github('schnorr/pajengr');" An initial version of the source code is provided on framagit. This template compiles with CMake. If SimGrid is correctly installed, you @@ -369,15 +373,15 @@ should be able to clone the `repository `_ and recompile everything as follows: -.. code-block:: shell +.. code-block:: console # (exporting SimGrid_PATH is only needed if SimGrid is installed in a non-standard path) - export SimGrid_PATH=/where/to/simgrid + $ export SimGrid_PATH=/where/to/simgrid - git clone https://framagit.org/simgrid/simgrid-template-s4u.git - cd simgrid-template-s4u/ - cmake . - make + $ git clone https://framagit.org/simgrid/simgrid-template-s4u.git + $ cd simgrid-template-s4u/ + $ cmake . + $ make If you struggle with the compilation, then you should double-check your :ref:`SimGrid installation `. On need, please refer to @@ -389,16 +393,16 @@ Discovering the Provided Code Please compile and execute the provided simulator as follows: -.. code-block:: shell +.. code-block:: console - make master-workers - ./master-workers small_platform.xml master-workers_d.xml + $ make master-workers + $ ./master-workers small_platform.xml master-workers_d.xml For a more "fancy" output, you can use simgrid-colorizer. -.. code-block:: shell +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer + $ ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer If you installed SimGrid to a non-standard path, you may have to specify the full path to simgrid-colorizer on the above line, such as @@ -410,10 +414,10 @@ For a classical Gantt-Chart visualization, you can use `Vite follows. But do not spend too much time installing Vite, because there is a better way to visualize SimGrid traces (see below). -.. code-block:: shell +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes - vite simgrid.trace + $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes + $ vite simgrid.trace .. image:: /tuto_s4u/img/vite-screenshot.png :align: center @@ -428,10 +432,10 @@ to use R. As a start, you can download this `starter script `_ and use it as follows: -.. code-block:: shell +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes - Rscript draw_gantt.R simgrid.trace + $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes + $ Rscript draw_gantt.R simgrid.trace It produces a ``Rplots.pdf`` with the following content: @@ -455,7 +459,7 @@ using the worker location (which should be filled in two locations), we could use their ID (which should be filled in one location only). -This could be done with the following deployment file. It's +This could be done with the following deployment file. It's not shorter than the previous one, but it's still simpler because the information is only written once. It thus follows the `DRY `_ `SPOT @@ -490,7 +494,7 @@ Wrap up The mailboxes are a very powerful mechanism in SimGrid, allowing many interesting application settings. They may feel unusual if you are used to BSD sockets or other classical systems, but you will soon -appreciate their power. They are only used to match +appreciate their power. They are only used to match communications but have no impact on the communication timing. ``put()`` and ``get()`` are matched regardless of their initiators' location and then the real communication occurs between @@ -601,11 +605,7 @@ simulation. Instead, retrieve the time in the simulated world with :cpp:func:`simgrid::s4u::Engine::get_clock`. You can still stop your workers with a specific task as previously, -or you may kill them forcefully with -:cpp:func:`simgrid::s4u::Actor::kill` (if you already have a reference -to the actor you want to kill) or -:cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` (if you only have its ID). - +or you may kill them forcefully with :cpp:func:`simgrid::s4u::Actor::kill`. Anyway, the new deployment `deployment3.xml` file should thus look like this: @@ -623,9 +623,9 @@ every 100 tasks and ``XBT_DEBUG`` when sending all the other tasks. Or you could show only the total number of tasks processed by default. You can still see the debug messages as follows: -.. code-block:: shell +.. code-block:: console - ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug + $ ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug Lab 4: Competing Applications