+++ /dev/null
-.. raw:: html
-
- <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
- <script>
- window.onload=function() { // Wait for the SVG to be loaded before changing it
- var elem=document.querySelector("#TOC").contentDocument.getElementById("PlatformBox")
- 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";
- }
- </script>
- <br/>
- <br/>
-
-.. _platform_reference:
-
-DTD Reference
-*************
-
-Your platform description should follow the specification presented in the
-`simgrid.dtd <https://simgrid.org/simgrid.dtd>`_ DTD file. The same DTD is used for both platform and deployment files.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_config:
-
-<config>
---------
-
-Adding configuration flags directly into the platform file becomes particularly
-useful when the realism of the described platform depends on some specific
-flags. For example, this could help you to finely tune SMPI. Almost all
-:ref:`command-line configuration items <options_list>` can be configured this
-way.
-
-Each configuration flag is described as a :ref:`pf_tag_prop` whose ``id`` is the
-name of the flag and ``value`` is what it has to be set to.
-
-**Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
-**Children tags:** :ref:`pf_tag_prop` |br|
-**Attributes:** none
-
-.. code-block:: xml
-
- <?xml version = '1.0'?>
- <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
- <platform version = "4.1">
- <config>
- <prop id = "maxmin/precision" value = "0.000010" />
- <prop id = "cpu/optim" value = "TI" />
- <prop id = "network/model" value = "SMPI" />
- <prop id = "smpi/bw-factor" value = "65472:0.940694;15424:0.697866;9376:0.58729" />
- </config>
-
- <!-- The rest of your platform -->
- </platform>
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_host:
-
-<host>
-------
-
-A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`.
-
-**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
-**Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
-**Attributes:**
-
-:``id``: Host name.
- Must be unique over the whole platform.
-:``speed``: Computational power (per core, in flop/s).
- If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
-:``core``: Amount of cores (default: 1).
- See :ref:`howto_multicore`.
-:``availability_file``:
- File containing the availability profile.
- Almost every lines of such files describe timed events as ``date ratio``.
- Example:
-
- .. code-block:: python
-
- 1 0.5
- 2 0.2
- 5 1
- LOOPAFTER 5
-
- - At time t = 1, half of the host computational power (0.5 means 50%) is used to process some background load, hence
- only 50% of this initial power remains available to your own simulation.
- - At time t = 2, the available power drops at 20% of the initial value.
- - At time t = 5, the host can compute at full speed again.
- - At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
- again to 50% at time t = 11.
-
- If your profile does not contain any LOOPAFTER line, then it will
- be executed only once and not repeated.
-
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
- Availability profiles of a :ref:`pf_tag_host` contain ratios.
-:``state_file``: File containing the state profile.
- Almost every lines of such files describe timed events as ``date boolean``.
- Example:
-
- .. code-block:: python
-
- 1 0
- 2 1
- LOOPAFTER 8
-
- - At time t = 1, the host is turned off (a zero value means OFF)
- - At time t = 2, the host is turned back on (any other value than zero means ON)
- - At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
- again at time t = 11.
-
- If your profile does not contain any LOOPAFTER line, then it will
- be executed only once and not repeated.
-
-:``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
- See :ref:`pf_tag_peer`.
-:``pstate``: Initial pstate (default: 0, the first one).
- See :ref:`howto_dvfs`.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_link:
-
-<link>
-------
-
-SimGrid links usually represent one-hop network connections (see :cpp:class:`simgrid::s4u::Link`), i.e., a single wire.
-They can also be used to abstract a larger network interconnect, e.g., the entire transcontinental network, into a
-single element.
-
-**Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones) |br|
-**Children tags:** :ref:`pf_tag_prop` |br|
-**Attributes:**
-
-:``id``: Link name. Must be unique over the whole platform.
-:``bandwidth``: Maximum bandwidth for this link. You must specify a unit as follows.
-
- **Units in bytes and powers of 2** (1 KiBps = 1,024 Bps):
- Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps. |br|
- **Units in bits and powers of 2** (1 Bps = 8 bps):
- bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
- **Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
- Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
- **Units in bits and powers of 10:**
- bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
-
-:``latency``: Latency for this link (default: 0.0). You must specify a unit as follows.
-
- ==== =========== ======================
- Unit Meaning Duration in seconds
- ==== =========== ======================
- ps picosecond 10⁻¹² = 0.000000000001
- ns nanosecond 10⁻⁹ = 0.000000001
- us microsecond 10⁻⁶ = 0.000001
- ms millisecond 10⁻³ = 0.001
- s second 1
- m minute 60
- h hour 60 * 60
- d day 60 * 60 * 24
- w week 60 * 60 * 24 * 7
- ==== =========== ======================
-
-:``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
- (default: ``SPLITDUPLEX``).
-
- If set to ``SPLITDUPLEX``, the link models the full-duplex
- behavior, as meant in TCP or UDP. To that extend, the link is
- actually split in two links whose names are suffixed with "_UP" and
- "_DOWN". You should then specify the direction to use when
- referring to that link in a :ref:`pf_tag_link_ctn`.
-
- If set to ``FATPIPE``, flows have no impact on each other, hence
- each flow can exploit the full bandwidth. This models Internet
- backbones that cannot get saturated by your application. From your
- application point of view, there is no congestion on these
- backbones.
-
- If set to ``SHARED``, the available bandwidth is fairly shared
- among ALL flows traversing this link. The resulting link is not
- full-duplex (as UDP or TCP would be): communications in both
- directions share the same link. Prefer ``SPLITDUPLEX`` for TCP flows.
-
-:``bandwidth_file``: File containing the bandwidth profile.
- Almost every lines of such files describe timed events as ``date
- bandwidth`` (in bytes per second).
- Example:
-
- .. code-block:: python
-
- 4.0 40000000
- 8.0 60000000
- LOOPAFTER 12.0
-
- - At time t = 4, the bandwidth is of 40 MBps.
- - At time t = 8, it raises to 60MBps.
- - At time t = 24, it drops at 40 MBps again.
-
- If your profile does not contain any LOOPAFTER line, then it will
- be executed only once and not repeated.
-
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
- Availability profiles of a :ref:`pf_tag_host` contain ratios.
-
-:``latency_file``: File containing the latency profile.
- Almost every lines of such files describe timed events as ``date
- latency`` (in seconds).
- Example:
-
- .. code-block:: python
-
- 1.0 0.001
- 3.0 0.1
- LOOPAFTER 5.0
-
- - At time t = 1, the latency is of 1ms (0.001 second)
- - At time t = 3, the latency is of 100ms (0.1 second)
- - At time t = 8 (5 seconds after the last event), the profile loops.
- - At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
-
- If your profile does not contain any LOOPAFTER line, then it will
- be executed only once and not repeated.
-
- .. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
- Availability profiles of a :ref:`pf_tag_host` contain ratios.
-
-:``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_link_ctn:
-
-<link_ctn>
-----------
-
-An element in a route, representing a previously defined link.
-
-**Parent tags:** :ref:`pf_tag_route` |br|
-**Children tags:** none |br|
-**Attributes:**
-
-:``id``: Link that is to be included in this route.
-:``direction``: either ``UP`` (by default) or ``DOWN``, specifying whether to
- use the uplink or downlink component of the link (that must
- follow the ``SPLITDUPLEX`` sharing policy). |br|
- Please refer to the ``sharing_policy`` attribute in
- :ref:`pf_tag_link`.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_peer:
-
-<peer>
-------
-
-This tag represents a peer, as in Peer-to-Peer (P2P) networks. It is
-handy to model situations where hosts have an asymmetric
-connectivity. Computers connected through set-top-boxes usually have a
-much better download rate than their upload rate. To model this,
-<peer> creates and connects several elements: an host, an upload link
-and a download link.
-
-**Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
-**Children tags:** none |br|
-**Attributes:**
-
-:``id``: Name of the host. Must be unique on the whole platform.
-:``speed``: Computational power (in flop/s).
- If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`).
-:``bw_in``: Bandwidth of the private downstream link, along with its
- unit. See :ref:`pf_tag_link`.
-:``bw_out``: Bandwidth of the private upstream link, along with its
- unit. See :ref:`pf_tag_link`.
-:``lat``: Latency of both private links. See :ref:`pf_tag_link`.
-:``coordinates``: Coordinates of the gateway for this peer.
-
- The communication latency between a host A = (xA,yA,zA) and a host B = (xB,yB,zB) is computed as follows:
-
- latency = sqrt( (xA-xB)² + (yA-yB)² ) + zA + zB
-
- See the documentation of
- :cpp:class:`simgrid::kernel::routing::VivaldiZone` for details on
- how the latency is computed from the coordinates, and on how the up
- and down bandwidth are used.
-:``availability_file``: File containing the availability profile.
- See the full description in :ref:`pf_tag_host`
-:``state_file``: File containing the state profile.
- See the full description in :ref:`pf_tag_host`
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_platform:
-
-<platform>
-----------
-
-**Parent tags:** none (this is the root tag of every file) |br|
-**Children tags:** :ref:`pf_tag_config` (must come first),
-:ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
-:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
-**Attributes:**
-
-:``version``: Version of the DTD, describing the whole XML format.
- This versionning allow future evolutions, even if we
- avoid backward-incompatible changes. The current version
- is **4.1**. The ``simgrid_update_xml`` program can
- upgrade most of the past platform files to the most recent
- formalism.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_prop:
-
-<prop>
-------
-
-This tag can be used to attach user-defined properties to some
-platform elements. Both the name and the value can be any string of
-your wish. You can use this to pass extra parameters to your code and
-the plugins.
-
-From your code, you can interact with these properties using the
-following functions:
-
-- Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
-- Cluster: this is a zone, see below.
-- Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
-- Link: :cpp:func:`simgrid::s4u::Link::get_property`
-- Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
-- Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`
-
-**Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
-:ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
-**Children tags:** none |br|
-**Attributes:**
-
-:``id``: Name of the defined property.
-:``value``: Value of the defined property.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_route:
-
-<route>
--------
-
-A path between two network locations, composed of several occurences
-of :ref:`pf_tag_link` .
-
-**Parent tags:** :ref:`pf_tag_zone` |br|
-**Children tags:** :ref:`pf_tag_link_ctn` |br|
-**Attributes:**
-
-:``src``: Host from which this route starts. Must be an existing host.
-:``dst``: Host to which this route leads. Must be an existing host.
-:``symmetrical``: Whether this route is symmetrical, ie, whether we
- are defining the route ``dst -> src`` at the same
- time. Valid values: ``yes``, ``no``,``YES``, ``NO``.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_router:
-
-<router>
-------------------------------------------------------------------
-
-A router is similar to a :ref:`pf_tag_host`, but it cannot contain
-any actor. It is only useful to some routing algorithms. In
-particular, they are useful when you want to use the NS3 bindings to
-break the routes that are longer than 1 hop.
-
-**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br|
-**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_storage` |br|
-**Attributes:**
-
-:``id``: Router name.
- No other host or router may have the same name over the whole platform.
-:``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
-
--------------------------------------------------------------------------------
-
-.. _pf_tag_zone:
-
-<zone>
-------
-
-A networking zone is an area in which elements are located. See :cpp:class:`simgrid::s4u::Zone`.
-
-**Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone` (only internal nodes, i.e., zones
-containing only inner zones or clusters but no basic
-elements such as host or peer) |br|
-**Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone` |br|
-**Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer` |br|
-**Attributes:**
-
-:``id``: Zone name.
- No other zone may have the same name over the whole platform.
-:``routing``: Routing algorithm to use.
-
-
-.. |br| raw:: html
-
- <br />
