\verbatim
"cmake -D[name]=[value] ... ./"
-[name] disable_gtnets [value] ON/OFF or TRUE/FALSE or 1/0
- disable_java ON/OFF or TRUE/FALSE or 1/0
- disable_lua ON/OFF or TRUE/FALSE or 1/0
- disable_ruby ON/OFF or TRUE/FALSE or 1/0
-
+[name] enable_gtnets [value] ON/OFF or TRUE/FALSE or 1/0
+ enable_java ON/OFF or TRUE/FALSE or 1/0
+ enable_lua ON/OFF or TRUE/FALSE or 1/0
+ enable_ruby ON/OFF or TRUE/FALSE or 1/0
enable_compile_optimizations ON/OFF or TRUE/FALSE or 1/0
enable_compile_warnings ON/OFF or TRUE/FALSE or 1/0
enable_maintainer_mode ON/OFF or TRUE/FALSE or 1/0
\subsubsection faq_cmakeoption2 Options explaination
- \li disable_gtnets : set to true implie that user doesn't want to use gtnets.
+ \li enable_gtnets : set to true implie that user wants to use gtnets.
- \li disable_java : set to true implie that user doesn't want to add java langage into simgrid compilation.
+ \li enable_java : set to true implie that user wants to add java langage into simgrid compilation.
- \li disable_lua : set to true implie that user doesn't want to add lua langage into simgrid compilation.
+ \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
- \li disable_ruby : set to true implie that user doesn't want to add ruby langage into simgrid compilation.
+ \li enable_ruby : set to true implie that user wants to add ruby langage into simgrid compilation.
\li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
Those options are initialized the first time you launch \"cmake ./\" whithout specified option.
\verbatim
-disable_gtnets off
-disable_java off
-disable_lua off
-disable_ruby off
-
+enable_gtnets on
+enable_lua on
+enable_ruby on
+enable_java off
enable_compile_optimizations off
enable_compile_warnings off
enable_maintainer_mode off
make install-simgrid install the project (doc/ lib/ include/)
make uninstall uninstall the project (doc/ lib/ include/)
make clean clean all targets
+make java-clean clean files created by java option
+make doc-clean clean files created for making doc
+make supernovae-clean clean supernovae files
+make maintainer-clean clean maintainer files
+make all-clean execute the 5 upper clean command
make html Create simgrid documentation
make maintainer-clean Remove all files generated by mainainer mode
\endverbatim
that will be used when these functions are called is the one returned by
the function \c MSG_host_self().
-\subsubsection faq_tracing_functions Example
+\subsubsection faq_tracing_example Example of Instrumentation
A simplified example using the tracing mandatory functions.
}
\endverbatim
+\subsubsection faq_tracing_analyzing Analyzing the SimGrid Traces
+
+The SimGrid library, during an instrumented simulation, creates a trace file in
+the Paje file format that contains the platform utilization for the simulation
+that was executed. The visualization analysis of this file is performed with the
+visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
+special configurations tunned to SimGrid needs. This part of the documentation
+explains how to configure and use Triva to analyse a SimGrid trace file.
+
+- <b>Installing Triva</b>: the tool is available in the INRIAGforge,
+at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
+Use the following command to get the sources, and then check the file
+<i>INSTALL.simplified</i>. This file contains instructions to install
+the tool's dependencies in a Ubuntu/Debian Linux.
+\verbatim
+$ svn checkout svn://scm.gforge.inria.fr/svn/triva
+$ cd triva
+$ cat INSTALL.simplified
+\endverbatim
+
+- <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
+ installation (you can execute it passing <em>--help</em> to check its
+options). If the triva binary is not available after following the
+installation instructions, you may want to execute the following command to
+initialize the GNUstep environment variables (note that the location of the
+<i>GNUstep.sh</i> file may vary depending on your GNUstep installation - the
+command is known to work in Ubuntu and Debian Linux):
+\verbatim
+$ source /usr/share/GNUstep/Makefiles/GNUstep.sh
+\endverbatim
+You should be able to see this output after the installation of triva:
+\verbatim
+$ ./Triva.app/Triva --help
+Usage: Triva [OPTION...] TRACEFILE
+Trace Analysis through Visualization
+
+ You need to use one of the following options:
+ -g, --graph Graph Analysis
+ -t, --treemap Treemap Analysis
+
+ Other auxiliary options to check the trace file:
+ -c, --check Check the integrity of trace file
+ -h, --hierarchy Export the trace type hierarchy
+ -l, --list List entity types
+
+ -?, --help Give this help list
+ --usage Give a short usage message
+\endverbatim
+Triva expects that the user choose one of the available options
+(currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
+and the trace file from the simulation.
+
+- <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
+ the tool always takes into account the concept of the <em>time-slice</em>.
+This concept means that what is being visualized in the screen is always
+calculated considering a specific time frame, with its beggining and end
+timestamp. The time-slice is configured by the user and can be changed
+dynamically through the window called <em>Time Interval</em> that is opened
+whenever a trace file is being analyzed. The next figure depicts the time-slice
+configuration window.
+In the top of the window, in the space named <i>Trace Time</i>,
+the two fields show the beggining of the trace (which usually starts in 0) and
+the end (that depends on the time simulated by SimGrid). The middle of the
+window, in the square named <i>Time Slice Configuration</i>, contains the
+aspects related to the time-slice, including its <i>start</i> and its
+<i>size</i>. The gray rectangle in the bottom of this part indicates the
+<i>current time-slice</i> that is considered for the drawings. If the checkbox
+<i>Update Drawings on Sliders Change</i> is not selected, the button
+<i>Apply</i> must be clicked in order to inform triva that the
+new time-slice must be considered. The bottom part of the window, in the space
+indicated by the square <i>Time Slice Animation</i> can be used to advance
+the time-frame automatically. The user configures the amount of time that the
+time-frame will forward and how frequent this update will happen. Once this is
+configured, the user clicks the <i>Play</i> button in order to see the dynamic
+changes on the drawings.
+<center>
+\htmlonly
+<a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+<b>Remarks:</b> when the trace has too many hosts or links, the computation to
+take into account a new time-slice can be expensive. When this happens, the
+<i>Frequency</i> parameter, but also updates caused by change on configurations
+when the checkbox <i>Update Drawings on Sliders
+Change</i> is selected will not be followed.
+
+- <b>Understanding Triva - graph</b>: this part of the documention explains how
+ to analyze the traces using the graph view of Triva, when the user executes
+the tool passing <em>--graph</em> as parameter. Triva opens three windows when
+this parameter is used: the <i>Time Interval</i> window (previously described),
+the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
+window. The Graph Representation is the window where drawings take place.
+Initially, it is completely white waiting for a proper graph configuration input
+by the user. We start the description of this type of analysis by describing the
+<i>Graph Configuration</i> window (depicted below). By using a particular
+configuration, triva
+can be used to customize the graph drawing according to
+the SimGrid trace that was created with user-specific categories. Before delving
+into the details of this customization, let us first explain the major parts of
+the graph configuration window. The buttons located in the top-right corner can
+be used to delete, copy and create a new configuration. The checkbox in the
+top-middle part of the window indicates if the configuration typed in the
+textfield is syntactically correct (we are using the non-XML
+<a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
+describe the configuration). The pop-up button located on the top-left corner
+indicates the selected configuration (the user can have multiple graph
+configurations). The bottom-left text field contains the name of the current
+configuration (updates on this field must be followed by typing enter on the
+keyboard to take into account the name change). The bottom-right <em>Apply</em>
+button activates the current configuration, resulting on an update on the graph
+drawings.
+<center>
+\htmlonly
+<a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+<b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
+basic configuration that should be used during the analysis of a SimGrid trace
+file. The basic logic of the configuration is as follows:
+\verbatim
+{
+ node = (HOST);
+ edge = (LINK);
+\endverbatim
+The nodes of the graph will be created based on the <i>node</i> parameter, which
+in this case is the different <em>"HOST"</em>s of the platform
+used to simulate. The <i>edge</i> parameter indicates that the edges of the
+graph will be created based on the <em>"LINK"</em>s of the platform. After the
+definition of these two parameters, the configuration must detail how
+<em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
+must have an entry for each of the types used. For <em>HOST</em>, as basic
+configuration, we have:
+\verbatim
+ HOST = {
+ size = power;
+ scale = global;
+ };
+\endverbatim
+The parameter <em>size</em> indicates which variable from the trace file will be
+used to define the size of the node HOST in the visualization. If the simulation
+was executed with availability traces, the size of the nodes will be changed
+according to these traces. The parameter <em>scale</em> indicates if the value
+of the variable is <em>global</em> or <em>local</em>. If it is global, the value
+will be relative to the power of all other hosts, if it is local, the value will
+be relative locally.
+For <em>LINK</em> we have:
+\verbatim
+ LINK = {
+ src = SrcHost;
+ dst = DstHost;
+
+ size = bandwidth;
+ scale = global;
+ };
+\endverbatim
+For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
+the configuration must contain two additional parameters: <em>src</em> and
+<em>dst</em> that are used to properly identify which nodes this edge is
+connecting. The values <em>SrcHost</em> and <em>DstHost</em> are always present
+in the SimGrid trace file and should not be changed in the configuration. The
+parameter <em>size</em> for the LINK, in this case, is configured as the
+variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
+here is exactly the same used for nodes. The last parameter is the GraphViz
+algorithm used to calculate the position of the nodes in the graph
+representation.
+\verbatim
+ graphviz-algorithm = neato;
+}
+\endverbatim
+<b>Customizing the Graph Representation</b>: triva is capable to handle
+a customized graph representation based on the variables present in the trace
+file. In the case of SimGrid, every time a category is created for tasks, two
+variables in the trace file are defined: one to indicate node utilization (how
+much power was used by that task category), and another to indicate link
+utilization (how much bandwidth was used by that category). For instance, if the
+user declares a category named <i>request</i>, there will be variables named
+<b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
+<b>b</b> for bandwidth). It is important to notice that the variable
+<i>prequest</i> in this case is only available for HOST, and
+<i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
+two categories for tasks: request and compute. To create a customized graph
+representation with a proportional separation of host and link utilization, use
+as configuration for HOST and LINK this:
+\verbatim
+ HOST = {
+ size = power;
+ scale = global;
+
+ sep_host = {
+ type = separation;
+ size = power;
+ values = (prequest, pcomputation);
+ };
+ };
+
+ LINK = {
+ src = SrcHost;
+ dst = DstHost;
+ size = bandwidth;
+ scale = global;
+
+ sep_link = {
+ type = separation;
+ size = bandwidth;
+ values = (brequest, bcomputation);
+ };
+ };
+\endverbatim
+Where <i>sep_host</i> contains a composition of type <i>separation</i> where
+its max size is the <i>power</i> of the host and the variables <i>prequest</i>
+and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
+<i>sep_link</i> is also a separation where max is defined as the
+<i>bandwidth</i> of the link, and the variables <i>brequest</i> and
+<i>bcomputation</i> are drawn proportionally within a LINK.
+<i>This configuration enables the analysis of resource utilization by MSG tasks,
+and the identification of load-balancing issues, network bottlenecks, for
+instance.</i> \n
+<b>Other compositions</b>: besides <i>separation</i>, it is possible to use
+other types of compositions, such as gradients, and colors, like this:
+\verbatim
+ gra_host = {
+ type = gradient;
+ scale = global;
+ values = (numberOfTasks);
+ };
+ color_host = {
+ type = color;
+ values = (is_server);
+ };
+\endverbatim
+Where <i>gra_host</i> creates a gradient within a node of the graph, using a
+global scale and using as value a variable called <i>numberOfTasks</i>, that
+could be declared by the user using the optional tracing functions of SimGrid.
+If scale is global, the max and min value for the gradient will be equal to the
+max and min numberOfTasks among all hosts, and if scale is local, the max and
+min value based on the value of numberOfTasks locally in each host.
+And <i>color_host</i> composition draws a square based on a positive value of
+the variable <i>is_server</i>, that could also be defined by the user using the
+SimGrid tracing functions. \n
+<b>The Graph Visualization</b>: The next figure shows a graph visualization of a
+given time-slice of the masterslave_forwarder example (present in the SimGrid
+sources). The red color indicates tasks from the <i>compute</i> category. This
+visualization was generated with the following configuration:
+\verbatim
+{
+ node = (HOST);
+ edge = (LINK);
+
+ HOST = {
+ size = power;
+ scale = global;
+
+ sep_host = {
+ type = separation;
+ size = power;
+ values = (pcompute, pfinalize);
+ };
+ };
+ LINK = {
+ src = SrcHost;
+ dst = DstHost;
+ size = bandwidth;
+ scale = global;
+
+ sep_link = {
+ type = separation;
+ size = bandwidth;
+ values = (bcompute, bfinalize);
+ };
+ };
+ graphviz-algorithm = neato;
+}
+\endverbatim
+<center>
+\htmlonly
+<a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+
+- <b>Understading Triva - colors</b>: An important issue when using Triva is how
+ to define colors. To do that, we have to know which variables are defined in
+the trace file generated by the SimGrid library. The parameter <em>--list</em>
+lists the variables for a given trace file:
+\verbatim
+$ Triva -l masterslave_forwarder.trace
+iFile
+c platform
+c HOST
+v power
+v is_slave
+v is_master
+v task_creation
+v task_computation
+v pcompute
+v pfinalize
+c LINK
+v bandwidth
+v latency
+v bcompute
+v bfinalize
+c user_type
+\endverbatim
+We can see that HOST has seven variables (from power to pfinalize) and LINK has
+four (from bandwidth to bfinalize). To define a red color for the
+<i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
+<i>compute</i>), execute:
+\verbatim
+$ defaults write Triva 'pcompute Color' '1 0 0'
+$ defaults write Triva 'bcompute Color' '1 0 0'
+\endverbatim
+Where the three numbers in each line are the RGB color with values from 0 to 1.
+
\section faq_troubleshooting Troubleshooting
\subsection faq_trouble_lib_compil SimGrid compilation and installation problems
