-/*! \page platform Step 1: %Model the underlying platform
+/*! \page platform Model the underlying 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.dtd">http://simgrid.gforge.inria.fr/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 3.
- 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
#### Adding a trace file ####
\verbatim
-<platform version="1">
- <host id="bob" power="500000000" availability_file="bob.trace" />
+<platform version="4">
+ <host id="bob" power="500Gf" availability_file="bob.trace" />
</platform>
\endverbatim
#### Example: Expliciting the default value "ON" ####
\verbatim
-<platform version="1">
- <host id="bob" power="500000000" state="ON" />
+<platform version="4">
+ <host id="bob" power="500Gf" state="ON" />
</platform>
\endverbatim
#### Adding a state file ####
\verbatim
-<platform version="1">
- <host id="bob" power="500000000" state_file="bob.fail" />
+<platform version="4">
+ <host id="bob" power="500Gf" state_file="bob.fail" />
</platform>
\endverbatim
~~~{.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.
bb_bw | no | int | Bandwidth for backbone (if any). See <b>link</b> section for syntax/details. If bb_bw and bb_lat (see below) attributes are omitted, no backbone is created (alternative cluster architecture <b>described before</b>).
bb_lat | no | int | Latency for backbone (if any). See <b>link</b> section for syntax/details. If bb_lat and bb_bw (see above) attributes are omitted, no backbone is created (alternative cluster architecture <b>described before</b>).
bb_sharing_policy | no | string | Sharing policy for the backbone (if any). See <b>link</b> section for syntax/details.
-availability_file | no | string | Allows you to use a file as input for availability. Similar to <b>hosts</b> attribute.
-state_file | no | string | Allows you to use a file as input for states. Similar to <b>hosts</b> attribute.
+limiter_link | no | int | Bandwidth for limiter link (if any). This adds a specific link for each node, to set the maximum bandwidth reached when communicating in both directions at the same time. In theory this value should be 2*bw for fullduplex links, but in reality this might be less. This value will depend heavily on the communication model, and on the cluster's hardware, so no default value can be set, this has to be measured. More details can be obtained in <a href="https://hal.inria.fr/hal-00919507/"> "Toward Better Simulation of MPI Applications on Ethernet/TCP Networks"</a>
loopback_bw | no | int | Bandwidth for loopback (if any). See <b>link</b> section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref pf_sharing_policy_fatpipe "\b FATPIPE".
loopback_lat | no | int | Latency for loopback (if any). See <b>link</b> section for syntax/details. See loopback_bw for more info.
topology | no | FLAT\|TORUS\|FAT_TREE (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), <a href="http://en.wikipedia.org/wiki/Torus_interconnect">TORUS </a> and FAT_TREE attributes for this tag.
\verbinclude example_filelist_xmltag_mount
-\anchor pf_storage_entity_mstorage
-#### <mstorage> ####
-\note
- This is currently unused.
-
-<b>mstorage</b> attributes :
-\li <b>typeId (mandatory)</b>: the id of the <b>storage</b> that must
- be mounted on that computer.
-\li <b>name (mandatory)</b>: the name that will be the logical
- reference to this disk (the mount point).
-
\subsubsection pf_storage_example_files Example files
Several examples were already discussed above; if you're interested in full examples,
\verbinclude example_filelist_routing_dijkstra
-Dijsktra example :
+Dijkstra example :
\verbatim
- <AS id="AS_2" routing="Dijsktra">
+ <AS id="AS_2" routing="Dijkstra">
<host id="AS_2_host1" power="1000000000"/>
<host id="AS_2_host2" power="1000000000"/>
<host id="AS_2_host3" power="1000000000"/>
\anchor pf_routing_model_dijkstracache
### DijkstraCache ###
-DijsktraCache example:
+DijkstraCache example:
\verbatim
-<AS id="AS_2" routing="DijsktraCache">
+<AS id="AS_2" routing="DijkstraCache">
<host id="AS_2_host1" power="1000000000"/>
...
(platform unchanged compared to upper example)
| Attribute name | Mandatory | Values | Description |
| --------------- | --------- | ------ | ----------- |
| id | yes | String | The identifier of the link that should be added to the route. |
-| direction | maybe | UP\|DOWN | If the link referenced by \c id has been declared as \ref pf_sharing_policy_fullduplex "FULLDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use FULLDUPLEX, this attribute has no effect.
+| direction | maybe | UP\|DOWN | If the link referenced by \c id has been declared as \ref pf_sharing_policy_fullduplex "FULLDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use FULLDUPLEX, do not use this attribute or SimGrid will not find the right link.
#### Example Files ####
information to SimGrid. Here is a file doing it all :
\verbatim
-<AS id="AS_Big" routing="Dijsktra">
+<AS id="AS_Big" routing="Dijkstra">
<AS id="AS_1" routing="Full">
<host id="AS_1_host1" power="1000000000"/>
<link id="AS_1_link" bandwidth="1250000000" latency="5E-4"/>
\section pf_other_tags Tags not (directly) describing the platform
-There are 3 tags, that you can use inside a \<platform\> tag that are
-not describing the platform:
-\li \ref pf_random "random": it allows you to define random generators you want to use
- for your simulation.
+The following tags can be used inside a \<platform\> tag even if they are not
+directly describing the platform:
\li \ref pf_config "config": it allows you to pass some configuration stuff like, for
example, the network model and so on. It follows the
\li \ref pf_include "include": allows you to include another file into the current one.
\verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
+<platform version="4">
<config id="General">
<prop id="maxmin/precision" value="0.000010"></prop>
<prop id="cpu/optim" value="TI"></prop>
<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">
...
\endverbatim
+\subsection pf_include include
-\subsection pf_random random
-
-<b>This has not yet been implemented.</b>
+Even if it can be used in other contexts, this tag was originally created
+to be used with \ref pf_trace. The idea was to have a file describing the
+platform, and another file attaching traces of a given period to the platform.
-\subsection pf_include include
+The drawback is that the file chuncks that will be included do not
+constitute valid XML files. This may explain why this feature was never really
+used in practice (as far as we know). Other mechanisms, such as the ability to load
+several platform files one after the other, could be considered in the future.
-The \c include tag allows you to import other platforms into your
+In the meanwhile, the \c include tag allows you to import other platforms into your
local file. This is done with the intention to help people
combine their different AS and provide new platforms. Those files
should contain XML that consists of
\ref pf_include "include", \ref pf_cluster "cluster", \ref pf_peer "peer", \ref pf_As "AS", \ref pf_trace "trace", \ref pf_trace "tags".
-\note
- Due to some obscure technical reasons, you have to open
- and close the tag in order to make it work.
+Do not forget to close the tag to make it work, or you will end up with an invalid XML file.
#### Attributes ####
| Attribute name | Mandatory | Values | Description |
| --------------- | --------- | ---------------------- | ----------- |
-| file | yes | String | Filename of the path you want to include with either relative or absolute path. Syntax is defined by your OS |
+| file | yes | String | Filename of the path you want to include with either relative or absolute path. |
#### Example ####
\verbatim
<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
+<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid/simgrid.dtd">
+<platform version="4">
<AS id="main" routing="Full">
<include file="clusterA.xml"></include>
<include file="clusterB.xml"></include>
| 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
<ASroute src="cl_4_1"
dst="cl_4_2"
gw_src="c_4_1-cl_4_1_router"
- gw_dst="c_4_2-cl_4_2_router"
- symmetrical="YES">
+ gw_dst="c_4_2-cl_4_2_router">
<link_ctn id="4_1"/>
<link_ctn id="bb_4"/>
<link_ctn id="4_2"/>
<ASroute src="cl_4_1"
dst="exitAS_4"
gw_src="c_4_1-cl_4_1_router"
- gw_dst="router_4"
- symmetrical="YES">
+ gw_dst="router_4">
<link_ctn id="4_1"/>
<link_ctn id="bb_4"/>
</ASroute>
<ASroute src="cl_4_2"
dst="exitAS_4"
gw_src="c_4_2-cl_4_2_router"
- gw_dst="router_4"
- symmetrical="YES">
+ gw_dst="router_4">
<link_ctn id="4_2"/>
<link_ctn id="bb_4"/>
</ASroute>
\verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
+<platform version="4">
<config id="General">
<prop id="network/coordinates" value="yes"></prop>
</config>
<AS id="AS0" routing="Vivaldi">
- <host id="100030591" coordinates="25.5 9.4 1.4" power="1500000000.0" />
- <host id="100036570" coordinates="-12.7 -9.9 2.1" power="730000000.0" />
+ <host id="100030591" coordinates="25.5 9.4 1.4" power="1.5Gf" />
+ <host id="100036570" coordinates="-12.7 -9.9 2.1" power="7.3Gf" />
...
- <host id="100429957" coordinates="17.5 6.7 18.8" power="830000000.0" />
+ <host id="100429957" coordinates="17.5 6.7 18.8" power="8.3Gf" />
</AS>
</platform>
\endverbatim
-Coordinates are then used to calculate latency between two hosts by
-calculating the euclidean distance between the two hosts coordinates.
-The results express the latency in ms.
+Coordinates are then used to calculate latency (in microseconds)
+between two hosts by calculating the distance between the two hosts
+coordinates with the following formula: distance( (x1, y1, z1), (x2,
+y2, z2) ) = euclidian( (x1,y1), (x2,y2) ) + abs(z1) + abs(z2)
+
+In other words, we take the euclidian distance on the two first
+dimensions, and then add the absolute values found on the third
+dimension. This may seem strange, but it was found to allow better
+approximations of the latency matrices (see the paper describing
+Vivaldi).
Note that the previous example defines a routing directly between hosts but it could be also used to define a routing between AS.
That is for example what is commonly done when using peers (see Section \ref pf_peer).
\verbatim
<?xml version='1.0'?>
<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
+<platform version="4">
<config id="General">
-
<prop id="network/coordinates" value="yes"></prop>
+ <prop id="network/coordinates" value="yes"></prop>
</config>
<AS id="AS0" routing="Vivaldi">
<peer id="peer-0" coordinates="173.0 96.8 0.1" power="730Mf" bw_in="13.38MBps" bw_out="1.024MBps" lat="500us"/>
\li <b>Cluster</b>: Cluster routing, specific to cluster tag, should
not be used.
-\subsection pf_switch Hey, I want to describe a switch but there 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, ok. But when you're trying to
simulate a switch, the only major impact it has when you're using
(as a link is not an edge by a hyperedge, you can connect more than 2
other links to it).
-\subsection pf_platform_multipath How to express multipath routing in platform files?
+\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
+your study, you should just create a larger cluster with all hosts at
+the same layer.
+
+In the rare case where your hosts are not homogeneous between the
+cabinets, you can create your cluster completely manually. For that,
+create an As using the Cluster routing, and then use one
+<cabinet> for each cabinet. This cabinet tag can only be used an
+As using the Cluster routing schema, and creating
+
+Be warned that creating a cluster manually from the XML with
+<cabinet>, <backbone> and friends is rather tedious. The
+easiest way to retrieve some control of your model without diving into
+the <cluster> internals is certainly to create one separate
+<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 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
the provided ones.
You are also free to declare platform where the routing is not
-symmetric. For example, add the following to the previous file:
+symmetrical. For example, add the following to the previous file:
\verbatim
<route src="C" dst="A">
the realism of very regular platforms which is questionable, but
that's another story).
-\section pf_flexml_bypassing Bypassing the XML parser with your own C functions
-<b>NOTE THAT THIS DOCUMENTATION, WHILE STILL WORKING, IS STRONGLY DEPRECATED</b>
-
-So you want to bypass the XML files parser, uh? Maybe doing some parameter
-sweep experiments on your simulations or so? This is possible, and
-it's not even really difficult (well. Such a brutal idea could be
-harder to implement). Here is how it goes.
-
-For this, you have to first remember that the XML parsing in SimGrid is done
-using a tool called FleXML. Given a DTD, this gives a flex-based parser. If
-you want to bypass the parser, you need to provide some code mimicking what
-it does and replacing it in its interactions with the SURF code. So, let's
-have a look at these interactions.
-
-FleXML parser are close to classical SAX parsers. It means that a
-well-formed SimGrid platform XML file might result in the following
-"events":
-
- - start "platform_description" with attribute version="2"
- - start "host" with attributes id="host1" power="1.0"
- - end "host"
- - start "host" with attributes id="host2" power="2.0"
- - end "host"
- - start "link" with ...
- - end "link"
- - start "route" with ...
- - start "link_ctn" with ...
- - end "link_ctn"
- - end "route"
- - end "platform_description"
-
-The communication from the parser to the SURF code uses two means:
-Attributes get copied into some global variables, and a surf-provided
-function gets called by the parser for each event. For example, the event
- - start "host" with attributes id="host1" power="1.0"
-
-let the parser do something roughly equivalent to:
-\verbatim
- strcpy(A_host_id,"host1");
- A_host_power = 1.0;
- STag_host();
-\endverbatim
-
-In SURF, we attach callbacks to the different events by initializing the
-pointer functions to some the right surf functions. Since there can be
-more than one callback attached to the same event (if more than one
-model is in use, for example), they are stored in a dynar. Example in
-host_ptask_L07.c:
-\verbatim
- /* Adding callback functions */
- surf_parse_reset_parser();
- surfxml_add_callback(STag_surfxml_host_cb_list, &parse_cpu_init);
- surfxml_add_callback(STag_surfxml_prop_cb_list, &parse_properties);
- surfxml_add_callback(STag_surfxml_link_cb_list, &parse_link_init);
- surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints);
- surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem);
- surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route);
-
- /* Parse the file */
- surf_parse_open(file);
- xbt_assert(!surf_parse(), "Parse error in %s", file);
- surf_parse_close();
-\endverbatim
-
-So, to bypass the FleXML parser, you need to write your own version of the
-surf_parse function, which should do the following:
- - Fill the A_<tag>_<attribute> variables with the wanted values
- - Call the corresponding STag_<tag>_fun function to simulate tag start
- - Call the corresponding ETag_<tag>_fun function to simulate tag end
- - (do the same for the next set of values, and loop)
-
-Then, tell SimGrid that you want to use your own "parser" instead of the stock one:
-\verbatim
- surf_parse = surf_parse_bypass_environment;
- MSG_create_environment(NULL);
- surf_parse = surf_parse_bypass_application;
- MSG_launch_application(NULL);
-\endverbatim
-
-A set of macros are provided at the end of
-include/surf/surfxml_parse.h to ease the writing of the bypass
-functions. An example of this trick is distributed in the file
-examples/msg/masterslave/masterslave_bypass.c
-
-
*/
