docs/source/Platform_cpp.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_cpp:
  14
  15 C++ Platforms
  16 #############
  17
  18 Using XML to describe the platforms is very convenient. It provides a
  19 human-readable, quick way to start your experiments. Although, XML format brings
  20 several drawbacks as your platforms get larger and more complex (see :ref:`platform_cpp_beyond`).
  21
  22 In this case, it may be more interesting to write your platform directly
  23 in C++ code. It allows you to programmatically describe your platform and
  24 remove the intermediate XML parser during simulations. Take care to follow
  25 the recommendations in :ref:`Modeling Hints <howto>` to keep a clear separation
  26 of concerns between your platform and your application.
  27
  28 Describing Resources
  29 ********************
  30
  31 A platform in SimGrid is composed of several resources organized in different
  32 Netzones. The different resources, such as hosts, disks and links, follow the same
  33 idiom: create()->set()->set()->seal().
  34
  35 .. code-block:: c++
  36
  37     NetZone* zone      = s4u::create_star_zone("zone0");
  38     Link* l_up   = zone->create_link("link_up", "125MBps")->set_latency("24us")->seal();
  39     Host* host   = zone->create_host("host0", "1Gf")->seal();
  40     zone->seal();
  41
  42 The first NetZone created will be the root zone of your platform. You're allowed to modified
  43 an object as long as you did not seal it.
  44
  45 For more details about how to describe the platforms, please give a look at :ref:`examples<platform_cpp_example>`
  46 or directly at the S4U API.
  47
  48 Links
  49 =====
  50
  51 In the XML, you are allowed to do the following description:
  52
  53 .. code-block:: xml
  54
  55     <link id="1" bandwidth="10kBps" latency="10ms" sharing_policy="SPLITDUPLEX"/>
  56
  57     <route src="S1" dst="C1" symmetrical="NO">
  58       <link_ctn id="1" direction="DOWN"/>
  59     </route>
  60
  61 It is important to notice that this is a syntactic sugar provided by the XML to ease
  62 the link utilization. A split-duplex link means that upgoing communications do not
  63 share the bandwidth with downgoing communications. To emulate this behavior,
  64 under the hood, SimGrid creates 2 links in this case: the *1_UP*
  65 link and the *1_DOWN* link. As you can see, the selection of link to use
  66 in the <route> tag is done by the ``direction=`` parameter.
  67
  68 Using the C++ interface, you should describe both links separately and use them
  69 in the route description.
  70
  71 .. code-block:: cpp
  72
  73     Link* l_up   = zone->create_link("1_UP", "125MBps")->set_latency("24us")->seal();
  74     Link* l_down = zone->create_link("1_DOWN", "125MBps")->set_latency("24us")->seal();
  75
  76     zone->add_route(S1, C1, nullptr, nullptr, {link_down});
  77
  78
  79 Loading the platform
  80 ====================
  81
  82 The C++ interface to build the platforms give you freedom to organize your code
  83 as you wish, separating (or unifying) your application from your platform code.
  84 However, we provide a small hack if you want to keep the same structure of the
  85 old code with XML platforms. You can pass a library (.so) file to ``Engine::load_platform``
  86 function, having a predefined function implemented. When loading the platform, the
  87 Engine will look for a function with this signature: "**void load_platform(const sg4::Engine& e)**", and
  88 execute it. It could be an easy way to make the transition between XML and C++ if necessary.
  89
  90 For more details, please refer to the cpp and CMakeLists.txt files in
  91 `examples/platform <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms>`_.
  92
  93
  94 .. _platform_cpp_example:
  95
  96 Example
  97 *******
  98
  99 The best way to build your C++ platform is starting from some examples.
 100 Give a look in the examples folder in `examples/ <https://framagit.org/simgrid/simgrid/tree/master/examples/>`_.
 101 For instance, the file `examples/cpp/clusters-multicpu/s4u-clusters-multicpu.cpp <https://framagit.org/simgrid/simgrid/-/blob/master/examples/cpp/clusters-multicpu/s4u-clusters-multicpu.cpp>`_ shows how to build complex platforms composed of
 102 clusters of clusters.
 103
 104 Here, we present a complete example showing how to create 3 regulars clusters
 105 connected through a shared link.
 106
 107 .. literalinclude:: ../../examples/platforms/griffon.cpp
 108    :language: cpp
 109
 110
 111 .. _platform_cpp_beyond:
 112
 113 Beyond the XML: the power of C++ platforms
 114 ******************************************
 115
 116 This section describes one of the advantages of using C++ code to write your platforms.
 117
 118 Let's see an example of the description of a Fat-Tree in XML (:ref:`platform_examples_fattree`)
 119
 120 .. literalinclude:: ../../examples/platforms/cluster_fat_tree.xml
 121    :language: xml
 122    :lines: 1-3,10-
 123
 124 Our cluster *bob* is composed of 16 hosts with the same 1Gf CPU power.
 125
 126 Imagine now that you want to simulate the same **Fat-Tree topology with** more complex **hosts**,
 127 composed of **1 CPU, 1 GPU and some interconnecting bus**.
 128
 129 Unfortunately, this is not possible with the XML description since its syntax obliges
 130 that the leaves in your Fat-Tree to be single Hosts. However, with the C++ API, your
 131 leaves can be composed of other zones, creating a **Fat-Tree of FullZones** for example.
 132
 133 Consequently, you can describe the desired platform as follows:
 134
 135 .. code-block:: c++
 136
 137     sg4::Engine e(&argc, argv);
 138     sg4::create_fatTree_zone("bob", e.get_netzone_root(), {2, {4, 4}, {1, 2}, {1, 2}}, {create_hostzone, create_loopback, {}}, 125e6,
 139                            50e-6, sg4::Link::SharingPolicy::SPLITDUPLEX)->seal();
 140
 141 Note that the leaves and loopback links are defined through callbacks, as follows:
 142
 143 .. code-block:: c++
 144
 145     /* create the loopback link for each leaf in the Fat-Tree */
 146     static sg4::Link* create_loopback(sg4::NetZone* zone, const std::vector<unsigned int>& /*coord*/, int id)
 147     {
 148         // note that you could set different loopback links for each leaf
 149         return zone->create_link("limiter-" + std::to_string(id), 1e6)->seal();
 150     }
 151
 152     /* create each leaf in the Fat-Tree, return a pair composed of: <object (host, zone), gateway> */
 153     static std::pair<simgrid::kernel::routing::NetPoint*, simgrid::kernel::routing::NetPoint*>
 154     create_hostzone(const sg4::NetZone* zone, const std::vector<unsigned int>& /*coord*/, int id)
 155     {
 156       /* creating zone */
 157       std::string hostname = "host" + std::to_string(id);
 158       auto* host_zone = sg4::create_full_zone(hostname);
 159       /* setting my parent zone */
 160       host_zone->set_parent(zone);
 161
 162       /* creating CPU */
 163       std::string cpu_name  = hostname + "-cpu" + std::to_string(i);
 164       const sg4::Host* cpu = host_zone->create_host(cpu_name, 1e9)->seal();
 165       /* creating GPU */
 166       std::string gpu_name  = hostname + "-gpu" + std::to_string(i);
 167       const sg4::Host* gpu = host_zone->create_host(gpu_name, 1e12)->seal();
 168       /* connecting them */
 169       sg4::Link* link   = host_zone->create_link("link-" + cpu_name, 10e9)->set_latency(10e-9)->seal();
 170       host_zone->add_route(cpu->get_netpoint(), gpu->get_netpoint(), nullptr, nullptr, std::vector<sg4::Link*>{link});
 171
 172       host_zone->seal();
 173       /* cpu is the gateway for this host */
 174       return std::make_pair(host_zone->get_netpoint(), cpu->get_netpoint());
 175     }
 176
 177 The code is straightforward and can be easily adapted to more complex environments thanks to the flexibility
 178 provided by the C++ API.
 179