Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
77abc9bbd17fead11fbe88e1d62e619b79dfbce0
[simgrid.git] / doc / doxygen / module-smpi.doc
1 /** @addtogroup SMPI_API
2
3 This programming environment enables the study of MPI application by
4 emulating them on top of the SimGrid simulator. This is particularly
5 interesting to study existing MPI applications within the comfort of
6 the simulator. The motivation for this work is detailed in the
7 reference article (available at http://hal.inria.fr/inria-00527150).
8
9 Our goal is to enable the study of *unmodified* MPI applications,
10 although we are not quite there yet (see @ref SMPI_what). In
11 addition, you can modify your code to speed up your studies or
12 otherwise increase their scalability (see @ref SMPI_adapting).
13
14 \section SMPI_who Who should use SMPI (and who shouldn't)
15
16 SMPI is now considered as stable and you can use it in production. You
17 may probably want to read the scientific publications that detail the
18 models used and their limits, but this should not be absolutely
19 necessary.
20
21 If you already fluently write and use MPI applications, SMPI should
22 sound very familiar to you. Use smpicc instead of mpicc, and smpirun
23 instead of mpirun. Some more information are given below on this page.
24
25 Of course, if you don't know what MPI is, the documentation of SMPI
26 will seem a bit terse to you. You should pick up a good MPI tutorial
27 on the Internet (or a course in your university) and come back to SMPI
28 once you know a bit more about MPI. Alternatively, you may want to
29 turn to the other SimGrid interface such as the \ref MSG_API
30 environment, or the \ref SD_API one.
31
32 \section SMPI_what What can run within SMPI?
33
34 You can run unmodified MPI applications (both C and Fortran) within
35 SMPI, provided that (1) you only use MPI calls that we implemented in
36 MPI and (2) you don't use any globals in your application.
37
38 \subsection SMPI_what_coverage MPI coverage of SMPI
39
40 Our coverage of the interface is very decent, but still incomplete;
41 Given the size of the MPI standard, it may well be that we never
42 implement absolutely all existing primitives. One sided communications
43 and I/O primitives are not targeted for now. Our current state is
44 still very decent:¬†we pass most of the MPICH coverage tests.
45
46 The full list of not yet implemented functions is documented in the
47 file <tt>include/smpi/smpi.h</tt> of the archive, between two lines
48 containing the <tt>FIXME</tt> marker. If you really need a missing
49 feature, please get in touch with us: we can guide you though the
50 SimGrid code to help you implementing it, and we'd glad to integrate
51 it in the main project afterward if you contribute them back.
52
53 \subsection SMPI_what_globals Issues with the globals
54
55 Concerning the globals, the problem comes from the fact that usually,
56 MPI processes run as real UNIX processes while they are all folded
57 into threads of a unique system process in SMPI. Global variables are
58 usually private to each MPI process while they become shared between
59 the processes in SMPI. This point is rather problematic, and currently
60 forces to modify your application to privatize the global variables.
61
62 We tried several techniques to work this around. We used to have a
63 script that privatized automatically the globals through static
64 analysis of the source code, but it was not robust enough to be used
65 in production. This issue, as well as several potential solutions, is
66 discussed in this article: "Automatic Handling of Global Variables for
67 Multi-threaded MPI Programs",
68 available at http://charm.cs.illinois.edu/newPapers/11-23/paper.pdf
69 (note that this article does not deal with SMPI but with a concurrent
70 solution called AMPI that suffers of the same issue). 
71
72 Currently, we have no solution to offer you, because all proposed solutions will
73 modify the performance of your application (in the computational
74 sections). Sacrificing realism for usability is not very satisfying, so we did
75 not implement them yet. You will thus have to modify your application if it uses
76 global variables. We are working on another solution, leveraging distributed
77 simulation to keep each MPI process within a separate system process, but this
78 is far from being ready at the moment.
79
80 \section SMPI_compiling Compiling your code
81
82 This is very simply done with the <tt>smpicc</tt> script. If you
83 already compiled any MPI code before, you already know how to use it.
84 If not, you should try to get your MPI code running on top of MPI
85 before giving SMPI a spin. Actually, that's very simple even if it's
86 the first time you use MPI code: just use smpicc as a compiler (in
87 replacement of gcc or your usual compiler), and you're set.
88
89 \section SMPI_executing Executing your code on top of the simulator
90
91 This is done though the <tt>smpirun</tt> script as follows.
92 <tt>my_hostfile.txt</tt> is a classical MPI hostfile (that is, this
93 file lists the machines on which the processes must be dispatched, one
94 per line)  <tt>my_platform.xml</tt> is a classical SimGrid platform
95 file. Of course, the hosts of the hostfile must exist in the provided
96 platform. <tt>./program</tt> is the MPI program that you want to
97 simulate (must be compiled by <tt>smpicc</tt>) while <tt>-arg</tt> is
98 a command-line parameter passed to this program.
99
100 \verbatim
101 smpirun -hostfile my_hostfile.txt -platform my_platform.xml ./program -arg
102 \endverbatim
103
104 smpirun accepts other parameters, such as <tt>-np</tt> if you don't
105 want to use all the hosts defined in the hostfile, <tt>-map</tt> to
106 display on which host each rank gets mapped of <tt>-trace</tt> to
107 activate the tracing during the simulation. You can get the full list
108 by running
109 \verbatim
110 smpirun -help
111 \endverbatim
112
113 \section SMPI_adapting Adapting your MPI code to the use of SMPI
114
115 As detailed in the reference article (available at
116 http://hal.inria.fr/inria-00527150), you may want to adapt your code
117 to improve the simulation performance. But these tricks may seriously
118 hinder the result quality (or even prevent the app to run) if used
119 wrongly. We assume that if you want to simulate an HPC application,
120 you know what you are doing. Don't prove us wrong!
121
122 \section SMPI_adapting_size Reducing your memory footprint
123
124 If you get short on memory (the whole app is executed on a single node when
125 simulated), you should have a look at the SMPI_SHARED_MALLOC and
126 SMPI_SHARED_FREE macros. It allows to share memory areas between processes: The
127 purpose of these macro is that the same line malloc on each process will point
128 to the exact same memory area. So if you have a malloc of 2M and you have 16
129 processes, this macro will change your memory consumption from 2M*16 to 2M
130 only. Only one block for all processes.
131
132 If your program is ok with a block containing garbage value because all
133 processes write and read to the same place without any kind of coordination,
134 then this macro can dramatically shrink your memory consumption. For example,
135 that will be very beneficial to a matrix multiplication code, as all blocks will
136 be stored on the same area. Of course, the resulting computations will useless,
137 but you can still study the application behavior this way. 
138
139 Naturally, this won't work if your code is data-dependent. For example, a Jacobi
140 iterative computation depends on the result computed by the code to detect
141 convergence conditions, so turning them into garbage by sharing the same memory
142 area between processes does not seem very wise. You cannot use the
143 SMPI_SHARED_MALLOC macro in this case, sorry.
144
145 This feature is demoed by the example file
146 <tt>examples/smpi/NAS/DT-folding/dt.c</tt>
147
148 \section SMPI_adapting_speed Toward faster simulations
149
150 If your application is too slow, try using SMPI_SAMPLE_LOCAL,
151 SMPI_SAMPLE_GLOBAL and friends to indicate which computation loops can
152 be sampled. Some of the loop iterations will be executed to measure
153 their duration, and this duration will be used for the subsequent
154 iterations. These samples are done per processor with
155 SMPI_SAMPLE_LOCAL, and shared between all processors with
156 SMPI_SAMPLE_GLOBAL. Of course, none of this will work if the execution
157 time of your loop iteration are not stable.
158
159 This feature is demoed by the example file 
160 <tt>examples/smpi/NAS/EP-sampling/ep.c</tt>
161
162
163 */