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)
  90   - \b CM02: Legacy network analytic model (Very similar to LV08, but
  91     without corrective factors. The timings of small messages are thus
  92     poorly modeled)
  93   - \b Reno: Model from Steven H. Low using lagrange_solve instead of
  94     lmm_solve (experts only; check the code for more info).
  95   - \b Reno2: Model from Steven H. Low using lagrange_solve instead of
  96     lmm_solve (experts only; check the code for more info).
  97   - \b Vegas: Model from Steven H. Low using lagrange_solve instead of
  98     lmm_solve (experts only; check the code for more info).
  99
 100 If you compiled SimGrid accordingly, you can use packet-level network
 101 simulators as network models (see \ref pls). In that case, you have
 102 two extra models:
 103   - \b GTNets: Network pseudo-model using the GTNets simulator instead
 104     of an analytic model
 105   - \b NS3: Network pseudo-model using the NS3 tcp model instead of an
 106     analytic model
 107
 108 Concerning the CPU, we have only one model for now:
 109   - \b Cas01: Simplistic CPU model (time=size/power)
 110
 111 The workstation concept is the aggregation of a CPU with a network
 112 card. Three models exists, but actually, only 2 of them are
 113 interesting. The "compound" one is simply due to the way our internal
 114 code is organized, and can easily be ignored. So at the end, you have
 115 two workstation models: The default one allows to aggregate an
 116 existing CPU model with an existing network model, but does not allow
 117 parallel tasks because these beasts need some collaboration between
 118 the network and CPU model. That is why, ptask_07 is used by default
 119 when using SimDag.
 120   - \b default: Default workstation model. Currently, CPU:Cas01 and
 121     network:LV08 (with cross traffic enabled)
 122   - \b compound: Workstation model that is automatically chosen if
 123     you change the network and CPU models
 124   - \b ptask_L07: Workstation model somehow similar to Cas01+CM02 but
 125     allowing parallel tasks
 126
 127 Finally, the network and CPU models that are based on lmm_solve (that
 128 is, all our analytical models) accept specific optimization
 129 configurations (through the \b network/optim and \b CPU/optim
 130 variables). The accepted values are (both default to 'Lazy'):
 131   - \b Lazy: Lazy action management (partial invalidation in lmm +
 132     heap in action remaining).
 133   - \b TI: Trace integration. Highly optimized mode when using
 134     availability traces (only available for the Cas01 CPU model for
 135     now).
 136   - \b Full: Full update of remaining and variables. Slow but may be
 137     useful when debugging.
 138
 139
 140 \subsection options_model_network Configuring the Network model
 141
 142 \subsubsection options_model_network_gamma Maximal TCP window size (network/TCP_gamma)
 143
 144 The analytical models need to know the maximal TCP window size to take
 145 the TCP congestion mechanism into account. This is set to 20000 by
 146 default, but can be changed using the network/TCP_gamma variable.
 147
 148 On linux, this value can be retrieved using the following
 149 commands. Both give a set of values, and you should use the last one,
 150 which is the maximal size.\verbatim
 151 cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window
 152 cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window
 153 \endverbatim
 154
 155 \subsubsection options_model_network_crosstraffic Simulating cross-traffic (network/crosstraffic)
 156
 157 As of SimGrid v3.7, cross-traffic effects can be taken into account in
 158 analytical simulations. It means that ongoing and incoming
 159 communication flows are treated independently. In addition, the LV08
 160 model adds 0.05 of usage on the opposite direction for each new
 161 created flow. This can be useful to simulate some important TCP
 162 phenomena such as ack compression.
 163
 164 For that to work, your platform must have two links for each
 165 pair of interconnected hosts. An example of usable platform is
 166 available in <tt>examples/msg/gtnets/crosstraffic-p.xml</tt>.
 167
 168 This is activated through the \b network/crosstraffic variable, that
 169 can be set to 0 (disable this feature) or 1 (enable it).
 170
 171 \section options_modelchecking Model-Checking
 172 \subsection options_modelchecking_howto How to use it
 173 To enable the experimental SimGrid model-checking support the program should
 174 be executed with the command line argument
 175 \verbatim
 176 --cfg=model-check:1
 177 \endverbatim
 178 Properties are expressed as assertions using the function
 179 \verbatim
 180 void MC_assert(int prop);
 181 \endverbatim
 182
 183 */