-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.
-
+As @ref starting_components "explained in the introduction," any
+SimGrid study must entail the description of the platform on which you
+want to simulate your application. You have to describe **each element
+of your platform**, such as computing hosts, clusters, each disks,
+links, etc. You must also define the **routing on your platform**, ie
+which path is taken between two hosts. Finally, you may also describe
+an **experimental scenario**, with qualitative changes (e.g.,
+bandwidth changes representing an external load) and qualitative
+changes (representing how some elements fail and restart over time).
+
+You should really separate your application from the platform
+description, as it will ease your experimental campain afterward.
+Mixing them is seen as a really bad experimental practice. The easiest
+to enforce this split is to put the platform description in a XML
+file. Many example platforms are provided in the archive, and this
+page gives all needed details to write such files, as well as some
+hints and tricks about describing your platform.
+
+On the other side, XML is sometimes not expressive enough for some
+platforms, in particular large platforms exhibiting repetitive
+patterns that are not simply expressed in XML. In practice, many
+users end up generating their XML platform files from some sort of
+scripts. It is probably preferable to rewrite your XML @ref
+platform_lua "platform using the lua scripting language" instead.
+In the future, it should be possible to describe the platform directly
+in C++, but this is not possible yet.
+
+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_overview Describing the platform with XML
+
+Your platform description should follow the specification presented in
+the [simgrid.dtd](http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd)
+DTD file. The same DTD is used for both the platform and deployment
+files.
+
+From time to time, this DTD evolves to introduce possibly
+backward-incompatible changes. That is why each platform desciption is
+enclosed within a @c platform tag, that have a @c version attribute.
+The current version is <b>4.1</b>. The @c simgrid_update_xml program can
+upgrade most of the past platform files to the recent formalism.
+
+\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 "http://simgrid.gforge.inria.fr/simgrid/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
+
+As we said, the englobing @ref pf_overview "<platform>" tag is
+used to specify the dtd version used for this file.
+
+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
+
+\subsubsection pf_tag_host <host>
+
+An host is the computing resource on which an actor can execute.
+
+Attribute | Values | Description
+----------------- | -------------------------------------- | -----------
+id | String (mandatory) | The identifier of the host. facilitates referring to this AS.
+speed | double (mandatory) | Computational power of every core of this host in FLOPS (must be positive)
+core | int (defaults to 1) | Number of cores (see @ref howto_multicore)
+state | optionally "OFF" | If set to OFF, the host is initially turned off.
+availability_file | File name (optional) | (Relative or absolute) filename to use as input; must contain availability traces for this host. The syntax of this file is defined below.
+state_file | File name (optional) | File to use as a state profile (see @ref howto_churn)
+coordinates | String (mandatory when using Vivaldi routing) | The coordinates of this host (see @ref pf_P2P_tags).
+pstate | Double (Defaults to 0) | FIXME: Not yet documented.
+
+#### Included tags ####
+
+ - @ref pf_tag_mount Specifies the storages mounted on that host
+ - @ref pf_tag_prop Specifies a user-defined property of that host, that you can retrieve with MSG_host_get_property_value() or simgrid::s4u::Host::property().
+
+#### Examples ####
+
+\code{.xml}
+<host id="host1" speed="1000000000"/>
+<host id="host2" speed="1000000000">
+ <prop id="color" value="blue"/>
+ <prop id="rendershape" value="square"/>
+</host>
+\endcode
+
+\anchor pf_host_dynamism
+### Expressing dynamism ###
+
+SimGrid provides mechanisms to change a hosts' availability over
+time, using the ``availability_file`` attribute to the ``\<host\>`` tag
+and a separate text file whose syntax is exemplified below.
+
+#### Adding a trace file ####