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