1 /*! \page faq Frequently Asked Questions
3 \section faq_installation Installing the SimGrid library
5 Many people have been asking me questions on how to use SimGrid. Quite
6 often, the questions were not really about SimGrid but on the
7 installation process. This section is intended to help people that are
8 not familiar with compiling C files under UNIX. If you follow these
9 instructions and still have some troubles, drop an e-mail to
10 <simgrid-user@lists.gforge.inria.fr>.
12 \subsection faq_compiling Compiling SimGrid
14 Suppose you have uncompressed SimGrid in some temporary location of
15 your home directory (say <tt>/home/joe/tmp/simgrid-2.18.2 </tt>). The
16 simplest way to use SimGrid is to install it in your home
17 directory. Change your directory to
18 <tt>/home/joe/tmp/simgrid-2.18.2</tt> and type
20 \verbatim./configure --prefix=$HOME
25 If at some point, something fails, you can report me this problem but,
26 please, avoid sending a laconic mail like "There is a problem. Is it
27 normal ?". Send me the config.log file which is automatically
28 generated by configure. Try to capture both the standard output and
29 the error output of the <tt>make</tt> command. There is no way for me
30 to help you if you do not give me a little bit of information.
32 Now, the following directory should have been created :
34 \li <tt>/home/joe/doc/simgrid/html/</tt>
35 \li <tt>/home/joe/lib/</tt>
36 \li <tt>/home/joe/include/</tt>
38 SimGrid is not a binary, it is a library. Both a static and a dynamic
39 version are available. Here is what you can find if you try a <tt>ls
42 \verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
45 Thus, there is two ways to link your program with SimGrid:
46 \li Either you use the static version, e.g
47 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
49 In this case, all the SimGrid functions are directly
50 included in <tt>MainProgram</tt> (hence a bigger binary).
51 \li Either you use the dynamic version (the preferred method)
52 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
54 In this case, the SimGrid functions are not included in
55 <tt>MainProgram</tt> and you need to set your environment
56 variable in such a way that <tt>libsimgrid.so</tt> will be
57 found at runtime. This can be done by adding the following
58 line in your .bashrc (if you use bash and if you have
59 installed the SimGrid libraries in your home directory):
60 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
63 \subsection faq_setting Setting up your own code
65 Do not build your simulator by modifying the SimGrid examples. Go
66 outside the SimGrid source tree and create your own working directory
67 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
69 Suppose your simulation has the following structure (remember it is
70 just an example to illustrate a possible way to compile everything;
71 feel free to organize it as you want).
73 \li <tt>sched.h</tt>: a description of the core of the
74 scheduler (i.e. which functions are can be used by the
75 agents). For example we could find the following functions
76 (master, forwarder, slave).
78 \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
79 implementing the core of the scheduler. Most of these
80 functions use the MSG functions defined in section \ref
83 \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
84 the MSG initialization (MSG_global_init()), the platform
85 creation (e.g. with MSG_create_environment()), the
86 deployment phase (e.g. with MSG_function_register() and
87 MSG_launch_application()) and the call to
90 To compile such a program, I suggest to use the following Makefile. It
91 is a generic Makefile that I generally use with my students when I
96 masterslave: masterslave.o sched.o
100 PEDANTIC_PARANOID_FREAK = -O0 -Wshadow -Wcast-align \
101 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
102 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
103 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
104 -Wpointer-arith -Wwrite-strings -finline-functions
105 REASONABLY_CAREFUL_DUDE = -Wall
106 NO_PRAYER_FOR_THE_WICKED = -w -O2
107 WARNINGS = $(REASONABLY_CAREFUL_DUDE)
108 CFLAGS = -g $(WARNINGS)
110 INCLUDES = -I$(INSTALL_PATH)/include
111 DEFS = -L$(INSTALL_PATH)/lib/
112 LDADD = -lm -lsimgrid
116 $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
119 $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
122 rm -f $(BIN_FILES) *.o *~
128 The first two lines indicates what should be build when typing make
129 (<tt>masterslave</tt>) and of which files it is to be made of
130 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
131 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
132 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
133 the static version, remove the <tt>-lsimgrid</tt> and add a
134 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
135 after the <tt>LIBS = </tt>.
137 More generally, if you have never written a Makefile by yourself, type
138 in a terminal : <tt>info make</tt> and read the introduction. The
139 previous example should be enough for a first try but you may want to
140 perform some more complex compilations...
142 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start ?
144 You are at the right place... Having a look to these
145 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>
146 may give you some insights on what SimGrid can help you to do and what
147 are its limitations. Then you definitely should read the \ref
148 MSG_examples. There is also a mailing list: <simgrid-user@lists.gforge.inria.fr>.
150 \subsection faq_generic Building a generic simulator
152 Please read carefully the \ref MSG_examples. You'll find in \ref
153 MSG_ex_master_slave a very simple consisting of a master (that owns a bunch of
154 tasks and distributes them) , some slaves (that process tasks whenever
155 they receive one) and some forwarder agents (that simply pass the
156 tasks they receive to some slaves).
158 \subsection faq_examples I want some more complex examples !
160 Many people have come to ask me a more complex example and each time,
161 they have realized afterward that the basics were in the previous three
164 Of course they have often been needing more complex functions like
165 MSG_process_suspend(), MSG_process_resume() and
166 MSG_process_isSuspended() (to perform synchronization), or
167 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
168 receptions), or even MSG_process_create() (to design asynchronous
169 communications or computations). But the examples are sufficient to
172 I know I should add some more examples, but not some more complex
173 ones... I should add some examples that illustrate some other
174 functionalities (like how to simply encode asynchronous
175 communications, RPC, process migrations, thread synchronization, ...)
176 and I will do it when I will have a little bit more time. I have tried
177 to document the examples so that they are understandable. I know it is
178 not really satisfying but it is the best I have managed to do yet.
180 \subsection faq_platform Building a realistic platform
182 I can speak more than an hour on this subject and I still do not have
183 the right answer, just some ideas. You can read the following
184 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
185 It may give you some hints. You can also have a look at the
186 <tt>tools/platform_generation/</tt> directory. There is a perl-script
187 I use to annotate a Tiers generated platform (may not be up-to-date
190 \subsection faq_visualization Visualizing the schedule
192 It is sometime convenient to "see" how the agents are behaving. If you
193 like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
194 as a filter to your MSG outputs. It works directly with INFO. Beware,
195 INFO() prints on stderr. Do not forget to redirect if you want to
196 filter (e.g. with bash):
198 ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
201 We also have a more graphical output. Have a look at MSG_paje_output(). It
202 generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
205 <a href="Paje_MSG_screenshot.jpg"><img src="Paje_MSG_screenshot_thn.jpg"></a>
209 \subsection faq_context_1000 I want thousands of simulated processes
211 SimGrid can use either pthreads library or the UNIX98 contextes. On most
212 systems, the number of pthreads is limited and then your simulation may be
213 limited for a stupid reason. This is especially true with the current linux
214 pthreads, and I cannot get more than 2000 simulated processes with pthreads
215 on my box. The UNIX98 contextes allow me to raise the limit to 25,000
216 simulated processes on my laptop.
218 The <tt>--with-context</tt> option of the <tt>./configure</tt> script allows
219 you to choose between UNIX98 contextes (<tt>--with-context=ucontext</tt>)
220 and the pthread version ( (<tt>--with-context=pthread</tt>). The default
221 value is ucontext when the script detect a working UNIX98 context
222 implementation. On Windows boxes, the provided value is discarded and an
223 adapted version is picked up.
225 We experienced some issues with contextes on some rare systems (solaris 8
226 and lower comes to mind). The main problem is that the configure script
227 detect the contextes as being functional when it's not true. If you happen
228 to use such a system, switch manually to the pthread version, and provide us
229 with a good patch for the configure script so that it is done automatically ;)
231 \subsection faq_context_10000 I want hundred thousands of simulated processes
233 As explained above, SimGrid can use UNIX98 contextes to represent and handle
234 the simulated processes. Thanks to this, the main limitation to the number
235 of simulated processes becomes the available memory.
237 Here are some tricks I had to use in order to run a token ring between
238 25,000 processes on my laptop (1Gb memory, 1.5Gb swap).
240 - First of all, make sure your code runs for a few hundreds processes
241 before trying to push the limit. Make sure it's valgrind-clean, ie that
242 valgrind does not report neither memory error nor memory leaks. Indeed,
243 numerous simulated processes result in *fat* simulation hindering debugging.
245 - It was really boring to write 25,000 entries in the deployment file, so I wrote
246 a little script <tt>examples/gras/tokenS/make_deployment.pl</tt>, which you may
247 want to adapt to your case.
249 - The deployment file became quite big, so I had to do what is in the FAQ
250 entry \ref faq_flexml_limit
252 - Each UNIX98 context has its own stack entry. As debugging this is quite
253 hairly, the default value is a bit overestimated so that user don't get
254 into trouble about this. You want to tune this size to increse the number
255 of processes. This is the <tt>STACK_SIZE</tt> define in
256 <tt>src/xbt/context_private.h</tt>, which is 128kb by default.
257 Reduce this as much as you can, but be warned that if this value is too
258 low, you'll get a segfault. The token ring example, which is quite simple,
259 runs with 40kb stacks.
262 \section faq_SG Where has SG disappeared ?!?
264 OK, it's time to explain what's happening to the SimGrid project. Let's
265 start with a little bit of history.
267 * Historically, SimGrid was a low-level toolkit for scheduling with
268 classical models such as DAGs. That was SimGrid v.1.* aka SG, written by
269 Henri Casanova. I had been using it in its earliest versions during an
272 Then we have realized that encoding distributed algorithm in SG was a
275 * So we have built MSG on top of SG and have released SimGrid v.2.*. MSG
276 offered a very basic API to encode a distributed application easily.
277 However encoding MSG on top of SG was not really convenient and did not
278 use the DAG part since the control of the task synchronization was done
279 on top of MSG and no more in SG. We have been playing a little bit with
280 MSG. We have realized that:
282 \li 1) the platform modeling was quite flexible and could be "almost"
283 automated (e.g. using random generator and post-annotations);
285 \li 2) SG was the bottleneck because of the way we were using
286 it. We needed to simulate concurrent transfers, complex load
287 sharing mechanisms. Many optimizations (e.g. trace integration)
288 were totally inefficient when combined with MSG and made extending SG
289 to implement new sharing policies, parallel tasks models, or failures
290 (many people were asking for these kind of features) a real pain;
292 \li 3) the application modeling was not really easy. Even though the
293 application modeling depends on people's applications, we thought
294 we could improve things here. One of our target here was realistic
295 distributed applications ranging from computer sensor networks like
296 the NWS to peer-to-peer applications;
298 * So we have been planning mainly two things for SimGrid 3:
300 \li 1) I have proposed to get rid of SG and to re-implement a new kernel
301 that would be faster and more flexible. That is what I did in the
302 end of 2004: SURF. SURF is based on a fast max-min linear solver
303 using O(1) data-structures. I have quickly replaced SG by SURF in
304 MSG and the result has been that on the MSG example, the new
305 version was more than 10 times faster while we had gain a lot of
306 flexibility. I think I could still easily make MSG faster but I
307 have to work on MSG now (e.g. using some of the O(1)
308 data-structures I've been using to build SURF) since it has become
309 the bottleneck. Some MSG functions have been removed from the API
310 but they were mainly intended to build the platform by hand (they
311 had appeared in the earliest versions of MSG) and were therefore
312 not useful anymore since we are providing a complete mechanism to
313 automatically build the platform and deploy the agents on it.;
315 \li 2) GRAS is a new project Martin and I have come up with. The idea is
316 to have a programming environment that let you program real
317 distributed applications while letting you the ability to run it in
318 the simulator without having to change the slightest line of your
319 code. From the simulation point of view, GRAS performs the
320 application modeling automatically... Up until now, GRAS works on
321 top MSG for historical reasons but I'm going to make it work
322 directly on top of SURF so that it can use all the flex and the
323 speed provided by SURF.
325 Those two things are working, but we want to make everything as clean as
326 possible before releasing SimGrid v.3.
328 So what about those nice DAGs we used to have in SimGrid v.1. ? They're not
329 anymore in SimGrid v.3. Let me recall you the way SimGrid 3 is organized:
343 XBT is our tool box and now, you should have an idea of what the other ones
344 are. As you can see, the primitive SG is not here anymore. However it could
345 still be brought back if people really need it. Here is how it would fit.
348 ______________________
350 |____________________|
351 | | MSG | GRAS | SG |
352 | -------------------|
354 | -------------------|
356 ----------------------
359 Re-implementing SG on top of SURF is really straightforward (it only
360 requires a little bit of time that I really don't have right now)
361 since the only thing that lacks to SURF is the DAG part. But adding it
362 to SURF would slow it down and therefore slow MSG and GRAS which is
363 not a good thing. However it is really not on the top of our TODO
364 list because we have to work on GRAS, and its MPI counterpart, and a
365 parallel task model, and ... Anyway, we finally have migrated our CVS
366 to gforge so people that are interested by helping on this part will
367 have the possibility to do it.
369 \subsection faq_SG_DAG But I wanted to implement a distributed dynamic scheduler of DAGs... How can I do that it SG is not available anymore in the next versions ?
371 Distributed is somehow "contagious". If you start making distributed
372 decisions, there is no way to handle DAGs directly anymore (unless I am
373 missing something). You have to encode your DAGs in term of communicating
374 process to make the whole scheduling process distributed. Believe me, it is
375 worth the effort since you'll then be able to try your algorithms in a very
376 wide variety of conditions.
378 If you decide that the distributed part is not that much important and that
379 DAG is really the level of abstraction you want to work with (but it
380 prevents you from having "realistic" platform modeling), then you should
381 keep using the 2.18.5 versions until somebody has ported SG on top of SURF.
382 Note however that SURF will be slower than the old SG to handle traces with
383 a lots of variations (there is no trace integration anymore).
386 \subsection faq_SURF_dynami How can I have variable resource availability?
388 A nice feature of SimGrid is that it enables you to seamlessly have
389 resources whose availability change over time. When you build a
390 platform, you generally declare CPUs like that:
393 <cpu name="Cpu A" power="100.00"/>
396 If you want the availability of "CPU A" to change over time, the only
397 thing you have to do is change this definition like that:
400 <cpu name="Cpu A" power="100.00" availability_file="trace_A.txt" state_file="trace_A_failure.txt"/>
403 For CPUs, availability files are expressed in fraction of available
404 power. Let's have a look at what "trace_A.txt" may look like:
413 At time 0, our CPU will deliver 100 Mflop/s. At time 11.0, it will
414 deliver only 50 Mflop/s until time 20.0 where it will will start
415 delivering 90 Mflop/s. Last at time 21.0 (20.0 plus the periodicity
416 1.0), we'll be back to the beginning and it will deliver 100Mflop/s.
418 Now let's look at the state file:
425 A negative value means "off" while a positive one means "on". At time
426 1.0, the CPU is on. At time 1.0, it is turned off and at time 2.0, it
427 is turned on again until time 12 (2.0 plus the periodicity 10.0). It
428 will be turned on again at time 13.0 until time 23.0, and so on.
430 Now, let's look how the same kind of thing can be done for network
431 links. A usual declaration looks like:
434 <network_link name="LinkA" bandwidth="10.0" latency="0.2"/>
437 You have at your disposal the following options: bandwidth_file,
438 latency_file and state_file. The only difference with CPUs is that
439 bandwidth_file and latency_file do not express fraction of available
440 power but are expressed directly in Mb/s and seconds.
442 \section faq_flexml_bypassing How could I have some C functions do what the platform and deployment files do?
444 So you want to bypass the XML files parser, uh? Maybe doin some parameter
445 sweep experiments on your simulations or so? This is possible, but it's not
446 really easy. Here is how it goes.
448 For this, you have to first remember that the XML parsing in SimGrid is done
449 using a tool called FleXML. Given a DTD, this gives a flex-based parser. If
450 you want to bypass the parser, you need to provide some code mimicking what
451 it does and replacing it in its interactions with the SURF code. So, let's
452 have a look at these interactions.
454 FleXML parser are close to classical SAX parsers. It means that a
455 well-formed SimGrid platform XML file might result in the following
458 - start "platform_description"
459 - start "cpu" with attributes name="host1" power="1.0"
461 - start "cpu" with attributes name="host2" power="2.0"
463 - start "network_link" with ...
465 - start "route" with ...
467 - start "route" with ...
469 - end "platform_description"
471 The communication from the parser to the SURF code uses two means:
472 Attributes get copied into some global variables, and a surf-provided
473 function gets called by the parser for each event. For example, the event
474 - start "cpu" with attributes name="host1" power="1.0"
476 let the parser do the equivalent of:
478 strcpy("host1",A_cpu_name);
483 In SURF, we attach callbacks to the different events by initializing the
484 pointer functions to some the right surf functions. Example in
485 workstation_KCCFLN05.c (surf_parse_open() ends up calling surf_parse()):
487 // Building the routes
488 surf_parse_reset_parser();
489 STag_route_fun=parse_route_set_endpoints;
490 ETag_route_element_fun=parse_route_elem;
491 ETag_route_fun=parse_route_set_route;
492 surf_parse_open(file);
493 xbt_assert1((!surf_parse()),"Parse error in %s",file);
497 So, to bypass the FleXML parser, you need to write your own version of the
498 surf_parse function, which should do the following:
499 - Call the corresponding STag_<tag>_fun function to simulate tag start
500 - Fill the A_<tag>_<attribute> variables with the wanted values
501 - Call the corresponding ETag_<tag>_fun function to simulate tag end
502 - (do the same for the next set of values, and loop)
504 Then, tell SimGrid that you want to use your own "parser" instead of the stock one:
506 surf_parse = surf_parse_bypass;
507 MSG_create_environment(NULL);
510 An example of this trick is distributed in the file examples/msg/msg_test_surfxml_bypassed.c
512 \section faq_flexml_limit I get the message "surf_parse_lex: Assertion `next<limit' failed."
514 This is because your platform file is too big for the parser.
516 Actually, the message comes directly from FleXML, the technology on top of
517 which the parser is built. FleXML has the bad idea of fetching the whole
518 document in memory before parsing it. And moreover, the memory buffer size
519 must be determinded at compilation time.
521 We use a value which seems big enough for our need withour bloating the
522 simulators footprints. But of course your mileage may vary. In this case,
523 just edit src/surf/surfxml.l modify the definition of
524 FLEXML_BUFFERSTACKSIZE. E.g.
527 #define FLEXML_BUFFERSTACKSIZE 1000000000
530 Then recompile and everything should be fine, provided that your version of
531 Flex is recent enough (>= 2.5.31). If not the compilation process should
534 A while ago, we worked on FleXML to reduce a bit its memory consumtion, but
535 these issues remain. There is two things we should do:
537 - use a dynamic buffer instead of a static one so that the only limit
538 becomes your memory, not a stupid constant fixed at compilation time
539 (maybe not so difficult).
540 - change the parser so that it does not need to get the whole file in
541 memory before parsing
542 (seems quite difficult, but I'm a complete newbe wrt flex stuff).
544 These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
545 the development of FleXML, I can grant you that any patches would be really
546 welcome and quickly integrated.
548 \section faq_host_load Where is the get_host_load function hidden in MSG?
550 There is no such thing because its semantic wouldn't be really clear. Of
551 course, it is something about the amount of host throughput, but there is as
552 many definition of "host load" as people asking for this function.
554 It may be instantaneous value or an average one. Moreover it may be only the
555 power of the computer, or may take the background load into account, or may
556 even take the currently running tasks into account. In some SURF models,
557 communications have an influence on computational power. Should it be taken
560 So, we decided not to include such a function into MSG and let people do it
561 thereselves so that they get the value matching exactly what they mean. One
562 possibility is to run active measurement as in next code snippet. It is very
563 close from what you would have to do out of the simulator, and thus gives
564 you information that you could also get in real settings to not hinder the
565 realism of your simulation.
568 double get_host_load() {
569 m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
570 double date = MSG_get_clock();
572 MSG_task_execute(task);
573 date = MSG_get_clock() - date;
574 MSG_task_destroy(task);
579 Of course, it may not match your personal definition of "host load". In this
580 case, please detail what you mean on the mailing list, and we will extend
581 this FAQ section to fit your taste if possible.
584 \author Arnaud Legrand (arnaud.legran::imag.fr)
585 \author Martin Quinson (martin.quinson::loria.fr)