docs: Rewrite the intro of platform description

diff --git a/docs/source/platform.rst b/docs/source/platform.rst
index 7617889..6e81d4d 100644 (file)
--- a/docs/source/platform.rst
+++ b/docs/source/platform.rst
@@ -15,31 +15,39 @@
 Describing your Simulated Platform
 ##################################
 
 Describing your Simulated Platform
 ##################################
 

-The goal of SimGrid is to run an application on a simulated platform.
-For that, you have to describe **each element of your platform**, such
-as computing hosts, clusters, each disks, links, etc. You must also
-define the **routing on your platform**, ie which path is taken
-between two hosts. Finally, you may also describe an **experimental
-scenario**, with qualitative changes (e.g., bandwidth changes
-representing an external load) and qualitative changes (representing
-how some elements fail and restart over time).
-
-You should really separate your application from the platform
-description, as it will ease your experimental campain afterward.
-Mixing them is seen as a really bad experimental practice. The easiest
-to enforce this split is to put the platform description in a XML
-file. Many example platforms are provided in the archive, and this
-page gives all needed details to write such files, as well as some
-hints and tricks about describing your platform.
-
-On the other side, XML is sometimes not expressive enough, in
-particular for large platforms exhibiting repetitive patterns that are
-not simply expressed in XML.  In practice, many users end up
-generating their XML platform files from some sort of scripts. It is
-probably preferable to rewrite your XML :ref:`platform using the lua
-scripting language <platform_lua>` instead.  In the future, it should
-be possible to describe the platform in python or directly in C++, but
-this is not possible yet.
-
+In SimGrid, platforms are usually described in XML. This formalism has
+some drawbacks, but using a specific format ensures that the platform
+is not mixed with the tested application. This separation of concern
+:ref:`is a must <howto_science>` for your Modeling and Simulation (M&S)
+work. When XML is too limiting, you may describe your platforms using
+the :ref:`lua bindings <platform_lua>` (it is not yet possible to do so in
+python or directly in C++).
+
+Since we know that writing platform description files is not trivial,
+we included :ref:`many examples <platform_examples>` in the archive. This
+documentation also contains some :ref:`hints and howtos <howto>`, as well
+as the full :ref:`XML reference guide <platform_reference>`.
+
+
+Any simulated platform must contain **basic elements**, such as hosts,
+links, storages, etc.  SimGrid gives you a great liberty when defining
+**routing of your platform**, ie the path taken between each pair of
+hosts.  Finally, you may also describe an **experimental scenario**,
+with qualitative changes (e.g., bandwidth changes representing an
+external load) and qualitative changes (representing how some elements
+fail and restart over time).
+
+Defining Basic Elements
+***********************
+
+There is not much to say about the definition of basic elements. Just
+use the appropriate tags: :ref:`pf_tag_host`, :ref:`pf_tag_link` and
+:ref:`pf_tag_storage`.
+
+Defining a Routing
+******************
+
+Performance Profiles and Churn
+******************************

 
 ..  LocalWords:  SimGrid
 
 ..  LocalWords:  SimGrid

diff --git a/docs/source/platform_examples.rst b/docs/source/platform_examples.rst
index 259c7c3..93996b2 100644 (file)
--- a/docs/source/platform_examples.rst
+++ b/docs/source/platform_examples.rst
@@ -10,6 +10,8 @@
    <br/>
    <br/>
 
    <br/>
    <br/>
 

+.. _platform_examples:
+   

 Platform Examples
 =================
 
 Platform Examples
 =================
 

diff --git a/docs/source/platform_howtos.rst b/docs/source/platform_howtos.rst
index 0c122ce..e96ffd0 100644 (file)
--- a/docs/source/platform_howtos.rst
+++ b/docs/source/platform_howtos.rst
@@ -12,6 +12,8 @@
    <br/>
    <br/>
 
    <br/>
    <br/>
 

+.. _howto:
+   

 Modeling Hints
 ##############
 
 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.
 
 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
 **************************
 
 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
 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
 
 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.
 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
 
 `Seven Pitfalls in Modeling and Simulation Research
 <https://dl.acm.org/citation.cfm?id=2430188>`_ is even more

diff --git a/docs/source/platform_reference.rst b/docs/source/platform_reference.rst
index 77f81e7..d78a23a 100644 (file)
--- a/docs/source/platform_reference.rst
+++ b/docs/source/platform_reference.rst
@@ -10,6 +10,8 @@
    <br/>
    <br/>
 
    <br/>
    <br/>
 

+.. _platform_reference:
+   

 DTD Reference
 *************
 
 DTD Reference
 *************
 


@@ -280,7 +282,13 @@ the plugins.
 
 From your code, you can interact with these properties using the
 following functions:
 
 From your code, you can interact with these properties using the
 following functions:

+
+- Actor: :cpp:func:`simgrid::s4u::Actor::get_property` or :cpp:func:`MSG_process_get_property_value`
+- Cluster: this is a zone, see below.

 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`
 - Host: :cpp:func:`simgrid::s4u::Host::get_property` or :cpp:func:`MSG_host_get_property_value`

+- Link: :cpp:func:`simgrid::s4u::Link::get_property`
+- Storage: :cpp:func:`simgrid::s4u::Storage::get_property` or :cpp:func:`MSG_storage_get_property_value`
+- Zone: :cpp:func:`simgrid::s4u::Zone::get_property` of :cpp:func:`MSG_zone_get_property_value`

 
 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
 :ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|
 
 **Parent tags:** :ref:`pf_tag_actor`, :ref:`pf_tag_config`, :ref:`pf_tag_cluster`, :ref:`pf_tag_host`,
 :ref:`pf_tag_link`, :ref:`pf_tag_storage`, :ref:`pf_tag_zone` |br|