\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
+SimGrid behavior. For a complete list of all configuration options
+accepted by the SimGrid version used in your simulator, simply pass
+the --help configuration flag to your program. If some of the options
+are not documented on this page, this is a bug that you should please
+report so that we can fix it.
+
+\section options_using Passing configuration options to the simulators
+
+There is several way to pass configuration options to the simulators.
+The most common way is to use the \c --cfg command line argument. For
+example, to set the item \c Item to the value \c Value, simply
+type the following: \verbatim
+my_simulator --cfg=Item:Value (other arguments)
+\endverbatim
-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
+Several \c --cfg command line arguments can naturally be used. If you
+need to include spaces in the argument, don't forget to quote the
+argument. You can even escape the included quotes (write \' for ' if
+you have your argument between ').
+
+Another solution is to use the \c \<config\> tag in the platform file. The
+only restriction is that this tag must occure before the first
+platform element (be it \c \<AS\>, \c \<cluster\>, \c \<peer\> or whatever).
+The \c \<config\> tag takes an \c id attribute, but it is currently
+ignored so you don't really need to pass it. The important par is that
+within that tag, you can pass one or several \c \<prop\> tags to specify
+the configuration to use. For example, setting \c Item to \c Value
+can be done by adding the following to the beginning of your platform
+file: \verbatim
+<config>
+ <prop id="Item" value="Value"/>
+</config>
\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.
+A last solution is to pass your configuration directly using the C
+interface. Unfortunately, this path is not really easy to use right
+now, and you mess directly with surf internal variables as follows. Check the
+\ref XBT_config "relevant page" for details on all the functions you
+can use in this context, \c _surf_cfg_set being the only configuration set
+currently used in SimGrid. \code
+#include <xbt/config.h>
-Running a fullduplex example:
-\verbatim
- cd simgrid_svn_sources/exemples/msg/gtnets
- ./gtnets fullduplex-p.xml fullduplex-d.xml --cfg=fullduplex:1
-\endverbatim
+extern xbt_cfg_t _surf_cfg_set;
-\subsection options_simgrid_configuration_alternate_network Using alternative flow models
+int main(int argc, char *argv[]) {
+ MSG_global_init(&argc, argv);
-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
+ xbt_cfg_set_parse(_surf_cfg_set,"Item:Value");
+
+ // Rest of your code
+}
+\endcode
+
+\section options_model Configuring the platform models
+
+\subsection options_model_select Selecting the platform models
+
+SimGrid comes with several network and CPU models built in, and you
+can change the used model at runtime by changing the passed
+configuration. The three main configuration items are given below.
+For each of these items, passing the special \c help value gives
+you a short description of all possible values. Also, \c --help-models
+should provide information about all models for all existing resources.
+ - \b network/model: specify the used network model
+ - \b cpu/model: specify the used CPU model
+ - \b workstation/model: specify the used workstation model
+
+As of writting, the accepted network models are the following. Over
+the time new models can be added, and some experimental models can be
+removed; check the values on your simulators for an uptodate
+information. Note that the CM02 model is described 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> while LV08 is
+described in
+<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>.
+
+ - \b LV08 (default one): Realistic network analytic model
+ (slow-start modeled by multiplying latency by 10.4, bandwidth by
+ .92; bottleneck sharing uses a payload of S=8775 for evaluating RTT)
+ - \b Constant: Simplistic network model where all communication
+ take a constant time (one second). This model provides the lowest
+ realism, but is (marginally) faster.
+ - \b SMPI: Realistic network model specifically tailored for HPC
+ settings (accurate modeling of slow start with correction factors on
+ three intervals: < 1KiB, < 64 KiB, >= 64 KiB). See also \ref
+ options_model_network_coefs "this section" for more info.
+ - \b CM02: Legacy network analytic model (Very similar to LV08, but
+ without corrective factors. The timings of small messages are thus
+ poorly modeled)
+ - \b Reno: Model from Steven H. Low using lagrange_solve instead of
+ lmm_solve (experts only; check the code for more info).
+ - \b Reno2: Model from Steven H. Low using lagrange_solve instead of
+ lmm_solve (experts only; check the code for more info).
+ - \b Vegas: Model from Steven H. Low using lagrange_solve instead of
+ lmm_solve (experts only; check the code for more info).
+
+If you compiled SimGrid accordingly, you can use packet-level network
+simulators as network models (see \ref pls). In that case, you have
+two extra models, described below, and some \ref options_pls "specific
+additional configuration flags".
+ - \b GTNets: Network pseudo-model using the GTNets simulator instead
+ of an analytic model
+ - \b NS3: Network pseudo-model using the NS3 tcp model instead of an
+ analytic model
+
+Concerning the CPU, we have only one model for now:
+ - \b Cas01: Simplistic CPU model (time=size/power)
+
+The workstation concept is the aggregation of a CPU with a network
+card. Three models exists, but actually, only 2 of them are
+interesting. The "compound" one is simply due to the way our internal
+code is organized, and can easily be ignored. So at the end, you have
+two workstation models: The default one allows to aggregate an
+existing CPU model with an existing network model, but does not allow
+parallel tasks because these beasts need some collaboration between
+the network and CPU model. That is why, ptask_07 is used by default
+when using SimDag.
+ - \b default: Default workstation model. Currently, CPU:Cas01 and
+ network:LV08 (with cross traffic enabled)
+ - \b compound: Workstation model that is automatically chosen if
+ you change the network and CPU models
+ - \b ptask_L07: Workstation model somehow similar to Cas01+CM02 but
+ allowing parallel tasks
+
+\subsection options_model_optim Optimization level of the platform models
+
+The network and CPU models that are based on lmm_solve (that
+is, all our analytical models) accept specific optimization
+configurations.
+ - items \b network/optim and \b CPU/optim (both default to 'Lazy'):
+ - \b Lazy: Lazy action management (partial invalidation in lmm +
+ heap in action remaining).
+ - \b TI: Trace integration. Highly optimized mode when using
+ availability traces (only available for the Cas01 CPU model for
+ now).
+ - \b Full: Full update of remaining and variables. Slow but may be
+ useful when debugging.
+ - items \b network/maxmin_selective_update and
+ \b cpu/maxmin_selective_update: configure whether the underlying
+ should be lazily updated or not. It should have no impact on the
+ computed timings, but should speed up the computation.
+
+It is still possible to disable the \c maxmin_selective_update feature
+because it can reveal counter-productive in very specific scenarios
+where the interaction level is high. In particular, if all your
+communication share a given backbone link, you should disable it:
+without \c maxmin_selective_update, every communications are updated
+at each step through a simple loop over them. With that feature
+enabled, every communications will still get updated in this case
+(because of the dependency induced by the backbone), but through a
+complicated pattern aiming at following the actual dependencies.
+
+\subsection options_model_precision Numerical precision of the platform models
+
+The analytical models handle a lot of floating point values. It is
+possible to change the epsilon used to update and compare them through
+the \b maxmin/precision item (default value: 1e-9). Changing it
+may speedup the simulation by discarding very small actions, at the
+price of a reduced numerical precision.
+
+\subsection options_model_nthreads Parallel threads for model updates
+
+By default, Surf computes the analytical models sequentially to share their
+resources and update their actions. It is possible to run them in parallel,
+using the \b surf/nthreads item (default value: 1). If you use a
+negative value, the amount of available cores is automatically
+detected and used instead.
+
+Depending on the workload of the models and their complexity, you may get a
+speedup or a slowdown because of the synchronization costs of threads.
+
+\subsection options_model_network Configuring the Network model
+
+\subsubsection options_model_network_gamma Maximal TCP window size
+
+The analytical models need to know the maximal TCP window size to take
+the TCP congestion mechanism into account. This is set to 20000 by
+default, but can be changed using the \b network/TCP_gamma item.
+
+On linux, this value can be retrieved using the following
+commands. Both give a set of values, and you should use the last one,
+which is the maximal size.\verbatim
+cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window
+cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window
\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.
+\subsubsection options_model_network_coefs Corrective simulation factors
-\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
+These factors allow to betterly take the slow start into account.
+The corresponding values were computed through data fitting one the
+timings of packet-level simulators. You should not change these values
+unless you are really certain of what you are doing. See
+<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>
+for more informations about these coeficients.
-\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).
+If you are using the SMPI model, these correction coeficients are
+themselves corrected by constant values depending on the size of the
+exchange. Again, only hardcore experts should bother about this fact.
-\verbatim
-$ cmake -Denable_tracing=ON .
-$ make
-\endverbatim
+\subsubsection options_model_network_crosstraffic Simulating cross-traffic
-\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.
+As of SimGrid v3.7, cross-traffic effects can be taken into account in
+analytical simulations. It means that ongoing and incoming
+communication flows are treated independently. In addition, the LV08
+model 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.
-\verbatim
-int main (int argc, char **argv)
-{
- MSG_global_init (&argc, &argv);
+For that to work, your platform must have two links for each
+pair of interconnected hosts. An example of usable platform is
+available in <tt>examples/msg/gtnets/crosstraffic-p.xml</tt>.
- //(... after deployment ...)
+This is activated through the \b network/crosstraffic item, that
+can be set to 0 (disable this feature) or 1 (enable it).
- //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");
+Note that with the default workstation model this option is activated by default.
- 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");
+\subsubsection options_model_network_coord Coordinated-based network models
- m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
- TRACE_msg_set_task_category (comp, "computation");
+When you want to use network coordinates, as it happens when you use
+an \<AS\> in your platform file with \c Vivaldi as a routing, you must
+set the \b network/coordinates to \c yes so that all mandatory
+initialization are done in the simulator.
- m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
- TRACE_msg_set_task_category (finalize, "finalize");
+\subsubsection options_model_network_sendergap Simulating sender gap
- //(...)
+(this configuration item is experimental and may change or disapear)
- MSG_clean();
- return 0;
-}
-\endverbatim
+It is possible to specify a timing gap between consecutive emission on
+the same network card through the \b network/sender_gap item. This
+is still under investigation as of writting, and the default value is
+to wait 0 seconds between emissions (no gap applied).
-\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
+\subsubsection options_pls Configuring packet-level pseudo-models
-- <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.
+When using the packet-level pseudo-models, several specific
+configuration flags are provided to configure the associated tools.
+There is by far not enough such SimGrid flags to cover every aspects
+of the associated tools, since we only added the items that we
+needed ourselves. Feel free to request more items (or even better:
+provide patches adding more items).
+
+When using NS3, the only existing item is \b ns3/TcpModel,
+corresponding to the ns3::TcpL4Protocol::SocketType configuration item
+in NS3. The only valid values (enforced on the SimGrid side) are
+'NewReno' or 'Reno' or 'Tahoe'.
+
+When using GTNeTS, two items exist:
+ - \b gtnets/jitter, that is a double value to oscillate
+ the link latency, uniformly in random interval
+ [-latency*gtnets_jitter,latency*gtnets_jitter). It defaults to 0.
+ - \b gtnets/jitter_seed, the positive seed used to reproduce jitted
+ results. Its value must be in [1,1e8] and defaults to 10.
+
+\section options_modelchecking Configuring the Model-Checking
+
+To enable the experimental SimGrid model-checking support the program should
+be executed with the command line argument
\verbatim
- graphviz-algorithm = neato;
-}
+--cfg=model-check:1
\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:
+Properties are expressed as assertions using the function
\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);
- };
- };
+void MC_assert(int prop);
\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:
+
+\section options_virt Configuring the User Process Virtualization
+
+\subsection options_virt_factory Selecting the virtualization factory
+
+In SimGrid, the user code is virtualized in a specific mecanism
+allowing the simulation kernel to control its execution: when a user
+process requires a blocking action (such as sending a message), it is
+interrupted, and only gets released when the simulated clock reaches
+the point where the blocking operation is done.
+
+In SimGrid, the containers in which user processes are virtualized are
+called contexts. Several context factory are provided, and you can
+select the one you want to use with the \b contexts/factory
+configuration item. Some of the following may not exist on your
+machine because of portability issues. In any case, the default one
+should be the most effcient one (please report bugs if the
+auto-detection fails for you). They are sorted here from the slowest
+to the most effient:
+ - \b thread: very slow factory using full featured threads (either
+ ptheads or windows native threads)
+ - \b ucontext: fast factory using System V contexts (or a portability
+ layer of our own on top of Windows fibers)
+ - \b raw: amazingly fast factory using a context switching mecanism
+ of our own, directly implemented in assembly (only available for x86
+ and amd64 platforms for now)
+
+The only reason to change this setting is when the debuging tools get
+fooled by the optimized context factories. Threads are the most
+debugging-friendly contextes.
+
+\subsection options_virt_stacksize Adapting the used stack size
+
+(this only works if you use ucontexts or raw context factories)
+
+Each virtualized used process is executed using a specific system
+stack. The size of this stack has a huge impact on the simulation
+scalability, but its default value is rather large. This is because
+the error messages that you get when the stack size is too small are
+rather disturbing: this leads to stack overflow (overwriting other
+stacks), leading to segfaults with corrupted stack traces.
+
+If you want to push the scalability limits of your code, you really
+want to reduce the \b contexts/stack_size item. Its default value
+is 128 (in Kib), while our Chord simulation works with stacks as small
+as 16 Kib, for example.
+
+\subsection options_virt_parallel Running user code in parallel
+
+Parallel execution of the user code is only considered stable in
+SimGrid v3.7 and higher. It is described in
+<a href="http://hal.inria.fr/inria-00602216/">INRIA RR-7653</a>.
+
+If you are using the \c ucontext or \c raw context factories, you can
+request to execute the user code in parallel. Several threads are
+launched, each of them handling as much user contexts at each run. To
+actiave this, set the \b contexts/nthreads item to the amount of
+cores that you have in your computer (or -1 to have the amount of cores
+auto-detected).
+
+Even if you asked several worker threads using the previous option,
+you can request to start the parallel execution (and pay the
+associated synchronization costs) only if the potential parallelism is
+large enough. For that, set the \b contexts/parallel_threshold
+item to the minimal amount of user contexts needed to start the
+parallel execution. In any given simulation round, if that amount is
+not reached, the contexts will be run sequentially directly by the
+main thread (thus saving the synchronization costs). Note that this
+option is mainly useful when the grain of the user code is very fine,
+because our synchronization is now very efficient.
+
+When parallel execution is activated, you can choose the
+synchronization schema used with the \b contexts/synchro item,
+which value is either:
+ - \b futex: ultra optimized synchronisation schema, based on futexes
+ (fast user-mode mutexes), and thus only available on Linux systems.
+ This is the default mode when available.
+ - \b posix: slow but portable synchronisation using only POSIX
+ primitives.
+ - \b busy_wait: not really a synchronisation: the worker threads
+ constantly request new contexts to execute. It should be the most
+ efficient synchronisation schema, but it loads all the cores of your
+ machine for no good reason. You probably prefer the other less
+ eager schemas.
+
+\section options_tracing Configuring the tracing subsystem
+
+The \ref tracing "tracing subsystem" can be configured in several
+different ways depending on the nature of the simulator (MSG, SimDag,
+SMPI) and the kind of traces that need to be obtained. See the \ref
+tracing_tracing_options "Tracing Configuration Options subsection" to
+get a detailed description of each configuration option.
+
+We detail here a simple way to get the traces working for you, even if
+you never used the tracing API.
+
+
+- Any SimGrid-based simulator (MSG, SimDag, SMPI, ...) and raw traces:
\verbatim
- gra_host = {
- type = gradient;
- scale = global;
- values = (numberOfTasks);
- };
- color_host = {
- type = color;
- values = (is_server);
- };
+--cfg=tracing:1 --cfg=tracing/uncategorized:1 --cfg=triva/uncategorized:uncat.plist
\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:
+ The first parameter activates the tracing subsystem, the second
+ tells it to trace host and link utilization (without any
+ categorization) and the third creates a graph configuration file
+ to configure Triva when analysing the resulting trace file.
+
+- MSG or SimDag-based simulator and categorized traces (you need to declare categories and classify your tasks according to them)
\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;
-}
+--cfg=tracing:1 --cfg=tracing/categorized:1 --cfg=triva/categorized:cat.plist
\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:
+ The first parameter activates the tracing subsystem, the second
+ tells it to trace host and link categorized utilization and the
+ third creates a graph configuration file to configure Triva when
+ analysing the resulting trace file.
+
+- SMPI simulator and traces for a space/time view:
\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
+smpirun -trace ...
\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'
+ The <i>-trace</i> parameter for the smpirun script runs the
+simulation with --cfg=tracing:1 and --cfg=tracing/smpi:1. Check the
+smpirun's <i>-help</i> parameter for additional tracing options.
+
+\section options_smpi Configuring SMPI
+
+The SMPI interface provides several specific configuration items.
+These are uneasy to see since the code is usually launched through the
+\c smiprun script directly.
+
+\subsection options_smpi_bench Automatic benchmarking of SMPI code
+
+In SMPI, the sequential code is automatically benchmarked, and these
+computations are automatically reported to the simulator. That is to
+say that if you have a large computation between a \c MPI_Recv() and a
+\c MPI_Send(), SMPI will automatically benchmark the duration of this
+code, and create an execution task within the simulator to take this
+into account. For that, the actual duration is measured on the host
+machine and then scaled to the power of the corresponding simulated
+machine. The variable \b smpi/running_power allows to specify the
+computational power of the host machine (in flop/s) to use when
+scaling the execution times. It defaults to 20000, but you really want
+to update it to get accurate simulation results.
+
+When the code is constituted of numerous consecutive MPI calls, the
+previous mechanism feeds the simulation kernel with numerous tiny
+computations. The \b smpi/cpu_threshold item becomes handy when this
+impacts badly the simulation performance. It specify a threshold (in
+second) under which the execution chunks are not reported to the
+simulation kernel (default value: 1e-6). Please note that in some
+circonstances, this optimization can hinder the simulation accuracy.
+
+\subsection options_smpi_timing Reporting simulation time
+
+Most of the time, you run MPI code through SMPI to compute the time it
+would take to run it on a platform that you don't have. But since the
+code is run through the \c smpirun script, you don't have any control
+on the launcher code, making difficult to report the simulated time
+when the simulation ends. If you set the \b smpi/display_timing item
+to 1, \c smpirun will display this information when the simulation ends. \verbatim
+Simulation time: 1e3 seconds.
\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);
+\section options_generic Configuring other aspects of SimGrid
+
+\subsection options_generic_path XML file inclusion path
+
+It is possible to specify a list of directories to search into for the
+\<include\> tag in XML files by using the \b path configuration
+item. To add several directory to the path, set the configuration
+item several times, as in \verbatim
+--cfg=path:toto --cfg=path:tutu
\endverbatim
+\subsection options_generic_exit Behavior on Ctrl-C
+
+By default, when Ctrl-C is pressed, the status of all existing
+simulated processes is displayed. This is very useful to debug your
+code, but it can reveal troublesome in some cases (such as when the
+amount of processes becomes really big). This behavior is disabled
+when \b verbose-exit is set to 0 (it is to 1 by default).
+
+\section options_index Index of all existing configuration items
+
+- \c contexts/factory: \ref options_virt_factory
+- \c contexts/nthreads: \ref options_virt_parallel
+- \c contexts/parallel_threshold: \ref options_virt_parallel
+- \c contexts/stack_size: \ref options_virt_stacksize
+- \c contexts/synchro: \ref options_virt_parallel
+
+- \c cpu/maxmin_selective_update: \ref options_model_optim
+- \c cpu/model: \ref options_model_select
+- \c cpu/optim: \ref options_model_optim
+
+- \c gtnets/jitter: \ref options_pls
+- \c gtnets/jitter_seed: \ref options_pls
+
+- \c maxmin/precision: \ref options_model_precision
+
+- \c network/bandwidth_factor: \ref options_model_network_coefs
+- \c network/coordinates: \ref options_model_network_coord
+- \c network/crosstraffic: \ref options_model_network_crosstraffic
+- \c network/latency_factor: \ref options_model_network_coefs
+- \c network/maxmin_selective_update: \ref options_model_optim
+- \c network/model: \ref options_model_select
+- \c network/optim: \ref options_model_optim
+- \c network/sender_gap: \ref options_model_network_sendergap
+- \c network/TCP_gamma: \ref options_model_network_gamma
+- \c network/weight_S: \ref options_model_network_coefs
+
+- \c ns3/TcpModel: \ref options_pls
+
+- \c surf/nthreads: \ref options_model_nthreads
+
+- \c smpi/running_power: \ref options_smpi_bench
+- \c smpi/display_timing: \ref options_smpi_timing
+- \c smpi/cpu_threshold: \ref options_smpi_bench
+
+- \c path: \ref options_generic_path
+- \c verbose-exit: \ref options_generic_exit
+
+- \c workstation/model: \ref options_model_select
+
*/
\ No newline at end of file
