3 <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
5 window.onload=function() { // Wait for the SVG to be loaded before changing it
6 var elem=document.querySelector("#TOC").contentDocument.getElementById("ReferenceBox")
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";
13 .. _platform_reference:
15 Complete XML Reference
16 **********************
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.
21 -------------------------------------------------------------------------------
28 SimGrid can simulate the time it takes to read or write data on disk, even if the stored data is not made persistent in
29 any way by SimGrid. This means that your application will correctly be slowed down when doing simulated I/O, but there
30 is no way to get the data stored this way.
32 We decided to not model anything beyond raw access in SimGrid because we believe that there is not single way of doing so.
33 We provide an example model of file system as a plugin, (sparsely) documented in :ref:`plugin_filesystem`.
35 **Parent tags:** :ref:`pf_tag_host` |br|
36 **Children tags:** :ref:`pf_tag_prop` |br|
39 :``id``: A name of your choice (must be unique on this host).
40 :``read_bw``: Read bandwidth for this disk. You must specify a unit as follows.
42 **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
43 Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
44 **Units in bits and powers of 2** (1 Bps = 8 bps):
45 bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
46 **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
47 Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
48 **Units in bits and powers of 10:**
49 bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
51 :``write_bw``: Write bandwidth for this disk. You must specify a unit as for the read bandwidth.
55 <host id="alice" speed="1Gf">
56 <disk id="Disk1" read_bw="200MBps" write_bw="80MBps">
57 <!-- you can add properties for anything you want: they are not used by SimGrid -->
58 <prop id="content" value="storage/content/small_content.txt"/>
60 <prop id="ram" value="100B" />
63 -------------------------------------------------------------------------------
70 Adding configuration flags directly into the platform file becomes particularly
71 useful when the realism of the described platform depends on some specific
72 flags. For example, this could help you to finely tune SMPI. Almost all
73 :ref:`command-line configuration items <options_list>` can be configured this
76 Each configuration flag is described as a :ref:`pf_tag_prop` whose ``id`` is the
77 name of the flag and ``value`` is what it has to be set to.
79 **Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
80 **Children tags:** :ref:`pf_tag_prop` |br|
85 <?xml version = '1.0'?>
86 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
87 <platform version = "4.1">
89 <prop id = "maxmin/precision" value = "0.000010" />
90 <prop id = "cpu/optim" value = "TI" />
91 <prop id = "network/model" value = "SMPI" />
92 <prop id = "smpi/bw-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
95 <!-- The rest of your platform -->
98 -------------------------------------------------------------------------------
105 A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
107 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
108 **Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_disk` |br|
112 Must be unique over the whole platform.
113 :``speed``: Computational power (per core, in flop/s).
114 If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
115 :``core``: Amount of cores (default: 1).
116 See :ref:`howto_multicore`.
117 :``availability_file``:
118 File containing the availability profile.
119 Almost every lines of such files describe timed events as ``date ratio``.
122 .. code-block:: python
129 - At time t = 1, half of the host computational power (0.5 means 50%) is used to process some background load, hence
130 only 50% of this initial power remains available to your own simulation.
131 - At time t = 2, the available power drops at 20% of the initial value.
132 - At time t = 5, the host can compute at full speed again.
133 - At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
134 again to 50% at time t = 11.
136 If your profile does not contain any LOOPAFTER line, then it will
137 be executed only once and not repeated.
139 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
140 Availability profiles of a :ref:`pf_tag_host` contain ratios.
141 :``state_file``: File containing the state profile.
142 Almost every lines of such files describe timed events as ``date boolean``.
145 .. code-block:: python
151 - At time t = 1, the host is turned off (a zero value means OFF)
152 - At time t = 2, the host is turned back on (any other value than zero means ON)
153 - At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
154 again at time t = 11.
156 If your profile does not contain any LOOPAFTER line, then it will
157 be executed only once and not repeated.
159 :``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
160 See :ref:`pf_tag_peer`.
161 :``pstate``: Initial pstate (default: 0, the first one).
162 See :ref:`howto_dvfs`.
164 -------------------------------------------------------------------------------
171 SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire.
172 They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a
173 single element. Links are characterized by their bandwidth and latency, and their sharing is realistic wrt TCP connexions.
174 Another unusual point is that SimGrid links can be used to connect more than two elements, just like
175 hyperlinks in an `hypergraph <https://en.wikipedia.org/wiki/Hypergraph>`_.
177 **Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
178 **Children tags:** :ref:`pf_tag_prop` |br|
181 :``id``: Link name. Must be unique over the whole platform.
182 :``bandwidth``: Maximum bandwidth for this link. You must specify a unit as follows.
184 **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
185 Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
186 **Units in bits and powers of 2** (1 Bps = 8 bps):
187 bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
188 **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
189 Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
190 **Units in bits and powers of 10:**
191 bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
193 :``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
195 ==== =========== ======================
196 Unit Meaning Duration in seconds
197 ==== =========== ======================
198 ps picosecond 10⁻¹² = 0.000000000001
199 ns nanosecond 10⁻⁹ = 0.000000001
200 us microsecond 10⁻⁶ = 0.000001
201 ms millisecond 10⁻³ = 0.001
206 w week 60 * 60 * 24 * 7
207 ==== =========== ======================
209 :``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
210 (default: ``SPLITDUPLEX``).
212 If set to ``SPLITDUPLEX``, the link models the full-duplex
213 behavior, as meant in TCP or UDP. To that extend, the link is
214 actually split in two links whose names are suffixed with "_UP" and
215 "_DOWN". You should then specify the direction to use when
216 referring to that link in a :ref:`pf_tag_link_ctn`.
218 If set to ``FATPIPE``, flows have no impact on each other, hence
219 each flow can exploit the full bandwidth. This models Internet
220 backbones that cannot get saturated by your application. From your
221 application point of view, there is no congestion on these
224 If set to ``SHARED``, the available bandwidth is fairly shared
225 among ALL flows traversing this link. The resulting link is not
226 full-duplex (as UDP or TCP would be): communications in both
227 directions share the same link. Prefer ``SPLITDUPLEX`` for TCP flows.
229 :``bandwidth_file``: File containing the bandwidth profile.
230 Almost every lines of such files describe timed events as ``date
231 bandwidth`` (in bytes per second).
234 .. code-block:: python
240 - At time t = 4, the bandwidth is of 40 MBps.
241 - At time t = 8, it raises to 60MBps.
242 - At time t = 24, it drops at 40 MBps again.
244 If your profile does not contain any LOOPAFTER line, then it will
245 be executed only once and not repeated.
247 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
248 Availability profiles of a :ref:`pf_tag_host` contain ratios.
250 :``latency_file``: File containing the latency profile.
251 Almost every lines of such files describe timed events as ``date
252 latency`` (in seconds).
255 .. code-block:: python
261 - At time t = 1, the latency is of 1ms (0.001 second)
262 - At time t = 3, the latency is of 100ms (0.1 second)
263 - At time t = 8 (5 seconds after the last event), the profile loops.
264 - At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
266 If your profile does not contain any LOOPAFTER line, then it will
267 be executed only once and not repeated.
269 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
270 Availability profiles of a :ref:`pf_tag_host` contain ratios.
272 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
274 -------------------------------------------------------------------------------
281 An element in a route, representing a previously defined link.
283 **Parent tags:** :ref:`pf_tag_route` |br|
284 **Children tags:** none |br|
287 :``id``: Link that is to be included in this route.
288 :``direction``: either ``UP`` (by default) or ``DOWN``, specifying whether to
289 use the uplink or downlink component of the link (that must
290 follow the ``SPLITDUPLEX`` sharing policy). |br|
291 Please refer to the ``sharing_policy`` attribute in
294 -------------------------------------------------------------------------------
301 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
302 handy to model situations where hosts have an asymmetric
303 connectivity. Computers connected through set-top-boxes usually have a
304 much better download rate than their upload rate. To model this,
305 <peer> creates and connects several elements: a host, an upload link
308 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
309 **Children tags:** none |br|
312 :``id``: Name of the host. Must be unique on the whole platform.
313 :``speed``: Computational power (in flop/s).
315 If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
316 :``bw_in``: Bandwidth of the private downstream link, along with its
317 unit. See :ref:`pf_tag_link`.
318 :``bw_out``: Bandwidth of the private upstream link, along with its
319 unit. See :ref:`pf_tag_link`.
320 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
321 :``coordinates``: Coordinates of the gateway for this peer.
323 The communication latency between a host A = (xA,yA,zA) and a host B = (xB,yB,zB) is computed as follows:
325 latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
327 See the documentation of
328 :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
329 how the latency is computed from the coordinates, and on how the up
330 and down bandwidth are used.
331 :``availability_file``: File containing the availability profile.
332 See the full description in :ref:`pf_tag_host`
333 :``state_file``: File containing the state profile.
334 See the full description in :ref:`pf_tag_host`
336 -------------------------------------------------------------------------------
343 **Parent tags:** none (this is the root tag of every file) |br|
344 **Children tags:** :ref:`pf_tag_config` (must come first),
345 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
346 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect`, or
347 :ref:`pf_tag_actor` in :ref:`deployment <deploy>` files. |br|
350 :``version``: Version of the DTD, describing the whole XML format.
351 This versioning allow future evolutions, even if we
352 avoid backward-incompatible changes. The current version
353 is **4.1**. The ``simgrid_update_xml`` program can
354 upgrade most of the past platform files to the most recent
357 -------------------------------------------------------------------------------
364 This tag can be used to attach user-defined properties to some
365 platform elements. Both the name and the value can be any string of
366 your wish. You can use this to pass extra parameters to your code and
369 From your code, you can interact with these properties using the
372 - Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
373 - Cluster: this is a zone, see below.
374 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
375 - Link: :cpp:func:`simgrid::s4u::Link::get_property`
376 - Disk: :cpp:func:`simgrid::s4u::Disk::get_property`
377 - Zone: :cpp:func:`simgrid::s4u::NetZone::get_property` of :cpp:func:`MSG_zone_get_property_value`
379 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
380 :ref:`pf_tag_link`, :ref:`pf_tag_disk`,:ref:`pf_tag_zone` |br|
381 **Children tags:** none |br|
384 :``id``: Name of the defined property.
385 :``value``: Value of the defined property.
387 -------------------------------------------------------------------------------
394 A path between two network locations, composed of several occurrences
395 of :ref:`pf_tag_link` .
397 **Parent tags:** :ref:`pf_tag_zone` |br|
398 **Children tags:** :ref:`pf_tag_link_ctn` |br|
399 **See also:** :ref:`pf_tag_zoneRoute` |br|
402 :``src``: Host from which this route starts. Must be the name of an existing host.
403 :``dst``: Host to which this route leads. Must be the name of an existing host.
404 :``symmetrical``: Whether this route is symmetrical, ie, whether we
405 are defining the route ``dst -> src`` at the same
406 time. Valid values: ``yes``, ``no``, ``YES``, ``NO``
409 -------------------------------------------------------------------------------
416 A router is similar to a :ref:`pf_tag_host`, but it cannot contain
417 any actor. It is only useful to some routing algorithms. In
418 particular, they are useful when you want to use the NS3 bindings to
419 break the routes that are longer than 1 hop.
421 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
424 :``id``: Router name.
425 No other host or router may have the same name over the whole platform.
426 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
428 -------------------------------------------------------------------------------
435 A networking zone is an area in which elements are located. See :cpp:class:`simgrid::s4u::NetZone`.
437 **Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` (only internal nodes, i.e., zones
438 containing only inner zones or clusters but no basic
439 elements such as host or peer) |br|
440 **Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone` |br|
441 **Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer` |br|
445 No other zone may have the same name over the whole platform.
446 :``routing``: Routing algorithm to use.
448 -------------------------------------------------------------------------------
450 .. _pf_tag_zoneRoute:
455 The purpose of this entity is to define a route between two zones.
456 Recall that all zones form a tree, so to connect two sibling zones,
457 you must give such a zoneRoute specifying the source and destination zones,
458 along with the gateway in each zone (i.e., the point to reach within that zone to reach the zone),
459 and the list of links to go from one zone to another.
461 **Parent tags:** :ref:`pf_tag_zone` |br|
462 **Children tags:** :ref:`pf_tag_link_ctn` |br|
463 **See also:** :ref:`pf_tag_route` |br|
466 :``src``: Zone from which this route starts. Must be an existing zone.
467 :``dst``: Zone to which this route leads. Must be an existing zone.
468 :``gw_src``: Netpoint (within src zone) from which this route starts. Must be an existing host/router.
469 :``gw_dst``: Netpoint (within dst zone) to which this route leads. Must be an existing host/router.
470 :``symmetrical``: Whether this route is symmetrical, ie, whether we
471 are defining the route ``dst -> src`` at the same
472 time. Valid values: ``yes``, ``no``, ``YES``, ``NO``.
474 Afterward, the path from `src_host` in zone `src`, to `dst_host` in
475 zone `dst`, is composed of 3 segments. First, move within zone `src`
476 from `src_host` to the specified gateway `gw_src`. Then, traverse all
477 links specified by the zoneRoute (purportedly within the common
478 ancestor) and finally, move within zone `dst` from `gw_dst` to
482 -------------------------------------------------------------------------------
489 This tag is commonly used when one wants to define many hosts and a network quickly.
490 Technically, cluster is a meta-tag: **from the inner SimGrid point of
491 view, a cluster is a network zone where some optimized routing is defined**.
492 The default inner organization of the cluster is as follow:
499 ____________|__________|_____________ backbone
501 l0| l1| l2| l97| l96 | | l99
507 Here, a set of **hosts** is defined. Each of them has a **link**
508 to a central backbone (backbone is a link itself, as a link can
509 be used to represent a switch).
510 A **router** allows to connect a **cluster** to the outside world. Internally,
511 SimGrid treats a cluster as a network zone containing all hosts: the router is the
512 gateway for the cluster.
514 There is an alternative organization, which is as follows:
529 The principle is the same, except that there is no backbone. This representation
530 can be obtained easily: just do not set the bb_* attributes.
532 **Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` |br|
533 **Children tags:** none |br|
536 :``id``: The identifier of the cluster. Facilitates referring to this cluster.
537 :``prefix``: Each node of the cluster has to have a name. This name will be prefixed with this prefix.
538 :``suffix``: Each node of the cluster will be suffixed with this suffix
539 :``radical``: Regexp used to generate cluster nodes name.
541 Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before.
543 The produced number is concatenated between prefix and suffix to form machine names.
544 :``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
545 :``core``: Same as the ``core`` attribute of the :ref:`pf_tag_host` tag.
546 :``bw``: Bandwidth for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
547 :``lat``: Latency for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
548 :``sharing_policy``: Sharing policy for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
549 :``bb_bw``: Bandwidth for backbone (if any). See :ref:`pf_tag_link` for syntax/details.
551 If bb_bw and bb_lat attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
552 :``bb_lat``: Latency for backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
554 If bb_lat and bb_bw attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
555 :``bb_sharing_policy``: Sharing policy for the backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
556 :``limiter_link``: Bandwidth for limiter link (if any).
558 This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time.
560 In theory this value should be 2*bw for splitduplex links, but in reality this might be less. This value will depend heavily on the communication model, and on the cluster's hardware, so no default value can be set, this has to be measured.
562 More details can be obtained in `Toward Better Simulation of MPI Applications on Ethernet/TCP Networks <https://hal.inria.fr/hal-00919507/>`_
563 :``loopback_bw``: Bandwidth for loopback (if any). See :ref:`pf_tag_link` section for syntax/details.
565 If loopback_bw and loopback_lat attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node.
567 The sharing policy of a loopback link is **FATPIPE** :ref:`pf_tag_link`.
568 :``loopback_lat``: Latency for loopback (if any). See loopback_bw for more info.
569 :``topology``: Network topology to use.
571 SimGrid currently supports FLAT (with or without backbone, as described before), TORUS, FAT_TREE and DRAGONFLY attributes for this tag.
573 See :ref:`platform_examples` for more details.
575 :``topo_parameters``: Specific parameters to pass for the topology defined in the topology tag.
577 For torus networks, comma-separated list of the number of nodes in each dimension of the torus.
579 Please refer to :ref:`platform_examples`.
585 Consider the following two (and independent) uses of the ``cluster`` tag:
589 <cluster id="my_cluster_1" prefix="" suffix="" radical="0-262144"
590 speed="1e9" bw="125e6" lat="5E-5"/>
592 <cluster id="my_cluster_2" prefix="c-" suffix=".me" radical="0-99"
593 speed="1e9" bw="125e6" lat="5E-5"
594 bb_bw="2.25e9" bb_lat="5E-4"/>
597 The second example creates one router and 100 machines with the following names:
601 c-my_cluster_2_router.me
610 The router name is defined as the resulting string: prefix + clusterId + "_router" + suffix.
611 In this case: *my_cluster_1_router* and *my_cluster_2_router.me*.
613 -------------------------------------------------------------------------------
621 This tag is only available when the routing mode of the network zone
622 is set to ``Cluster``.
624 The cabinet tag is, like the :ref:`pf_tag_cluster` tag,
625 a meta-tag. This means that it is simply a shortcut for creating a set of (homogenous) hosts and links quickly;
626 unsurprisingly, this tag was introduced to setup cabinets in data centers. Unlike
627 :ref:`pf_tag_cluster`, however, the :ref:`pf_tag_cabinet` assumes that you create the backbone
628 and routers yourself; see our examples below.
630 **Parent tags:** :ref:`pf_tag_zone` |br|
631 **Children tags:** none |br|
634 :``id``: The identifier of the cabinet. Facilitates referring to it.
635 :``prefix``: Each node of the cabinet has to have a name. This name will be prefixed with this prefix.
636 :``suffix``: Each node of the cabinet will be suffixed with this suffix.
637 :``radical``: Regexp used to generate cabinet nodes name.
638 Syntax: "10-20" will give you 11 machines numbered from 10 to 20, "10-20;2" will give you 12 machines, one with the number 2, others numbered as before.
640 The produced number is concatenated between prefix and suffix to form machine names.
641 :``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
642 :``bw``: Bandwidth for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details.
643 :``lat``: Latency for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details.
646 Please note that as of now, it is impossible to change attributes such as,
647 amount of cores (always set to 1), the initial state of hosts/links
648 (always set to ON), the sharing policy of the links (always set to **SPLITDUPLEX** :ref:`pf_tag_link` ).
653 The following example shows how to use the cabinet tag.
655 .. literalinclude:: ../../examples/platforms/meta_cluster.xml
658 Please note that you must specify the :ref:`pf_backbone` tag by yourself;
659 this is not done automatically and there are no checks
660 that ensure this backbone was defined.
662 The hosts generated in the above example are named host-1.cluster, host-2.cluster1