doc/options.doc

   1 /*! \page options Simgrid options and configurations
   2
   3 \htmlinclude .options.doc.toc
   4
   5 A number of options can be given at runtime to change the default
   6 SimGrid behavior. For a complete list of all configuration options
   7 accepted by the SimGrid version used in your simulator, simply pass
   8 the --help configuration flag to your program. If some of the options
   9 are not documented on this page, this is a bug that you should please
  10 report so that we can fix it.
  11
  12 \section options_using Passing configuration options to the simulators
  13
  14 There is several way to pass configuration options to the simulators.
  15 The most common way is to use the \c --cfg command line argument. For
  16 example, to set the variable \c Variable to the value \c Value, simply
  17 type the following: \verbatim
  18 my_simulator --cfg=Variable:Value (other arguments)
  19 \endverbatim
  20
  21 Several \c --cfg command line arguments can naturally be used. If you
  22 need to include spaces in the argument, don't forget to quote the
  23 argument. You can even escape the included quotes (write \' for ' if
  24 you have your argument between ').
  25
  26 Another solution is to use the \c \<config\> tag in the platform file. The
  27 only restriction is that this tag must occure before the first
  28 platform element (be it \c \<AS\>, \c \<cluster\>, \c \<peer\> or whatever).
  29 The \c \<config\> tag takes an \c id attribute, but it is currently
  30 ignored so you don't really need to pass it. The important par is that
  31 within that tag, you can pass one or several \c \<prop\> tags to specify
  32 the configuration to use. For example, setting \c Variable to \c Value
  33 can be done by adding the following to the beginning of your platform
  34 file: \verbatim
  35 <config>
  36   <prop id="Variable" value="Value"/>
  37 </config>
  38 \endverbatim
  39
  40 A last solution is to pass your configuration directly using the C
  41 interface. Unfortunately, this path is not really easy to use right
  42 now, and you mess directly with surf variables as follows. Check the
  43 \ref XBT_config "relevant page" for details on all the functions you
  44 can use in this context (\c _surf_cfg_set is the only configuration set
  45 currently used in SimGrid). \code
  46 #include <xbt/config.h>
  47
  48 extern xbt_cfg_t _surf_cfg_set;
  49
  50 int main(int argc, char *argv[]) {
  51      MSG_global_init(&argc, argv);
  52
  53      xbt_cfg_set_parse(_surf_cfg_set,"Variable:Value");
  54
  55      // Rest of your code
  56 }
  57 \endcode
  58
  59 \section options_model Configuring the platform models
  60
  61 \subsection options_model_select Selecting the platform models
  62
  63 SimGrid comes with several network and CPU models built in, and you
  64 can change the used model at runtime by changing the passed
  65 configuration. The three main configuration variables are given below.
  66 For each of these variable, passing the special \c help value gives
  67 you a short description of all possible values.
  68    - \b network/model: specify the used network model
  69    - \b cpu/model: specify the used CPU model
  70    - \b workstation/model: specify the used workstation model
  71
  72 As of writting, the accepted network models are the following. Over
  73 the time new models can be added, and some experimental models can be
  74 removed; check the values on your simulators for an uptodate
  75 information. Note that the CM02 model is described in the research report
  76 <a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A
  77 Network Model for Simulation of Grid Application</a> while LV08 is
  78 described in
  79 <a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>.
  80
  81   - \b LV08 (default one): Realistic network analytic model
  82     (slow-start modeled by multiplying latency by 10.4, bandwidth by
  83     .92; bottleneck sharing uses a payload of S=8775 for evaluating RTT)
  84   - \b Constant: Simplistic network model where all communication
  85     take a constant time (one second). This model provides the lowest
  86     realism, but is (marginally) faster.
  87   - \b SMPI: Realistic network model specifically tailored for HPC
  88     settings (accurate modeling of slow start with correction factors on
  89     three intervals: < 1KiB, < 64 KiB, >= 64 KiB). See also \ref
  90     options_model_network_coefs "this section" for more info.
  91   - \b CM02: Legacy network analytic model (Very similar to LV08, but
  92     without corrective factors. The timings of small messages are thus
  93     poorly modeled)
  94   - \b Reno: Model from Steven H. Low using lagrange_solve instead of
  95     lmm_solve (experts only; check the code for more info).
  96   - \b Reno2: Model from Steven H. Low using lagrange_solve instead of
  97     lmm_solve (experts only; check the code for more info).
  98   - \b Vegas: Model from Steven H. Low using lagrange_solve instead of
  99     lmm_solve (experts only; check the code for more info).
 100
 101 If you compiled SimGrid accordingly, you can use packet-level network
 102 simulators as network models (see \ref pls). In that case, you have
 103 two extra models:
 104   - \b GTNets: Network pseudo-model using the GTNets simulator instead
 105     of an analytic model
 106   - \b NS3: Network pseudo-model using the NS3 tcp model instead of an
 107     analytic model
 108
 109 Concerning the CPU, we have only one model for now:
 110   - \b Cas01: Simplistic CPU model (time=size/power)
 111
 112 The workstation concept is the aggregation of a CPU with a network
 113 card. Three models exists, but actually, only 2 of them are
 114 interesting. The "compound" one is simply due to the way our internal
 115 code is organized, and can easily be ignored. So at the end, you have
 116 two workstation models: The default one allows to aggregate an
 117 existing CPU model with an existing network model, but does not allow
 118 parallel tasks because these beasts need some collaboration between
 119 the network and CPU model. That is why, ptask_07 is used by default
 120 when using SimDag.
 121   - \b default: Default workstation model. Currently, CPU:Cas01 and
 122     network:LV08 (with cross traffic enabled)
 123   - \b compound: Workstation model that is automatically chosen if
 124     you change the network and CPU models
 125   - \b ptask_L07: Workstation model somehow similar to Cas01+CM02 but
 126     allowing parallel tasks
 127
 128 \subsection options_model_optim Optimization level of the platform models
 129
 130 The network and CPU models that are based on lmm_solve (that
 131 is, all our analytical models) accept specific optimization
 132 configurations.
 133   - variables \b network/optim and \b CPU/optim (both default to 'Lazy'):
 134     - \b Lazy: Lazy action management (partial invalidation in lmm +
 135       heap in action remaining).
 136     - \b TI: Trace integration. Highly optimized mode when using
 137       availability traces (only available for the Cas01 CPU model for
 138       now).
 139     - \b Full: Full update of remaining and variables. Slow but may be
 140       useful when debugging.
 141   - variables \b network/maxmin_selective_update and
 142     \b cpu/maxmin_selective_update: configure whether the underlying
 143     should be lazily updated or not. It should have no impact on the
 144     computed timings, but should speed up the computation.
 145
 146 It is still possible to disable the \c maxmin_selective_update feature
 147 because it can reveal counter-productive in very specific scenarios
 148 where the interaction level is high. In particular, if all your
 149 communication share a given backbone link, you should disable it:
 150 without \c maxmin_selective_update, every communications are updated
 151 at each step through a simple loop over them. With that feature
 152 enabled, every communications will still get updated in this case
 153 (because of the dependency induced by the backbone), but through a
 154 complicated pattern aiming at following the actual dependencies.
 155
 156 \subsection options_model_precision Numerical precision of the platform models
 157
 158 The analytical models handle a lot of floating point values. It is
 159 possible to change the epsilon used to update and compare them through
 160 the \b maxmin/precision variable (default value: 1e-9). Changing it
 161 may speedup the simulation by discarding very small actions, at the
 162 price of a reduced numerical precision.
 163
 164 \subsection options_model_network Configuring the Network model
 165
 166 \subsubsection options_model_network_gamma Maximal TCP window size
 167
 168 The analytical models need to know the maximal TCP window size to take
 169 the TCP congestion mechanism into account. This is set to 20000 by
 170 default, but can be changed using the \b network/TCP_gamma variable.
 171
 172 On linux, this value can be retrieved using the following
 173 commands. Both give a set of values, and you should use the last one,
 174 which is the maximal size.\verbatim
 175 cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window
 176 cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window
 177 \endverbatim
 178
 179 \subsubsection options_model_network_coefs Corrective simulation factors
 180
 181 These factors allow to betterly take the slow start into account.
 182 The corresponding values were computed through data fitting one the
 183 timings of packet-level simulators. You should not change these values
 184 unless you are really certain of what you are doing. See
 185 <a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>
 186 for more informations about these coeficients.
 187
 188 If you are using the SMPI model, these correction coeficients are
 189 themselves corrected by constant values depending on the size of the
 190 exchange. Again, only hardcore experts should bother about this fact.
 191
 192 \subsubsection options_model_network_crosstraffic Simulating cross-traffic
 193
 194 As of SimGrid v3.7, cross-traffic effects can be taken into account in
 195 analytical simulations. It means that ongoing and incoming
 196 communication flows are treated independently. In addition, the LV08
 197 model adds 0.05 of usage on the opposite direction for each new
 198 created flow. This can be useful to simulate some important TCP
 199 phenomena such as ack compression.
 200
 201 For that to work, your platform must have two links for each
 202 pair of interconnected hosts. An example of usable platform is
 203 available in <tt>examples/msg/gtnets/crosstraffic-p.xml</tt>.
 204
 205 This is activated through the \b network/crosstraffic variable, that
 206 can be set to 0 (disable this feature) or 1 (enable it).
 207
 208 \subsection options_model_network_coord Coordinated-based network models
 209
 210 When you want to use network coordinates, as it happens when you use
 211 an \<AS\> in your platform file with \c Vivaldi as a routing, you must
 212 set the \b network/coordinates to \c yes so that all mandatory
 213 initialization are done in the simulator.
 214
 215 \subsection options_model_network_sendergap Simulating sender gap
 216
 217 (this variable is experimental and may change or disapear)
 218
 219 It is possible to specify a timing gap between consecutive emission on
 220 the same network card through the \b network/sender_gap variable. This
 221 is still under investigation as of writting, and the default value is
 222 to wait 0 seconds between emissions (no gap applied).
 223
 224 \section options_modelchecking Model-Checking specific configuration variables
 225
 226 To enable the experimental SimGrid model-checking support the program should
 227 be executed with the command line argument
 228 \verbatim
 229 --cfg=model-check:1
 230 \endverbatim
 231 Properties are expressed as assertions using the function
 232 \verbatim
 233 void MC_assert(int prop);
 234 \endverbatim
 235
 236 \section options_generic Various generic configuration variables
 237
 238 \section options_generic_path XML file inclusion path
 239
 240 It is possible to specify a list of directories to search into for the
 241 \<include\> tag in XML files by using the \b path configuration
 242 variable. To add several directory to the path, set the configuration
 243 variable several times, as in \verbatim
 244 --cfg=path:toto --cfg=path:tutu
 245 \endverbatim
 246
 247 \section options_generic_exit Behavior on Ctrl-C
 248
 249 By default, when Ctrl-C is pressed, the status of all existing
 250 simulated processes is displayed. This is very useful to debug your
 251 code, but it can reveal troublesome in some cases (such as when the
 252 amount of processes becomes really big). This behavior is disabled
 253 when \b verbose-exit is set to 0 (it is to 1 by default).
 254
 255 \section options_index Index of all existing variables
 256
 257 - \c cpu/maxmin_selective_update: \ref options_model_optim
 258 - \c cpu/model: \ref options_model_select
 259 - \c cpu/optim: \ref options_model_optim
 260
 261 - \c maxmin/precision: \ref options_model_precision
 262
 263 - \c network/bandwidth_factor: \ref options_model_network_coefs
 264 - \c network/coordinates: \ref options_model_network_coord
 265 - \c network/crosstraffic: \ref options_model_network_crosstraffic
 266 - \c network/latency_factor: \ref options_model_network_coefs
 267 - \c network/maxmin_selective_update: \ref options_model_optim
 268 - \c network/model: \ref options_model_select
 269 - \c network/optim: \ref options_model_optim
 270 - \c network/sender_gap: \ref options_model_network_sendergap
 271 - \c network/TCP_gamma: \ref options_model_network_gamma
 272 - \c network/weight_S: \ref options_model_network_coefs
 273
 274 - \c path: \ref options_generic_path
 275 - \c verbose-exit: \ref options_generic_exit
 276
 277 - \c workstation/model: \ref options_model_select
 278
 279 */