From: Martin Quinson Date: Mon, 1 Apr 2019 21:37:58 +0000 (+0200) Subject: various doc improvements X-Git-Tag: v3_22~1 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/501196fba8269024636b011851ce7ea63d7696c9 various doc improvements --- diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 7622719696..66e93c9fef 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -1,67 +1,6 @@ /*! @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} - - - - - - - - - - - - - - -@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 @@ -700,29 +639,6 @@ the shortest paths. @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. - -Example: -@code - - - - - - -@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 diff --git a/docs/source/Tutorial_MPI_Applications.rst b/docs/source/Tutorial_MPI_Applications.rst index 703f4ee94c..673d4eadb4 100644 --- a/docs/source/Tutorial_MPI_Applications.rst +++ b/docs/source/Tutorial_MPI_Applications.rst @@ -81,21 +81,26 @@ examples. 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 ....................... diff --git a/docs/source/index.rst b/docs/source/index.rst index 3718fc10da..91fd582cd3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,7 +30,6 @@ Welcome to SimGrid's documentation!    The MSG Interface    The Java Bindings Describing the Simulated Platform -    Examples    Modeling Hints    DTD Reference Describing the Experimental Scenario diff --git a/docs/source/platform.rst b/docs/source/platform.rst index 4a9f3f9f2d..1909927daf 100644 --- 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. -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 ` 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 ****************************** diff --git a/docs/source/platform_examples.rst b/docs/source/platform_examples.rst deleted file mode 100644 index a3473f283e..0000000000 --- a/docs/source/platform_examples.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. raw:: html - - - -
-
- -.. _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 ````, 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 ` 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 e31551cd66..4e729a5ba0 100644 --- 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| + +.. _pf_tag_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: @@ -315,6 +334,26 @@ following functions: :``value``: Value of the defined property. |hr| + +.. _pf_tag_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: @@ -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`. +|hr| + +.. _pf_tag_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
diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index e5a6a85eab..9fb63c2941 100644 --- 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/platform_examples.rst docs/source/platform_howtos.rst docs/source/platform_reference.rst docs/source/Configuring_SimGrid.rst