doc/FAQ.doc
doc/installSimgrid.doc
doc/bindings.doc
+ doc/options.doc
+ doc/use.doc
doc/gtut-howto-design.doc
doc/gtut-howto.doc
doc/gtut-introduction.doc
COMMAND ${CMAKE_COMMAND} -E echo "XX First Doxygen pass"
COMMAND ${DOXYGEN_PATH}/doxygen Doxyfile
COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/index_create.pl simgrid.tag index-API.doc
- COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/toc_create.pl FAQ.doc index.doc contrib.doc gtut-introduction.doc history.doc installSimgrid.doc bindings.doc
+ COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/toc_create.pl FAQ.doc index.doc contrib.doc gtut-introduction.doc history.doc installSimgrid.doc bindings.doc options.doc
COMMAND ${CMAKE_COMMAND} -E echo "XX Second Doxygen pass"
COMMAND ${DOXYGEN_PATH}/doxygen Doxyfile
installSimgrid.doc \
bindings.doc \
FAQ.doc \
+ options.doc \
+ use.doc \
contrib.doc \
publis.doc \
people.doc \
for real execution. So, you just have to relink your code to chose one of
both world.
-\subsection faq_generic First steps with SimGrid
-
-If you decide to go for the MSG interface, please read carefully the
-\ref MSG_examples. You'll find in \ref MSG_ex_master_slave a very
-simple consisting of a master (that owns a bunch of tasks and
-distributes them) , some slaves (that process tasks whenever they
-receive one) and some forwarder agents (that simply pass the tasks
-they receive to some slaves).
-
-If you decide to go for the GRAS interface, you should definitively
-read the \ref GRAS_tut. The first section constitutes an introduction
-to the tool and presents the model we use. The second section
-constitutes a complete step-by-step tutorial building a distributed
-application from the beginning and exemplifying most of the GRAS
-features in the process. The last section groups some HOWTOS
-highlighting a given feature of the framework in a more concise way.
-
-If you decide to go for another interface, I'm afraid your only sources
-of information will be the source code and the mailing lists...
-
\subsection faq_visualization Visualizing and analyzing the results
It is sometime convenient to "see" how the agents are behaving. If you
./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
\endverbatim
-We also have a more graphical output. Have a look at section \ref faq_tracing.
+We also have a more graphical output. Have a look at section \ref options_tracing.
\subsection faq_C Argh! Do I really have to code in C?
functions. An example of this trick is distributed in the file
examples/msg/masterslave/masterslave_bypass.c
-\subsection faq_simgrid_configuration Changing SimGrid's behavior
-
-A number of options can be given at runtime to change the default
-SimGrid behavior. In particular, you can change the default cpu and
-network models...
-
-\subsubsection faq_simgrid_configuration_fullduplex Using Fullduplex
-
-Experimental fullduplex support is now available on the svn branch. In order to fullduple to work your platform must have two links for each pair
-of interconnected hosts, see an example here:
-\verbatim
- simgrid_svn_sources/exemples/msg/gtnets/fullduplex-p.xml
-\endverbatim
-
-Using fullduplex support ongoing and incoming communication flows are
-treated independently for most models. The exception is the LV08 model which
-adds 0.05 of usage on the opposite direction for each new created flow. This
-can be useful to simulate some important TCP phenomena such as ack compression.
-
-Running a fullduplex example:
-\verbatim
- cd simgrid_svn_sources/exemples/msg/gtnets
- ./gtnets fullduplex-p.xml fullduplex-d.xml --cfg=fullduplex:1
-\endverbatim
-
-
-
-
-
-\subsubsection faq_simgrid_configuration_gtnets Using GTNetS
-
-It is possible to use a packet-level network simulator
-instead of the default flow-based simulation. You may want to use such
-an approach if you have doubts about the validity of the default model
-or if you want to perform some validation experiments. At the moment,
-we support the GTNetS simulator (it is still rather experimental
-though, so leave us a message if you play with it).
-
-
-<i>
-To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
-and build/install it from scratch
-</i>
-
- - <b>Download and enter the recent downloaded GTNetS directory</b>
-
- \verbatim
- svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
- cd GTNetS
- \endverbatim
-
-
- - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
-
- \verbatim
- unzip gtnets-current.zip
- tar zxvf gtnets-current-patch.tgz
- cd gtnets-current
- cat ../00*.patch | patch -p1
- \endverbatim
-
- - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
-
- \verbatim
- cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
- \endverbatim
-
- - <b>Compile GTNetS</b>
-
- Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
-
-
- \verbatim
- ln -sf Makefile.linux Makefile
- make depend
- make debug
- \endverbatim
-
-
- - <b>NOTE</b> A lot of warnings are expected but the application should compile
- just fine. If the makefile insists in compiling some QT libraries
- please try a make clean before asking for help.
-
-
- - <b>To compile optimized version</b>
-
- \verbatim
- make opt
- \endverbatim
-
-
- - <b>Installing GTNetS</b>
-
- It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
-
- \verbatim
- ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
- export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
- mkdir /<userhome>/usr/include/gtnets
- cp -fr SRC/*.h /<userhome>/usr/include/gtnets
- \endverbatim
-
-
- - <b>Enable GTNetS support in SimGrid</b>
-
-In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
-
- \verbatim
- Since v3.4 (with cmake)
- cmake . -Dgtnets_path=/<userhome>/usr
-
- Until v3.4 (with autotools)
- ./configure --with-gtnets=/<userhome>/usr
- \endverbatim
-
- - <b>Once you have followed all the instructions for compiling and
- installing successfully you can activate this feature at
- runntime with the following options:</b>
-
- \verbatim
- Since v3.4 (with cmake)
- cd simgrid
- make
- ctest -R gtnets
-
- Until v3.4 (with autotools)
- cd simgrid/example/msg/
- make
- make check
- \endverbatim
-
-
- - <b>Or try the GTNetS model dogbone example with</b>
-
- \verbatim
- gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
- \endverbatim
-
-
- A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
-
-
- More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
-
-
- - <b>DISCLAIMER</b>
- The patches provided by us worked successfully with GTNetS found
- <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
- dated from 12th June 2008. Due to the discontinuing development of
- GTNetS it is impossible to precise a version number. We STRONGLY recommend you
- to download and install the GTNetS version found in SimGrid repository as explained above.
-
-
-
-
-\subsubsection faq_simgrid_configuration_alternate_network Using alternative flow models
-
-The default simgrid network model uses a max-min based approach as
-explained in the research report
-<a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A Network Model for Simulation of Grid Application</a>.
-Other models have been proposed and implemented since then (see for example
-<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
-and can be activated at runtime. For example:
-\verbatim
-./mycode platform.xml deployment.xml --cfg=workstation/model:compound --cfg=network/model:LV08 -cfg=cpu/model:Cas01
-\endverbatim
-
-Possible models for the network are currently "Constant", "CM02",
-"LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
-probably be added in the future and many of the previous ones are
-experimental and are likely to disappear without notice... To know the
-list of the currently implemented models, you should use the
---help-models command line option.
-
-\verbatim
-./masterslave_forwarder ../small_platform.xml deployment_masterslave.xml --help-models
-Long description of the workstation models accepted by this simulator:
- CLM03: Default workstation model, using LV08 and CM02 as network and CPU
- compound: Workstation model allowing you to use other network and CPU models
- ptask_L07: Workstation model with better parallel task modeling
-Long description of the CPU models accepted by this simulator:
- Cas01_fullupdate: CPU classical model time=size/power
- Cas01: Variation of Cas01_fullupdate with partial invalidation optimization of lmm system. Should produce the same values, only faster
- CpuTI: Variation of Cas01 with also trace integration. Should produce the same values, only faster if you use availability traces
-Long description of the network models accepted by this simulator:
- Constant: Simplistic network model where all communication take a constant time (one second)
- CM02: Realistic network model with lmm_solve and no correction factors
- LV08: Realistic network model with lmm_solve and these correction factors: latency*=10.4, bandwidth*=.92, S=8775
- Reno: Model using lagrange_solve instead of lmm_solve (experts only)
- Reno2: Model using lagrange_solve instead of lmm_solve (experts only)
- Vegas: Model using lagrange_solve instead of lmm_solve (experts only)
-\endverbatim
-
-\subsection faq_tracing Tracing Simulations for Visualization
-
-The trace visualization is widely used to observe and understand the behavior
-of parallel applications and distributed algorithms. Usually, this is done in a
-two-step fashion: the user instruments the application and the traces are
-analyzed after the end of the execution. The visualization itself can highlights
-unexpected behaviors, bottlenecks and sometimes can be used to correct
-distributed algorithms. The SimGrid team has instrumented the library
-in order to let users trace their simulations and analyze them. This part of the
-user manual explains how the tracing-related features can be enabled and used
-during the development of simulators using the SimGrid library.
-
-\subsubsection faq_tracing_howitworks How it works
-
-For now, the SimGrid library is instrumented so users can trace the <b>platform
-utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
-register how much power is used for each host and how much bandwidth is used for
-each link of the platform. The idea with this type of tracing is to observe the
-overall view of resources utilization in the first place, especially the
-identification of bottlenecks, load-balancing among hosts, and so on.
-
-The idea of the tracing facilities is to give SimGrid users to possibility to
-classify MSG and SimDAG tasks by category, tracing the platform utilization
-(hosts and links) for each of the categories. For that,
-the tracing interface enables the declaration of categories and a function to
-mark a task with a previously declared category. <em>The tasks that are not
-classified according to a category are not traced</em>. Even if the user
-does not specify any category, the simulations can still be traced in terms
-of resource utilization by using a special parameter that is detailed below.
-
-\subsubsection faq_tracing_enabling Enabling using CMake
-
-With the sources of SimGrid, it is possible to enable the tracing
-using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
-The section \ref faq_tracing_functions describes all the functions available
-when this Cmake options is activated. These functions will have no effect
-if SimGrid is configured without this option (they are wiped-out by the
-C-preprocessor).
-
-\verbatim
-$ cmake -Denable_tracing=ON .
-$ make
-\endverbatim
-
-\subsubsection faq_tracing_functions Tracing Functions
-
-\li <b>\c TRACE_category (const char *category)</b>: This function should be used
-to define a user category. The category can be used to differentiate the tasks
-that are created during the simulation (for example, tasks from server1,
-server2, or request tasks, computation tasks, communication tasks).
-All resource utilization (host power and link bandwidth) will be
-classified according to the task category. Tasks that do not belong to a
-category are not traced. The color for the category that is being declared
-is random (use next function to specify a color).
-
-\li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
-as TRACE_category, but let user specify a color encoded as a RGB-like string with
-three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
-color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
-
-\li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
-This function should be called after the creation of a MSG task, to define the
-category of that task. The first parameter \c task must contain a task that was
-created with the function \c MSG_task_create. The second parameter
-\c category must contain a category that was previously defined by the function
-\c TRACE_category.
-
-\li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
-This function should be called after the creation of a SimDAG task, to define the
-category of that task. The first parameter \c task must contain a task that was
-created with the function \c MSG_task_create. The second parameter
-\c category must contain a category that was previously defined by the function
-\c TRACE_category.
-
-\li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
-Declare a user variable that will be associated to host/link. A variable can
-be used to trace user variables such as the number of tasks in a server,
-the number of clients in an application (for hosts), and so on.
-
-\li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
-Set the value of a given user variable for a given host/link. The value
-of this variable is always associated to the host/link. The host/link
-parameters should be its name as the one listed in the platform file.
-
-\li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
-Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
-the time used to trace it. Users can specify a time that is not the
-simulated clock time as defined by the core simulator. This allows
-a fine-grain control of time definition, but should be used with
-caution since the trace can be inconsistent if resource utilization
-traces are also traced.
-
-\li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
-Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
-destination hosts (as the names from the platform file). The tracing library
-will get the corresponding route that connects those two hosts (src and dst) and
-[set|add|sub] the value's variable for all the links of the route.
-
-\li <b>\c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value)</b>:
-Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
-
-\subsubsection faq_tracing_options Tracing configuration Options
-
-These are the options accepted by the tracing system of SimGrid:
-
-\li <b>\c
-tracing
-</b>:
- Safe switch. It activates (or deactivates) the tracing system.
- No other tracing options take effect if this one is not activated.
-
-\li <b>\c
-tracing/platform
-</b>:
- Register the simulation platform in the trace file.
-
-\li <b>\c
-tracing/onelink_only
-</b>:
- By default, the tracing system uses all routes in the platform file
- to re-create a "graph" of the platform and register it in the trace file.
- This option let the user tell the tracing system to use only the routes
- that are composed with just one link.
-
-\li <b>\c
-tracing/categorized
-</b>:
- It activates the categorized resource utilization tracing. It should
- be enabled if tracing categories are used by this simulator.
-
-\li <b>\c
-tracing/uncategorized
-</b>:
- It activates the uncategorized resource utilization tracing. Use it if
- this simulator do not use tracing categories and resource use have to be
- traced.
-
-\li <b>\c
-tracing/filename
-</b>:
- A file with this name will be created to register the simulation. The file
- is in the Paje format and can be analyzed using Triva or Paje visualization
- tools. More information can be found in these webpages:
- <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
- <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
-
-\li <b>\c
-tracing/smpi
-</b>:
- This option only has effect if this simulator is SMPI-based. Traces the MPI
- interface and generates a trace that can be analyzed using Gantt-like
- visualizations. Every MPI function (implemented by SMPI) is transformed in a
- state, and point-to-point communications can be analyzed with arrows.
-
-\li <b>\c
-tracing/smpi/group
-</b>:
- This option only has effect if this simulator is SMPI-based. The processes
- are grouped by the hosts where they were executed.
-
-\li <b>\c
-tracing/msg/task
-</b>:
- This option only has effect if this simulator is MSG-based. It traces the
- behavior of all categorized MSG tasks, grouping them by hosts.
-
-\li <b>\c
-tracing/msg/process
-</b>:
- This option only has effect if this simulator is MSG-based. It traces the
- behavior of all categorized MSG processes, grouping them by hosts. This option
- can be used to track process location if this simulator has process migration.
-
-
-\li <b>\c
-triva/categorized:graph_categorized.plist
-</b>:
- This option generates a graph configuration file for Triva considering
- categorized resource utilization.
-
-\li <b>\c
-triva/uncategorized:graph_uncategorized.plist
-</b>:
- This option generates a graph configuration file for Triva considering
- uncategorized resource utilization.
-
-\subsubsection faq_tracing_example Example of Instrumentation
-
-A simplified example using the tracing mandatory functions.
-
-\verbatim
-int main (int argc, char **argv)
-{
- MSG_global_init (&argc, &argv);
-
- //(... after deployment ...)
-
- //note that category declaration must be called after MSG_create_environment
- TRACE_category_with_color ("request", "1 0 0");
- TRACE_category_with_color ("computation", "0.3 1 0.4");
- TRACE_category ("finalize");
-
- m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
- m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
- m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
- m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
- TRACE_msg_set_task_category (req1, "request");
- TRACE_msg_set_task_category (req2, "request");
- TRACE_msg_set_task_category (req3, "request");
- TRACE_msg_set_task_category (req4, "request");
-
- m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
- TRACE_msg_set_task_category (comp, "computation");
-
- m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
- TRACE_msg_set_task_category (finalize, "finalize");
-
- //(...)
-
- MSG_clean();
- return 0;
-}
-\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</i>. This file contains instructions to install
-the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
-be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
-\verbatim
-$ svn checkout svn://scm.gforge.inria.fr/svn/triva
-$ cd triva
-$ cat INSTALL
-\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. We strongly recommend that you
-use the latest GNUstep packages, and not the packages available through apt-get
-in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
-available packages, you can execute this command:
-\verbatim
-$ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
-\endverbatim
-You should be able to see this output after the installation of triva:
-\verbatim
-$ ./Triva.app/Triva --help
-Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
-Trace Analysis through Visualization
-
-TimeInterval
- --ti_frequency {double} Animation: frequency of updates
- --ti_hide Hide the TimeInterval window
- --ti_forward {double} Animation: value to move time-slice
- --ti_apply Apply the configuration
- --ti_update Update on slider change
- --ti_animate Start animation
- --ti_start {double} Start of time slice
- --ti_size {double} Size of time slice
-Triva
- --comparison Compare Trace Files (Experimental)
- --graph Configurable Graph
- --list Print Trace Type Hierarchy
- --hierarchy Export Trace Type Hierarchy (dot)
- --stat Trace Statistics and Memory Utilization
- --instances List All Trace Entities
- --linkview Link View (Experimental)
- --treemap Squarified Treemap
- --merge Merge Trace Files (Experimental)
- --check Check Trace File Integrity
-GraphConfiguration
- --gc_conf {file} Graph Configuration in Property List Format
- --gc_apply Apply the configuration
- --gc_hide Hide the GraphConfiguration window
-\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 = source;
- dst = destination;
-
- 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>source</em> and <em>destination</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 = source;
- dst = destination;
- 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 = source;
- dst = destination;
- 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.
-
-\subsection faq_modelchecking Model-Checking
-\subsubsection faq_modelchecking_howto How to use it
-To enable the experimental SimGrid model-checking support the program should
-be executed with the command line argument
-\verbatim
---cfg=model-check:1
-\endverbatim
-Properties are expressed as assertions using the function
-\verbatim
-void MC_assert(int prop);
-\endverbatim
-
\section faq_troubleshooting Troubleshooting
\subsection faq_trouble_lib_compil SimGrid compilation and installation problems
******************************************************************
-\subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
+subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
At the moment, we do not distribute Windows pre-compiled version of SimGrid
because the support for this platform is still experimental. We know that
Nowadays, functions get automatically exported, so we don't need to load our
header files with tons of __declspec(dllexport) cruft. We only need to do so
for data, but there is no public data in SimGrid so we are good.
-
-
Since GRAS is technically part of the SimGrid project, you have to install
SimGrid to install GRAS. Doing so is explained in the relevant FAQ section
-(\ref faq_installation).
+(\ref installSimgrid).
Newcommers should install the stable release from the tarball, since the
snapshots may suffer from (additionnal;) stability issues. Only go for the
--- /dev/null
+/*! \page options Simgrid options and configurations
+
+\htmlinclude .options.doc.toc
+
+\section options_simgrid_configuration Changing SimGrid's behavior
+
+A number of options can be given at runtime to change the default
+SimGrid behavior. In particular, you can change the default cpu and
+network models...
+
+\subsection options_simgrid_configuration_fullduplex Using Fullduplex
+
+Experimental fullduplex support is now available on the svn branch. In order to fullduple to work your platform must have two links for each pair
+of interconnected hosts, see an example here:
+\verbatim
+ simgrid_svn_sources/exemples/msg/gtnets/fullduplex-p.xml
+\endverbatim
+
+Using fullduplex support ongoing and incoming communication flows are
+treated independently for most models. The exception is the LV08 model which
+adds 0.05 of usage on the opposite direction for each new created flow. This
+can be useful to simulate some important TCP phenomena such as ack compression.
+
+Running a fullduplex example:
+\verbatim
+ cd simgrid_svn_sources/exemples/msg/gtnets
+ ./gtnets fullduplex-p.xml fullduplex-d.xml --cfg=fullduplex:1
+\endverbatim
+
+\subsection options_simgrid_configuration_gtnets Using GTNetS
+
+It is possible to use a packet-level network simulator
+instead of the default flow-based simulation. You may want to use such
+an approach if you have doubts about the validity of the default model
+or if you want to perform some validation experiments. At the moment,
+we support the GTNetS simulator (it is still rather experimental
+though, so leave us a message if you play with it).
+
+
+<i>
+To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
+and build/install it from scratch
+</i>
+
+ - <b>Download and enter the recent downloaded GTNetS directory</b>
+
+ \verbatim
+ svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
+ cd GTNetS
+ \endverbatim
+
+
+ - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
+
+ \verbatim
+ unzip gtnets-current.zip
+ tar zxvf gtnets-current-patch.tgz
+ cd gtnets-current
+ cat ../00*.patch | patch -p1
+ \endverbatim
+
+ - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
+
+ \verbatim
+ cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
+ \endverbatim
+
+ - <b>Compile GTNetS</b>
+
+ Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
+
+
+ \verbatim
+ ln -sf Makefile.linux Makefile
+ make depend
+ make debug
+ \endverbatim
+
+
+ - <b>NOTE</b> A lot of warnings are expected but the application should compile
+ just fine. If the makefile insists in compiling some QT libraries
+ please try a make clean before asking for help.
+
+
+ - <b>To compile optimized version</b>
+
+ \verbatim
+ make opt
+ \endverbatim
+
+
+ - <b>Installing GTNetS</b>
+
+ It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
+
+ \verbatim
+ ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
+ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
+ mkdir /<userhome>/usr/include/gtnets
+ cp -fr SRC/*.h /<userhome>/usr/include/gtnets
+ \endverbatim
+
+
+ - <b>Enable GTNetS support in SimGrid</b>
+
+In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
+
+ \verbatim
+ Since v3.4 (with cmake)
+ cmake . -Dgtnets_path=/<userhome>/usr
+
+ Until v3.4 (with autotools)
+ ./configure --with-gtnets=/<userhome>/usr
+ \endverbatim
+
+ - <b>Once you have followed all the instructions for compiling and
+ installing successfully you can activate this feature at
+ runntime with the following options:</b>
+
+ \verbatim
+ Since v3.4 (with cmake)
+ cd simgrid
+ make
+ ctest -R gtnets
+
+ Until v3.4 (with autotools)
+ cd simgrid/example/msg/
+ make
+ make check
+ \endverbatim
+
+
+ - <b>Or try the GTNetS model dogbone example with</b>
+
+ \verbatim
+ gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
+ \endverbatim
+
+
+ A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
+
+
+ More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
+
+
+ - <b>DISCLAIMER</b>
+ The patches provided by us worked successfully with GTNetS found
+ <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
+ dated from 12th June 2008. Due to the discontinuing development of
+ GTNetS it is impossible to precise a version number. We STRONGLY recommend you
+ to download and install the GTNetS version found in SimGrid repository as explained above.
+
+
+
+
+\subsection options_simgrid_configuration_alternate_network Using alternative flow models
+
+The default simgrid network model uses a max-min based approach as
+explained in the research report
+<a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A Network Model for Simulation of Grid Application</a>.
+Other models have been proposed and implemented since then (see for example
+<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
+and can be activated at runtime. For example:
+\verbatim
+./mycode platform.xml deployment.xml --cfg=workstation/model:compound --cfg=network/model:LV08 -cfg=cpu/model:Cas01
+\endverbatim
+
+Possible models for the network are currently "Constant", "CM02",
+"LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
+probably be added in the future and many of the previous ones are
+experimental and are likely to disappear without notice... To know the
+list of the currently implemented models, you should use the
+--help-models command line option.
+
+\verbatim
+./masterslave_forwarder ../small_platform.xml deployment_masterslave.xml --help-models
+Long description of the workstation models accepted by this simulator:
+ CLM03: Default workstation model, using LV08 and CM02 as network and CPU
+ compound: Workstation model allowing you to use other network and CPU models
+ ptask_L07: Workstation model with better parallel task modeling
+Long description of the CPU models accepted by this simulator:
+ Cas01_fullupdate: CPU classical model time=size/power
+ Cas01: Variation of Cas01_fullupdate with partial invalidation optimization of lmm system. Should produce the same values, only faster
+ CpuTI: Variation of Cas01 with also trace integration. Should produce the same values, only faster if you use availability traces
+Long description of the network models accepted by this simulator:
+ Constant: Simplistic network model where all communication take a constant time (one second)
+ CM02: Realistic network model with lmm_solve and no correction factors
+ LV08: Realistic network model with lmm_solve and these correction factors: latency*=10.4, bandwidth*=.92, S=8775
+ Reno: Model using lagrange_solve instead of lmm_solve (experts only)
+ Reno2: Model using lagrange_solve instead of lmm_solve (experts only)
+ Vegas: Model using lagrange_solve instead of lmm_solve (experts only)
+\endverbatim
+
+\section options_tracing Tracing Simulations for Visualization
+
+The trace visualization is widely used to observe and understand the behavior
+of parallel applications and distributed algorithms. Usually, this is done in a
+two-step fashion: the user instruments the application and the traces are
+analyzed after the end of the execution. The visualization itself can highlights
+unexpected behaviors, bottlenecks and sometimes can be used to correct
+distributed algorithms. The SimGrid team has instrumented the library
+in order to let users trace their simulations and analyze them. This part of the
+user manual explains how the tracing-related features can be enabled and used
+during the development of simulators using the SimGrid library.
+
+\subsection options_tracing_howitworks How it works
+
+For now, the SimGrid library is instrumented so users can trace the <b>platform
+utilization</b> using the MSG, SimDAG and SMPI interface. This means that the tracing will
+register how much power is used for each host and how much bandwidth is used for
+each link of the platform. The idea with this type of tracing is to observe the
+overall view of resources utilization in the first place, especially the
+identification of bottlenecks, load-balancing among hosts, and so on.
+
+The idea of the tracing facilities is to give SimGrid users to possibility to
+classify MSG and SimDAG tasks by category, tracing the platform utilization
+(hosts and links) for each of the categories. For that,
+the tracing interface enables the declaration of categories and a function to
+mark a task with a previously declared category. <em>The tasks that are not
+classified according to a category are not traced</em>. Even if the user
+does not specify any category, the simulations can still be traced in terms
+of resource utilization by using a special parameter that is detailed below.
+
+\subsection options_tracing_enabling Enabling using CMake
+
+With the sources of SimGrid, it is possible to enable the tracing
+using the parameter <b>-Denable_tracing=ON</b> when the cmake is executed.
+The section \ref options_tracing_functions describes all the functions available
+when this Cmake options is activated. These functions will have no effect
+if SimGrid is configured without this option (they are wiped-out by the
+C-preprocessor).
+
+\verbatim
+$ cmake -Denable_tracing=ON .
+$ make
+\endverbatim
+
+\subsection options_tracing_functions Tracing Functions
+
+\li <b>\c TRACE_category (const char *category)</b>: This function should be used
+to define a user category. The category can be used to differentiate the tasks
+that are created during the simulation (for example, tasks from server1,
+server2, or request tasks, computation tasks, communication tasks).
+All resource utilization (host power and link bandwidth) will be
+classified according to the task category. Tasks that do not belong to a
+category are not traced. The color for the category that is being declared
+is random (use next function to specify a color).
+
+\li <b>\c TRACE_category_with_color (const char *category, const char *color)</b>: Same
+as TRACE_category, but let user specify a color encoded as a RGB-like string with
+three floats from 0 to 1. So, to specify a red color, the user can pass "1 0 0" as
+color parameter. A light-gray color can be specified using "0.7 0.7 0.7" as color.
+
+\li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
+This function should be called after the creation of a MSG task, to define the
+category of that task. The first parameter \c task must contain a task that was
+created with the function \c MSG_task_create. The second parameter
+\c category must contain a category that was previously defined by the function
+\c TRACE_category.
+
+\li <b>\c TRACE_sd_set_task_category (SD_task_t task, const char *category)</b>:
+This function should be called after the creation of a SimDAG task, to define the
+category of that task. The first parameter \c task must contain a task that was
+created with the function \c MSG_task_create. The second parameter
+\c category must contain a category that was previously defined by the function
+\c TRACE_category.
+
+\li <b>\c TRACE_[host|link]_variable_declare (const char *variable)</b>:
+Declare a user variable that will be associated to host/link. A variable can
+be used to trace user variables such as the number of tasks in a server,
+the number of clients in an application (for hosts), and so on.
+
+\li <b>\c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value)</b>:
+Set the value of a given user variable for a given host/link. The value
+of this variable is always associated to the host/link. The host/link
+parameters should be its name as the one listed in the platform file.
+
+\li <b>\c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value)</b>:
+Same as TRACE_[host|link]_variable_[set|add|sub], but let user specify
+the time used to trace it. Users can specify a time that is not the
+simulated clock time as defined by the core simulator. This allows
+a fine-grain control of time definition, but should be used with
+caution since the trace can be inconsistent if resource utilization
+traces are also traced.
+
+\li <b>\c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value)</b>:
+Same as TRACE_link_variable_[set|add|sub], but now users specify a source and
+destination hosts (as the names from the platform file). The tracing library
+will get the corresponding route that connects those two hosts (src and dst) and
+[set|add|sub] the value's variable for all the links of the route.
+
+\li <b>\c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value)</b>:
+Same as TRACE_link_srcdst_variable_[set|add|sub], but user specify a time different from the simulated time.
+
+\subsection options_tracing_options Tracing configuration Options
+
+These are the options accepted by the tracing system of SimGrid:
+
+\li <b>\c
+tracing
+</b>:
+ Safe switch. It activates (or deactivates) the tracing system.
+ No other tracing options take effect if this one is not activated.
+
+\li <b>\c
+tracing/platform
+</b>:
+ Register the simulation platform in the trace file.
+
+\li <b>\c
+tracing/onelink_only
+</b>:
+ By default, the tracing system uses all routes in the platform file
+ to re-create a "graph" of the platform and register it in the trace file.
+ This option let the user tell the tracing system to use only the routes
+ that are composed with just one link.
+
+\li <b>\c
+tracing/categorized
+</b>:
+ It activates the categorized resource utilization tracing. It should
+ be enabled if tracing categories are used by this simulator.
+
+\li <b>\c
+tracing/uncategorized
+</b>:
+ It activates the uncategorized resource utilization tracing. Use it if
+ this simulator do not use tracing categories and resource use have to be
+ traced.
+
+\li <b>\c
+tracing/filename
+</b>:
+ A file with this name will be created to register the simulation. The file
+ is in the Paje format and can be analyzed using Triva or Paje visualization
+ tools. More information can be found in these webpages:
+ <a href="http://triva.gforge.inria.fr/">http://triva.gforge.inria.fr/</a>
+ <a href="http://paje.sourceforge.net/">http://paje.sourceforge.net/</a>
+
+\li <b>\c
+tracing/smpi
+</b>:
+ This option only has effect if this simulator is SMPI-based. Traces the MPI
+ interface and generates a trace that can be analyzed using Gantt-like
+ visualizations. Every MPI function (implemented by SMPI) is transformed in a
+ state, and point-to-point communications can be analyzed with arrows.
+
+\li <b>\c
+tracing/smpi/group
+</b>:
+ This option only has effect if this simulator is SMPI-based. The processes
+ are grouped by the hosts where they were executed.
+
+\li <b>\c
+tracing/msg/task
+</b>:
+ This option only has effect if this simulator is MSG-based. It traces the
+ behavior of all categorized MSG tasks, grouping them by hosts.
+
+\li <b>\c
+tracing/msg/process
+</b>:
+ This option only has effect if this simulator is MSG-based. It traces the
+ behavior of all categorized MSG processes, grouping them by hosts. This option
+ can be used to track process location if this simulator has process migration.
+
+
+\li <b>\c
+triva/categorized:graph_categorized.plist
+</b>:
+ This option generates a graph configuration file for Triva considering
+ categorized resource utilization.
+
+\li <b>\c
+triva/uncategorized:graph_uncategorized.plist
+</b>:
+ This option generates a graph configuration file for Triva considering
+ uncategorized resource utilization.
+
+\subsection options_tracing_example Example of Instrumentation
+
+A simplified example using the tracing mandatory functions.
+
+\verbatim
+int main (int argc, char **argv)
+{
+ MSG_global_init (&argc, &argv);
+
+ //(... after deployment ...)
+
+ //note that category declaration must be called after MSG_create_environment
+ TRACE_category_with_color ("request", "1 0 0");
+ TRACE_category_with_color ("computation", "0.3 1 0.4");
+ TRACE_category ("finalize");
+
+ m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
+ m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
+ m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
+ m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
+ TRACE_msg_set_task_category (req1, "request");
+ TRACE_msg_set_task_category (req2, "request");
+ TRACE_msg_set_task_category (req3, "request");
+ TRACE_msg_set_task_category (req4, "request");
+
+ m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
+ TRACE_msg_set_task_category (comp, "computation");
+
+ m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
+ TRACE_msg_set_task_category (finalize, "finalize");
+
+ //(...)
+
+ MSG_clean();
+ return 0;
+}
+\endverbatim
+
+\subsection options_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</i>. This file contains instructions to install
+the tool's dependencies in a Ubuntu/Debian Linux. The tool can also
+be compiled in MacOSes natively, check <i>INSTALL.mac</i> file.
+\verbatim
+$ svn checkout svn://scm.gforge.inria.fr/svn/triva
+$ cd triva
+$ cat INSTALL
+\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. We strongly recommend that you
+use the latest GNUstep packages, and not the packages available through apt-get
+in Ubuntu/Debian packaging systems. If you install GNUstep using the latest
+available packages, you can execute this command:
+\verbatim
+$ source /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
+\endverbatim
+You should be able to see this output after the installation of triva:
+\verbatim
+$ ./Triva.app/Triva --help
+Usage: Triva [OPTIONS...] TRACE0 [TRACE1]
+Trace Analysis through Visualization
+
+TimeInterval
+ --ti_frequency {double} Animation: frequency of updates
+ --ti_hide Hide the TimeInterval window
+ --ti_forward {double} Animation: value to move time-slice
+ --ti_apply Apply the configuration
+ --ti_update Update on slider change
+ --ti_animate Start animation
+ --ti_start {double} Start of time slice
+ --ti_size {double} Size of time slice
+Triva
+ --comparison Compare Trace Files (Experimental)
+ --graph Configurable Graph
+ --list Print Trace Type Hierarchy
+ --hierarchy Export Trace Type Hierarchy (dot)
+ --stat Trace Statistics and Memory Utilization
+ --instances List All Trace Entities
+ --linkview Link View (Experimental)
+ --treemap Squarified Treemap
+ --merge Merge Trace Files (Experimental)
+ --check Check Trace File Integrity
+GraphConfiguration
+ --gc_conf {file} Graph Configuration in Property List Format
+ --gc_apply Apply the configuration
+ --gc_hide Hide the GraphConfiguration window
+\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 = source;
+ dst = destination;
+
+ 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>source</em> and <em>destination</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 = source;
+ dst = destination;
+ 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 = source;
+ dst = destination;
+ 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 options_modelchecking Model-Checking
+\subsection options_modelchecking_howto How to use it
+To enable the experimental SimGrid model-checking support the program should
+be executed with the command line argument
+\verbatim
+--cfg=model-check:1
+\endverbatim
+Properties are expressed as assertions using the function
+\verbatim
+void MC_assert(int prop);
+\endverbatim
+
+*/
\ No newline at end of file
--- /dev/null
+/*! \page use Use SimGrid
+
+\section use_generic First steps with SimGrid
+
+If you decide to go for the MSG interface, please read carefully the
+\ref MSG_examples. You'll find in \ref MSG_ex_master_slave a very
+simple consisting of a master (that owns a bunch of tasks and
+distributes them) , some slaves (that process tasks whenever they
+receive one) and some forwarder agents (that simply pass the tasks
+they receive to some slaves).
+
+If you decide to go for the GRAS interface, you should definitively
+read the \ref GRAS_tut. The first section constitutes an introduction
+to the tool and presents the model we use. The second section
+constitutes a complete step-by-step tutorial building a distributed
+application from the beginning and exemplifying most of the GRAS
+features in the process. The last section groups some HOWTOS
+highlighting a given feature of the framework in a more concise way.
+
+If you decide to go for another interface, I'm afraid your only sources
+of information will be the source code and the mailing lists...
+
+*/
\ No newline at end of file
my @extra_files = qw(html/index.html html/faq.html html/history.html html/contrib.html html/people.html
html/publis.html html/publis_core.html html/publis_extern.html html/publis_intra.html
html/pages.html html/modules.html html/annotated.html html/functions.html html/functions_vars.html index.php
- html/GRAS_tut.html html/installSimgrid.html html/bindings.html);
+ html/GRAS_tut.html html/installSimgrid.html html/bindings.html html/options.html html/use.html);
# GRAS tutorial
map {push @extra_files, "html/GRAS_tut_$_.html"} qw (intro
}
if( $_ =~ /<\/ul>/ && $tabs){
my $tmp_buff="";
- $tmp_buff .= ' <li><a href="installSimgrid.html"><span>Install SimGrid</span></a></li>'."\n";
- $tmp_buff .= ' <li><a href="bindings.html"><span>Bindings</span></a></li>'."\n";
- $tmp_buff .= ' <li><a href="faq.html"><span>FAQ Page</span></a></li>'."\n";
- $tmp_buff .= ' <li><a href="publis.html"><span>Publications</span></a></li>'."\n";
+ $tmp_buff .= ' <li><a href="use.html"><span>Use SimGrid</span></a></li>'."\n";
+ $tmp_buff .= ' <li><a href="publis.html"><span>Publications</span></a></li>'."\n";
$tmp_buff .= ' <li><a href="people.html"><span>People</span></a></li>'."\n";
$tmp_buff .= ' <li><a href="history.html"><span>History</span></a></li>'."\n";
$tmp_buff .= ' <li><a href="contrib.html"><span>Contrib</span></a></li>'."\n";
$tmp_buff .= ' <li><a href="http://simgrid.gforge.inria.fr/"><span>Home</span></a></li>'."\n";
$tmp_buff .= $_;
$tabs = 0;
+
+ # Rework the navbar and add menu for use.html
+ # Fix the current "button" of buggy Doxygen tabs
+ if($file =~ /^html\/use.*/
+ || $file =~ /^html\/installSimgrid.*/
+ || $file =~ /^html\/options.*/
+ || $file =~ /^html\/bindings.*/
+ || $file =~ /^html\/faq.*/)
+ {
+ $tmp_buff .= ' <div class="tabs_group_use">'."\n";
+ $tmp_buff .= ' <ul class="tablist">'."\n";
+ $tmp_buff .= ' <li><a href="installSimgrid.html"><span>Install SimGrid</span></a></li>'."\n";
+ $tmp_buff .= ' <li><a href="options.html"><span>Options & configurations</span></a></li>'."\n";
+ $tmp_buff .= ' <li><a href="bindings.html"><span>Bindings</span></a></li>'."\n";
+ $tmp_buff .= ' <li><a href="faq.html"><span>FAQ Page</span></a></li>'."\n";
+ $tmp_buff .= ' </ul></div>'."\n";
+ $tmp_buff .= ' </div>'."\n";
+
+ my $filename = $file;
+ $filename =~ s/html\///g;
+ $filename =~ s/\.html//g;
+ $filename =~ s/publis_.*/publis/g;
+ $tmp_buff =~ s/<li class="current">/<li>/g;
+ $tmp_buff =~ s/<li><a href="$filename.html">/<li class="current"><a href="$filename.html">/g;
+ $tmp_buff =~ s/<li><a href="use.html">/<li class="current"><a href="$filename.html">/g;
+
+ }
# Rework the navbar
# Fix the current "button" of buggy Doxygen tabs
- if($file =~ /^html\/faq.*/
- || $file =~ /^html\/publis.*/
+ if($file =~ /^html\/publis.*/
|| $file =~ /^html\/people.*/
|| $file =~ /^html\/history.*/
- || $file =~ /^html\/contrib.*/
- || $file =~ /^html\/installSimgrid.*/
- || $file =~ /^html\/bindings.*/)
+ || $file =~ /^html\/contrib.*/)
{
my $filename = $file;
$filename =~ s/html\///g;
$tmp_buff =~ s/<li class="current">/<li>/g;
$tmp_buff =~ s/<li><a href="$filename.html">/<li class="current"><a href="$filename.html">/g;
}
- print TO $tmp_buff;
+
+
+ print TO $tmp_buff;
next;
}
- s|<span>Modules</span>|<span>Modules API</span>|g;
+ s|<span>Modules</span>|<span>Modules API</span>|g;
s|<span>Related Pages</span>|<span>Site Plan</span>|g;
print TO $_;
