From: Martin Quinson Date: Mon, 17 Sep 2018 07:54:46 +0000 (+0200) Subject: Merge branch 'master' of scm.gforge.inria.fr:/gitroot/simgrid/simgrid X-Git-Tag: v3_21~97 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/9bfc714f74d8044a224b5c94ad3f69e540361841?hp=40c872b697c0fa3062d90942c12febd4f80b1876 Merge branch 'master' of scm.gforge.inria.fr:/gitroot/simgrid/simgrid --- diff --git a/docs/source/_ext/hidden_code_block.py b/docs/source/_ext/hidden_code_block.py new file mode 100644 index 0000000000..a009d43226 --- /dev/null +++ b/docs/source/_ext/hidden_code_block.py @@ -0,0 +1,128 @@ +"""Simple, inelegant Sphinx extension which adds a directive for a +highlighted code-block that may be toggled hidden and shown in HTML. +This is possibly useful for teaching courses. + +The directive, like the standard code-block directive, takes +a language argument and an optional linenos parameter. The +hidden-code-block adds starthidden and label as optional +parameters. + +Examples: + +.. hidden-code-block:: python + :starthidden: False + + a = 10 + b = a + 5 + +.. hidden-code-block:: python + :label: --- SHOW/HIDE --- + + x = 10 + y = x + 5 + +Thanks to http://www.javascriptkit.com/javatutors/dom3.shtml for +inspiration on the javascript. + +Thanks to Milad 'animal' Fatenejad for suggesting this extension +in the first place. + +Written by Anthony 'el Scopz' Scopatz, January 2012. +https://github.com/scopatz/hiddencode + +Released under the WTFPL (http://sam.zoy.org/wtfpl/). +""" + +from docutils import nodes +from docutils.parsers.rst import directives +from sphinx.directives.code import CodeBlock + +HCB_COUNTER = 0 + +js_showhide = """\ + +""" + +def nice_bool(arg): + tvalues = ('true', 't', 'yes', 'y') + fvalues = ('false', 'f', 'no', 'n') + arg = directives.choice(arg, tvalues + fvalues) + return arg in tvalues + + +class hidden_code_block(nodes.General, nodes.FixedTextElement): + pass + + +class HiddenCodeBlock(CodeBlock): + """Hidden code block is Hidden""" + + option_spec = dict(starthidden=nice_bool, + label=str, + **CodeBlock.option_spec) + + def run(self): + # Body of the method is more or less copied from CodeBlock + code = u'\n'.join(self.content) + hcb = hidden_code_block(code, code) + hcb['language'] = self.arguments[0] + hcb['linenos'] = 'linenos' in self.options + hcb['starthidden'] = self.options.get('starthidden', True) + hcb['label'] = self.options.get('label', '+ show/hide code') + hcb.line = self.lineno + return [hcb] + + +def visit_hcb_html(self, node): + """Visit hidden code block""" + global HCB_COUNTER + HCB_COUNTER += 1 + + # We want to use the original highlighter so that we don't + # have to reimplement it. However it raises a SkipNode + # error at the end of the function call. Thus we intercept + # it and raise it again later. + try: + self.visit_literal_block(node) + except nodes.SkipNode: + pass + + # The last element of the body should be the literal code + # block that was just made. + code_block = self.body[-1] + + fill_header = {'divname': 'hiddencodeblock{0}'.format(HCB_COUNTER), + 'startdisplay': 'none' if node['starthidden'] else 'block', + 'label': node.get('label'), + } + + divheader = ("""""" + """{label}
""" + '''
''' + ).format(**fill_header) + + code_block = js_showhide + divheader + code_block + "
" + + # reassign and exit + self.body[-1] = code_block + raise nodes.SkipNode + + +def depart_hcb_html(self, node): + """Depart hidden code block""" + # Stub because of SkipNode in visit + + +def setup(app): + app.add_directive('hidden-code-block', HiddenCodeBlock) + app.add_node(hidden_code_block, html=(visit_hcb_html, depart_hcb_html)) diff --git a/docs/source/conf.py b/docs/source/conf.py index d335a48c0e..9f3d260b78 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,8 +13,10 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os, subprocess -# import sys -# sys.path.insert(0, os.path.abspath('.')) + +# Search for our extensions too +import sys +sys.path.append(os.path.abspath('_ext')) # -- Project information ----------------------------------------------------- @@ -44,6 +46,7 @@ extensions = [ # 'sphinx.ext.ifconfig', 'breathe', 'exhale', + 'hidden_code_block', ] todo_include_todos = True diff --git a/docs/source/index.rst b/docs/source/index.rst index 13d7d83e2c..1cd37b77f2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,7 +8,7 @@ Welcome to SimGrid's documentation! :caption: Tutorials: Simulating Algorithms - Simulating MPI Apps + Simulating MPI Applications .. toctree:: :maxdepth: 2 diff --git a/docs/source/tuto_s4u.rst b/docs/source/tuto_s4u.rst index 70818edab9..8acbbb2cc8 100644 --- a/docs/source/tuto_s4u.rst +++ b/docs/source/tuto_s4u.rst @@ -19,7 +19,7 @@ completion of these activities. Each actor executes a user-provided function on a simulated |Host|_ with which it can interact. Communications are not directly sent to actors, but posted onto a |Mailbox|_ that serve as rendez-vous point -between communicating processes. +between communicating actors. .. |Actors| replace:: **Actors** .. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html @@ -492,7 +492,7 @@ Creating the workers from the master For that, the master needs to retrieve the list of hosts declared in the platform with :cpp:func:`simgrid::s4u::Engine::get_all_hosts`. -Then, the master should start the worker processes with +Then, the master should start the worker actors with :cpp:func:`simgrid::s4u::Actor::create`. ``Actor::create(name, host, func, params...)`` is a very flexible diff --git a/docs/source/tuto_s4u/draw_gantt.R b/docs/source/tuto_s4u/draw_gantt.R index 68b18ff1e9..5fd230b83e 100644 --- a/docs/source/tuto_s4u/draw_gantt.R +++ b/docs/source/tuto_s4u/draw_gantt.R @@ -1,23 +1,18 @@ #!/usr/bin/env Rscript args = commandArgs(trailingOnly=TRUE) library(ggplot2) + +# Load and relabel the data df = read.csv(args[1], header=F, strip.white=T) names(df) = c("Type", "Actor", "Container", "Start", "End", "Duration", "Level", "State"); -ggplot(df) - geom_segment(aes(x=Start, xend=End, - y=Actor, yend=Actor,color=State), size=5) - scale_fill_brewer(palette="Set1") - theme_bw() - theme ( - plot.margin = unit(c(0,0,0,0), "cm"), - legend.spacing = unit(1, "mm"), - panel.grid = element_blank(), - legend.position = "top", - legend.justification = "left", - legend.box.spacing = unit(0, "pt"), - legend.box.margin = margin(0,0,0,0)) -> p; +# Actually draw the graph +p = ggplot(df) + geom_segment(aes(x=Start, xend=End, y=Actor, yend=Actor,color=State), size=5); + +# Cosmetics to compact the resulting graph p.height <- length(unique(df$Actor)) * 0.05 + 2; pdf(height = p.height) + +# Produce the pdf file plot(p) dev.off() diff --git a/docs/source/tuto_s4u/img/Rscript-screenshot.png b/docs/source/tuto_s4u/img/Rscript-screenshot.png index 22b8c3b50b..c3859f4e68 100644 Binary files a/docs/source/tuto_s4u/img/Rscript-screenshot.png and b/docs/source/tuto_s4u/img/Rscript-screenshot.png differ diff --git a/docs/source/tuto_s4u/img/vite-screenshot.png b/docs/source/tuto_s4u/img/vite-screenshot.png index 133bece4d0..b4051b99a2 100644 Binary files a/docs/source/tuto_s4u/img/vite-screenshot.png and b/docs/source/tuto_s4u/img/vite-screenshot.png differ diff --git a/docs/source/tuto_smpi.rst b/docs/source/tuto_smpi.rst new file mode 100644 index 0000000000..4599f92040 --- /dev/null +++ b/docs/source/tuto_smpi.rst @@ -0,0 +1,114 @@ +.. _usecase_smpi: + +Simulating MPI Applications +=========================== + +Discover SMPI +------------- + +SimGrid can not only :ref:`simulate algorithms `, but +it can also be used to execute real MPI applications on top of +virtual, simulated platforms with the SMPI module. Even complex +C/C++/F77/F90 applications should run out of the box in this +environment. In fact, almost all proxy apps provided by the `ExaScale +Project `_ only require minor +modifications to `run on top of SMPI +`_. + +This setting permits to debug your MPI applications in a perfectly +reproducible setup, with no Heisenbugs. Enjoy the full Clairevoyance +provided by the simulator while running what-if analysis on platforms +that are still to be built! Several `production-grade MPI applications +`_ +use SimGrid for their integration and performance testing. + +MPI 2.2 is already partially covered: over 160 primitives are +supported. Some parts of the standard are still missing: MPI-IO, MPI3 +collectives, spawning ranks, and some others. If one of the functions +you use is still missing, please drop us an email. We may find the +time to implement it for you. + +Multi-threading support is very limited in SMPI. Only funneled +applications are supported: at most one thread per rank can issue any +MPI calls. For better timing predictions, your application should even +be completely mono-threaded. Using OpenMP (or pthreads directly) may +greatly decrease SimGrid predictive power. That may still be OK if you +only plan to debug your application in a reproducible setup, without +any performance-related analysis. + +How does it work? +^^^^^^^^^^^^^^^^^ + +In SMPI, communications are simulated while computations are +emulated. This means that while computations occur as they would in +the real systems, communication calls are intercepted and achived by +the simulator. + +To start using SMPI, you just need to compile your application with +``smpicc`` instead of ``mpicc``, or with ``smpiff`` instead of +``mpiff``, or with ``smpicxx`` instead of ``mpicxx``. Then, the only +difference between the classical ``mpirun`` and the new ``smpirun`` is +that it requires a new parameter ``-platform`` with a file describing +the virtual platform on which your application shall run. + +Internally, all ranks of your application are executed as threads of a +single unix process. That's not a problem if your application has +global variables, because ``smpirun`` loads one application instance +per MPI rank as if it was another dynamic library. Then, MPI +communication calls are implemented using SimGrid: data is exchanged +through memory copy, while the simulator's performance models are used +to predict the time taken by each communications. Any computations +occuring between two MPI calls are benchmarked, and the corresponding +time is reported into the simulator. + +.. image:: /tuto_smpi/img/big-picture.png + :align: center + + +Describing Your Platform +------------------------ + +As a SMPI user, you are supposed to provide a description of your +virtual platform, that is mostly a set of simulated hosts and network +links with some performance characteristics. SimGrid provides a plenty +of :ref:`documentation `_ and examples (in the +`examples/platforms `_ +source directory), and this section only shows a small set of introductory +examples. + +Simple Example with 3 hosts +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +At the most basic level, you can describe your simulated platform as a +graph of hosts and network links. For instance: + +.. image:: /tuto_smpi/img/3hosts.png + :align: center + +.. hidden-code-block:: xml + :starthidden: True + :label: See the XML platform description file... + + + + + + + + + + + + + + + + + +In this XML, note the way in which hosts, links, and routes are +defined. All hosts are defined with a power (i.e., compute speed in +Gflops), and links with a latency (in us) and bandwidth (in MBytes per +second). Other units are possible and written as expected. By default, +routes are symmetrical. + +.. LocalWords: SimGrid diff --git a/docs/source/tuto_smpi/3hosts.xml b/docs/source/tuto_smpi/3hosts.xml new file mode 100644 index 0000000000..dc058953bb --- /dev/null +++ b/docs/source/tuto_smpi/3hosts.xml @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/docs/source/tuto_smpi/img/3hosts.png b/docs/source/tuto_smpi/img/3hosts.png new file mode 100644 index 0000000000..fa21d52e3a Binary files /dev/null and b/docs/source/tuto_smpi/img/3hosts.png differ diff --git a/docs/source/tuto_smpi/img/big-picture.png b/docs/source/tuto_smpi/img/big-picture.png new file mode 100644 index 0000000000..d51189a128 Binary files /dev/null and b/docs/source/tuto_smpi/img/big-picture.png differ diff --git a/docs/source/tuto_smpi/img/big-picture.svg b/docs/source/tuto_smpi/img/big-picture.svg new file mode 100644 index 0000000000..6ee76a9515 --- /dev/null +++ b/docs/source/tuto_smpi/img/big-picture.svg @@ -0,0 +1,774 @@ + + + +image/svg+xml + +host 2 +host 3 +host 0 +host 1 +Network +rank 2 +rank 3 +rank 0 +rank 1 +single UNIX process +Simulated Network +rank 0 +rank 1 +rank 2 +rank 3 +Real Settings +SimGrid Simulation + \ No newline at end of file