docs/source/usecase_algorithms.rst

   1 .. _usecase_simalgo:
   2
   3 Simulating Algorithms
   4 =====================
   5
   6 SimGrid was conceived as a tool to study distributed algorithms. Its
   7 modern S4U interface makes it easy to assess Cloud, P2P, HPC, IoT and
   8 similar settings.
   9
  10 A typical SimGrid simulation is composed of several **Actors**
  11 |api_s4u_Actor|_ , that execute user-provided functions. The actors
  12 have to explicitly use the S4U inteface to express their computation,
  13 communication, disk usage and other **Activities** |api_s4u_Activity|_
  14 , so that they get reflected within the simulator. These activities
  15 take place on **Resources** (CPUs, links, disks). SimGrid predicts the
  16 time taken by each activity and orchestrates accordingly the actors
  17 waiting for the completion of these activities.
  18
  19 .. |api_s4u_Actor| image:: /images/extlink.png
  20    :align: middle
  21    :width: 12
  22 .. _api_s4u_Actor: api/classsimgrid_1_1s4u_1_1Actor.html#class-documentation
  23
  24 .. |api_s4u_Activity| image:: /images/extlink.png
  25    :align: middle
  26    :width: 12
  27 .. _api_s4u_Activity: api/classsimgrid_1_1s4u_1_1Activity.html#class-documentation
  28
  29
  30 Each actor executes a user-provided function on a simulated **Host**
  31 |api_s4u_Host|_ with which it can interact. Communications are not
  32 directly sent to actors, but posted onto **Mailboxes**
  33 |api_s4u_Mailbox|_ that serve as rendez-vous points between
  34 communicating processes.
  35
  36 .. |api_s4u_Host| image:: /images/extlink.png
  37    :align: middle
  38    :width: 12
  39 .. _api_s4u_Host: api/classsimgrid_1_1s4u_1_1Host.html#class-documentation
  40
  41 .. |api_s4u_Mailbox| image:: /images/extlink.png
  42    :align: middle
  43    :width: 12
  44 .. _api_s4u_Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation
  45
  46
  47 The Master/Workers Example
  48 --------------------------
  49
  50 This section introduces a first example of SimGrid simulation. This
  51 simple application is composed of two kind of actors: the **master**
  52 is in charge of distributing some computational tasks to a set of
  53 **workers** that execute them.
  54
  55 .. image:: /images/tuto-masterworkers-intro.svg
  56    :align: center
  57
  58 We first present a round-robin version of this application, where the
  59 master dispatches the tasks to the workers, one after the other, until
  60 all tasks are dispatched. Later in this tutorial, you will be given
  61 the opportunity to improve this scheme.
  62
  63 The Actors
  64 ..........
  65
  66 Let's start with the code of the worker. It is represented by the
  67 *master* function below. This simple function takes 4 parameters,
  68 given as a vector of strings:
  69
  70    - the number of workers managed by the master.
  71    - the number of tasks to dispatch
  72    - the computational size (in flops to compute) of each task
  73    - the communication size (in bytes to exchange) of each task
  74
  75 Then, the tasks are sent one after the other, each on a mailbox named
  76 "worker-XXX" where XXX is the number of an existing worker. On the
  77 other side, a given worker (which code is given below) wait for
  78 incomming tasks on its own mailbox. Notice how this mailbox mechanism
  79 allow the actors to find each other without having all information:
  80 the master don't have to know the actors nor even where they are, it
  81 simply pushes the messages on mailbox which name is predetermined.
  82
  83 At the end, once all tasks are dispatched, the master dispatches
  84 another task per worker, but this time with a negative amount of flops
  85 to compute. Indeed, this application decided by convention, that the
  86 workers should stop when encountering such a negative compute_size.
  87
  88 At the end of the day, the only SimGrid specific functions used in
  89 this example are :func:`simgrid::s4u::Mailbox::by_name` and
  90 :func:`simgrid::s4u::Mailbox::put`. Also, XBT_INFO() is used as a
  91 replacement to printf() or to cout to ensure that the messages are
  92 nicely loggued along with the simulated time and actor name.
  93
  94
  95 .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
  96    :language: c++
  97    :start-after: master-begin
  98    :end-before: master-end
  99
 100 Here comes the code of the worker actors. This function expects only one
 101 parameter from its vector of strings: its identifier so that it knows
 102 on which mailbox its incomming tasks will arrive. Its code is very
 103 simple: as long as it gets valid computation requests (whose
 104 compute_amount is positive), it compute this task and waits for the
 105 next one.
 106
 107 .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
 108    :language: c++
 109    :start-after: worker-begin
 110    :end-before: worker-end
 111
 112 Starting the Simulation
 113 .......................
 114
 115 And this is it. In only a few lines, we defined the algorithm of our
 116 master/workers examples. Well, this is true, but an algorithm alone is
 117 not enough to define a simulation.
 118
 119 First, SimGrid is a library, not a program. So you need to define your
 120 own `main()` function, as follows. This function is in charge of
 121 creating a SimGrid simulation engine (on line 3), register the actor
 122 functions to the engine (on lines 7 and 8), load the virtual platform
 123 from its description file (on line 11), map actors onto that platform
 124 (on line 12) and run the simulation until its completion on line 15.
 125
 126 .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
 127    :language: c++
 128    :start-after: main-begin
 129    :end-before: main-end
 130    :linenos:
 131
 132 After that, the missing pieces are the platform and deployment
 133 files.
 134
 135 Platform File
 136 .............
 137
 138 Platform files define the virtual platform on which the provided
 139 application will take place. In contains one or several **Network
 140 Zone** |api_s4u_NetZone|_ that contain both **Host-** |api_s4u_Host|_
 141 and **Link-** |api_s4u_Link|_ Resources, as well as routing
 142 information.
 143
 144 Such files can get rather long and boring, so the example below is
 145 only an excerpts of the full ``examples/platforms/small_platform.xml``
 146 file. For example, most routing information are missing, and only the
 147 route between the hosts Tremblay and Fafard is given. This path
 148 traverses 6 links (4, 3, 2, 0, 1 and 8). The full file, along with
 149 other examples, can be found in the archive under
 150 ``examples/platforms``.
 151
 152 .. |api_s4u_NetZone| image:: /images/extlink.png
 153    :align: middle
 154    :width: 12
 155 .. _api_s4u_NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html#class-documentation
 156
 157 .. |api_s4u_Link| image:: /images/extlink.png
 158    :align: middle
 159    :width: 12
 160 .. _api_s4u_Link: api/classsimgrid_1_1s4u_1_1Link.html#class-documentation
 161
 162 .. literalinclude:: ../../examples/platforms/small_platform.xml
 163    :language: xml
 164    :lines: 1-10,12-20,56-63,192-
 165    :caption: (excerpts of the small_platform.xml file)
 166
 167 Deployment File
 168 ...............
 169
 170 Deployment files specify the execution scenario: it lists the actors
 171 that should be started, along with their parameter. In the following
 172 example, we start 6 actors: one master and 5 workers.
 173
 174 .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers_d.xml
 175    :language: xml
 176
 177 Execution Example
 178 .................
 179
 180 This time, we have all parts: once the program is compiled, we can
 181 execute it as follows. Note how the XBT_INFO() requests turned into
 182 informative messages.
 183
 184 .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers.tesh
 185    :language: shell
 186    :start-after: s4u-app-masterworkers-fun
 187    :prepend: $$$ ./masterworkers platform.xml deploy.xml
 188    :append: $$$
 189    :dedent: 2
 190
 191
 192 ..  LocalWords:  SimGrid