-/*! \page platform Platform Description
-
-@tableofcontents
-
-In order to run any simulation, SimGrid needs 3 things: something to run
-(so, your code), a description of the platform on which you want to run your
-application, and finally it needs something to know where to deploy what.
-
-For the latest 2 entries, you have basically 2 ways to give it as an input :
-\li You can program it, either using the Lua console (\ref
- MSG_Lua_funct) or if you're using MSG some of its platform and
- deployments functions(\ref msg_simulation). If you want to use it,
- please refer to its doc. (you can also check the section \ref
- pf_flexml_bypassing but this is strongly deprecated, as there is a
- new way to do it properly, but not yet documented).
-\li You can use two XML files: a platform description file and a
- deployment description one.
-
-For the deployment stuff, please take a look at \ref deployment
-
-The platform description may be complicated. This documentation is all
-about how to write this file: what are the basic concept it relies on,
-what possibilities are offered, and some hints and tips on how to
-write a good platform description.
-
-\section pf_overview Some words about XML and DTD
-
-We choose to use XML because of some of its possibilities: if you're
-using an accurate XML editor, or simply using any XML plug-in for
-eclipse, it will allow you to have cool stuff like auto-completion,
-validation and checking, so all syntax errors may be avoided this
-way.
-
-the XML checking is done based on the dtd which is nowadays online at
-<a href="http://simgrid.gforge.inria.fr/simgrid.dtd">http://simgrid.gforge.inria.fr/simgrid.dtd</a>
-while you might be tempted to read it, it will not help you that much.
-
-If you read it, you should notice two or three important things :
-\li The platform tags contains a version attributes. At the time of
- writing this doc the current version is 3.
-\li The DTD contains definitions for the 2 files used by SimGrid (platform
- description and deployment).
-\li There is a bunch of possibilities ! Let's see what's in it
-
-
-\section pf_basics Basic concepts
-
-Nowadays, the Internet is composed of a bunch of independently managed
-networks. Within each of those networks, there are entry and exit
-points (most of the time, you can both enter and exit through the same
-point) that allows to go out of the current network and reach other
-networks. At the upper level, these networks are known as
-<b>Autonomous System (AS)</b>, while at the lower level they are named
-sub-networks, or LAN. Indeed they are autonomous: routing is defined
-within the limits of his network by the administrator, and so, those
-networks can continue to operate without the existence of other
-networks. There are some rules to get out of networks by the entry
-points (or gateways). Those gateways allow you to go from a network to
-another one. Inside of each autonomous system, there is a bunch of
-equipments (cables, routers, switches, computers) that belong to the
-autonomous system owner.
-
-SimGrid platform description file relies exactly on the same concepts
-as real life platform. Every resource (computers, network equipments,
-and so on) belongs to an AS. Within this AS, you can define the
-routing you want between its elements (that's done with the routing
-model attribute and eventually with some \<route\> tag). You define AS
-by using ... well ... the \<AS\> tag. An AS can also contain some AS :
-AS allows you to define the hierarchy of your platform.
-
-Within each AS, you basically have the following type of resources:
-\li <b>host</b>: an host, with cores in it, and so on
-\li <b>router</b>: a router or a gateway.
-\li <b>link</b>: a link, that defines a connection between two (or
- more) resources (and have a bandwidth and a latency)
-\li <b>cluster</b>: like a real cluster, contains many hosts
- interconnected by some dedicated network.
-
-Between those elements, a routing has to be defined. As the AS is
-supposed to be Autonomous, this has to be done at the AS level. As AS
-handles two different types of entities (<b>host/router</b> and
-<b>AS</b>) you will have to define routes between those elements. A
-network model have to be provided for AS, but you may/will need,
-depending of the network model, or because you want to bypass the
-default behavior to defines routes manually. There are 3 tags to use:
-\li <b>ASroute</b>: to define routes between two <b>AS</b>
-\li <b>route</b>: to define routes between two <b>host/router</b>
-\li <b>bypassRoute</b>: to define routes between two <b>AS</b> that
- will bypass default routing.
-
-Here is an illustration of the overall concepts:
-
-\htmlonly
-<a href="AS_hierarchy.png" border=0><img src="AS_hierarchy.png" width="30%" border=0 align="center"></a>
-<br/>
-\endhtmlonly
- Circles represent processing units and squares represent network routers. Bold
- lines represent communication links. 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).
-
-
-This is all for the concepts ! To make a long story short, a SimGrid
-platform is made of a hierarchy of AS, each of them containing
-resources, and routing is defined at AS level. Let's have a deeper
-look in the tags.
-
-
-
-\section pf_pftags Describing resources and their organization
-
-\subsection pf_As Platform organization tag : AS
-
-AS (or Autonomous System) is an organizational unit that contains
-resources and defines routing between them, and eventually some other
-AS. So it allows you to define a hierarchy into your platform.
-<b>*ANY*</b> resource <b>*MUST*</b> belong to an AS. There are a few
-attributes.
-
-<b>AS</b> attributes :
-\li <b>id (mandatory)</b>: the identifier of AS to be used when
- referring to it.
-\li <b>routing (mandatory)</b>: the routing model used into it. By
- model we mean the internal way the simulator will manage routing.
- That also have a big impact on how many information you'll have to
- provide to help the simulator to route between the AS elements.
- <b>routing</b> possible values are <b>Full, Floyd, Dijkstra,
- DijkstraCache, none, Vivaldi, Cluster</b>. For more
- explanation about what to choose, take a look at the section
- devoted to it below.
-
-Elements into an AS are basically resources (computers, network
-equipments) and some routing information if necessary (see below for
-more explanation).
-
-<b>AS example</b>
-\verbatim
-<AS id="AS0" routing="Full">
- <host id="host1" power="1000000000"/>
- <host id="host2" power="1000000000"/>
- <link id="link1" bandwidth="125000000" latency="0.000100"/>
- <route src="host1" dst="host2"><link_ctn id="link1"/></route>
- </AS>
-\endverbatim
-
-In this example, AS0 contains two hosts (host1 and host2). The route
-between the hosts goes through link1.
-
-
-\subsection pf_Cr Computing resources: hosts, clusters and peers.
-
-\subsubsection pf_host host
-
-A <b>host</b> represents a computer, where you will be able to execute
-code and from which you can send and receive information. A host can
-contain more than 1 core. Here are the attributes of a host :
-
-
-<b>host</b> attributes :
-\li <b>id (mandatory)</b>: the identifier of the host to be used when
- referring to it.
-\li <b>power (mandatory)</b>:the peak number FLOPS the CPU can manage.
- Expressed in flop/s.
-\li <b>core</b>: The number of core of this host (by default, 1). If
- you specify the amount of cores, the 'power' parameter is the power
- of each core.
- For example, if you specify that your host has 6 cores, it will be
- available to up to 6 sequential tasks without sharing. If more
- tasks are placed on this host, the resource will be shared
- accordingly. For example, if you schedule 12 tasks on that host,
- each will get half of the specified computing power. Please note
- that although sound, this model were never scientifically assessed.
- Please keep this fact in mind when using it.
-\li <b>availability</b>: specify if the percentage of power available.
-\li <b>availability_file</b>: Allow you to use a file as input. This
- file will contain availability traces for this computer. The
- syntax of this file is defined below. Possible values : absolute
- or relative path, syntax similar to the one in use on your system.
-\li <b>state</b>: the computer state, as in : is that computer ON or
- OFF. Possible values : "ON" or "OFF".
-\li <b>state_file</b>: Same mechanism as availability_file, similar
- syntax for value.
-\li <b>coordinates</b>: you'll have to give it if you choose the
- vivaldi, coordinate-based routing model for the AS the host
- belongs to. More details about it in the P2P coordinate based
- section.
-
-An host can contain some <b>mount</b> that defines mounting points
-between some storage resource and the <b>host</b>. Please refer to the
-storage doc for more information.
-
-An host can also contain the <b>prop</b> tag. the prop tag allows you
-to define additional information on this host following the
-attribute/value schema. You may want to use it to give information to
-the tool you use for rendering your simulation, for example.
-
-<b>host example</b>
-\verbatim
- <host id="host1" power="1000000000"/>
- <host id="host2" power="1000000000">
- <prop id="color" value="blue"/>
- <prop id="rendershape" value="square"/>
- </host>
-\endverbatim
-
-
-<b>Expressing dynamicity.</b>
-It is also possible to seamlessly declare a host whose
-availability changes over time using the availability_file
-attribute and a separate text file whose syntax is exemplified below.
-
-<b>Adding a trace file</b>
-\verbatim
- <platform version="1">
- <host id="bob" power="500000000"
- availability_file="bob.trace" />
- </platform>
-\endverbatim
-<b>Example of "bob.trace" file</b>
-\verbatim
-PERIODICITY 1.0
- 0.0 1.0
- 11.0 0.5
- 20.0 0.8
-\endverbatim
-
-At time 0, our host will deliver 500~Mflop/s. At time 11.0, it will
-deliver half, that is 250~Mflop/s until time 20.0 where it will
-will start delivering 80\% of its power, that is 400~Mflop/s. Last, at
-time 21.0 (20.0 plus the periodicity 1.0), we loop back to the
-beginning and the host will deliver again 500~Mflop/s.
-
-<b>Changing initial state</b>
-
-It is also possible to specify whether the host
-is up or down by setting the <b>state</b> attribute to either <b>ON</b>
-(default value) or <b>OFF</b>.
-
-<b>Expliciting the default value "ON"</b>
-\verbatim
- <platform version="1">
- <host id="bob"
- power="500000000"
- state="ON" />
- </platform>
-\endverbatim
-<b>Host switched off</b>
-\verbatim
- <platform version="1">
- <host id="bob"
- power="500000000"
- state="OFF" />
- </platform>
-\endverbatim
-<b>Expressing churn</b>
-To express the fact that a host can change state over time (as in P2P
-systems, for instance), it is possible to use a file describing the time
-at which the host is turned on or off. An example of the content
-of such a file is presented below.
-<b>Adding a state file</b>
- \verbatim
- <platform version="1">
- <host id="bob" power="500000000"
- state_file="bob.fail" />
- </platform>
- \endverbatim
-<b>Example of "bob.fail" file</b>
-\verbatim
- PERIODICITY 10.0
- 1.0 -1.0
- 2.0 1.0
-\endverbatim
-
-A negative value means <b>down</b> while a positive one means <b>up and
- running</b>. From time 0.0 to time 1.0, the host is on. At time 1.0, it is
-turned off and at time 2.0, it is turned on again until time 12 (2.0 plus the
-periodicity 10.0). It will be turned on again at time 13.0 until time 23.0, and
-so on.
-
-
-
-\subsubsection pf_cluster cluster
-
-A <b>cluster</b> represents a cluster. It is most of the time used
-when you want to have a bunch of machine defined quickly. It must be
-noted that cluster is meta-tag : <b>from the inner SimGrid point of
-view, a cluster is an AS where some optimized routing is defined</b>.