#############
Using XML to describe the platforms is very convenient. It provides a
-human-readable, quick way to start your experiments. Although, as the
-platform grows in size, XML format brings some drawbacks which may
-make your life harder, specially for big and regular platforms such as
-homogeneous clusters.
+human-readable, quick way to start your experiments. Although, XML format brings
+several drawbacks as your platforms get larger and more complex (see :ref:`platform_cpp_beyond`).
In this case, it may be more interesting to write your platform directly
in C++ code. It allows you to programmatically describe your platform and
-remove the intermediate XML parsing during simulations. Take care to follows
+remove the intermediate XML parser during simulations. Take care to follow
the recommendations in :ref:`Modeling Hints <howto>` to keep a clear separation
-of concerns between your platforms and your applications.
+of concerns between your platform and your application.
Describing Resources
********************
The first NetZone created will be the root zone of your platform. You're allowed to modified
an object as long as you did not seal it.
-For more details about how to describe the platforms, please give a look at
the :ref:`examples<platform_cpp_example>`
-or directly the S4U API.
+For more details about how to describe the platforms, please give a look at :ref:`examples<platform_cpp_example>`
+or directly at the S4U API.
Links
=====
However, we provide a small hack if you want to keep the same structure of the
old code with XML platforms. You can pass a library (.so) file to ``Engine::load_platform``
function, having a predefined function implemented. When loading the platform, the
-Engine will look for a function called "**void load_platform(const sg4::Engine& e)**" and
+Engine will look for a function with this signature: "**void load_platform(const sg4::Engine& e)**", and
execute it. It could be an easy way to make the transition between XML and C++ if necessary.
For more details, please refer to the cpp and CMakeLists.txt files in
.. literalinclude:: ../../examples/platforms/griffon.cpp
:language: cpp
+
+
+.. _platform_cpp_beyond:
+
+Beyond the XML: the power of C++ platforms
+**************
+
+This section describes one of the advantages of using C++ code to write your platforms.
+
+Let's see an example of the description of a Fat-Tree in XML (:ref:`platform_examples_fattree`)
+
+.. literalinclude:: ../../examples/platforms/cluster_fat_tree.xml
+ :language: xml
+ :lines: 1-3,10-
+
+Our cluster *bob* is composed of 16 hosts with the same 1Gf CPU power.
+
+Imagine now that you want to simulate the same **Fat-Tree topology with** more complex **hosts**,
+composed of **1 CPU, 1 GPU and some interconnecting bus**.
+
+Unfortunately, this is not possible with the XML description since its syntax obliges
+that the leaves in your Fat-Tree to be single Hosts. However, with the C++ API, your
+leaves can be composed of other zones, creating a **Fat-Tree of FullZones** for example.
+
+Consequently, you can describe the desired platform as follows:
+
+.. code-block:: c++
+
+ sg4::Engine e(&argc, argv);
+ sg4::create_fatTree_zone("bob", e.get_netzone_root(), {2, {4, 4}, {1, 2}, {1, 2}}, {create_hostzone, create_loopback, {}}, 125e6,
+ 50e-6, sg4::Link::SharingPolicy::SPLITDUPLEX)->seal();
+
+Note that the leaves and loopback links are defined through callbacks, as follows:
+
+.. code-block:: c++
+
+ /* create the loopback link for each leaf in the Fat-Tree */
+ static sg4::Link* create_loopback(sg4::NetZone* zone, const std::vector<unsigned int>& /*coord*/, int id)
+ {
+ // note that you could set different loopback links for each leaf
+ return zone->create_link("limiter-" + std::to_string(id), 1e6)->seal();
+ }
+
+ /* create each leaf in the Fat-Tree, return a pair composed of: <object (host, zone), gateway> */
+ static std::pair<simgrid::kernel::routing::NetPoint*, simgrid::kernel::routing::NetPoint*>
+ create_hostzone(const sg4::NetZone* zone, const std::vector<unsigned int>& /*coord*/, int id)
+ {
+ /* creating zone */
+ std::string hostname = "host" + std::to_string(id);
+ auto* host_zone = sg4::create_full_zone(hostname);
+ /* setting my parent zone */
+ host_zone->set_parent(zone);
+
+ /* creating CPU */
+ std::string cpu_name = hostname + "-cpu" + std::to_string(i);
+ const sg4::Host* cpu = host_zone->create_host(cpu_name, 1e9)->seal();
+ /* creating GPU */
+ std::string gpu_name = hostname + "-gpu" + std::to_string(i);
+ const sg4::Host* gpu = host_zone->create_host(gpu_name, 1e12)->seal();
+ /* connecting them */
+ sg4::Link* link = host_zone->create_link("link-" + cpu_name, 10e9)->set_latency(10e-9)->seal();
+ host_zone->add_route(cpu->get_netpoint(), gpu->get_netpoint(), nullptr, nullptr, std::vector<sg4::Link*>{link});
+
+ host_zone->seal();
+ /* cpu is the gateway for this host */
+ return std::make_pair(host_zone->get_netpoint(), cpu->get_netpoint());
+ }
+
+The code is straightforward and can be easily adapted to more complex environments thanks to the flexibility
+provided by the C++ API.
+
TLDR: use :ref:`pf_tag_route`
-The communications inside a given zone is defined by ``routing=`` parameter
-in the :ref:`pf_tag_zone`. For example, in a *Full* zone, the user must declare
+The routing mechanism inside a given zone is defined by ``routing=`` parameter
+in the :ref:`pf_tag_zone` (see options in :ref:`intra-zone section <intra_zone>`). For example, in a *Full* zone, the user must declare
a :ref:`pf_tag_route` for each pair of hosts inside the zone. Other zones, such as *Floyd*
or *Dijkstra* will calculate the shortest path, while *DragonFly* and *Fat-Tree* uses
specialized routing algorithms to improve performance.
behind a route between zone is exactly the same as for hosts. The only difference is
the 2 new gateway parameters in the syntax of :ref:`pf_tag_zoneroute`.
-A zone is not a physical resource, just a collection of resources. Consequently, you
-need to describe the gateway, i.e. the physical resource inside the zone used for the route.
+A zone is not a physical resource, just a collection of resources (including other zones).
+Consequently, you need to describe the gateway, i.e. the physical resource inside the zone used for the route.
It gives you 4 parameters to describe a zoneRoute:
- src: The object of source zone
- dst: The object of destination zone
- gw_src: Gateway inside src zone. A Host (or router) belonging to src zone.
- - gw_dst: Gateway inside dst zone. A Host (or router) belonging to src zone.
+ - gw_dst: Gateway inside dst zone. A Host (or router) belonging to dst zone.
- links: Links that connect gw_src to gw_dst.
-.. note:: You must be careful to call zoneRoute with the correct parameters: zones for src and dst, and hosts/routers for gw_src and gw_dst
+.. note:: The gateways must be a component of the zone (either directly or member of some child sub-zone). SimGrid will verify these parameters when adding a route.
.. warning:: SimGrid does not have the concept of default gateway/router. Each zoneRoute must describe the appropriate gateways which may be different for each route.
between nodes inside SimGrid, keep reading it.
+.. _intra_zone:
+
Intra-zone communications
=========================
- **Dijkstra/Floyd**: calculates the shortest path between each pair
of nodes using the routes described by the user (:ref:`pf_tag_route`).
As long as you graph is connected, no problems.
+
+ - Dijkstra: shortest-path calculated considering the path's latency. As
+ the latency of links can change during simulation, it's recomputed each
+ time a route is necessary.
+
+ - Floyd: use the number of hops to build shortest path. It's calculated only
+ once at the beginning of the simulation (as the platform is fixed).
+
- **Cluster/Fat-Tree/DragonFly/Torus**: routing is defined by the topology, automatically created.
+ These zones must be defined through the :ref:`pf_tag_cluster` tag in the XML.
- **Star**: star-like topology. Users describe routes from/to every host in the zone.
- **Vivaldi/Wi-Fi**: "fully-connected" zones with special characteristics.
-
+.. _inter_zone:
Inter-zone communications
=========================
:scale: 70%
Inter-zone communications are a little more complicated since you need to pass
-through several zones. Let's give a look with more details in a communication
+through several zones. Let's have a look in more details in a communication
within our initial topology.
In this case, *Host1* within *AS2* wants to communicate with *Host2* from *AS5-4*.
- **Dst ancestor**: *AS5*, it's the *AS5* that contains *AS5-4*.
2. **Adding route from src to dst ancestor**: Ask *AS1* for the route between *AS2* and *AS5*.
- Add *Link1* to our list of links
+
+ This route is defined by the following configuration
+
+ .. code-block:: xml
+
+ <zoneRoute> src="AS2" dst="AS5" gw_src="Host1" gw_dst"="gw1">
+ <link_ctn id="Link1">
+ </zoneRoute>
+
+ Add *Link1* to our list of links.
+
+ Also, we can see in this route that the gateway for *AS2* is *Host1* and for *AS5* is *gw1*.
+
+ Consequently, we need to go from *Host1* to *AS2*'s gateway (*Host1*) and from *Host2* to *AS5*'s
+ gateway (*gw1*).
3. **Recursively search for route between hosts (Host1/Host2) and ancestors (AS2, AS5)**
3.2. **Route from Host2 to AS5's gateway (gw1)**: start step 1 again, searching
for a common root (*AS5* in this case) and the common ancestors (*AS5-4* and *AS5-3*).
+
+ This route is defined as follows.
+
+ .. code-block:: xml
+
+ <zoneRoute> src="AS5-4" dst="AS5-3" gw_src="gw2" gw_dst"="gw1">
+ <link_ctn id="Link3">
+ </zoneRoute>
+
Add *Link3* to list of links.
4. **Add local links in src and dst zones**
4.2. **Route from Host2 to AS5-4's gateway**: follow intra-zone and add *Link2*.
+ The last route, as it is an internal route in *AS5-4*, is defined using the :ref:`pf_tag_route` tag.
+
+ .. code-block:: xml
+
+ <route> src="Host2" dst="gw2">
+ <link_ctn id="Link2">
+ </route>
+
In the end, our communication from *Host1/AS2* to *Host2/AS5-4* will pass through
the links: *Link1, Link3* and *Link2*.
for step 4.1 where we would add the link between *Host3* and *Host1* inside *AS2* zone.
+The Loopback
+************
+
+The link used of loopback communications has a special treatment in SimGrid. As it can be
+quite tedious to describe each a loopback link for each host in the platform, SimGrid provides
+a global **FATPIPE** link which is used by all hosts by default.
+
+By default, this link has the following characteristics:
+
+- **Bandwidth**: 10GBps. It can be changed through configuration, see :ref:`cfg=network/loopback`.
+
+- **Latency**: 0ms. See :ref:`cfg=network/loopback` for more details.
+
+.. warning::
+
+ These default values are arbitrary chosen and must be carefully configured to reflect
+ your environment if needed.
+
+In addition, you can add :ref:`pf_tag_route` from a node to itself to modify the loopback link
+for a specific node. In this case, SimGrid will get this link (instead of the global one) for
+the local communications.
+
+.. code-block:: xml
+
+ <link id="loopback" bandwidth="100MBps" latency="0"/>
+ <route src="Tremblay" dst="Tremblay">
+ <link_ctn id="loopback"/>
+ </route>
+
+Finally, some zones (e.g. :ref:`pf_tag_cluster`) allow you to describe the characteristics of
+the loopback nodes inside the zone. These links are equivalent to adding specific routes and
+have higher priority than the global loopback link.
+
+.. note::
+
+ **Loopback links are used only for local communications**.
+
+ You may have noticed that we didn't include them at step 3.1 in :ref:`inter_zone`.
+ Loopback links will be used only when src and dst are the same, not in the recursive search
+ described above.
We decided to not model anything beyond raw access in SimGrid because we believe that there is not single way of doing so.
We provide an example model of file system as a plugin, (sparsely) documented in :ref:`plugin_filesystem`.
-**Parent tags:** :ref:`pf_tag_host` |br|
-**Children tags:** :ref:`pf_tag_prop` |br|
+**Parent tags:** :ref:`pf_tag_host`
+
+**Children tags:** :ref:`pf_tag_prop`
+
**Attributes:**
:``id``: A name of your choice (must be unique on this host).
:``read_bw``: Read bandwidth for this disk. 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|
+ Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps.
**Units in bits and powers of 2** (1 Bps = 8 bps):
- bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
+ bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps.
**Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
- Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
+ Bps, KBps, MBps, GBps, TBps, PBps, or EBps.
**Units in bits and powers of 10:**
bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
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|
+**Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags)
+
+**Children tags:** :ref:`pf_tag_prop`
+
**Attributes:** none
.. code-block:: xml
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_disk` |br|
+**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters)
+
+**Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_disk`
+
**Attributes:**
:``id``: Host name.
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|
+**Parent tags:** :ref:`pf_tag_zone` (both leaf zones and inner zones)
+
+**Children tags:** :ref:`pf_tag_prop`
+
**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|
+ Bps, KiBps, MiBps, GiBps, TiBps, PiBps, or EiBps.
**Units in bits and powers of 2** (1 Bps = 8 bps):
- bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps. |br|
+ bps, Kibps, Mibps, Gibps, Tibps, Pibps, or Eibps.
**Units in bytes and powers of 10** (1 KBps = 1,000 Bps):
- Bps, KBps, MBps, GBps, TBps, PBps, or EBps. |br|
+ Bps, KBps, MBps, GBps, TBps, PBps, or EBps.
**Units in bits and powers of 10:**
bps, Kbps, Mbps, Gbps, Tbps, Pbps, or Ebps.
An element in a route, representing a previously defined link.
-**Parent tags:** :ref:`pf_tag_route` |br|
-**Children tags:** none |br|
+**Parent tags:** :ref:`pf_tag_route`
+
+**Children tags:** none
+
**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|
+ follow the ``SPLITDUPLEX`` sharing policy).
+
Please refer to the ``sharing_policy`` attribute in
:ref:`pf_tag_link`.
<peer> creates and connects several elements: a host, an upload link
and a download link.
-**Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing) |br|
-**Children tags:** none |br|
+**Parent tags:** :ref:`pf_tag_zone` (only with Vivaldi routing)
+
+**Children tags:** none
+
**Attributes:**
:``id``: Name of the host. Must be unique on the whole platform.
<platform>
----------
-**Parent tags:** none (this is the root tag of every file) |br|
+**Parent tags:** none (this is the root tag of every file)
+
**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`, or
-:ref:`pf_tag_actor` in :ref:`deployment <deploy>` files.|br|
+:ref:`pf_tag_actor` in :ref:`deployment <deploy>` files.
+
**Attributes:**
:``version``: Version of the DTD, describing the whole XML format.
- 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_disk`,:ref:`pf_tag_storage` (deprecated), :ref:`pf_tag_zone` |br|
-**Children tags:** none |br|
+:ref:`pf_tag_link`, :ref:`pf_tag_disk`,:ref:`pf_tag_zone`
+
+**Children tags:** none
+
**Attributes:**
:``id``: Name of the defined property.
A path between two network locations, composed of several occurrences
of :ref:`pf_tag_link` .
-**Parent tags:** :ref:`pf_tag_zone` |br|
-**Children tags:** :ref:`pf_tag_link_ctn` |br|
+**Parent tags:** :ref:`pf_tag_zone`
+
+**Children tags:** :ref:`pf_tag_link_ctn`
+
**Attributes:**
:``src``: Host from which this route starts. Must be an existing host.
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|
+**Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters)
+
**Attributes:**
:``id``: Router name.
**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|
+elements such as host or peer)
+
+**Children tags (if internal zone):** :ref:`pf_tag_cluster`, :ref:`pf_tag_link`, :ref:`pf_tag_zone`
+
+**Children tags (if leaf zone):** :ref:`pf_tag_host`, :ref:`pf_tag_link`, :ref:`pf_tag_peer`
+
**Attributes:**
:``id``: Zone name.
along with the gateway in each zone (i.e., the point to reach within that zone to reach the zone),
and the list of links to go from one zone to another.
-**Parent tags:** :ref:`pf_tag_zone` |br|
-**Children tags:** :ref:`pf_tag_link_ctn` |br|
+**Parent tags:** :ref:`pf_tag_zone`
+
+**Children tags:** :ref:`pf_tag_link_ctn`
+
**Attributes:**
:``src``: Zone from which this route starts. Must be an existing zone.
are defining the route ``dst -> src`` at the same
time. Valid values: ``yes``, ``no``, ``YES``, ``NO``.
-.. |br| raw:: html
+-------------------------------------------------------------------------------
+
+.. _pf_tag_cluster:
+
+<cluster>
+---------
+
+This tag is commonly used when one wants to define many hosts and a network quickly.
+Technically, cluster is a meta-tag: **from the inner SimGrid point of
+view, a cluster is a network zone where some optimized routing is defined**.
+The default inner organization of the cluster is as follow:
+
+.. code-block:: text
+
+ __________
+ | |
+ | router |
+ ____________|__________|_____________ backbone
+ | | | | | |
+ l0| l1| l2| l97| l96 | | l99
+ | | | ........ | | |
+ | |
+ c-0.me c-99.me
+
+
+Here, a set of **hosts** is defined. Each of them has a **link**
+to a central backbone (backbone is a link itself, as a link can
+be used to represent a switch).
+A **router** allows to connect a **cluster** to the outside world. Internally,
+SimGrid treats a cluster as a network zone containing all hosts: the router is the
+gateway for the cluster.
+
+There is an alternative organization, which is as follows:
+
+.. code-block:: text
+
+ __________
+ | |
+ | router |
+ |__________|
+ / | \
+ / | \
+ l0 / l1| \l2
+ / | \
+ / | \
+ host0 host1 host2
+
+The principle is the same, except that there is no backbone. This representation
+can be obtained easily: just do not set the bb_* attributes.
+
+**Parent tags:** :ref:`pf_tag_platform`, :ref:`pf_tag_zone`
+
+**Children tags:** none
+
+**Attributes:**
+
+:``id``: The identifier of the cluster. Facilitates referring to this cluster.
+:``prefix``: Each node of the cluster has to have a name. This name will be prefixed with this prefix.
+:``suffix``: Each node of the cluster will be suffixed with this suffix
+:``radical``: Regexp used to generate cluster nodes name.
+
+ 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.
+
+ The produced number is concatenated between prefix and suffix to form machine names.
+:``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
+:``core``: Same as the ``core`` attribute of the :ref:`pf_tag_host` tag.
+:``bw``: Bandwidth for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``lat``: Latency for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``sharing_policy``: Sharing policy for the links between nodes and backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+:``bb_bw``: Bandwidth for backbone (if any). See :ref:`pf_tag_link` for syntax/details.
+
+ If bb_bw and bb_lat attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
+:``bb_lat``: Latency for backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
+
+ If bb_lat and bb_bw attributes are omitted, no backbone is created (alternative cluster architecture described earlier).
+:``bb_sharing_policy``: Sharing policy for the backbone (if any). See :ref:`pf_tag_link` section for syntax/details.
+:``limiter_link``: Bandwidth for limiter link (if any).
+
+ This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time.
+
+ 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.
+
+ More details can be obtained in `Toward Better Simulation of MPI Applications on Ethernet/TCP Networks <https://hal.inria.fr/hal-00919507/>`_
+:``loopback_bw``: Bandwidth for loopback (if any). See :ref:`pf_tag_link` section for syntax/details.
+
+ 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.
+
+ The sharing policy of a loopback link is **FATPIPE** :ref:`pf_tag_link`.
+:``loopback_lat``: Latency for loopback (if any). See loopback_bw for more info.
+:``topology``: Network topology to use.
+
+ SimGrid currently supports FLAT (with or without backbone, as described before), TORUS, FAT_TREE and DRAGONFLY attributes for this tag.
+
+ See :ref:`platform_examples` for more details.
+
+:``topo_parameters``: Specific parameters to pass for the topology defined in the topology tag.
+
+ For torus networks, comma-separated list of the number of nodes in each dimension of the torus.
+
+ Please refer to :ref:`platform_examples`.
+
+
+Cluster example
+^^^^^^^^^^^^^^^
+
+Consider the following two (and independent) uses of the ``cluster`` tag:
+
+.. code-block:: xml
+
+ <cluster id="my_cluster_1" prefix="" suffix="" radical="0-262144"
+ speed="1e9" bw="125e6" lat="5E-5"/>
+
+ <cluster id="my_cluster_2" prefix="c-" suffix=".me" radical="0-99"
+ speed="1e9" bw="125e6" lat="5E-5"
+ bb_bw="2.25e9" bb_lat="5E-4"/>
+
+
+The second example creates one router and 100 machines with the following names:
+
+.. code-block:: text
+
+ c-my_cluster_2_router.me
+ c-0.me
+ c-1.me
+ c-2.me
+ ...
+ c-99.me
+
+.. note::
+
+ The router name is defined as the resulting string: prefix + clusterId + "_router" + suffix.
+ In this case: *my_cluster_1_router* and *my_cluster_2_router.me*.
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_cabinet:
+
+<cabinet>
+---------
+
+.. note::
+ This tag is only available when the routing mode of the network zone
+ is set to ``Cluster``.
+
+The cabinet tag is, like the :ref:`pf_tag_cluster` tag,
+a meta-tag. This means that it is simply a shortcut for creating a set of (homogenous) hosts and links quickly;
+unsurprisingly, this tag was introduced to setup cabinets in data centers. Unlike
+:ref:`pf_tag_cluster`, however, the :ref:`pf_tag_cabinet` assumes that you create the backbone
+and routers yourself; see our examples below.
+
+**Parent tags:** :ref:`pf_tag_zone`
+
+**Children tags:** none
+
+**Attributes:**
+
+:``id``: The identifier of the cabinet. Facilitates referring to it.
+:``prefix``: Each node of the cabinet has to have a name. This name will be prefixed with this prefix.
+:``suffix``: Each node of the cabinet will be suffixed with this suffix.
+:``radical``: Regexp used to generate cabinet nodes name.
+ 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.
+
+ The produced number is concatenated between prefix and suffix to form machine names.
+:``speed``: Same as the ``speed`` attribute of the :ref:`pf_tag_host` tag.
+:``bw``: Bandwidth for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details.
+:``lat``: Latency for the links between nodes and backbone (if any). See the :ref:`pf_tag_link` for syntax/details.
+
+.. note::
+ Please note that as of now, it is impossible to change attributes such as,
+ amount of cores (always set to 1), the initial state of hosts/links
+ (always set to ON), the sharing policy of the links (always set to **SPLITDUPLEX** :ref:`pf_tag_link` ).
+
+
+Cabinet example
+^^^^^^^^^^^^^^^
+The following example shows how to use the cabinet tag.
+
+.. literalinclude:: ../../examples/platforms/meta_cluster.xml
+
+\note
+ Please note that you must specify the :ref:`pf_backbone` tag by yourself;
+ this is not done automatically and there are no checks
+ that ensure this backbone was defined.
+
+The hosts generated in the above example are named host-1.cluster, host-2.cluster1
+etc.
- <br />
