allow to set a profile to links and hosts from S4U

[simgrid.git] / docs / source / platform_howtos.rst

diff --git a/docs/source/platform_howtos.rst b/docs/source/platform_howtos.rst
index 0c122ce..5c68aca 100644 (file)
--- a/docs/source/platform_howtos.rst
+++ b/docs/source/platform_howtos.rst
@@ -12,6 +12,8 @@
    <br/>
    <br/>
 
+.. _howto:
+   
 Modeling Hints
 ##############
 
@@ -23,6 +25,8 @@ This page collects several hints and tricks on modeling situations.
 Even if you are looking for a very advanced, specific use case, these
 examples may help you to design the solution you need.
 
+.. _howto_science:
+
 Doing Science with SimGrid
 **************************
 
@@ -31,7 +35,7 @@ research. This tool was indeed invented to that extend, and we strive
 to streamline this kind of usage. But SimGrid is no magical tool, and
 it is of your responsability that the tool actually provides sensible
 results. Fortunately, there is a vast literature on how to avoid
-Modeling & Simulations pitfalls. We review here two particular works.
+Modeling & Simulations pitfalls. We review here some specific works.
 
 In `An Integrated Approach to Evaluating Simulation Credibility
 <http://www.dtic.mil/dtic/tr/fulltext/u2/a405051.pdf>`_, the authors
@@ -40,8 +44,10 @@ in the simulation tools they use. First of all, you must know what you
 actually expect to discover whether the tool actually covers your
 needs. Then, as they say, "a fool with a tool is still a fool", so you
 need to think about your methodology before you submit your articles.
-You really should read this article, that contains many other
-interesting advices.
+`Towards a Credibility Assessment of Models and Simulations
+<https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/20080015742.pdf>`_
+gives a formal methodology to assess the credibility of your
+simulation results.
 
 `Seven Pitfalls in Modeling and Simulation Research
 <https://dl.acm.org/citation.cfm?id=2430188>`_ is even more
@@ -54,8 +60,8 @@ freely available, though.
 
 .. _howto_churn:
 
-Modeling Churn in P2P
-*********************
+Modeling Churn (e.g. in P2P)
+****************************
 
 One of the biggest challenges in P2P settings is to cope with the
 churn, meaning that resources keep appearing and disappearing. In
@@ -64,12 +70,10 @@ eg :cpp:func:`simgrid::s4u::Host::turn_on`. To reduce the burden when
 the churn is high, you can also attach a **state profile** to the host
 directly.
 
-This is not possible from S4U yet (TODO), and you should use the
-``state_file`` attribute of :ref:`pf_tag_host`, :ref:`pf_tag_cluster`
-or :ref:`pf_tag_link`.
-
-Every lines (but the last) of such files describe timed events with
-the form "date value". Example:
+This can be done through the XML file, using the ``state_file``
+attribute of :ref:`pf_tag_host`, :ref:`pf_tag_cluster` or
+:ref:`pf_tag_link`. Every lines (but the last) of such files describe
+timed events with the form "date value". Example:
 
 .. code-block:: python
                
@@ -85,6 +89,12 @@ the form "date value". Example:
 If your trace does not contain a LOOPAFTER line, then your profile is
 only executed once and not repetitively.
 
+Another possibility is to use the
+:cpp:func:`simgrid::s4u::Host::set_state_profile()` or 
+:cpp:func:`simgrid::s4u::Link::set_state_profile()` functions. These
+functions take a profile, that can be an fixed profile exhaustively
+listing the events, or something else if you wish.
+
 .. _howto_multicore:
 
 Modeling Multicore Machines