X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2cc20f1526f80e1c731e986a50c5b77fa7e223d8..97a6a52b7b30e6e30d0e5e809dfb16a2574a3717:/doc/options.doc diff --git a/doc/options.doc b/doc/options.doc index 086012d3b5..5bb02b7fe4 100644 --- a/doc/options.doc +++ b/doc/options.doc @@ -2,630 +2,492 @@ \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 \ tag in the platform file. The +only restriction is that this tag must occure before the first +platform element (be it \c \, \c \, \c \ or whatever). +The \c \ 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 \ 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 + + + \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 -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 Network Model for Simulation of Grid Application. -Other models have been proposed and implemented since then (see for example -Accuracy Study and Improvement of Network Simulation in the SimGrid Framework) -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 +Network Model for Simulation of Grid Application while LV08 is +described in +Accuracy Study and Improvement of Network Simulation in the SimGrid Framework. + + - \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 +Accuracy Study and Improvement of Network Simulation in the SimGrid Framework +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 platform -utilization 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. The tasks that are not -classified according to a category are not traced. 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 -Denable_tracing=ON 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 \c TRACE_category (const char *category): 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 \c TRACE_category_with_color (const char *category, const char *color): 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 \c TRACE_msg_set_task_category (m_task_t task, const char *category): -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 \c TRACE_sd_set_task_category (SD_task_t task, const char *category): -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 \c TRACE_[host|link]_variable_declare (const char *variable): -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 \c TRACE_[host|link]_variable_[set|add|sub] (const char *[host|link], const char *variable, double value): -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 \c TRACE_[host|link]_variable_[set|add|sub]_with_time (double time, const char *[host|link], const char *variable, double value): -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 \c TRACE_link_srcdst_variable_[set|add|sub] (const char *src, const char *dst, const char *variable, double value): -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 \c TRACE_link_srcdst_variable_[set|add|sub]_with_time (double time, const char *src, const char *dst, const char *variable, double value): -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 \c -tracing -: - Safe switch. It activates (or deactivates) the tracing system. - No other tracing options take effect if this one is not activated. - -\li \c -tracing/platform -: - Register the simulation platform in the trace file. - -\li \c -tracing/onelink_only -: - 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 \c -tracing/categorized -: - It activates the categorized resource utilization tracing. It should - be enabled if tracing categories are used by this simulator. - -\li \c -tracing/uncategorized -: - 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 \c -tracing/filename -: - 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: - http://triva.gforge.inria.fr/ - http://paje.sourceforge.net/ - -\li \c -tracing/smpi -: - 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 \c -tracing/smpi/group -: - This option only has effect if this simulator is SMPI-based. The processes - are grouped by the hosts where they were executed. - -\li \c -tracing/msg/task -: - 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 \c -tracing/msg/process -: - 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 \c -triva/categorized:graph_categorized.plist -: - This option generates a graph configuration file for Triva considering - categorized resource utilization. - -\li \c -triva/uncategorized:graph_uncategorized.plist -: - 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 examples/msg/gtnets/crosstraffic-p.xml. - //(... 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 \ 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 Triva, 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. - -- Installing Triva: the tool is available in the INRIAGforge, -at http://triva.gforge.inria.fr. -Use the following command to get the sources, and then check the file -INSTALL. 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 INSTALL.mac file. -\verbatim -$ svn checkout svn://scm.gforge.inria.fr/svn/triva -$ cd triva -$ cat INSTALL -\endverbatim +\subsubsection options_pls Configuring packet-level pseudo-models -- Executing Triva: a binary called Triva is available after the - installation (you can execute it passing --help 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 --graph or --treemap for a visualization analysis) -and the trace file from the simulation. - -- Understanding Triva - time-slice: the analysis of a trace file using - the tool always takes into account the concept of the time-slice. -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 Time Interval 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 Trace Time, -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 Time Slice Configuration, contains the -aspects related to the time-slice, including its start and its -size. The gray rectangle in the bottom of this part indicates the -current time-slice that is considered for the drawings. If the checkbox -Update Drawings on Sliders Change is not selected, the button -Apply 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 Time Slice Animation 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 Play button in order to see the dynamic -changes on the drawings. -
-\htmlonly - -\endhtmlonly -
-Remarks: 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 -Frequency parameter, but also updates caused by change on configurations -when the checkbox Update Drawings on Sliders -Change is selected will not be followed. - -- Understanding Triva - graph: this part of the documention explains how - to analyze the traces using the graph view of Triva, when the user executes -the tool passing --graph as parameter. Triva opens three windows when -this parameter is used: the Time Interval window (previously described), -the Graph Representation window, and the Graph Configuration -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 -Graph Configuration 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 -Property List Format 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 Apply -button activates the current configuration, resulting on an update on the graph -drawings. -
-\htmlonly - -\endhtmlonly -
-Basic SimGrid Configuration: 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 node parameter, which -in this case is the different "HOST"s of the platform -used to simulate. The edge parameter indicates that the edges of the -graph will be created based on the "LINK"s of the platform. After the -definition of these two parameters, the configuration must detail how -HOSTs and LINKs should be drawn. For that, the configuration -must have an entry for each of the types used. For HOST, as basic -configuration, we have: -\verbatim - HOST = { - size = power; - scale = global; - }; -\endverbatim -The parameter size 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 scale indicates if the value -of the variable is global or local. 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 LINK we have: -\verbatim - LINK = { - src = source; - dst = destination; - - size = bandwidth; - scale = global; - }; -\endverbatim -For the types specified in the edge parameter (such as LINK), -the configuration must contain two additional parameters: src and -dst that are used to properly identify which nodes this edge is -connecting. The values source and destination are always present -in the SimGrid trace file and should not be changed in the configuration. The -parameter size for the LINK, in this case, is configured as the -variable bandwidth, with a global 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 -Customizing the Graph Representation: 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 request, there will be variables named -prequest and a brequest (p for power and -b for bandwidth). It is important to notice that the variable -prequest in this case is only available for HOST, and -brequest is only available for LINK. Example: 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 sep_host contains a composition of type separation where -its max size is the power of the host and the variables prequest -and pcomputation are drawn proportionally to the size of the HOST. And -sep_link is also a separation where max is defined as the -bandwidth of the link, and the variables brequest and -bcomputation are drawn proportionally within a LINK. -This configuration enables the analysis of resource utilization by MSG tasks, -and the identification of load-balancing issues, network bottlenecks, for -instance. \n -Other compositions: besides separation, 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 +INRIA RR-7653. + +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 gra_host creates a gradient within a node of the graph, using a -global scale and using as value a variable called numberOfTasks, 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 color_host composition draws a square based on a positive value of -the variable is_server, that could also be defined by the user using the -SimGrid tracing functions. \n -The Graph Visualization: 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 compute 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 -
-\htmlonly - -\endhtmlonly -
- -- Understading Triva - colors: 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 --list -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 -pcompute and bcompute (which are defined based on user category -compute), execute: -\verbatim -$ defaults write Triva 'pcompute Color' '1 0 0' -$ defaults write Triva 'bcompute Color' '1 0 0' + The -trace parameter for the smpirun script runs the +simulation with --cfg=tracing:1 and --cfg=tracing/smpi:1. Check the +smpirun's -help 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 +\ 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