Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
completely rewrite the 'Getting Started' page
authorMartin Quinson <martin.quinson@loria.fr>
Thu, 19 May 2016 07:14:45 +0000 (09:14 +0200)
committerMartin Quinson <martin.quinson@loria.fr>
Thu, 19 May 2016 07:22:20 +0000 (09:22 +0200)
doc/doxygen/getting_started.doc

index ea3b489..134e446 100644 (file)
-/*! @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:  <trace_connect trace="Tremblay_power" element="Tremblay" kind="SPEED"/>
-./platforms/two_hosts_platform_with_availability_included.xml:26:<trace_connect kind="SPEED" trace="A" element="Cpu A"/>
-./platforms/two_hosts_platform_with_availability_included.xml:27:<trace_connect kind="HOST_AVAIL" trace="A_failure" element="Cpu A"/>
-./platforms/two_hosts_platform_with_availability_included.xml:28:<trace_connect kind="SPEED" trace="B" element="Cpu B"/>
-@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