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