3 <object id="TOC" data="graphical-toc.svg" width="100%" 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("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";
13 .. _platform_reference:
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.
23 ------------------------------------------------------------------
25 ------------------------------------------------------------------
27 Adding configuration flags directly into the platform file becomes particularly useful when the realism of the described
28 platform depends on some specific flags. For example, this could help you to finely tune SMPI. Almost all
29 :ref:`command-line configuration items <options_list>` can be configured this way.
31 Each configuration flag is described as a :ref:`pf_tag_prop` whose 'id' is the name of the flag and 'value' is what it
34 **Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
35 **Children tags:** :ref:`pf_tag_prop` |br|
40 <?xml version = '1.0'?>
41 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
42 <platform version = "4.1">
44 <prop id = "maxmin/precision" value = "0.000010" />
45 <prop id = "cpu/optim" value = "TI" />
46 <prop id = "network/model" value = "SMPI" />
47 <prop id = "smpi/bw-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
50 <!-- The rest of your platform -->
57 ------------------------------------------------------------------
59 ------------------------------------------------------------------
61 A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
63 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
64 **Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
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``.
78 .. code-block:: python
85 - At time t = 1, half of the host computational power (0.5 means 50%) is used to process some background load, hence
86 only 50% of this initial power remains available to your own simulation.
87 - At time t = 2, the available power drops at 20% of the initial value.
88 - At time t = 5, the host can compute at full speed again.
89 - At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
90 again to 50% at time t = 11.
92 If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
94 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
95 Availability profiles of a :ref:`pf_tag_host` contain ratios.
96 :``state_file``: File containing the state profile.
97 Almost every lines of such files describe timed events as ``date boolean``.
100 .. code-block:: python
106 - At time t = 1, the host is turned off (a zero value means OFF)
107 - At time t = 2, the host is turned back on (any other value than zero means ON)
108 - At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
109 again at time t = 11.
111 If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
113 :``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
114 See :ref:`pf_tag_peer`.
115 :``pstate``: Initial pstate (default: 0, the first one).
116 See :ref:`howto_dvfs`.
122 ------------------------------------------------------------------
124 ------------------------------------------------------------------
126 SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire.
127 They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a
130 **Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
131 **Children tags:** :ref:`pf_tag_prop` |br|
134 :``id``: Link name. Must be unique over the whole platform.
135 :``bandwidth``: Maximum bandwidth for this link. You must specify a unit as follows.
137 **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
138 Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
139 **Units in bits and powers of 2** (1 Bps = 8 bps):
140 bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
141 **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
142 Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
143 **Units in bits and powers of 10:**
144 bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
146 :``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
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
159 w week 60 * 60 * 24 * 7
160 ==== =========== ======================
162 :``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
163 (default: ``SHARED``).
165 If set to ``SHARED``, the available bandwidth is fairly shared among all the flows traversing this link. This tend to
166 model the bandwidth sharing behavior of the UDP or TCP protocols.
168 If set to ``FATPIPE``, flows have no impact on each other, hence each flow can exploit the full bandwidth of this
169 link. This aims at modeling the behavior of the Internet backbones that cannot get saturated by your application.
170 What you experience of such networks usually is their latency only.
172 If set to ``SPLITDUPLEX``, the link models cross-traffic
173 effects. Under the ``SHARED`` policy, two flows of reverse
174 direction share the same resource, and can only get half of the
175 bandwidth each. But TCP connections are full duplex, meaning that
176 both directions can get the full bandwidth. To model this, any
177 link under the ``SPLITDUPLEX`` policy is split in two links (whose
178 names are suffixed with "_UP" and "_DOWN"). Then you must specify
179 which direction gets actually used when referring to that link in a
180 :ref:`pf_tag_link_ctn`.
182 :``bandwidth_file``: File containing the bandwidth profile.
183 Almost every lines of such files describe timed events as ``date
184 bandwidth`` (in bytes per second).
187 .. code-block:: python
193 - At time t = 4, the bandwidth is of 40 MBps.
194 - At time t = 8, it raises to 60MBps.
195 - At time t = 24, it drops at 40 MBps again.
197 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
198 Availability profiles of a :ref:`pf_tag_host` contain ratios.
200 :``latency_file``: File containing the latency profile.
201 Almost every lines of such files describe timed events as ``date
202 latency`` (in seconds).
205 .. code-block:: python
211 - At time t = 1, the latency is of 1ms (0.001 second)
212 - At time t = 3, the latency is of 100ms (0.1 second)
213 - At time t = 8 (5 seconds after the last event), the profile loops.
214 - At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
216 If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
218 .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
219 Availability profiles of a :ref:`pf_tag_host` contain ratios.
221 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
227 ------------------------------------------------------------------
229 ------------------------------------------------------------------
231 An element in a route, representing a previously defined link.
233 **Parent tags:** :ref:`pf_tag_route` |br|
234 **Children tags:** none |br|
237 :``id``: Link that is to be included in this route.
238 :``direction``: Whether to use the uplink (with ``UP``) or downlink
239 (with ``DOWN``) of the link. This is only valid if the
240 link has ``sharing=SPLITDUPLEX``.
246 ------------------------------------------------------------------
248 ------------------------------------------------------------------
250 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
251 handy to model situations where hosts have an asymmetric
252 connectivity. Computers connected through set-top-boxes usually have a
253 much better download rate than their upload rate. To model this,
254 <peer> creates and connects several elements: an host, an upload link
257 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
258 **Children tags:** none |br|
261 :``id``: Name of the host. Must be unique on the whole platform.
262 :``speed``: Computational power (in flop/s).
263 If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
264 :``bw_in``: Bandwidth of the private downstream link, along with its
265 unit. See :ref:`pf_tag_link`.
266 :``bw_out``: Bandwidth of the private upstream link, along with its
267 unit. See :ref:`pf_tag_link`.
268 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
269 :``coordinates``: Coordinates of the gateway for this peer.
271 The communication latency between a host A = (xA,yA,zA) and a host B = (xB,yB,zB) is computed as follows:
273 latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
275 See the documentation of
276 :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
277 how the latency is computed from the coordinates, and on how the up
278 and down bandwidth are used.
279 :``availability_file``: File containing the availability profile.
280 See the full description in :ref:`pf_tag_host`
281 :``state_file``: File containing the state profile.
282 See the full description in :ref:`pf_tag_host`
288 ------------------------------------------------------------------
290 ------------------------------------------------------------------
292 **Parent tags:** none (this is the root tag of every file) |br|
293 **Children tags:** :ref:`pf_tag_config` (must come first),
294 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
295 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
298 :``version``: Version of the DTD, describing the whole XML format.
299 This versionning allow future evolutions, even if we
300 avoid backward-incompatible changes. The current version
301 is **4.1**. The ``simgrid_update_xml`` program can
302 upgrade most of the past platform files to the most recent
309 ------------------------------------------------------------------
311 ------------------------------------------------------------------
313 This tag can be used to attach user-defined properties to some
314 platform elements. Both the name and the value can be any string of
315 your wish. You can use this to pass extra parameters to your code and
318 From your code, you can interact with these properties using the
321 - Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
322 - Cluster: this is a zone, see below.
323 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
324 - Link: :cpp:func:`simgrid::s4u::Link::get_property`
325 - Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
326 - Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`
328 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
329 :ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
330 **Children tags:** none |br|
333 :``id``: Name of the defined property.
334 :``value``: Value of the defined property.
340 ------------------------------------------------------------------
342 ------------------------------------------------------------------
344 A path between two network locations, composed of several :ref:`pf_tag_link`s.
346 **Parent tags:** :ref:`pf_tag_zone` |br|
347 **Children tags:** :ref:`pf_tag_link_ctn` |br|
350 :``src``: Host from which this route starts. Must be an existing host.
351 :``dst``: Host to which this route leads. Must be an existing host.
352 :``symmetrical``: Whether this route is symmetrical, ie, whether we
353 are defining the route ``dst -> src`` at the same
354 time. Valid values: ``yes``, ``no``,``YES``, ``NO``.
360 ------------------------------------------------------------------
362 ------------------------------------------------------------------
364 A router is similar to a :ref:`pf_tag_host`, but it cannot contain
365 any actor. It is only useful to some routing algorithms. In
366 particular, they are useful when you want to use the NS3 bindings to
367 break the routes that are longer than 1 hop.
369 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
370 **Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
373 :``id``: Router name.
374 No other host or router may have the same name over the whole platform.
375 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
381 ------------------------------------------------------------------
383 ------------------------------------------------------------------
385 A networking zone is an area in which elements are located. See :cpp:class:`simgrid::s4u::Zone`.
387 **Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` (only internal nodes, i.e., zones
388 containing only inner zones or clusters but no basic
389 elements such as host or peer) |br|
390 **Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone` |br|
391 **Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer` |br|
395 No other zone may have the same name over the whole platform.
396 :``routing``: Routing algorithm to use.