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
  19 the `simgrid.dtd <https://simgrid.org/simgrid.dtd>`_
  20 DTD file. The same DTD is used for both the platform and deployment
  21 files.
  22
  23 .. _pf_tag_config:
  24
  25 ------------------------------------------------------------------
  26 <config>
  27 ------------------------------------------------------------------
  28
  29 Adding configuration flags into the platform file is particularly
  30 useful when the described platform is best used with specific
  31 flags. For example, you could finely tune SMPI in your platform file
  32 directly.  Almost all :ref:`command-line configuration items <options_list>`
  33 can be configured this way.
  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 |hr|
  55
  56 .. _pf_tag_host:
  57
  58 ------------------------------------------------------------------
  59 <host>
  60 ------------------------------------------------------------------
  61
  62 An host is the computing resource on which an actor can execute. See :cpp:class:`simgrid::s4u::Host`.
  63
  64 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
  65 **Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
  66 **Attributes:**
  67
  68 :``id``: Host name.
  69    Must be unique over the whole platform.
  70 :``speed``: Computational power (per core, in flop/s).
  71    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
  72 :``core``: Amount of cores (default: 1).
  73    See :ref:`howto_multicore`.
  74 :``availability_file``:
  75    File containing the availability profile.
  76    Almost every lines of such files describe timed events as ``date ratio``.
  77    Example:
  78
  79    .. code-block:: python
  80
  81       1 0.5
  82       2 0.2
  83       5 1
  84       LOOPAFTER 8
  85
  86    - At time t=1, half of its power is taken by some background
  87      computations, so only 50% of its initial power remains available
  88      (0.5 means 50%).
  89    - At time t=2, the available power drops at 20% of the total.
  90    - At time t=5, the host computes back at full speed.
  91    - At time t=10, the history is reset (because that's 5 seconds after
  92      the last event). So the available speed will drop at t=11.
  93
  94    If your trace does not contain a LOOPAFTER line, then your profile
  95    is only executed once and not repetitively.
  96
  97    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
  98       :ref:`pf_tag_link` are absolute values, but Availability
  99       profiles of :ref:`pf_tag_host` are ratio.
 100 :``state_file``: File containing the state profile.
 101    Almost every lines of such files describe timed events as ``date boolean``.
 102    Example:
 103
 104    .. code-block:: python
 105
 106       1 0
 107       2 1
 108       LOOPAFTER 8
 109
 110    - At time t=1, the host is turned off (value 0 means OFF)
 111    - At time t=2, it is turned back on (other values means ON)
 112    - At time t=10, the history is reset (because that's 8 seconds after
 113      the last event). So the host will be turned off again at t=11.
 114
 115    If your trace does not contain a LOOPAFTER line, then your profile
 116    is only executed once and not repetitively.
 117
 118 :``coordinates``: Vivaldi coordinates (Vivaldi zones only).
 119    See :ref:`pf_tag_peer`.
 120 :``pstate``: Initial pstate (default: 0, the first one).
 121    See :ref:`howto_dvfs`.
 122
 123 |hr|
 124
 125 .. _pf_tag_link:
 126
 127 ------------------------------------------------------------------
 128 <link>
 129 ------------------------------------------------------------------
 130
 131 Network links can represent one-hop network connections (see
 132 :cpp:class:`simgrid::s4u::Link`). SimGrid links can be used to
 133 represent either a single wire, or to abstract a larger network
 134 interconnect in a single element. A single link can for example be
 135 used to model the transcontinental network.
 136
 137 **Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
 138 **Children tags:** :ref:`pf_tag_prop` |br|
 139 **Attributes:**
 140
 141 :``id``:  Link name. Must be unique over the whole platform.
 142 :``bandwidth``: Maximum bandwidth for this link. You must specify the
 143    unit as follows.
 144
 145    **Units in bytes and powers of 2** (1 KiBps = 1024 Bps):
 146       Bps, KiBps, MiBps, GiBps, TiBps, PiBps, EiBps |br|
 147    **Units in bits  and powers of 2** (1 Bps = 8 bps):
 148       bps, Kibps, Mibps, Gibps, Tibps, Pibps, Eibps |br|
 149    **Units in bytes and powers of 10:**  (1 KBps = 1000 Bps)
 150       Bps, KBps, MBps, GBps, TBps, PBps, EBps |br|
 151    **Units in bits  and powers of 10:**
 152       'Ebps', 'Pbps', 'Tbps', 'Gbps', 'Mbps', 'kbps', 'bps'
 153
 154 :``latency``: Latency for this link (default: 0.0). You must specify
 155    the unit as follows.
 156
 157    ==== =========== ======================
 158    Unit Meaning     Duration in seconds
 159    ==== =========== ======================
 160    ps   picosecond  10⁻¹² = 0.000000000001
 161    ns   nanosecond  10⁻⁹ = 0.000000001
 162    us   microsecond 10⁻⁶ = 0.000001
 163    ms   millisecond 10⁻³ = 0.001
 164    s    second      1
 165    m    minute      60
 166    h    hour        60 * 60
 167    d    day         60 * 60 * 24
 168    w    week        60 * 60 * 24 * 7
 169    ==== =========== ======================
 170
 171
 172 :``sharing_policy``: Sharing policy for the link.
 173    Either ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX`` (default: ``SHARED``).
 174
 175    If set to ``SHARED``, the available bandwidth is shared fairly
 176    between all flows traversing this link. This tend to model the
 177    sharing behavior of UDP or TCP.
 178
 179    If set to ``FATPIPE``, the flows have no mutual impact, and each
 180    flow can obtain the full bandwidth of this link. This is intended
 181    to model the internet backbones that cannot get saturated by your
 182    application: you mostly experience their latency.
 183
 184    If set to ``SPLITDUPLEX``, the link models cross-traffic
 185    effects. Under the ``SHARED`` policy, two flows of reverse
 186    direction share the same resource, and can only get half of the
 187    bandwidth each. But TCP connections are full duplex, meaning that
 188    all both directions can get the full bandwidth. To model this, any
 189    link under the ``SPLITDUPLEX`` policy is split in two links (their
 190    names are suffixed with "_UP" and "_DOWN"). You must then specify
 191    which direction gets actually used when referring to that link in a
 192    :ref:`pf_tag_link_ctn`.
 193
 194 :``bandwidth_file``: File containing the bandwidth profile.
 195    Almost every lines of such files describe timed events as ``date
 196    bandwidth`` (in bytes per second).
 197    Example:
 198
 199    .. code-block:: python
 200
 201       4.0 40000000
 202       8.0 60000000
 203       LOOPAFTER 12.0
 204
 205    - At time t=4, the bandwidth is of 40 MBps.
 206    - At time t=8, it raises to 60MBps.
 207    - At time t=24, it drops at 40 MBps again.
 208
 209    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
 210       :ref:`pf_tag_link` are absolute values, but Availability
 211       profiles of :ref:`pf_tag_host` are ratio.
 212 :``latency_file``: File containing the latency profile.
 213    Almost every lines of such files describe timed events as ``date
 214    latency`` (in seconds).
 215    Example:
 216
 217    .. code-block:: python
 218
 219       1.0 0.001
 220       3.0 0.1
 221       LOOPAFTER 5.0
 222
 223    - At time t=1, the latency is of 1ms (0.001 second)
 224    - At time t=3, the latency is of 100ms (0.1 second)
 225    - At time t=8 (5 seconds after the last event), the profile loops.
 226    - At time t=9 (1 second after the loop reset), the latency is back at 1ms.
 227
 228    If your trace does not contain a LOOPAFTER line, then your profile
 229    is only executed once and not repetitively.
 230
 231    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
 232       :ref:`pf_tag_link` are absolute values, but Availability
 233       profiles of :ref:`pf_tag_host` are ratio.
 234 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
 235
 236 |hr|
 237
 238 .. _pf_tag_peer:
 239
 240 ------------------------------------------------------------------
 241 <peer>
 242 ------------------------------------------------------------------
 243
 244 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
 245 handy to model situations where hosts have an asymmetric
 246 connectivity. Computers connected through set-to-boxes usually have a
 247 much better download rate than their upload rate.  To model this,
 248 <peer> creates and connects several elements: an host, an upload link
 249 and a download link.
 250
 251 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
 252 **Children tags:** none |br|
 253 **Attributes:**
 254
 255 :``id``: Name of the host. Must be unique on the whole platform.
 256 :``speed``: Computational power (in flop/s).
 257    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
 258 :``bw_in``: Bandwidth of the private downstream link, along with its
 259             unit. See :ref:`pf_tag_link`.
 260 :``bw_out``: Bandwidth of the private upstream link, along with its
 261              unit. See :ref:`pf_tag_link`.
 262 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
 263 :``coordinates``: Coordinates of the gateway for this peer.
 264
 265    The communication latency between an host A=(xA,yA,zA) and an host
 266    B=(xB,yB,zB) is computed as follows:
 267
 268    latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
 269
 270    See the documentation of
 271    :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
 272    how the latency is computed from the coordinate, and on the the up
 273    and down bandwidth are used.
 274 :``availability_file``: File containing the availability profile.
 275    See the full description in :ref:`pf_tag_host`
 276 :``state_file``: File containing the state profile.
 277    See the full description in :ref:`pf_tag_host`
 278
 279 |hr|
 280
 281 .. _pf_tag_platform:
 282
 283 ------------------------------------------------------------------
 284 <platform>
 285 ------------------------------------------------------------------
 286
 287 **Parent tags:** none (this is the root tag of every file) |br|
 288 **Children tags:** :ref:`pf_tag_config` (must come first),
 289 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
 290 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
 291 **Attributes:**
 292
 293 :``version``: Version of the DTD, describing the whole XML format.
 294               This versionning allow future evolutions, even if we
 295               avoid backward-incompatible changes. The current version
 296               is **4.1**. The ``simgrid_update_xml`` program can
 297               upgrade most of the past platform files to the recent
 298               formalism.
 299
 300 |hr|
 301
 302 .. _pf_tag_prop:
 303
 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 |hr|
 332
 333 .. _pf_tag_router:
 334
 335 ------------------------------------------------------------------
 336 <router>
 337 ------------------------------------------------------------------
 338
 339 A router is similar to an :ref:`pf_tag_host`, but it cannot contain
 340 any actor. It is only useful to some routing algorithms. In
 341 particular, they are useful when you want to use the NS3 bindings to
 342 break the routes that are longer than 1 hop.
 343
 344 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
 345 **Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
 346 **Attributes:**
 347
 348 :``id``: Router name.
 349    No other host or router may have the same name over the whole platform.
 350 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
 351
 352 .. |br| raw:: html
 353
 354    <br />
 355
 356 .. |hr| raw:: html
 357
 358    <hr />