docs/source/platform_reference.rst

   1 .. raw:: html
   2
   3    <object id="TOC" data="graphical-toc.svg" width="100%" 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("PlatformBox")
   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_reference:
  14
  15 DTD Reference
  16 *************
  17
  18 Your platform description should follow the specification presented in the
  19 `simgrid.dtd <https://simgrid.org/simgrid.dtd>`_ DTD file. The same DTD is used for both platform and deployment files.
  20
  21 -------------------------------------------------------------------------------
  22
  23 .. _pf_tag_config:
  24
  25 <config>
  26 --------
  27
  28 Adding configuration flags directly into the platform file becomes particularly useful when the realism of the described
  29 platform depends on some specific flags. For example, this could help you to finely tune SMPI. Almost all
  30 :ref:`command-line configuration items <options_list>` can be configured this way.
  31
  32 Each configuration flag is described as a :ref:`pf_tag_prop` whose 'id' is the name of the flag and 'value' is what it
  33 has to be set to.
  34
  35 **Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
  36 **Children tags:** :ref:`pf_tag_prop` |br|
  37 **Attributes:** none
  38
  39 .. code-block:: xml
  40
  41    <?xml version = '1.0'?>
  42    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
  43    <platform version = "4.1">
  44      <config>
  45        <prop id = "maxmin/precision" value = "0.000010" />
  46        <prop id = "cpu/optim" value = "TI" />
  47        <prop id = "network/model" value = "SMPI" />
  48        <prop id = "smpi/bw-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
  49      </config>
  50
  51      <!-- The rest of your platform -->
  52    </platform>
  53
  54 -------------------------------------------------------------------------------
  55
  56 .. _pf_tag_host:
  57
  58 <host>
  59 ------
  60
  61 A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
  62
  63 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
  64 **Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
  65 **Attributes:**
  66
  67 :``id``: Host name.
  68    Must be unique over the whole platform.
  69 :``speed``: Computational power (per core, in flop/s).
  70    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
  71 :``core``: Amount of cores (default: 1).
  72    See :ref:`howto_multicore`.
  73 :``availability_file``:
  74    File containing the availability profile.
  75    Almost every lines of such files describe timed events as ``date ratio``.
  76    Example:
  77
  78    .. code-block:: python
  79
  80       1 0.5
  81       2 0.2
  82       5 1
  83       LOOPAFTER 5
  84
  85    - At time t = 1, half of the host computational power (0.5 means 50%) is used to process some background load, hence
  86      only 50% of this initial power remains available to your own simulation.
  87    - At time t = 2, the available power drops at 20% of the initial value.
  88    - At time t = 5, the host can compute at full speed again.
  89    - At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
  90      again to 50% at time t = 11.
  91
  92    If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
  93
  94    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
  95       Availability profiles of a :ref:`pf_tag_host` contain ratios.
  96 :``state_file``: File containing the state profile.
  97    Almost every lines of such files describe timed events as ``date boolean``.
  98    Example:
  99
 100    .. code-block:: python
 101
 102       1 0
 103       2 1
 104       LOOPAFTER 8
 105
 106    - At time t = 1, the host is turned off (a zero value means OFF)
 107    - At time t = 2, the host is turned back on (any other value than zero means ON)
 108    - At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
 109      again at time t = 11.
 110
 111    If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
 112
 113 :``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
 114    See :ref:`pf_tag_peer`.
 115 :``pstate``: Initial pstate (default: 0, the first one).
 116    See :ref:`howto_dvfs`.
 117
 118 -------------------------------------------------------------------------------
 119
 120 .. _pf_tag_link:
 121
 122 <link>
 123 ------
 124
 125 SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire.
 126 They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a
 127 single element.
 128
 129 **Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
 130 **Children tags:** :ref:`pf_tag_prop` |br|
 131 **Attributes:**
 132
 133 :``id``:  Link name. Must be unique over the whole platform.
 134 :``bandwidth``: Maximum bandwidth for this link. You must specify a unit as follows.
 135
 136    **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
 137      Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
 138    **Units in bits  and powers of 2** (1 Bps = 8 bps):
 139      bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
 140    **Units in bytes and powers of 10**  (1 KBps = 1,000 Bps):
 141      Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
 142    **Units in bits  and powers of 10:**
 143      bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
 144
 145 :``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
 146
 147    ==== =========== ======================
 148    Unit Meaning     Duration in seconds
 149    ==== =========== ======================
 150    ps   picosecond  10⁻¹² = 0.000000000001
 151    ns   nanosecond  10⁻⁹ = 0.000000001
 152    us   microsecond 10⁻⁶ = 0.000001
 153    ms   millisecond 10⁻³ = 0.001
 154    s    second      1
 155    m    minute      60
 156    h    hour        60 * 60
 157    d    day         60 * 60 * 24
 158    w    week        60 * 60 * 24 * 7
 159    ==== =========== ======================
 160
 161 :``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
 162    (default: ``SHARED``).
 163
 164    If set to ``SHARED``, the available bandwidth is fairly shared among all the flows traversing this link. This tend to
 165    model the bandwidth sharing behavior of the UDP or TCP protocols.
 166
 167    If set to ``FATPIPE``, flows have no impact on each other, hence each flow can exploit the full bandwidth of this
 168    link. This aims at modeling the behavior of the Internet backbones that cannot get saturated by your application.
 169    What you experience of such networks usually is their latency only.
 170
 171    If set to ``SPLITDUPLEX``, the link models cross-traffic
 172    effects. Under the ``SHARED`` policy, two flows of reverse
 173    direction share the same resource, and can only get half of the
 174    bandwidth each. But TCP connections are full duplex, meaning that
 175    both directions can get the full bandwidth. To model this, any
 176    link under the ``SPLITDUPLEX`` policy is split in two links (whose
 177    names are suffixed with "_UP" and "_DOWN"). Then you must specify
 178    which direction gets actually used when referring to that link in a
 179    :ref:`pf_tag_link_ctn`.
 180
 181 :``bandwidth_file``: File containing the bandwidth profile.
 182    Almost every lines of such files describe timed events as ``date
 183    bandwidth`` (in bytes per second).
 184    Example:
 185
 186    .. code-block:: python
 187
 188       4.0 40000000
 189       8.0 60000000
 190       LOOPAFTER 12.0
 191
 192    - At time t = 4, the bandwidth is of 40 MBps.
 193    - At time t = 8, it raises to 60MBps.
 194    - At time t = 24, it drops at 40 MBps again.
 195
 196    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
 197       Availability profiles of a :ref:`pf_tag_host` contain ratios.
 198
 199 :``latency_file``: File containing the latency profile.
 200    Almost every lines of such files describe timed events as ``date
 201    latency`` (in seconds).
 202    Example:
 203
 204    .. code-block:: python
 205
 206       1.0 0.001
 207       3.0 0.1
 208       LOOPAFTER 5.0
 209
 210    - At time t = 1, the latency is of 1ms (0.001 second)
 211    - At time t = 3, the latency is of 100ms (0.1 second)
 212    - At time t = 8 (5 seconds after the last event), the profile loops.
 213    - At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
 214
 215    If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
 216
 217   .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
 218       Availability profiles of a :ref:`pf_tag_host` contain ratios.
 219
 220 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
 221
 222 -------------------------------------------------------------------------------
 223
 224 .. _pf_tag_link_ctn:
 225
 226 <link_ctn>
 227 ----------
 228
 229 An element in a route, representing a previously defined link.
 230
 231 **Parent tags:** :ref:`pf_tag_route` |br|
 232 **Children tags:** none |br|
 233 **Attributes:**
 234
 235 :``id``: Link that is to be included in this route.
 236 :``direction``: Whether to use the uplink (with ``UP``) or downlink
 237                 (with ``DOWN``) of the link. This is only valid if the
 238                 link has ``sharing=SPLITDUPLEX``.
 239
 240 -------------------------------------------------------------------------------
 241
 242 .. _pf_tag_peer:
 243
 244 <peer>
 245 ------
 246
 247 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
 248 handy to model situations where hosts have an asymmetric
 249 connectivity. Computers connected through set-top-boxes usually have a
 250 much better download rate than their upload rate.  To model this,
 251 <peer> creates and connects several elements: an host, an upload link
 252 and a download link.
 253
 254 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
 255 **Children tags:** none |br|
 256 **Attributes:**
 257
 258 :``id``: Name of the host. Must be unique on the whole platform.
 259 :``speed``: Computational power (in flop/s).
 260    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
 261 :``bw_in``: Bandwidth of the private downstream link, along with its
 262             unit. See :ref:`pf_tag_link`.
 263 :``bw_out``: Bandwidth of the private upstream link, along with its
 264              unit. See :ref:`pf_tag_link`.
 265 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
 266 :``coordinates``: Coordinates of the gateway for this peer.
 267
 268    The communication latency between a host A = (xA,yA,zA) and a host B = (xB,yB,zB) is computed as follows:
 269
 270    latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
 271
 272    See the documentation of
 273    :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
 274    how the latency is computed from the coordinates, and on how the up
 275    and down bandwidth are used.
 276 :``availability_file``: File containing the availability profile.
 277    See the full description in :ref:`pf_tag_host`
 278 :``state_file``: File containing the state profile.
 279    See the full description in :ref:`pf_tag_host`
 280
 281 -------------------------------------------------------------------------------
 282
 283 .. _pf_tag_platform:
 284
 285 <platform>
 286 ----------
 287
 288 **Parent tags:** none (this is the root tag of every file) |br|
 289 **Children tags:** :ref:`pf_tag_config` (must come first),
 290 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
 291 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
 292 **Attributes:**
 293
 294 :``version``: Version of the DTD, describing the whole XML format.
 295               This versionning allow future evolutions, even if we
 296               avoid backward-incompatible changes. The current version
 297               is **4.1**. The ``simgrid_update_xml`` program can
 298               upgrade most of the past platform files to the most recent
 299               formalism.
 300
 301 -------------------------------------------------------------------------------
 302
 303 .. _pf_tag_prop:
 304
 305 <prop>
 306 ------
 307
 308 This tag can be used to attach user-defined properties to some
 309 platform elements. Both the name and the value can be any string of
 310 your wish. You can use this to pass extra parameters to your code and
 311 the plugins.
 312
 313 From your code, you can interact with these properties using the
 314 following functions:
 315
 316 - Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
 317 - Cluster: this is a zone, see below.
 318 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
 319 - Link: :cpp:func:`simgrid::s4u::Link::get_property`
 320 - Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
 321 - Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`
 322
 323 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
 324 :ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
 325 **Children tags:** none |br|
 326 **Attributes:**
 327
 328 :``id``: Name of the defined property.
 329 :``value``: Value of the defined property.
 330
 331 -------------------------------------------------------------------------------
 332
 333 .. _pf_tag_route:
 334
 335 <route>
 336 -------
 337
 338 A path between two network locations, composed of several :ref:`pf_tag_link`s.
 339
 340 **Parent tags:** :ref:`pf_tag_zone` |br|
 341 **Children tags:** :ref:`pf_tag_link_ctn` |br|
 342 **Attributes:**
 343
 344 :``src``: Host from which this route starts. Must be an existing host.
 345 :``dst``: Host to which this route leads. Must be an existing host.
 346 :``symmetrical``: Whether this route is symmetrical, ie, whether we
 347                   are defining the route ``dst -> src`` at the same
 348                   time. Valid values: ``yes``, ``no``,``YES``, ``NO``.
 349
 350 -------------------------------------------------------------------------------
 351
 352 .. _pf_tag_router:
 353
 354 <router>
 355 ------------------------------------------------------------------
 356
 357 A router is similar to a :ref:`pf_tag_host`, but it cannot contain
 358 any actor. It is only useful to some routing algorithms. In
 359 particular, they are useful when you want to use the NS3 bindings to
 360 break the routes that are longer than 1 hop.
 361
 362 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
 363 **Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
 364 **Attributes:**
 365
 366 :``id``: Router name.
 367    No other host or router may have the same name over the whole platform.
 368 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
 369
 370 -------------------------------------------------------------------------------
 371
 372 .. _pf_tag_zone:
 373
 374 <zone>
 375 ------
 376
 377 A networking zone is an area in which elements are located. See :cpp:class:`simgrid::s4u::Zone`.
 378
 379 **Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` (only internal nodes, i.e., zones
 380 containing only inner zones or clusters but no basic
 381 elements such as host or peer) |br|
 382 **Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone` |br|
 383 **Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer` |br|
 384 **Attributes:**
 385
 386 :``id``: Zone name.
 387    No other zone may have the same name over the whole platform.
 388 :``routing``: Routing algorithm to use.
 389
 390
 391 .. |br| raw:: html
 392
 393    <br />