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
<br/>
<br/>
+.. _howto:
+
Modeling Hints
##############
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
**************************
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
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
<br/>
<br/>
+.. _platform_reference:
+
DTD Reference
*************
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`
+- 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|