docs/source/Tutorial_DAG.rst

   1 .. _simdag:
   2
   3 Simulating DAG
   4 ==============
   5
   6 This tutorial presents the basics to understand how DAG are represented in Simgrid and how to simulate their workflow.
   7
   8 Definition of a DAG
   9 -------------------
  10
  11 Directed Acyclic Graph:
  12
  13 .. math::
  14
  15    \mathcal{G} = (\mathcal{V},\mathcal{E})
  16
  17 Set of vertices representing :ref:`Activities <API_s4u_Activity>`:
  18
  19 .. math::
  20
  21    \mathcal{V} = {v_i | i = 1, ..., V}
  22
  23 Set of edges representing precedence constraints between :ref:`Activities <API_s4u_Activity>`:
  24
  25 .. math::
  26
  27    \mathcal{E} = {e_i,j | (i,j) \in {1, ..., V} x {1, ..., V}}
  28
  29 .. image:: /img/dag.svg
  30    :align: center
  31
  32 Representing Vertices/Activities
  33 ................................
  34
  35 There is two types of :ref:`Activities <API_s4u_Activity>` that can represent Vertices: :ref:`Exec <API_s4u_Exec>` and :ref:`Comm <API_s4u_Comm>`.
  36 Thoses activities must be initiated and configured to properly describe your worflow.
  37
  38 An Exec represents the execution of an amount of flop on a :ref:`Host <API_s4u_Host>` of your platform.
  39
  40 .. code-block:: cpp
  41
  42    ExecPtr exec = Exec::init();
  43    exec->set_flops_amount(int);
  44    exec->set_host(Host*);
  45    exec->start();
  46
  47 A Comm represents a data transfer between two :ref:`Hosts <API_s4u_Host>` of your platform.
  48
  49 .. code-block:: cpp
  50
  51    CommPtr comm = Comm::sendto_init();
  52    comm->set_source(Host*);
  53    comm->set_destination(Host*);
  54    comm->start();
  55
  56 Representing Edges/Dependencies
  57 ...............................
  58
  59 An activity will not start until all of its dependencies have been completed.
  60 Activities may have any number of successors.
  61 Dependencies between Activities are created using :cpp:func:`simgrid::s4u::Activity::add_successor`.
  62
  63 .. code-block:: cpp
  64
  65    exec->add_successor(comm);
  66
  67 The Activity ``comm`` will not start until ``exec`` has been completed.
  68
  69 Lab 1: Basics
  70 ---------------
  71
  72 The goal of this lab is to describe the following DAG:
  73
  74 .. image:: /img/dag1.svg
  75    :align: center
  76
  77 In this DAG we want ``c1`` to compute 1e9 flops, ``c2`` to compute 5e9 flops and ``c3`` to compute 2e9 flops.
  78 There is also a data transfer of 5e8 bytes between ``c1`` and ``c3``.
  79
  80 First of all, include the Simgrid library and define the log category.
  81
  82 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
  83    :language: cpp
  84    :lines: 6-8
  85
  86 Inside the ``main`` function create an instance of :ref:`Engine <API_s4u_Engine>` and load the platform.
  87
  88 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
  89    :language: cpp
  90    :lines: 12-13
  91
  92 Retrieve pointers to some hosts.
  93
  94 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
  95    :language: cpp
  96    :lines: 15-16
  97
  98 Initiate the activities.
  99
 100 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 101    :language: cpp
 102    :lines: 18-21
 103
 104 Give names to thoses activities.
 105
 106 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 107    :language: cpp
 108    :lines: 23-26
 109
 110 Set the amount of work for each activity.
 111
 112 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 113    :language: cpp
 114    :lines: 28-31
 115
 116 Define the dependencies between the activities.
 117
 118 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 119    :language: cpp
 120    :lines: 33-35
 121
 122 Set the location of each Exec activity and source and destination for the Comm activity.
 123
 124 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 125    :language: cpp
 126    :lines: 37-41
 127
 128 Start the executions of Activities without dependencies.
 129
 130 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 131    :language: cpp
 132    :lines: 43-44
 133
 134 Add a callback to monitor the activities.
 135
 136 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 137    :language: cpp
 138    :lines: 46-49
 139
 140 Finally, run the simulation.
 141
 142 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.cpp
 143    :language: cpp
 144    :lines: 51
 145
 146 The execution of this code should give you the following output:
 147
 148 .. literalinclude:: ../../examples/cpp/dag-tuto/s4u-dag-tuto.tesh
 149    :language: none
 150    :lines: 4-
 151 Lab 2: Import a DAG from a file
 152 -------------------------------
 153
 154 In this lab we present how to import a DAG into you Simgrid simulation, either using a DOT file, a JSON file, or a DAX file.
 155
 156 The files presented in this lab describe the following DAG:
 157
 158 .. image:: /img/dag2.svg
 159    :align: center
 160
 161 From a DOT file
 162 ...............
 163
 164 A DOT file describes a workflow in accordance with the graphviz format.
 165
 166 The following DOT file describes the workflow presented at the beginning of this lab:
 167
 168 .. literalinclude:: ../../examples/cpp/dag-from-dot-simple/dag.dot
 169    :language: dot
 170
 171 It can be imported as a vector of Activities into Simgrid using :cpp:func:`simgrid::s4u::create_DAG_from_DOT`. Then, you have to assign hosts to your Activities.
 172
 173 .. literalinclude:: ../../examples/cpp/dag-from-dot-simple/s4u-dag-from-dot-simple.cpp
 174    :language: cpp
 175
 176 The execution of this code should give you the following output:
 177
 178 .. literalinclude:: ../../examples/cpp/dag-from-dot-simple/s4u-dag-from-dot-simple.tesh
 179    :language: none
 180    :lines: 4-
 181
 182 From a JSON file
 183 ................
 184
 185 A JSON file describes a workflow in accordance with the `wfformat <https://github.com/wfcommons/wfformat>`_ .
 186
 187 The following JSON file describes the workflow presented at the beginning of this lab:
 188
 189 .. literalinclude:: ../../examples/cpp/dag-from-json-simple/dag.json
 190    :language: json
 191
 192 It can be imported as a vector of Activities into Simgrid using :cpp:func:`simgrid::s4u::create_DAG_from_json`.
 193
 194 .. literalinclude:: ../../examples/cpp/dag-from-json-simple/s4u-dag-from-json-simple.cpp
 195    :language: cpp
 196
 197 The execution of this code should give you the following output:
 198
 199 .. literalinclude:: ../../examples/cpp/dag-from-json-simple/s4u-dag-from-json-simple.tesh
 200    :language: none
 201    :lines: 4-
 202
 203 From a DAX file [deprecated]
 204 ............................
 205
 206 A DAX file describes a workflow in accordance with the `Pegasus <http://pegasus.isi.edu/>`_ format.
 207
 208 The following DAX file describes the workflow presented at the beginning of this lab:
 209
 210 .. literalinclude:: ../../examples/cpp/dag-from-dax-simple/dag.xml
 211    :language: xml
 212
 213 It can be imported as a vector of Activities into Simgrid using :cpp:func:`simgrid::s4u::create_DAG_from_DAX`.
 214
 215 .. literalinclude:: ../../examples/cpp/dag-from-dax-simple/s4u-dag-from-dax-simple.cpp
 216    :language: cpp