/*! @page platform Describing the virtual platform
-
-As usual, SimGrid is a versatile framework, and you should find the
-way of describing your platform that best fits your experimental
-practice.
-
-@section pf_first_example First Platform Example
-
-Here is a very simple platform file, containing 3 resources (two hosts
-and one link), and explicitly giving the route between the hosts.
-
-@code{.xml}
-<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
-<platform version="4.1">
- <zone id="first zone" routing="Full">
- <!-- the resources -->
- <host id="host1" speed="1Mf"/>
- <host id="host2" speed="2Mf"/>
- <link id="link1" bandwidth="125MBps" latency="100us"/>
- <!-- the routing: specify how the hosts are interconnected -->
- <route src="host1" dst="host2">
- <link_ctn id="link1"/>
- </route>
- </zone>
-</platform>
-@endcode
-
-
-Then, every resource (specified with @ref pf_tag_host, @ref
-pf_tag_link or others) must be located within a given **networking
-zone**. Each zone is in charge of the routing between its
-resources. It means that when an host wants to communicate with
-another host of the same zone, it is the zone's duty to find the list
-of links that are involved in the communication. Here, since the @ref
-pf_tag_zone tag has **Full** as a **routing attribute**, all routes
-must be explicitely given using the @ref pf_tag_route and @ref
-pf_tag_linkctn tags (this @ref pf_rm "routing model" is both simple
-and inefficient :) It is OK to not specify the route between two
-hosts, as long as the processes located on them never try to
-communicate together.
-
-A zone can contain several zones itself, leading to a hierarchical
-decomposition of the platform. This can be more efficient (as the
-inter-zone routing gets factorized with @ref pf_tag_zoneroute), and
-allows to have more than one routing model in your platform. For
-example, you could have a coordinate-based routing for the WAN parts
-of your platforms, a full routing within each datacenter, and a highly
-optimized routing within each cluster of the datacenter. In this
-case, determining the route between two given hosts gets @ref
-routing_basics "somewhat more complex" but SimGrid still computes
-these routes for you in a time- and space-efficient manner.
-Here is an illustration of these concepts:
-
-
-
-Circles represent processing units and squares represent network
-routers. Bold lines represent communication links. The zone "AS2"
-models the core of a national network interconnecting a small flat
-cluster (AS4) and a larger hierarchical cluster (AS5), a subset of a
-LAN (AS6), and a set of peers scattered around the world (AS7).
-
@section pf_res Resource description
@subsection pf_res_computing Computing Resources
@subsection pf_tag_zone <zone>
-Before SimGrid v3.16, networking zones used to be called Autonomous
-Systems, but this was misleading as zones may include other zones in a
-hierarchical manner. If you find any remaining reference to network
-zones, please report this as a bug.
-
-Attribute | Value | Description
------------ | ------------------------------------------------- | ----------------------------------------------
-id | String (mandatory) | The identifier of this zone (must be unique)
-routing | One of the existing routing algorithm (mandatory) | See Section @ref pf_rm for details.
-
-<b>Example:</b>
-@code
-<zone id="zone0" routing="Full">
- <host id="host1" speed="1000000000"/>
- <host id="host2" speed="1000000000"/>
- <link id="link1" bandwidth="125000000" latency="0.000100"/>
- <route src="host1" dst="host2"><link_ctn id="link1"/></route>
-</zone>
-@endcode
-
-In this example, zone0 contains two hosts (host1 and host2). The route
-between the hosts goes through link1.
-
@subsection pf_rm Routing models
For each network zone, you must define explicitly which routing model will
Simple Example with 3 hosts
...........................
-At the most basic level, you can describe your simulated platform as a
-graph of hosts and network links. For instance:
+Imagine you want to describe a little platform with three hosts,
+interconnected as follows:
.. image:: /tuto_smpi/3hosts.png
:align: center
+This can be done with the following platform file, that considers the
+simulated platform as a graph of hosts and network links.
+
.. literalinclude:: /tuto_smpi/3hosts.xml
:language: xml
-Note the way in which hosts, links, and routes are defined in
-this XML. All hosts are defined with a speed (in Gflops), and links
-with a latency (in us) and bandwidth (in MBytes per second). Other
-units are possible and written as expected. Routes specify the list of
-links encountered from one route to another. Routes are symmetrical by
-default.
+The elements basic elements (with :ref:`pf_tag_host` and
+:ref:`pf_tag_link`) are described first, and then the routes between
+any pair of hosts are explicitely given with :ref:`pf_tag_route`. Any
+host must be given a computational speed (in flops) while links must
+be given a latency (in seconds) and a bandwidth (in bytes per
+second). Note that you can write 1Gflops instead of 1000000000flops,
+and similar. Last point: :ref:`pf_tag_route`s are symmetrical by
+default (but this can be changed).
Cluster with a Crossbar
.......................
The MSG Interface <app_msg.rst>
The Java Bindings <app_java.rst>
Describing the Simulated Platform <platform.rst>
- Examples <platform_examples.rst>
Modeling Hints <platform_howtos.rst>
DTD Reference <platform_reference.rst>
Describing the Experimental Scenario <scenario.rst>
an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
-Defining Basic Elements
-***********************
+First Example
+*************
-These are the components of your platform.
+Imagine you want to describe a little platform with three hosts,
+interconnected as follows:
+.. image:: /tuto_smpi/3hosts.png
+ :align: center
+
+This can be done with the following platform file, that considers the
+simulated platform as a graph of hosts and network links.
+
+.. literalinclude:: /tuto_smpi/3hosts.xml
+ :language: xml
+
+The most important elements are the basic ones: :ref:`pf_tag_host`,
+:ref:`pf_tag_link`, and similar. Then come the routes between any pair
+of hosts, that are given explicitely with :ref:`pf_tag_route` (routes
+are symmetrical by default). Any host must be given a computational
+speed (in flops) while links must be given a latency (in seconds) and
+a bandwidth (in bytes per second). Note that you can write 1Gflops
+instead of 1000000000flops, and similar.
+
+Every platform element must be located within a given **networking
+zone** . Zones are in
+charge of the routing, see below.
+
+The last thing you must know on SimGrid platform files is that the
+root tag must be :ref:`pf_tag_platform`. If the ``version`` attribute
+does not match what SimGrid expects, you will be hinted to use to the
+``simgrid_update_xml`` utility to update your file.
-There is not much to say about the definition of basic elements. Just
-use the appropriate tags: :ref:`pf_tag_host`, :ref:`pf_tag_link` and
-:ref:`pf_tag_storage`.
Defining a Routing
******************
+Networking zones (:ref:`pf_tag_zone`) are used to factorize the description
+to reduce the size of your platform on disk and in memory. Then, when
+a host wants to communicate with another host belonging to the same
+zone, it is the zone's duty to find the list of links that are
+involved in the communication. In the above example, since we use
+``routing="Full"``, all routes must be explicitly given using the
+:ref:`pf_tag_route` and :ref:`pf_tag_link_ctn` tags (this :ref:`routing
+model <pf_rm>` is both simple and inefficient :) It is OK to not
+specify each and every route between hosts, as long as you do not try
+to start a communication on any of the missing routes during your
+simulation.
+
+Any zone may contain sub-zones, allowing for a hierarchical
+decomposition of the platform. Routing can be made more efficient (as the
+inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
+allows you to have more than one routing model in your platform. For
+example, you can have a coordinate-based routing for the WAN parts
+of your platforms, a full routing within each datacenter, and a highly
+optimized routing within each cluster of the datacenter. In this
+case, determining the route between two given hosts gets :ref:`routing_basics`
+"somewhat more complex" but SimGrid still computes
+these routes for you in a time- and space-efficient manner.
+Here is an illustration of these concepts:
+
+.. image:: img/zone_hierarchy.png
+
+Circles represent processing units and squares represent network
+routers. Bold lines represent communication links. The zone "AS2" models the core of a national network interconnecting a
+small flat cluster (AS4) and a larger hierarchical cluster (AS5), a
+subset of a LAN (AS6), and a set of peers scattered around the world
+(AS7).
+
+.. todo:: Add more examples, such as the cloud example described in
+ previous paragraph
+
Performance Profiles and Churn
******************************
+++ /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_examples:
-
-Platform Examples
-=================
-
-Here is a very simple platform file, containing 3 resources (two hosts
-and one link), and explicitly giving the route between the hosts.
-
-.. literalinclude:: ../../examples/platforms/two_hosts.xml
- :language: xml
-
-The root tag must be ``<platform>``, and its ``version`` attribute
-specifies which version of the DTD is use. When an evolution of the DTD introduces
-backward-incompatible changes, this number gets updated. Use the
-``simgrid_update_xml`` utility to upgrade your platform files on need.
-
-Then, every platform element must be located within a given
-**networking zone** introduced with the :ref:`pf_tag_zone` tag. Zones
-are in charge of the routing. If a host wants to communicate with
-another host belonging to the same zone, it is the zone's duty to find the list
-of links that are involved in the communication. Here, since we use
-``routing="Full"``, all routes must be explicitly given using the
-:ref:`pf_tag_route` and :ref:`pf_tag_linkctn` tags (this :ref:`routing
-model <pf_rm>` is both simple and inefficient :) It is OK to not
-specify each and every route between hosts, as long as you do not try to start
-a communication on any of the missing routes during your simulation.
-
-Any zone may contain sub-zones, allowing for a hierarchical
-decomposition of the platform. Routing can be made more efficient (as the
-inter-zone routing gets factored with :ref:`pf_tag_zoneroute`), and
-allows you to have more than one routing model in your platform. For
-example, you can have a coordinate-based routing for the WAN parts
-of your platforms, a full routing within each datacenter, and a highly
-optimized routing within each cluster of the datacenter. In this
-case, determining the route between two given hosts gets :ref:`routing_basics`
-"somewhat more complex" but SimGrid still computes
-these routes for you in a time- and space-efficient manner.
-Here is an illustration of these concepts:
-
-.. image:: img/zone_hierarchy.png
-
-The zone "AS2" models the core of a national network interconnecting a
-small flat cluster (AS4) and a larger hierarchical cluster (AS5), a
-subset of a LAN (AS6), and a set of peers scattered around the world
-(AS7).
-
-.. todo:: Add more examples, such as the cloud example described in
- previous paragraph
-
:``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
|hr|
+
+.. _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``: Whether to use the uplink (with ``UP``) or downlink
+ (with ``DOWN``) of the link. This is only valid if the
+ link has ``sharing=SPLITDUPLEX``.
+
+|hr|
.. _pf_tag_peer:
:``value``: Value of the defined property.
|hr|
+
+.. _pf_tag_route:
+
+------------------------------------------------------------------
+<route>
+------------------------------------------------------------------
+
+A path between two network locations, composed of several :ref:`pf_tag_link`s.
+
+**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``.
+
+|hr|
.. _pf_tag_router:
No other host or router may have the same name over the whole platform.
:``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.
+|hr|
+
+.. _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 />
docs/source/Start_Your_Own_Project.rst
docs/source/models.rst
docs/source/platform.rst
- docs/source/platform_examples.rst
docs/source/platform_howtos.rst
docs/source/platform_reference.rst
docs/source/Configuring_SimGrid.rst
