X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/4055c3365c0644e74d06aa1dc70b2188166da41b..10b586757ab8526c1e1e25317898b21a0c430e02:/doc/modules.doc diff --git a/doc/modules.doc b/doc/modules.doc index 9f2a486776..c8e5eb5a0c 100644 --- a/doc/modules.doc +++ b/doc/modules.doc @@ -8,24 +8,6 @@ */ -/** \defgroup SURF_API SURF - \ingroup SimGrid_API - \brief Kernel of all the simulators used in SimGrid, and associated models. - - SURF provides the core functionnalities to simulate a virtual - platform. It is very low-level and is not intended to be used as - such but rather to serve as a basis for higher-level simulators. - We're still working on it and the structure is a little bit - complex. - - It is where platform models are encoded. If you need a model that is not - encoded yet, please tell me () and we'll - see if it is feasible or not (hopefully it should be but who knows). - - Please note that as it is not really intended for public use, - this module is only partially documented. -*/ - /** \defgroup MSG_API MSG \ingroup SimGrid_API \brief Simple programming environment @@ -48,6 +30,15 @@ */ +/** \defgroup SIMIX_API SIMIX + \ingroup SimGrid_API + \brief POSIX-like interface for building simulation + + This is a developer-level interface that should be useful only if you + plan to design a new interface for SimGrid. +*/ + + /** \defgroup GRAS_API GRAS \ingroup SimGrid_API \brief Realistic programming environment (Grid Reality And Simulation) @@ -97,25 +88,103 @@ \ingroup SimGrid_API \brief Programming environment for the simulation of MPI applications - Once implemented, this programming environment will allow you to study - within the simulator any MPI application without having to modify them - for that. In other words, it will constitute an emulation solution for - parallel codes. +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 this (and who shouldn't) +\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 work on a distributed application, have a look at the - \ref GRAS_API environment. - If you want to study some heuristics for a given problem (and if your - goal is to produce theorems, 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). +You should use this programming environment of the SimGrid suite if +you want to study existing MPI applications. If you want to create a +distributed application, you may be interested in the \ref GRAS_API +environment instead (but note that GRAS is not very actively +maintained nowadays). 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 + + +*/ /** \defgroup SD_API SimDag @@ -144,3 +213,43 @@ probably want to contact us before). */ + +/** +@defgroup SURF_API SURF +@ingroup SimGrid_API +@brief Internal kernel of all the simulators used in SimGrid, and associated models. + +SURF provides the core functionnalities to simulate a virtual +platform. It is very low-level and is not intended to be used by end +users, but rather to serve as a basis for higher-level simulators. Its +interface are not frozen (and will probably never be), and the +structure emphasis on performance over ease of use. This module +contains the platform models. If you need a model that is not encoded +yet, please come to the devel mailing list so that we can discuss on +the feasibility of your idea. + +Please note that as it is not really intended for public use, this +module is only partially documented. +*/ + + +/** +@defgroup TRACE_API TRACE +@ingroup SimGrid_API +@brief Tracing mechanism and its functions. + +SimGrid can trace the resource (of hosts and links) utilization using +any of its programming interfaces (MSG, SimDAG and SMPI). This means +that the tracing will register how much power is used for each host +and how much bandwidth is used for each link of the platform. + +The idea of the tracing facilities is to give SimGrid users to +possibility to classify MSG and SimDAG tasks by category, tracing the +platform utilization (hosts and links) for each of the categories. +The API enables the declaration of categories and a function to +associate them to the tasks (MSG and SD). The tasks that are not +classified according to a category are not traced. If no categories +are specified, simulations can still be traced using a special +parameter in the command line (see \ref tracing_tracing for details). +*/ +