<br/>
<br/>
-Describing your Virtual Platform
-================================
+Describing your Simulated Platform
+##################################
+
+In SimGrid, platforms are usually described in XML. This formalism has
+some drawbacks, but using a specific format ensures that the platform
+is not mixed with the tested application. This separation of concern
+:ref:`is a must <howto_science>` for your Modeling and Simulation (M&S)
+work. When XML is too limiting, you may describe your platforms using
+the :ref:`lua bindings <platform_lua>` (it is not yet possible to do so in
+python or directly in C++).
+
+We understand that writing a complex platform description can be tricky, we thus included
+:ref:`many examples <platform_examples>` in the archive. This
+documentation also contains some :ref:`hints and howtos <howto>`, as well
+as the full :ref:`XML reference guide <platform_reference>`.
+
+
+Any simulated platform must contain **basic elements**, such as hosts, links, storages, etc. SimGrid gives you a great
+liberty when defining the **routing of your platform**, i.e., the network path taken between each pair of hosts.
+Finally, you may also describe an **experimental scenario**, with qualitative (e.g., bandwidth variations representing
+an external load) and qualitative (e.g., representing how some elements fail and restart over time) changes.
+
+
+First Example
+*************
+
+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.
+
+
+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
+******************************
+
+.. LocalWords: SimGrid
