-In order to run any simulation, SimGrid must be provided with three things:
-something to run (i.e., your code), a description of the platform on which you want to simulate your application, and
-information about the deployment of the application: Which process should be executed onto which processor/core?
-
-For the last two items, there are essentially three possible ways you can provide
-this information as an input:
-\li You can program, if you're using MSG, some of the platform and
- deployment functions. If you choose to follow this approach, check the dedicated documentation
- (\ref msg_simulation).
-\li You can use two XML files: one for the platform description and the other for the deployment.
-\li You can program the description of your platform in Lua format.
-
-For more information on SimGrid's deployment features, please refer to the \ref deployment section.
-
-The platform description may be intricate. This documentation is all about how to write this file. First, the basic
-concepts are introduced. Then, advanced options are explained. Finally, some hints and tips on how to write a better
-platform description are given.
-
-\section pf_overview Some words about XML and DTD
-
-We opted for XML not only because it is extensible but also because many tools (and plugins for existing tools) are
-available that facilitate editing and validating XML files. Furthermore, libraries that parse XML are often already
-available and very well tested.
-
-The XML checking is done based on the [simgrid.dtd](http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd) Document Type
-Definition (DTD) file.
-
-If you read the DTD, you should notice the following:
-\li The platform tag has a version attribute. The current version is <b>4</b>. This attribute might be used in the
- provide backward compatibility.
-\li The DTD contains definitions for both the platform description and deployment files used by SimGrid.
-
-\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); this allows to leave the current network and reach other
-networks, possibly even in other locations. At the upper level, such a
-network is called <b>Autonomous System (AS)</b>, while at the lower
-level it is named sub-network, or LAN (local area network). They are
-indeed autonomous: routing is defined (within the limits of his
-network) by the administrator, and so, those networks can operate
-without a connection to other networks. So-called gateways allow you
-to go from one network to another, if such a (physical) connection
-exists. Every node in one network that can be directly reached (i.e.,
-without traversing other nodes) from another network is called a
-gateway. Each autonomous system consists of equipment such as cables
-(network links), routers and switches as well as computers.
-
-The structure of the SimGrid platform description relies exactly on
-the same concept as a real-life platform (see above). Every resource
-(computers, network equipment etc.) belongs to an AS, which can be
-defined by using the \<AS\> tag. Within an AS, the routing between its
-elements can be defined abitrarily. There are several modes for
-routing, and exactly one mode must be selected by specifying the
-routing attribute in the AS tag:
-
-\verbatim
-<AS id="AS0" routing="Full">
-\endverbatim
-
-\remark
- Other supported values for the routing attribute can be found below, Section
- \ref pf_raf.
-
-There is also the ``<route>`` tag; this tag takes two attributes,
-``src`` (source) and ``dst`` (destination). Both source and
-destination must be valid identifiers for routers (these will be
-introduced later). Contained by the ``<route>`` are network links;
-these links must be used in order to communicate from the source to
-the destination specified in the tag. Hence, a route merely describes
-how to reach a router from another router.
-
-\remark
- More information and (code-)examples can be found in Section \ref pf_rm.
-
-An AS can also contain itself one or more AS; this allows you to model
-the hierarchy of your platform.
-
-### Within each AS, the following types of resources exist:
-
-%Resource | Documented in Section | Description
---------------- | --------------------- | -----------
-AS | | Every Autonomous System (AS) may contain one or more AS.
-host | \ref pf_host | This entity carries out the actual computation. For this reason, it contains processors (with potentially multiple cores).
-router | \ref pf_router | In SimGrid, routers are used to provide helpful information to routing algorithms. Routers may also act as gateways, connecting several autonomous systems with each other.
-link | \ref pf_link | In SimGrid, (network)links define a connection between two or potentially even more resources. Every link has a bandwidth and a latency and may potentially experience congestion.
-cluster | \ref pf_cluster | In SimGrid, clusters were introduced to model large and homogenous environments. They are not really a resource by themselves - technically, they are only a shortcut, as they will internally set up all the hosts, network and routing for you, i.e., using this resource, one can easily setup thousands of hosts and links in a few lines of code. Each cluster is itself an AS.
-
-As it is desirable to interconnect these resources, a routing has to
-be defined. The AS is supposed to be Autonomous, hence this has to be
-done at the AS level. The AS handles two different types of entities
-(<b>host/router</b> and <b>AS</b>). However, the user is responsible
-to define routes between those resources, otherwise entities will be
-unconnected and therefore unreachable from other entities. Although
-several routing algorithms are built into SimGrid (see \ref pf_rm),
-you might encounter a case where you want to define routes manually
-(for instance, due to specific requirements of your platform).
-
-There are three 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 (as specified by the ``routing`` attribute
- supplied to ``<AS>``, see above).
+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