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