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