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