docs/source/platform.rst

   1 .. _platform:
   2
   3 .. raw:: html
   4
   5    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
   6    <script>
   7    window.onload=function() { // Wait for the SVG to be loaded before changing it
   8      var elem=document.querySelector("#TOC").contentDocument.getElementById("PlatformBox")
   9      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";
  10
  11      for (name of ["RoutingBox", "ProfileBox"]) {
  12        var elem=document.querySelector("#TOC").contentDocument.getElementById(name)
  13        elem.style="fill-opacity:0;opacity:0.93999999;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
  14      }
  15    }
  16    </script>
  17    <br/>
  18    <br/>
  19
  20 Describing your Simulated Platform
  21 ##################################
  22
  23 In SimGrid, platforms are usually described in XML. This formalism has
  24 some drawbacks, but using a specific format ensures that the platform
  25 is not mixed with the tested application. This separation of concern
  26 :ref:`is a must <howto_science>` for your Modeling and Simulation (M&S)
  27 work. When XML is too limiting, you may describe your platforms using
  28 the :ref:`lua bindings <platform_lua>` (it is not yet possible to do so in
  29 python or directly in C++).
  30
  31 We understand that writing a complex platform description can be tricky, we thus included
  32 :ref:`many examples <platform_examples>` in the archive. This
  33 documentation also contains some :ref:`hints and howtos <howto>`, as well
  34 as the full :ref:`XML reference guide <platform_reference>`.
  35
  36
  37 Any simulated platform must contain **basic elements**, such as hosts, links, storages, etc. SimGrid gives you a great
  38 liberty when defining the **routing of your platform**, i.e., the network path taken between each pair of hosts.
  39 Finally, you may also describe an **experimental scenario**, with qualitative (e.g., bandwidth variations representing
  40 an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
  41
  42
  43 First Example
  44 *************
  45
  46 Imagine you want to describe a little platform with three hosts,
  47 interconnected as follows:
  48
  49 .. image:: /tuto_smpi/3hosts.png
  50    :align: center
  51
  52 This can be done with the following platform file, that considers the
  53 simulated platform as a graph of hosts and network links.
  54
  55 .. literalinclude:: /tuto_smpi/3hosts.xml
  56    :language: xml
  57
  58 The most important elements are the basic ones: :ref:`pf_tag_host`,
  59 :ref:`pf_tag_link`, and similar. Then come the routes between any pair
  60 of hosts, that are given explicitely with :ref:`pf_tag_route` (routes
  61 are symmetrical by default). Any host must be given a computational
  62 speed (in flops) while links must be given a latency (in seconds) and
  63 a bandwidth (in bytes per second). Note that you can write 1Gflops
  64 instead of 1000000000flops, and similar.
  65
  66 Every platform element must be located within a given **networking
  67 zone** .  Zones are in
  68 charge of the routing, see below.
  69
  70 The last thing you must know on SimGrid platform files is that the
  71 root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
  72 does not match what SimGrid expects, you will be hinted to use to the
  73 ``simgrid_update_xml`` utility to update your file.
  74
  75
  76 Defining a Routing
  77 ******************
  78
  79 Networking zones (:ref:`pf_tag_zone`) are used to factorize the description
  80 to reduce the size of your platform on disk and in memory. Then, when
  81 a host wants to communicate with another host belonging to the same
  82 zone, it is the zone's duty to find the list of links that are
  83 involved in the communication. In the above examples, since we use
  84 ``routing="Full"``, all routes must be explicitly given using the
  85 :ref:`pf_tag_route` and :ref:`pf_tag_link_ctn` tags (this :ref:`routing
  86 model <pf_rm>` is both simple and inefficient :) It is OK to not
  87 specify each and every route between hosts, as long as you do not try
  88 to start a communication on any of the missing routes during your
  89 simulation.
  90
  91 Any zone may contain sub-zones, allowing for a hierarchical
  92 decomposition of the platform. Routing can be made more efficient (as the
  93 inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
  94 allows you to have more than one routing model in your platform. For
  95 example, you can have a coordinate-based routing for the WAN parts
  96 of your platforms, a full routing within each datacenter, and a highly
  97 optimized routing within each cluster of the datacenter.  In this
  98 case, determining the route between two given hosts gets :ref:`routing_basics`
  99 "somewhat more complex" but SimGrid still computes
 100 these routes for you in a time- and space-efficient manner.
 101 Here is an illustration of these concepts:
 102
 103 .. image:: img/zone_hierarchy.png
 104
 105 Circles represent processing units and squares represent network
 106 routers. Bold lines represent communication links. The zone "AS2" models the core of a national network interconnecting a
 107 small flat cluster (AS4) and a larger hierarchical cluster (AS5), a
 108 subset of a LAN (AS6), and a set of peers scattered around the world
 109 (AS7).
 110
 111 .. todo:: Add more examples, such as the cloud example described in
 112           previous paragraph
 113
 114 Performance Profiles and Churn
 115 ******************************
 116
 117 ..  LocalWords:  SimGrid