From 1555391de700f5bafbbcf3bde5fbe425ff7469ef Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Thu, 19 May 2016 09:14:45 +0200 Subject: [PATCH 1/1] completely rewrite the 'Getting Started' page --- doc/doxygen/getting_started.doc | 241 +++++++++++++++++++++++--------- 1 file changed, 175 insertions(+), 66 deletions(-) diff --git a/doc/doxygen/getting_started.doc b/doc/doxygen/getting_started.doc index ea3b48997d..134e446f68 100644 --- a/doc/doxygen/getting_started.doc +++ b/doc/doxygen/getting_started.doc @@ -1,69 +1,178 @@ -/*! @page getting_started Getting started with SimGrid +/*! @page getting_started Getting Started: SimGrid Main Concepts @tableofcontents -Welcome to the SimGrid's documentation! %As you may know, SimGrid is an actively -developed research software and has a lot of different features. This documentation is a -@c "work in progress" (and we need the help of the user community to improve it! -If you're ready to step up and help us, see Section @ref -contributing "Contributing"), but many features are already well described. - -%As for many projects, our documentation mostly consists in separate sections -for @ref gs_new_users "new" and @ref gs_experienced_users "experienced" users. -We also have several specific pages and a technical documentation. Finally, we provide users -with many @ref gs_examples "examples" that can easily be adapted to your -own needs. This page gives you a brief overview of the available resources. - -@section gs_introduction Introduction, Installation, and how to get help - -| Document name | Description | -| --------------- | ------------------------------------------------- | -| @ref install | Explains how SimGrid can be installed on Linux, Windows, and MacOS. This installation can be done from a package or from source. | -| @ref tutorial | Introduces the user to basic features of SimGrid. | -| @ref FAQ | Our FAQ | -| @ref contact | Explains how to ask your questions to the community. | - -@section gs_new_users Documentation for new users - -| Document name | Description | -| ----------------- | ------------------------------------------------- | -| @ref install | Explains how SimGrid can be installed on Linux, Windows, and MacOS. This installation can be done from a package or from source. | -| @ref tutorial | Introduces the user to basic features of SimGrid. | -| [Online Tutorials](http://simgrid.gforge.inria.fr/tutorials.html) | These tutorials cover most of the basics and might be valuable for what you want to do, especially the [SimGrid User 101](http://simgrid.gforge.inria.fr/tutorials/simgrid-use-101.pdf). | -| @ref MSG_examples | This page details several examples that we wrote for the MSG API. They are working simulations and you may learn something by looking at them. | -| @ref bindings | You can write your simulator in Java, if you prefer. | - -In order to actually use SimGrid, three steps are necessary: - -@li Step 1: @ref platform -@li Step 2: @ref options -@li Step 3: @ref deployment - -@section gs_experienced_users Documentation for experienced users - -| Document name | Description | -| ----------------- | ------------------------------------------------- | -| @ref tracing | Shows how the behavior of a program can be written to a file so that it can be analyzed. | -| @ref pls | You can use the NS3 simulation models instead of our own. | -| @ref inside | If you want to contribute or obtain a deeper understanding of SimGrid, this is the right location. | - -@section gs_examples Examples shipped with SimGrid - -SimGrid ships with many examples. Those using the MSG API are detailed in Section @ref -MSG_examples. You can find them in the folder @c examples/. Especially -when you're looking for examples on how to use a specific XML-tag, -this will prove valuable, as you can easily search through all the -files with tools like @c grep. - - -Here is the output of a quick search for examples for @ref pf_trace "trace_connect": - -@verbatim -% grep -R -i -n --include="*.xml" "trace_connect" . -./platforms/two_hosts.xml:17: -./platforms/two_hosts_platform_with_availability_included.xml:26: -./platforms/two_hosts_platform_with_availability_included.xml:27: -./platforms/two_hosts_platform_with_availability_included.xml:28: -@endverbatim - -*/ +SimGrid is a simulator of distributed computer systems. It can be used +to either assess abstract algorithms, or to profile and debug real +distributed applications. SimGrid enables studies in the domains of +(data-)Grids, Clusters, IaaS Clouds, High Performance Computing, +Volunteer Computing and Peer-to-Peer. + +SimGrid is a feature rich framework, with many options and +possibilities. Hopefully its documentation will help you getting at +full gear. But nothing's perfect, and this documentation is really no +exception here. Please help us improving it by reporting the issues +that you see. + +SimGrid is a Free Software distributed under the LGPL licence. It +means that you are welcome to use it as you wish, or even to modify +and distribute your version (as long as your version is as free as +ours). It also means that SimGrid is developed by a vivid community of +users and developers. We hope that you will join the community! + +SimGrid beneficied of many fundings from various research instances, +including: the ANR, Inria, CNRS, University of Lorraine, University of +Hawai'i at Manoa, ENS Rennes and many others. Thanks to our generous +donators! SimGrid would not exist without the research that they funded. + +@section starting_components Typical Study based on SimGrid + +Any SimGrid study entails the following components: + + - The studied **Application**. This can be either a distributed + algorithm described in our simple APIs, or a full featured real + parallel application using the MPI interface (or other). + + - The **Virtual Platform**. This is a description of a given + distributed system (machines, links, disks, clusters, etc). Most of + the platform files are written in XML althrough a Lua interface is + under development. SimGrid makes it easy to augment the Virtual + Platform with a Dynamic Scenario where for example the links are + slowed down (because of external usage), the machines fail. You + have even support to specify the applicative workload that you want + to feed to your application. + + - The application's **Deployment Description**. In SimGrid terminology, + the application is an inert set of source files and binaries. To + make it run, you have to describe how your application should be + deployed on the virtual platform. Specify which process is located + on which host, along with its parameters. + + - The **Platform Models**. They describe how the virtual platform + reacts to the actions of the application. For example, they compute + the time taken by a given communication on the virtual platform. + These models are already included in SimGrid, and you only need to + pick one and maybe tweak its configuration to get your results. + +These components are put together to run a **simulation**, that is an +experiment or a probe. The result of one or many simulation provides +an **outcome** (logs, visualization, statistical analysis) that help +answering the **question** targeted by this study. + +The questions that SimGrid can solve include the following: + + - **Compare an Application to another**. This is the classical use + case for scientists, who use SimGrid to test how the solution that + they contribute compares to the existing solutions from the + literature. + + - **Design the best Virtual Platform for a given Application.** + Tweaking the platform file is much easier than building a new real + platform for testing purpose. SimGrid also allows co-design of the + platform and the application by modifying both of them. + + - **Debug Real Applications**. With real platforms, is sometimes + difficult to reproduce the exact run leading to the bug that you + are tracking. SimGrid gives you experimental reproducibility, + clairevoyance (you can explore every part of the system in no + [simulated] time without modifying it). It makes it very easy to + mock some parts of the real system that are not under study. + +@section starting_gears SimGrid Execution Gears + +Depending on the intended study, SimGrid can be run in several gears, +that are different execution modes. + +** **Simulation Gear**. This is the most common gear, where you want +to study how your application behaves on the virtual platform under +the experimental scenario. + +In this gear, SimGrid can provide information about the time taken by +your application, the amount of energy dissipated by the platform to +run your application and the detailed usage of each resource. + +** **Model-Checking Gear**. This can be seen as a sort of exhaustive +testing gear, where every possible outcome of your application is +explored. In some sense, this gear tests your application for all +possible platforms that you could imagine (and more). + +You just provide the application and its deployment (amount of +processes and parameters), and the model-checker will literally +explore all possible outcomes by testing all possible message +interleaving: if at some point a given process can either receive the +message A first or the message B depending on the platform +characteristics, the model-checker will explore the scenario where A +arrives first, and then rewind to the same point to explore the +scenarion where B arrives first. + +This is a very powerful gear, where you can evaluate the correction of +your application. It can verify either *safety properties* (asserts) +or *liveless properties* stating for example that if a given event +occures, then another given event will occur in a finite amount of +steps. This gear is not only usable with the abstract algorithms +developed on top of the SimGrid APIs, but also with real MPI +applications (to some extend). + +The main limit of Model Checking lays in the huge amount of scenarios +to explore. SimGrid tries to explore only non-redundent scenarios +thanks to classical reduction techniques (such as DPOR and statefull +exploration) but the exploration may well never finish if you don't +carefully adapt your application to this gear. + +Another limit of this gear is that it does not use the performance +models of the simulation gear. Time becomes discrete: You can say for +example that the application took 42 steps to run, but there is no way +to know the amount of seconds that it took or the amount of watts that +it dissipated. + +** **Benchmark Recording Gear**. During debug sessions, continuous +integration testing and other similar use cases, you are often only +interested in the control flow. If your application apply filters to +huge images split in small blocks, the filtered image is probably not +what you are interested in. You are probably looking for a way to run +each computation kernel only once, save on disk the time it takes and +some other metadata. This code block can then be skipped in simulation +and replaced by a synthetic block using the cached information. The +virtual platform will take this block into account without requesting +the real hosting machine to benchmark it. + +@section starting_successes SimGrid Success Stories + +TBD + +@section starting_limits SimGrid Limits + +This framework is by no means the perfect holly grail able to solve +every problem on earth. + +** **SimGrid scope is limited to distributed systems.** Real-time +multithreaded systems are not in the scope. You could probably tweak +SimGrid for such studies (or the framework could possibily be extended +in this direction), but another framework specifically targeting this +usecase would probably be more suited. + +** **There is no perfect model, only models adapted to your study.** +The SimGrid models target fast, large studies yet requesting a +realistic results. In particular, our models abstract away parameters +and phenomenon that are often irrelevant to the realism in our +context. + +SimGrid is simply not intended to any study that would mandate the +abstracted phenomenon. Here are some **studies that you should not do +with SimGrid**: + + - Studying the effect of L3 vs L2 cache effects on your application + - Comparing variantes of TCP + - Exploring pathological cases where TCP breaks down, resulting in + abnormal executions. + - Studying security aspects of your application, in presence of + malicious agents. + +@section starting_next Where to proceed next? + +Now that you know about the basic concepts of SimGrid, you can give it +a try. If it's not done yet, first @ref install "install it". Then, +proceed to the section on @ref app "describing the application" that +you want to study. + +*/ \ No newline at end of file -- 2.20.1