docs/source/Platform_examples.rst

   1 .. raw:: html
   2
   3    <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
   4    <script>
   5    window.onload=function() { // Wait for the SVG to be loaded before changing it
   6      var elem=document.querySelector("#TOC").contentDocument.getElementById("ExamplesBox")
   7      elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
   8    }
   9    </script>
  10    <br/>
  11    <br/>
  12
  13 .. _platform_examples:
  14
  15 Network Topology Examples
  16 =========================
  17
  18 .. _platform_example_3hosts:
  19
  20 Simple Example with 3 hosts
  21 ---------------------------
  22
  23 Imagine you want to describe a little platform with three hosts,
  24 interconnected as follows:
  25
  26 .. image:: /tuto_smpi/3hosts.png
  27    :align: center
  28
  29 This can be done with the following platform file, that considers the
  30 simulated platform as a graph of hosts and network links.
  31
  32 .. literalinclude:: /tuto_smpi/3hosts.xml
  33    :language: xml
  34
  35 The elements basic elements (with :ref:`pf_tag_host` and
  36 :ref:`pf_tag_link`) are described first, and then the routes between
  37 any pair of hosts are explicitly given with :ref:`pf_tag_route`.
  38
  39 Any host must be given a computational speed in flops while links must
  40 be given a latency and a bandwidth. You can write 1Gf for
  41 1,000,000,000 flops (full list of units in the reference guide of
  42 :ref:`pf_tag_host` and :ref:`pf_tag_link`).
  43
  44 Routes defined with :ref:`pf_tag_route` are symmetrical by default,
  45 meaning that the list of traversed links from A to B is the same as
  46 from B to A. Explicitly define non-symmetrical routes if you prefer.
  47
  48 The last thing you must know on SimGrid platform files is that the
  49 root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
  50 does not match what SimGrid expects, you will be hinted to use to the
  51 ``simgrid_update_xml`` utility to update your file.
  52
  53 There is often more than one way to model a given platform. For example, the above platform could also be
  54 :ref:`expressed using a shortest path algorithm <platform_rm_shortest>` instead of explicitely listing all routes as in
  55 the example above.
  56
  57 Cluster with a Crossbar
  58 -----------------------
  59
  60 A very common parallel computing platform is a homogeneous cluster in
  61 which hosts are interconnected via a crossbar switch with as many
  62 ports as hosts, so that any disjoint pairs of hosts can communicate
  63 concurrently at full speed. For instance:
  64
  65 .. literalinclude:: ../../examples/platforms/cluster_crossbar.xml
  66    :language: xml
  67    :lines: 1-3,18-
  68
  69 One specifies a name prefix and suffix for each host, and then give an
  70 integer range. In the example the cluster contains 65535 hosts (!),
  71 named ``node-0.simgrid.org`` to ``node-65534.simgrid.org``. All hosts
  72 have the same power (1 Gflop/sec) and are connected to the switch via
  73 links with same bandwidth (125 MBytes/sec) and latency (50
  74 microseconds).
  75
  76 .. todo::
  77
  78    Add the picture.
  79
  80 Cluster with a Shared Backbone
  81 ------------------------------
  82
  83 Another popular model for a parallel platform is that of a set of
  84 homogeneous hosts connected to a shared communication medium, a
  85 backbone, with some finite bandwidth capacity and on which
  86 communicating host pairs can experience contention. For instance:
  87
  88
  89 .. literalinclude:: ../../examples/platforms/cluster_backbone.xml
  90    :language: xml
  91    :lines: 1-3,18-
  92
  93 The only differences with the crossbar cluster above are the ``bb_bw``
  94 and ``bb_lat`` attributes that specify the backbone characteristics
  95 (here, a 500 microseconds latency and a 2.25 GByte/sec
  96 bandwidth). This link is used for every communication within the
  97 cluster. The route from ``node-0.simgrid.org`` to ``node-1.simgrid.org``
  98 counts 3 links: the private link of ``node-0.simgrid.org``, the backbone
  99 and the private link of ``node-1.simgrid.org``.
 100
 101 .. todo::
 102
 103    Add the picture.
 104
 105 Torus Cluster
 106 -------------
 107
 108 Many HPC facilities use torus clusters to reduce sharing and
 109 performance loss on concurrent internal communications. Modeling this
 110 in SimGrid is very easy. Simply add a ``topology="TORUS"`` attribute
 111 to your cluster. Configure it with the ``topo_parameters="X,Y,Z"``
 112 attribute, where ``X``, ``Y`` and ``Z`` are the dimension of your
 113 torus.
 114
 115 .. image:: ../../examples/platforms/cluster_torus.svg
 116    :align: center
 117
 118 .. literalinclude:: ../../examples/platforms/cluster_torus.xml
 119    :language: xml
 120
 121 Note that in this example, we used ``loopback_bw`` and
 122 ``loopback_lat`` to specify the characteristics of the loopback link
 123 of each node (i.e., the link allowing each node to communicate with
 124 itself). We could have done so in previous example too. When no
 125 loopback is given, the communication from a node to itself is handled
 126 as if it were two distinct nodes: it goes twice through the private
 127 link and through the backbone (if any).
 128
 129 .. _platform_examples_fattree:
 130
 131 Fat-Tree Cluster
 132 ----------------
 133
 134 This topology was introduced to reduce the amount of links in the
 135 cluster (and thus reduce its price) while maintaining a high bisection
 136 bandwidth and a relatively low diameter. To model this in SimGrid,
 137 pass a ``topology="FAT_TREE"`` attribute to your cluster. The
 138 ``topo_parameters=#levels;#downlinks;#uplinks;link count`` follows the
 139 semantic introduced in the `Figure 1B of this article
 140 <http://webee.eedev.technion.ac.il/wp-content/uploads/2014/08/publication_574.pdf>`_.
 141
 142 Here is the meaning of this example: ``2 ; 4,4 ; 1,2 ; 1,2``
 143
 144 - That's a two-level cluster (thus the initial ``2``).
 145 - Routers are connected to 4 elements below them, regardless of its
 146   level. Thus the ``4,4`` component that is used as
 147   ``#downlinks``. This means that the hosts are grouped by 4 on a
 148   given router, and that there is 4 level-1 routers (in the middle of
 149   the figure).
 150 - Hosts are connected to only 1 router above them, while these routers
 151   are connected to 2 routers above them (thus the ``1,2`` used as
 152   ``#uplink``).
 153 - Hosts have only one link to their router while every path between a
 154   level-1 routers and level-2 routers use 2 parallel links. Thus the
 155   ``1,2`` that is used as ``link count``.
 156
 157 .. image:: ../../examples/platforms/cluster_fat_tree.svg
 158    :align: center
 159
 160 .. literalinclude:: ../../examples/platforms/cluster_fat_tree.xml
 161    :language: xml
 162    :lines: 1-3,10-
 163
 164 .. todo:
 165
 166    Model some other platforms, for example from https://link.springer.com/article/10.1007/s11227-019-03142-8
 167
 168 Dragonfly Cluster
 169 -----------------
 170
 171 This topology was introduced to further reduce the amount of links
 172 while maintaining a high bandwidth for local communications. To model
 173 this in SimGrid, pass a ``topology="DRAGONFLY"`` attribute to your
 174 cluster. It's based on the implementation of the topology used on
 175 Cray XC systems, described in paper
 176 `Cray Cascade: A scalable HPC system based on a Dragonfly network <https://dl.acm.org/citation.cfm?id=2389136>`_.
 177
 178 System description follows the format ``topo_parameters=#groups;#chassis;#routers;#nodes``
 179 For example, ``3,4 ; 3,2 ; 3,1 ; 2``:
 180
 181 - ``3,4``: There are 3 groups with 4 links between each (blue level).
 182   Links to nth group are attached to the nth router of the group
 183   on our implementation.
 184 - ``3,2``: In each group, there are 3 chassis with 2 links between each nth router
 185   of each group (black level)
 186 - ``3,1``: In each chassis, 3 routers are connected together with a single link
 187   (green level)
 188 - ``2``: Each router has two nodes attached (single link)
 189
 190 .. image:: ../../examples/platforms/cluster_dragonfly.svg
 191    :align: center
 192
 193 .. literalinclude:: ../../examples/platforms/cluster_dragonfly.xml
 194    :language: xml
 195
 196
 197 Star Zone
 198 ---------
 199
 200 In a Star topology, as the name says, nodes are organized following a star.
 201 It's similar to a cluster topology but you have the flexibility to set
 202 different route for every component in the star.
 203 Unfortunately, it's only available in the C++ interface.
 204
 205 .. image:: img/starzone.svg
 206     :scale: 80%
 207     :align: center
 208
 209 The particularity of this zone is how routes are declared. Instead of declaring the
 210 source and destination, routes are described from a node to everybody else or from
 211 everybody else to the node. In the example, the node *A* uses the *Link1* and *Backbone*
 212 to communicate with other nodes (note that this is valid for both nodes inside or outside
 213 the zone). More precisely, a communication from node *A* to *B* would use links: *Link1, Backbone,
 214 Link3_down*. Note that duplicated links are removed from the route, i.e. in this example we'll use *Backbone*
 215 only once.
 216
 217 Also, note that the nodes (A, B and C) can be either hosts or other zones. In case of using zones,
 218 set the gateway parameter properly when adding the route.
 219
 220 The following code illustrates how to create this Star Zone and add the appropriates routes.
 221
 222 .. code-block:: cpp
 223
 224     auto* zone = sg4::create_star_zone("star");
 225     /* create hosts */
 226     const sg4::Host* hostA = zone->create_host("A", 1e9)->seal();
 227     const sg4::Host* hostB = zone->create_host("B", 1e9)->seal();
 228
 229     /* create links */
 230     sg4::Link* link1      = zone->create_link("link1", 1e6)->seal();
 231     sg4::Link* link3_up   = zone->create_link("link3_up", 1e6)->seal();
 232     sg4::Link* link3_down = zone->create_link("link3_down", 1e6)->seal();
 233     sg4::Link* backbone   = zone->create_link("backbone", 1e9)->seal();
 234
 235     /* symmetric route route: A->ALL and ALL->A, shared link1 */
 236     zone->add_route(hostA->get_netpoint(), nullptr, nullptr, nullptr,
 237                     std::vector<sg4::Link*>{link1, backbone}, true);
 238     /* route host B -> ALL, split-duplex link3, direction UP */
 239     zone->add_route(hostB->get_netpoint(), nullptr, nullptr, nullptr,
 240                     std::vector<sg4::Link*>{link3_up, backbone}, false);
 241     /* route host ALL -> B, split-duplex link3, direction DOWN */
 242     zone->add_route(nullptr, hostB->get_netpoint(), nullptr, nullptr,
 243                     std::vector<sg4::Link*>{backbone, link3_down}, false);
 244
 245 .. todo:: Complete this page of the manual.
 246
 247    SimGrid comes with an extensive set of platforms in the
 248    `examples/platforms <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms>`_
 249    directory that should be described here.