various doc improvements

diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc
index 7622719..66e93c9 100644 (file)
--- a/doc/doxygen/platform.doc
+++ b/doc/doxygen/platform.doc
@@ -1,67 +1,6 @@
 /*! @page platform Describing the virtual platform
 
 
 /*! @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:
-
-![A hierarchy of networking zones.](AS_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).
-

 @section pf_res Resource description
 
 @subsection pf_res_computing Computing Resources
 @section pf_res Resource description
 
 @subsection pf_res_computing Computing Resources


@@ -700,29 +639,6 @@ the shortest paths.
 
 @subsection  pf_tag_zone &lt;zone&gt;
 
 
 @subsection  pf_tag_zone &lt;zone&gt;
 

-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
 @subsection pf_rm Routing models
 
 For each network zone, you must define explicitly which routing model will

diff --git a/docs/source/Tutorial_MPI_Applications.rst b/docs/source/Tutorial_MPI_Applications.rst
index 703f4ee..673d4ea 100644 (file)
--- a/docs/source/Tutorial_MPI_Applications.rst
+++ b/docs/source/Tutorial_MPI_Applications.rst
@@ -81,21 +81,26 @@ examples.
 Simple Example with 3 hosts
 ...........................
 
 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
 
 
 .. 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
 
 .. 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
 .......................
 
 Cluster with a Crossbar
 .......................

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3718fc1..91fd582 100644 (file)
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -30,7 +30,6 @@ Welcome to SimGrid's documentation!
          The MSG Interface <app_msg.rst>
          The Java Bindings <app_java.rst>
       Describing the Simulated Platform <platform.rst>
          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>
          Modeling Hints <platform_howtos.rst>
          DTD Reference <platform_reference.rst>
       Describing the Experimental Scenario <scenario.rst>

diff --git a/docs/source/platform.rst b/docs/source/platform.rst
index 4a9f3f9..1909927 100644 (file)
--- a/docs/source/platform.rst
+++ b/docs/source/platform.rst
@@ -35,19 +35,77 @@ Finally, you may also describe an **experimental scenario**, with qualitative (e
 an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
 
 
 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
 ******************
 
 
 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
 ******************************
 
 Performance Profiles and Churn
 ******************************
 

diff --git a/docs/source/platform_examples.rst b/docs/source/platform_examples.rst
deleted file mode 100644 (file)
index a3473f2..0000000
--- a/docs/source/platform_examples.rst
+++ /dev/null
@@ -1,61 +0,0 @@
-.. 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
-

diff --git a/docs/source/platform_reference.rst b/docs/source/platform_reference.rst
index e31551c..4e729a5 100644 (file)
--- a/docs/source/platform_reference.rst
+++ b/docs/source/platform_reference.rst
@@ -221,6 +221,25 @@ single element.
 :``state_file``: File containing the state profile. See :ref:`pf_tag_host`.
 
 |hr|
 :``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:
 
 
 .. _pf_tag_peer:
 


@@ -315,6 +334,26 @@ following functions:
 :``value``: Value of the defined property.
 
 |hr|
 :``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:
 
 
 .. _pf_tag_router:
 


@@ -335,6 +374,28 @@ break the routes that are longer than 1 hop.
    No other host or router may have the same name over the whole platform.
 :``coordinates``: Vivaldi coordinates. See :ref:`pf_tag_peer`.     
 
    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 />
 .. |br| raw:: html
 
    <br />

diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake
index e5a6a85..9fb63c2 100644 (file)
--- a/tools/cmake/DefinePackages.cmake
+++ b/tools/cmake/DefinePackages.cmake
@@ -888,7 +888,6 @@ set(DOC_SOURCES
   docs/source/Start_Your_Own_Project.rst
   docs/source/models.rst
   docs/source/platform.rst
   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
   docs/source/platform_howtos.rst
   docs/source/platform_reference.rst
   docs/source/Configuring_SimGrid.rst