From d356b692a6a8031a987fbff621e90b372c805e89 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 25 Mar 2013 20:52:35 +0100 Subject: [PATCH] split SMPI documentation into a specific file (no real change) --- buildtools/Cmake/DefinePackages.cmake | 1 + doc/Doxyfile.in | 1 + doc/doxygen/module-smpi.doc | 96 +++++++++++++++++++++++++++ doc/doxygen/modules.doc | 95 -------------------------- 4 files changed, 98 insertions(+), 95 deletions(-) create mode 100644 doc/doxygen/module-smpi.doc diff --git a/buildtools/Cmake/DefinePackages.cmake b/buildtools/Cmake/DefinePackages.cmake index 0cf83fa8eb..32908034a3 100644 --- a/buildtools/Cmake/DefinePackages.cmake +++ b/buildtools/Cmake/DefinePackages.cmake @@ -657,6 +657,7 @@ set(DOC_SOURCES doc/doxygen/module-sd.doc doc/doxygen/module-simix.doc doc/doxygen/module-surf.doc + doc/doxygen/module-smpi.doc doc/doxygen/module-trace.doc doc/doxygen/module-xbt.doc doc/doxygen/modules.doc diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index b399a5c60d..4b9d2125e2 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -685,6 +685,7 @@ INPUT = doxygen/index.doc \ doxygen/module-sd.doc \ doxygen/module-surf.doc \ doxygen/module-simix.doc \ + doxygen/module-smpi.doc \ doxygen/module-trace.doc \ index-API.doc \ @top_srcdir@/doc/doxygen/logcategories.doc \ diff --git a/doc/doxygen/module-smpi.doc b/doc/doxygen/module-smpi.doc new file mode 100644 index 0000000000..71e68a0b6d --- /dev/null +++ b/doc/doxygen/module-smpi.doc @@ -0,0 +1,96 @@ +/** @addtogroup SMPI_API + +This programming environment permits to study existing MPI application +by emulating them on top of the SimGrid simulator. In other words, it +will constitute an emulation solution for parallel codes. You don't +even have to modify your code for that, although that may help, as +detailed below. + +\section SMPI_who Who should use SMPI (and who shouldn't) + +You should use this programming environment of the SimGrid suite if +you want to study existing MPI applications. If you want to study +some heuristics for a given problem (and if your goal is to produce +theorems and publications, not code), have a look at the \ref MSG_API +environment, or the \ref SD_API one if you need to use DAGs. If none +of those programming environments fits your needs, you may consider +implementing your own directly on top of \ref SURF_API (but you +probably want to contact us before). + +\section SMPI_what What can run within SMPI? + +You can run unmodified MPI applications (both C and Fortran) within +SMPI, provided you only use MPI calls that we implemented in MPI. Our +coverage of the interface is not bad, but will probably never be +complete. One sided communications and I/O primitives are not targeted +for now. The full list of not yet implemented functions is available +in file include/smpi/smpi.h of the archive, between two lines +containing the FIXME marker. If you really need a missing +feature, please get in touch with us: we can guide you though the +SimGrid code to help you implementing it, and we'd glad to integrate +it in the main project afterward if you contribute them back. + +\section SMPI_adapting Adapting your MPI code to the use of SMPI + +As detailed in the reference article (available at +http://hal.inria.fr/inria-00527150), you may want to adapt your code +to improve the simulation performance. But these tricks may seriously +hinder the result qualtity (or even prevent the app to run) if used +wrongly. We assume that if you want to simulate an HPC application, +you know what you are doing. Don't prove us wrong! + +If you get short on memory (the whole app is executed on a single node +when simulated), you should have a look at the SMPI_SHARED_MALLOC and +SMPI_SHARED_FREE macros. It allows to share memory areas between +processes. For example, matrix multiplication code may want to store +the blocks on the same area. Of course, the resulting computations +will useless, but you can still study the application behavior this +way. Of course, if your code is data-dependent, this won't work. + +If your application is too slow, try using SMPI_SAMPLE_LOCAL, +SMPI_SAMPLE_GLOBAL and friends to indicate which computation loops can +be sampled. Some of the loop iterations will be executed to measure +their duration, and this duration will be used for the subsequent +iterations. These samples are done per processor with +SMPI_SAMPLE_LOCAL, and shared between all processors with +SMPI_SAMPLE_GLOBAL. Of course, none of this will work if the execution +time of your loop iteration are not stable. + +Yes, that's right, these macros are not documented yet, but we'll fix +it as soon as time permits. Sorry about that -- patch welcomed! +Meanwhile, grep for them on the examples for more information. + +\section SMPI_compiling Compiling your code + +This is very simply done with the smpicc script. If you +already compiled any MPI code before, you already know how to use it. +If not, you should try to get your MPI code running on top of MPI +before giving SMPI a spin. Actually, that's very simple even if it's +the first time you use MPI code: just use smpicc as a compiler (in +replacement of gcc or your usual compiler), and you're set. + +\section SMPI_executing Executing your code on top of the simulator + +This is done though the smpirun script as follows. +my_hostfile.txt is a classical MPI hostfile (that is, this +file lists the machines on which the processes must be dispatched, one +per line) my_platform.xml is a classical SimGrid platform +file. Of course, the hosts of the hostfile must exist in the provided +platform. ./program is the MPI program that you want to +simulate (must be compiled by smpicc) while -arg is +a command-line parameter passed to this program. + +\verbatim +smpirun -hostfile my_hostfile.txt -platform my_platform.xml ./program -arg +\endverbatim + +smpirun accepts other parameters, such as -np if you don't +want to use all the hosts defined in the hostfile, -map to +display on which host each rank gets mapped of -trace to +activate the tracing during the simulation. You can get the full list +by running +\verbatim +smpirun -help +\endverbatim + +*/ \ No newline at end of file diff --git a/doc/doxygen/modules.doc b/doc/doxygen/modules.doc index d21c24c94a..ce56ce343b 100644 --- a/doc/doxygen/modules.doc +++ b/doc/doxygen/modules.doc @@ -52,101 +52,6 @@ parameter in the command line (see \ref tracing for details). /** \defgroup SMPI_API SMPI \brief Programming environment for the simulation of MPI applications - -This programming environment permits to study existing MPI application -by emulating them on top of the SimGrid simulator. In other words, it -will constitute an emulation solution for parallel codes. You don't -even have to modify your code for that, although that may help, as -detailed below. - -\section SMPI_who Who should use SMPI (and who shouldn't) - -You should use this programming environment of the SimGrid suite if -you want to study existing MPI applications. If you want to study -some heuristics for a given problem (and if your goal is to produce -theorems and publications, not code), have a look at the \ref MSG_API -environment, or the \ref SD_API one if you need to use DAGs. If none -of those programming environments fits your needs, you may consider -implementing your own directly on top of \ref SURF_API (but you -probably want to contact us before). - -\section SMPI_what What can run within SMPI? - -You can run unmodified MPI applications (both C and Fortran) within -SMPI, provided you only use MPI calls that we implemented in MPI. Our -coverage of the interface is not bad, but will probably never be -complete. One sided communications and I/O primitives are not targeted -for now. The full list of not yet implemented functions is available -in file include/smpi/smpi.h of the archive, between two lines -containing the FIXME marker. If you really need a missing -feature, please get in touch with us: we can guide you though the -SimGrid code to help you implementing it, and we'd glad to integrate -it in the main project afterward if you contribute them back. - -\section SMPI_adapting Adapting your MPI code to the use of SMPI - -As detailed in the reference article (available at -http://hal.inria.fr/inria-00527150), you may want to adapt your code -to improve the simulation performance. But these tricks may seriously -hinder the result qualtity (or even prevent the app to run) if used -wrongly. We assume that if you want to simulate an HPC application, -you know what you are doing. Don't prove us wrong! - -If you get short on memory (the whole app is executed on a single node -when simulated), you should have a look at the SMPI_SHARED_MALLOC and -SMPI_SHARED_FREE macros. It allows to share memory areas between -processes. For example, matrix multiplication code may want to store -the blocks on the same area. Of course, the resulting computations -will useless, but you can still study the application behavior this -way. Of course, if your code is data-dependent, this won't work. - -If your application is too slow, try using SMPI_SAMPLE_LOCAL, -SMPI_SAMPLE_GLOBAL and friends to indicate which computation loops can -be sampled. Some of the loop iterations will be executed to measure -their duration, and this duration will be used for the subsequent -iterations. These samples are done per processor with -SMPI_SAMPLE_LOCAL, and shared between all processors with -SMPI_SAMPLE_GLOBAL. Of course, none of this will work if the execution -time of your loop iteration are not stable. - -Yes, that's right, these macros are not documented yet, but we'll fix -it as soon as time permits. Sorry about that -- patch welcomed! -Meanwhile, grep for them on the examples for more information. - -\section SMPI_compiling Compiling your code - -This is very simply done with the smpicc script. If you -already compiled any MPI code before, you already know how to use it. -If not, you should try to get your MPI code running on top of MPI -before giving SMPI a spin. Actually, that's very simple even if it's -the first time you use MPI code: just use smpicc as a compiler (in -replacement of gcc or your usual compiler), and you're set. - -\section SMPI_executing Executing your code on top of the simulator - -This is done though the smpirun script as follows. -my_hostfile.txt is a classical MPI hostfile (that is, this -file lists the machines on which the processes must be dispatched, one -per line) my_platform.xml is a classical SimGrid platform -file. Of course, the hosts of the hostfile must exist in the provided -platform. ./program is the MPI program that you want to -simulate (must be compiled by smpicc) while -arg is -a command-line parameter passed to this program. - -\verbatim -smpirun -hostfile my_hostfile.txt -platform my_platform.xml ./program -arg -\endverbatim - -smpirun accepts other parameters, such as -np if you don't -want to use all the hosts defined in the hostfile, -map to -display on which host each rank gets mapped of -trace to -activate the tracing during the simulation. You can get the full list -by running -\verbatim -smpirun -help -\endverbatim - - */ -- 2.20.1