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
  55 .. _pf_tag_host:
  56
  57 ------------------------------------------------------------------
  58 <host>
  59 ------------------------------------------------------------------
  60
  61 An host is the computing resource on which an actor can execute. See :cpp:class:`simgrid::s4u::Host`.
  62
  63 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
  64 **Children tags:** :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 8
  84
  85    - At time t=1, half of its power is taken by some background
  86      computations, so only 50% of its initial power remains available
  87      (0.5 means 50%).
  88    - At time t=2, the available power drops at 20% of the total.
  89    - At time t=5, the host computes back at full speed.
  90    - At time t=10, the history is reset (because that's 5 seconds after
  91      the last event). So the available speed will drop at t=11.
  92
  93    If your trace does not contain a LOOPAFTER line, then your profile
  94    is only executed once and not repetitively.
  95
  96    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
  97       :ref:`pf_tag_link` are absolute values, but Availability
  98       profiles of :ref:`pf_tag_host` are ratio.
  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 (value 0 means OFF)
 110    - At time t=2, it is turned back on (other values means ON)
 111    - At time t=10, the history is reset (because that's 8 seconds after
 112      the last event). So the host will be turned off again at t=11.
 113
 114    If your trace does not contain a LOOPAFTER line, then your profile
 115    is only executed once and not repetitively.
 116
 117 :``coordinates``: Vivaldi coordinates (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 .. _pf_tag_link:
 123
 124 ------------------------------------------------------------------
 125 <link>
 126 ------------------------------------------------------------------
 127
 128 Network links can represent one-hop network connections. See :cpp:class:`simgrid::s4u::Link`.
 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 the
 136    unit as follows.
 137
 138    **Units in bytes and powers of 2** (1 KiBps = 1024 Bps):
 139       Bps, KiBps, MiBps, GiBps, TiBps, PiBps, EiBps |br|
 140    **Units in bits  and powers of 2** (1 Bps = 8 bps):
 141       bps, Kibps, Mibps, Gibps, Tibps, Pibps, Eibps |br|
 142    **Units in bytes and powers of 10:**  (1 KBps = 1000 Bps)
 143       Bps, KBps, MBps, GBps, TBps, PBps, EBps |br|
 144    **Units in bits  and powers of 10:**
 145       'Ebps', 'Pbps', 'Tbps', 'Gbps', 'Mbps', 'kbps', 'bps'
 146
 147 :``latency``: Latency for this link (default: 0.0). You must specify
 148    the unit as follows.
 149
 150    ==== =========== ======================
 151    Unit Meaning     Duration in seconds
 152    ==== =========== ======================
 153    ps   picosecond  10⁻¹² = 0.000000000001
 154    ns   nanosecond  10⁻⁹ = 0.000000001
 155    us   microsecond 10⁻⁶ = 0.000001
 156    ms   millisecond 10⁻³ = 0.001
 157    s    second      1
 158    m    minute      60
 159    h    hour        60 * 60
 160    d    day         60 * 60 * 24
 161    w    week        60 * 60 * 24 * 7
 162    ==== =========== ======================
 163
 164
 165 :``sharing_policy``: Sharing policy for the link.
 166    Either ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX`` (default: ``SHARED``).
 167
 168    If set to ``SHARED``, the available bandwidth is shared fairly
 169    between all flows traversing this link. This tend to model the
 170    sharing behavior of UDP or TCP.
 171
 172    If set to ``FATPIPE``, the flows have no mutual impact, and each
 173    flow can obtain the full bandwidth of this link. This is intended
 174    to model the internet backbones that cannot get saturated by your
 175    application: you mostly experience their latency.
 176
 177    If set to ``SPLITDUPLEX``, the link models cross-traffic
 178    effects. Under the ``SHARED`` policy, two flows of reverse
 179    direction share the same resource, and can only get half of the
 180    bandwidth each. But TCP connections are full duplex, meaning that
 181    all both directions can get the full bandwidth. To model this, any
 182    link under the ``SPLITDUPLEX`` policy is split in two links (their
 183    names are suffixed with "_UP" and "_DOWN"). You must then specify
 184    which direction gets actually used when referring to that link in a
 185    :ref:`pf_tag_link_ctn`.
 186
 187 :``bandwidth_file``: File containing the bandwidth profile.
 188    Almost every lines of such files describe timed events as ``date
 189    bandwidth`` (in bytes per second).
 190    Example:
 191
 192    .. code-block:: python
 193
 194       4.0 40000000
 195       8.0 60000000
 196       LOOPAFTER 12.0
 197
 198    - At time t=4, the bandwidth is of 40 MBps.
 199    - At time t=8, it raises to 60MBps.
 200    - At time t=24, it drops at 40 MBps again.
 201
 202    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
 203       :ref:`pf_tag_link` are absolute values, but Availability
 204       profiles of :ref:`pf_tag_host` are ratio.
 205 :``latency_file``: File containing the latency profile.
 206    Almost every lines of such files describe timed events as ``date
 207    latency`` (in seconds).
 208    Example:
 209
 210    .. code-block:: python
 211
 212       1.0 0.001
 213       3.0 0.1
 214       LOOPAFTER 5.0
 215
 216    - At time t=1, the latency is of 1ms (0.001 second)
 217    - At time t=3, the latency is of 100ms (0.1 second)
 218    - At time t=8 (5 seconds after the last event), the profile loops.
 219    - At time t=9 (1 second after the loop reset), the latency is back at 1ms.
 220
 221    If your trace does not contain a LOOPAFTER line, then your profile
 222    is only executed once and not repetitively.
 223
 224    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
 225       :ref:`pf_tag_link` are absolute values, but Availability
 226       profiles of :ref:`pf_tag_host` are ratio.
 227 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
 228
 229 .. _pf_tag_peer:
 230
 231 ------------------------------------------------------------------
 232 <peer>
 233 ------------------------------------------------------------------
 234
 235 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
 236 handy to model situations where hosts have an asymmetric
 237 connectivity. Computers connected through set-to-boxes usually have a
 238 much better download rate than their upload rate.  To model this,
 239 <peer> creates and connects several elements: an host, an upload link
 240 and a download link.
 241
 242 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
 243 **Children tags:** none |br|
 244 **Attributes:**
 245
 246 :``id``: Name of the host. Must be unique on the whole platform.
 247 :``speed``: Computational power (in flop/s).
 248    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
 249 :``bw_in``: Bandwidth of the private downstream link, along with its
 250             unit. See :ref:`pf_tag_link`.
 251 :``bw_out``: Bandwidth of the private upstream link, along with its
 252              unit. See :ref:`pf_tag_link`.
 253 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
 254 :``coordinates``: Coordinates of the gateway for this peer.
 255
 256    The communication latency between an host A=(xA,yA,zA) and an host
 257    B=(xB,yB,zB) is computed as follows:
 258
 259    latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
 260
 261    See the documentation of
 262    :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
 263    how the latency is computed from the coordinate, and on the the up
 264    and down bandwidth are used.
 265 :``availability_file``: File containing the availability profile.
 266    See the full description in :ref:`pf_tag_host`
 267 :``state_file``: File containing the state profile.
 268    See the full description in :ref:`pf_tag_host`
 269
 270 .. _pf_tag_platform:
 271
 272 ------------------------------------------------------------------
 273 <platform>
 274 ------------------------------------------------------------------
 275
 276 **Parent tags:** none (this is the root tag of every file) |br|
 277 **Children tags:** :ref:`pf_tag_config` (must come first),
 278 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
 279 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
 280 **Attributes:**
 281
 282 :``version``: Version of the DTD, describing the whole XML format.
 283               This versionning allow future evolutions, even if we
 284               avoid backward-incompatible changes. The current version
 285               is **4.1**. The ``simgrid_update_xml`` program can
 286               upgrade most of the past platform files to the recent
 287               formalism.
 288
 289
 290 .. _pf_tag_prop:
 291
 292 ------------------------------------------------------------------
 293 <prop>
 294 ------------------------------------------------------------------
 295
 296 This tag can be used to attach user-defined properties to some
 297 platform elements. Both the name and the value can be any string of
 298 your wish. You can use this to pass extra parameters to your code and
 299 the plugins.
 300
 301 From your code, you can interact with these properties using the
 302 following functions:
 303
 304 - Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
 305 - Cluster: this is a zone, see below.
 306 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
 307 - Link: :cpp:func:`simgrid::s4u::Link::get_property`
 308 - Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
 309 - Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`
 310
 311 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
 312 :ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
 313 **Children tags:** none |br|
 314 **Attributes:**
 315
 316 :``id``: Name of the defined property.
 317 :``value``: Value of the defined property.
 318
 319 .. _pf_tag_router:
 320
 321 ------------------------------------------------------------------
 322 <router>
 323 ------------------------------------------------------------------
 324
 325 A router is similar to an :ref:`pf_tag_host`, but it cannot contain
 326 any actor. It is only useful to some routing algorithms. In
 327 particular, they are useful when you want to use the NS3 bindings to
 328 break the routes that are longer than 1 hop.
 329
 330 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
 331 **Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
 332 **Attributes:**
 333
 334 :``id``: Router name.
 335    No other host or router may have the same name over the whole platform.
 336 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
 337
 338 .. |br| raw:: html
 339
 340    <br />