-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:
+It is certainly very tempting to defining how the information is
+routed in the simulated network in a way that is very similar to how
+it is defined on real network. One would have to define the routing
+tables of each routers interconnections sub-networks, just like in the
+real life. Given the daunting amount of configuration required, we
+could complete the information given by the user with classical
+protocols such as BGP and RIP. Many network simulator take such
+configuration as an input, for good reasons.
+
+This is not the way it goes in SimGrid: the network routing is defined
+in a global and compact way instead. This eases the modeling of very
+large systems, and allows highly optimized datastructures and
+algorithms in the simulator. The proposed description mechanism is
+thus much more convinient and efficient. In addition, it is more
+expressive than the classical solution based on forwarding tables on
+each host and router.
+
+The price to pay is that this representation of networks is very
+specific to SimGrid, so you will have to read further to understand
+it, even if you already know how real networks work.
+
+The central notion here are \b Networking \b Zones. NetZones represent
+network areas in which the routing is done in an homogeneous way.
+Conceptually, netzones generalize from the ideas of local networks
+(such as Ethernet switched networks) and Autonomous System. The
+network as a whole is represented as a single hierarchy of netzones,
+meaning that every netzone is part of another netzone (but the \c
+NetRoot, which is the top-level netzone).
+
+The main goal of the routing module is to provide a list of links
+traversed by a given communication and/or a latency to apply. These
+information are then used by the network model to compute the time
+that this communication takes. This information is retrieved by three
+combined algorithms: intra-zone routing, inter-zone routing, and the
+bypass mechanism.
+
+The <b>intra-zone level</b> is naturally handled by the netzones. Each
+netzone have to specify the routing algorithm it uses for that.
+@ref{FullZone} netzones have complete matrix where matrix(a,b)
+represents the full path (the list of links) between the hosts a and
+b. @ref{FloydZone} apply the Floyd-Warshall algorithm to compute the
+paths. @ref{ClusterZone} model classical switched or hub networks,
+where each component is connected through a private link onto a common
+backbone. Many other routing algorithms are provided to model the
+classical needs, but you can naturally define your own routing if the
+provided ones do not fit your needs.
+
+The <b>inter-zone algorithm</b> is used when the communication
+traverses more than one zone. The overall path goes from the source up
+in the netzones' tree, until the first common ancestor zone, and moves
+down to the destination. It crawls the differing netzones on its path
+according to the user-defined inter-zone routes, moving from gateway
+to gateway.
+
+You can also use the <b>bypass mechanism</b> to specify manually some
+shortcuts that directly provide the list of links interconnecting two
+given processes.
+
+
+\verbatim
+<AS id="netzone0" 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.
+
+A netzone can also contain itself one or more netzone; 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: