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 which hosts are interconnected via a crossbar switch
  61 with as many ports as hosts, so that any disjoint pairs of hosts can communicate concurrently at full speed. Because there
  62 is no contention on the switch, it is modeled as if there were a direct link from each host to the outgoing router. For
  63 instance:
  64
  65
  66 .. literalinclude:: ../../examples/platforms/cluster_crossbar.xml
  67    :language: xml
  68    :lines: 1-3,18-
  69
  70 One specifies a name prefix and suffix for each host, and then give an integer range. In the example the cluster contains
  71 65536 hosts (!), named ``node-0.simgrid.org`` to ``node-65535.simgrid.org``. All hosts have the same power (1 Gflop/sec)
  72 and are connected directly to the switch via private links with same bandwidth (125 MBytes/sec) and latency (50
  73 microseconds).
  74
  75 The outgoing router is named ``${prefix}${cluster_id}_router${suffix}`` so in this case, this is
  76 ``node-cluster-crossbar_router.simgrid.org``.
  77
  78 .. image:: ../../examples/platforms/cluster_crossbar.svg
  79    :align: center
  80
  81 Cluster with a Shared Backbone
  82 ------------------------------
  83
  84 Another popular model for a parallel platform is that of a set of homogeneous hosts connected to a shared communication
  85 medium, a backbone, with some limited bandwidth capacity and on which communicating host pairs can experience contention.
  86 For instance:
  87
  88 .. literalinclude:: ../../examples/platforms/cluster_backbone.xml
  89    :language: xml
  90    :lines: 1-3,18-
  91
  92 The main differences with the crossbar cluster above are the ``bb_bw`` and ``bb_lat`` attributes that specify the backbone
  93 characteristics (here, a 500 microseconds latency and a 2.25 GBytes/sec bandwidth). This link is used for every
  94 communication within the cluster. The route from ``node-0.simgrid.org`` to ``node-1.simgrid.org`` counts 3 links: the
  95 private link of ``node-0.simgrid.org``, the backbone and the private link of ``node-1.simgrid.org``. The route from
  96 ``node-0.simgrid.org`` to the outer internet counts 2 links: the private link of ``node-0.simgrid.org`` and the backbone.
  97
  98 .. image:: ../../examples/platforms/cluster_backbone.svg
  99    :align: center
 100
 101 Torus Cluster
 102 -------------
 103
 104 Many HPC facilities use torus clusters to reduce sharing and
 105 performance loss on concurrent internal communications. Modeling this
 106 in SimGrid is very easy. Simply add a ``topology="TORUS"`` attribute
 107 to your cluster. Configure it with the ``topo_parameters="X,Y,Z"``
 108 attribute, where ``X``, ``Y`` and ``Z`` are the dimension of your
 109 torus.
 110
 111 .. image:: ../../examples/platforms/cluster_torus.svg
 112    :align: center
 113
 114 .. literalinclude:: ../../examples/platforms/cluster_torus.xml
 115    :language: xml
 116
 117 Note that in this example, we used ``loopback_bw`` and
 118 ``loopback_lat`` to specify the characteristics of the loopback link
 119 of each node (i.e., the link allowing each node to communicate with
 120 itself). We could have done so in previous example too. When no
 121 loopback is given, the communication from a node to itself is handled
 122 as if it were two distinct nodes: it goes twice through the private
 123 link and through the backbone (if any).
 124
 125 .. _platform_examples_fattree:
 126
 127 Fat-Tree Cluster
 128 ----------------
 129
 130 This topology was introduced to reduce the amount of links in the
 131 cluster (and thus reduce its price) while maintaining a high bisection
 132 bandwidth and a relatively low diameter. To model this in SimGrid,
 133 pass a ``topology="FAT_TREE"`` attribute to your cluster. The
 134 ``topo_parameters=#levels;#downlinks;#uplinks;link count`` follows the
 135 semantic introduced in the `Figure 1(b) of this article
 136 <https://ece.technion.ac.il/wp-content/uploads/2021/01/publication_776.pdf>`_.
 137
 138 Here is the meaning of this example: ``2 ; 4,4 ; 1,2 ; 1,2``
 139
 140 - That's a two-level cluster (thus the initial ``2``).
 141 - Routers are connected to 4 elements below them, regardless of its
 142   level. Thus the ``4,4`` component that is used as
 143   ``#downlinks``. This means that the hosts are grouped by 4 on a
 144   given router, and that there is 4 level-1 routers (in the middle of
 145   the figure).
 146 - Hosts are connected to only 1 router above them, while these routers
 147   are connected to 2 routers above them (thus the ``1,2`` used as
 148   ``#uplink``).
 149 - Hosts have only one link to their router while every path between a
 150   level-1 routers and level-2 routers use 2 parallel links. Thus the
 151   ``1,2`` that is used as ``link count``.
 152
 153 .. image:: ../../examples/platforms/cluster_fat_tree.svg
 154    :align: center
 155
 156 .. literalinclude:: ../../examples/platforms/cluster_fat_tree.xml
 157    :language: xml
 158    :lines: 1-3,10-
 159
 160 .. todo:
 161
 162    Model some other platforms, for example from https://link.springer.com/article/10.1007/s11227-019-03142-8
 163
 164 Dragonfly Cluster
 165 -----------------
 166
 167 This topology was introduced to further reduce the amount of links
 168 while maintaining a high bandwidth for local communications. To model
 169 this in SimGrid, pass a ``topology="DRAGONFLY"`` attribute to your
 170 cluster. It's based on the implementation of the topology used on
 171 Cray XC systems, described in paper
 172 `Cray Cascade: A scalable HPC system based on a Dragonfly network <https://dl.acm.org/citation.cfm?id=2389136>`_.
 173
 174 System description follows the format ``topo_parameters=#groups;#chassis;#routers;#nodes``
 175 For example, ``3,4 ; 3,2 ; 3,1 ; 2``:
 176
 177 - ``3,4``: There are 3 groups with 4 links between each (blue level).
 178   Links to nth group are attached to the nth router of the group
 179   on our implementation.
 180 - ``3,2``: In each group, there are 3 chassis with 2 links between each nth router
 181   of each group (black level)
 182 - ``3,1``: In each chassis, 3 routers are connected together with a single link
 183   (green level)
 184 - ``2``: Each router has two nodes attached (single link)
 185
 186 .. image:: ../../examples/platforms/cluster_dragonfly.svg
 187    :align: center
 188
 189 .. literalinclude:: ../../examples/platforms/cluster_dragonfly.xml
 190    :language: xml
 191
 192
 193 Star Zone
 194 ---------
 195
 196 A Star topology can be seen as a crossbar cluster that does not interconnect hosts, but subzones. It can for example be
 197 used to model a cluster of complex hosts, where each host is disaggregated, with CPUs, GPUs and maybe a network on chip. It
 198 is similar to a cluster topology, with the flexibility to set different route for every component in the star. Because of
 199 its complexity, this topology is only available from the C++ interface.
 200
 201 .. image:: img/starzone.svg
 202     :scale: 80%
 203     :align: center
 204
 205 The particularity of this zone is how routes are declared. Instead of declaring the
 206 source and destination, routes are described from a node to everybody else or from
 207 everybody else to the node. In the example, the node *A* uses the *Link1* and *Backbone*
 208 to communicate with other nodes (note that this is valid for both nodes inside or outside
 209 the zone). More precisely, a communication from node *A* to *B* would use links: *Link1, Backbone,
 210 Link3_down*. Note that duplicated links are removed from the route, i.e. in this example we'll use *Backbone*
 211 only once.
 212
 213 Also, note that the nodes (A, B and C) can be either hosts or other zones. In case of using zones,
 214 set the gateway parameter properly when adding the route.
 215
 216 The following code illustrates how to create this Star Zone and add the appropriates routes.
 217
 218 .. code-block:: cpp
 219
 220     auto* zone = sg4::create_star_zone("star");
 221     /* create hosts */
 222     const sg4::Host* hostA = zone->create_host("A", 1e9)->seal();
 223     const sg4::Host* hostB = zone->create_host("B", 1e9)->seal();
 224
 225     /* create links */
 226     sg4::Link* link1      = zone->create_link("link1", 1e6)->seal();
 227     sg4::Link* link3_up   = zone->create_link("link3_up", 1e6)->seal();
 228     sg4::Link* link3_down = zone->create_link("link3_down", 1e6)->seal();
 229     sg4::Link* backbone   = zone->create_link("backbone", 1e9)->seal();
 230
 231     /* symmetric route route: A->ALL and ALL->A, shared link1 */
 232     zone->add_route(hostA->get_netpoint(), nullptr, nullptr, nullptr,
 233                     std::vector<sg4::Link*>{link1, backbone}, true);
 234     /* route host B -> ALL, split-duplex link3, direction UP */
 235     zone->add_route(hostB->get_netpoint(), nullptr, nullptr, nullptr,
 236                     std::vector<sg4::Link*>{link3_up, backbone}, false);
 237     /* route host ALL -> B, split-duplex link3, direction DOWN */
 238     zone->add_route(nullptr, hostB->get_netpoint(), nullptr, nullptr,
 239                     std::vector<sg4::Link*>{backbone, link3_down}, false);
 240
 241 .. todo:: Complete this page of the manual.
 242
 243    SimGrid comes with an extensive set of platforms in the
 244    `examples/platforms <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms>`_
 245    directory that should be described here.