-/*! \page platform %Model the underlying platform
+/*! \page platform Describing the virtual platform
@tableofcontents
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 lastly information about the deployment
-process: Which process should be deployed to which processor/core?
+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 two possible ways you can provide
+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 MSG's platform and
- deployment functions (\ref msg_simulation). If you want to use this,
- check the particular documentation. (You can also check the section
- \ref pf_flexml_bypassing, however, this documentation is deprecated;
- there is a new, but undocumented, way to do it properly).
-\li You can use two XML files: one contains the platform description while
- the other contains the deployment instructions. The platform description
- can also be in Lua format.
-
-For more information on SimGrid's deployment features, please refer to
-the \ref deployment documentation.
-
-The platform description may be intricate. This documentation is all
-about how to write this file: The basic concepts are introduced. Furthermore,
-advanced options are explained. Additionally, some hints and tips on how to
-write a good platform description are given.
+\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 chose to use XML not only because it's 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
+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 Document Type Definition (DTD) file,
-available at
-<a href="http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd</a>.
+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 tags contain a version attribute; the current version is 4.
- This property might be used in the future to provide backwards
- compatibility.
-\li The DTD contains definitions for the two files used by SimGrid (i.e.,
- platform description and deployment).
+\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
~~~{.py}
PERIODICITY 10.0
- 1.0 -1.0
- 2.0 1.0
+ 1.0 0
+ 2.0 1
~~~
-A negative value means <b>down</b> (i.e., OFF) while a positive one means <b>up and
- running</b> (i.e., ON). 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
+A zero value means <b>down</b> (i.e., OFF) while a positive one means <b>up and
+ running</b> (i.e., ON). From time 0.0 to time 1.0, the host is on as usual. At time 1.0, it is
+turned off and at time 2.0, it is turned on again until time 12 (2 plus the
+periodicity 10). It will be turned off again at time 13.0 until time 23.0, and
so on.
is just some doc valuable only at the time of writing.
This section describes the storage management under SimGrid ; nowadays
it's only usable with MSG. It relies basically on linux-like concepts.
- You also may want to have a look to its corresponding section in \ref
- msg_file_management ; access functions are organized as a POSIX-like
+ You also may want to have a look to its corresponding section in
+ @ref msg_file ; access functions are organized as a POSIX-like
interface.
\subsubsection pf_sto_conc Storage - Main Concepts
<prop id="host/model" value="compound"></prop>
<prop id="network/model" value="SMPI"></prop>
<prop id="path" value="~/"></prop>
- <prop id="smpi/bw_factor" value="65472:0.940694;15424:0.697866;9376:0.58729"></prop>
+ <prop id="smpi/bw-factor" value="65472:0.940694;15424:0.697866;9376:0.58729"></prop>
</config>
<AS id="AS0" routing="Full">
| trace | yes | String | Identifier of the referenced trace (specified of the trace's \c id attribute) |
| element | yes | String | The identifier of the referenced entity as given by its \c id attribute |
-\section pf_hints Hints and tips, or how to write a platform efficiently
+\section pf_hints Hints, tips and frequently requested features
Now you should know at least the syntax and be able to create a
platform by your own. However, after having ourselves wrote some platforms, there
produce good platform and some choices you can make in order to have
faster simulations. Here's some hints and tips, then.
+@subsection Finding the platform example that you need
+
+Most platform files that we ship are in the @c examples/platforms
+folder. The good old @c grep tool can find the examples you need when
+wondering on a specific XML tag. Here is an example session searching
+for @ref pf_trace "trace_connect":
+
+@verbatim
+% cd examples/platforms
+% grep -R -i -n --include="*.xml" "trace_connect" .
+./two_hosts_platform_with_availability_included.xml:26:<trace_connect kind="SPEED" trace="A" element="Cpu A"/>
+./two_hosts_platform_with_availability_included.xml:27:<trace_connect kind="HOST_AVAIL" trace="A_failure" element="Cpu A"/>
+./two_hosts_platform_with_availability_included.xml:28:<trace_connect kind="SPEED" trace="B" element="Cpu B"/>
+./two_hosts.xml:17: <trace_connect trace="Tremblay_power" element="Tremblay" kind="SPEED"/>
+@endverbatim
+
\subsection pf_as_h AS Hierarchy
The AS design allows SimGrid to go fast, because computing route is
done only for the set of resources defined in this AS. If you're using
\li <b>Cluster</b>: Cluster routing, specific to cluster tag, should
not be used.
-\subsection pf_switch How to describe a switch given that is no switch tag?
+\subsection pf_switch I want to describe a switch but there is no switch tag!
+
+Actually we did not include switch tag. But when you're trying to
+simulate a switch, assuming
+fluid bandwidth models are used (which SimGrid uses by default unless
+ns-3 or constant network models are activated), the limiting factor is
+switch backplane bandwidth. So, essentially, at least from
+the simulation perspective, a switch is similar to a
+link: some device that is traversed by flows and with some latency and
+so,e maximum bandwidth. Thus, you can simply simulate a switch as a
+link. Many links
+can be connected to this "switch", which is then included in routes just
+as a normal link.
-Actually we did not include switch tag, ok. But when you're trying to
-simulate a switch, the only major impact it has when you're using
-fluid model (and SimGrid uses fluid model unless you activate
-ns-3 or constant network mode) is the impact of the upper limit of
-the switch motherboard speed that will eventually be reached if you're
-using intensively your switch. So, the switch impact is similar to a
-link one. That's why we are used to describe a switch using a link tag
-(as a link is not an edge by a hyperedge, you can connect more than 2
-other links to it).
-\subsection pf_multicabinets How to model multi-cabinets clusters?
+\subsection pf_multicabinets I want to describe multi-cabinets clusters!
You have several possibilities, as usual when modeling things. If your
cabinets are homogeneous and the intercabinet network negligible for
<cluster> per cabinet and interconnect them together. This is
what we did in the G5K example platform for the Graphen cluster.
-\subsection pf_platform_multipath How to express multipath routing in platform files?
+\subsection pf_platform_multipath I want to express multipath routing in platform files!
It is unfortunately impossible to express the fact that there is more
than one routing path between two given hosts. Let's consider the
