Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Merge branch 'master' of https://framagit.org/simgrid/simgrid
[simgrid.git] / 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 the 
19 `simgrid.dtd <https://simgrid.org/simgrid.dtd>`_ DTD file. The same DTD is used for both platform and deployment files. 
20
21 .. _pf_tag_config:
22
23 ------------------------------------------------------------------
24 <config>
25 ------------------------------------------------------------------
26
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.
30
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
32 has to be set to.
33
34 **Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
35 **Children tags:** :ref:`pf_tag_prop` |br|
36 **Attributes:** none
37
38 .. code-block:: xml
39
40    <?xml version = '1.0'?>
41    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
42    <platform version = "4.1">
43      <config>
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" />
48      </config>
49
50      <!-- The rest of your platform -->
51    </platform>
52
53 |hr|
54    
55 .. _pf_tag_host:
56
57 ------------------------------------------------------------------
58 <host>
59 ------------------------------------------------------------------
60
61 A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
62
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|
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 5
84
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.
91
92    If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
93
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``.
98    Example:
99
100    .. code-block:: python
101
102       1 0
103       2 1
104       LOOPAFTER 8
105
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.
110
111    If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
112
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`.
117
118 |hr|
119    
120 .. _pf_tag_link:
121
122 ------------------------------------------------------------------
123 <link>
124 ------------------------------------------------------------------
125
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 
128 single element.
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 a unit as follows.
136
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.
145
146 :``latency``: Latency for this link (default: 0.0). You must specify a 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 :``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
163    (default: ``SHARED``).
164
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.
167
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.
171
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    all both directions can get the full bandwidth. To model this, any
177    link under the ``SPLITDUPLEX`` policy is split in two links (their
178    names are suffixed with "_UP" and "_DOWN"). You must then specify
179    which direction gets actually used when referring to that link in a
180    :ref:`pf_tag_link_ctn`.
181         
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).
185    Example:
186
187    .. code-block:: python
188
189       4.0 40000000
190       8.0 60000000
191       LOOPAFTER 12.0
192
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.
196
197    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
198       :ref:`pf_tag_link` are absolute values, but Availability
199       profiles of :ref:`pf_tag_host` are ratio.
200 :``latency_file``: File containing the latency profile.
201    Almost every lines of such files describe timed events as ``date
202    latency`` (in seconds).
203    Example:
204                    
205    .. code-block:: python
206                    
207       1.0 0.001
208       3.0 0.1
209       LOOPAFTER 5.0
210
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.
215       
216    If your trace does not contain a LOOPAFTER line, then your profile
217    is only executed once and not repetitively.
218   
219    .. warning:: Don't get fooled: Bandwidth and Latency profiles of a
220       :ref:`pf_tag_link` are absolute values, but Availability
221       profiles of :ref:`pf_tag_host` are ratio.
222 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
223
224 |hr|
225
226 .. _pf_tag_peer:
227
228 ------------------------------------------------------------------
229 <peer>
230 ------------------------------------------------------------------
231
232 This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
233 handy to model situations where hosts have an asymmetric
234 connectivity. Computers connected through set-to-boxes usually have a
235 much better download rate than their upload rate.  To model this,
236 <peer> creates and connects several elements: an host, an upload link
237 and a download link.
238
239 **Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
240 **Children tags:** none |br|
241 **Attributes:**
242
243 :``id``: Name of the host. Must be unique on the whole platform.
244 :``speed``: Computational power (in flop/s).
245    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`). 
246 :``bw_in``: Bandwidth of the private downstream link, along with its
247             unit. See :ref:`pf_tag_link`.
248 :``bw_out``: Bandwidth of the private upstream link, along with its
249              unit. See :ref:`pf_tag_link`.
250 :``lat``: Latency of both private links. See :ref:`pf_tag_link`.
251 :``coordinates``: Coordinates of the gateway for this peer.
252
253    The communication latency between an host A=(xA,yA,zA) and an host
254    B=(xB,yB,zB) is computed as follows:
255  
256    latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
257
258    See the documentation of
259    :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
260    how the latency is computed from the coordinate, and on the the up
261    and down bandwidth are used.
262 :``availability_file``: File containing the availability profile.
263    See the full description in :ref:`pf_tag_host`
264 :``state_file``: File containing the state profile.
265    See the full description in :ref:`pf_tag_host`
266
267 |hr|
268
269 .. _pf_tag_platform:
270
271 ------------------------------------------------------------------
272 <platform>
273 ------------------------------------------------------------------
274
275 **Parent tags:** none (this is the root tag of every file) |br|
276 **Children tags:** :ref:`pf_tag_config` (must come first),
277 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
278 :ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
279 **Attributes:** 
280
281 :``version``: Version of the DTD, describing the whole XML format.
282               This versionning allow future evolutions, even if we
283               avoid backward-incompatible changes. The current version
284               is **4.1**. The ``simgrid_update_xml`` program can
285               upgrade most of the past platform files to the recent
286               formalism.
287
288 |hr|
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 |hr|
320
321 .. _pf_tag_router:
322
323 ------------------------------------------------------------------
324 <router>
325 ------------------------------------------------------------------
326
327 A router is similar to an :ref:`pf_tag_host`, but it cannot contain
328 any actor. It is only useful to some routing algorithms. In
329 particular, they are useful when you want to use the NS3 bindings to
330 break the routes that are longer than 1 hop.
331
332 **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e. zones containing no inner zones nor clusters) |br|
333 **Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
334 **Attributes:**
335
336 :``id``: Router name.
337    No other host or router may have the same name over the whole platform.
338 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.      
339
340 .. |br| raw:: html
341
342    <br />
343
344 .. |hr| raw:: html
345
346    <hr />