From 832290b6ad79b7a2dcbf29137578e840e000b3ad Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sun, 30 Jun 2019 13:18:11 +0200 Subject: [PATCH] Various doc improvement, mostly on rendering --- docs/source/Introduction.rst | 9 +- docs/source/Platform_Examples.rst | 62 ++++ ...atform_reference.rst => XML_Reference.rst} | 6 +- docs/source/img/graphical-toc.svg | 264 ++++++++++-------- docs/source/index.rst | 3 +- tools/cmake/DefinePackages.cmake | 3 +- 6 files changed, 224 insertions(+), 123 deletions(-) create mode 100644 docs/source/Platform_Examples.rst rename docs/source/{platform_reference.rst => XML_Reference.rst} (99%) diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index db93878e8d..8196c6a1d2 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -3,13 +3,18 @@ Main Concepts ============= -Typical Study based on SimGrid ------------------------------- .. raw:: html +
+
+ +Introduction +============ +Typical Study based on SimGrid +------------------------------ Any SimGrid study entails the following components: diff --git a/docs/source/Platform_Examples.rst b/docs/source/Platform_Examples.rst new file mode 100644 index 0000000000..37cff2471d --- /dev/null +++ b/docs/source/Platform_Examples.rst @@ -0,0 +1,62 @@ +.. raw:: html + + + +
+
+ +.. _platform_examples: + +Platform Examples +================= + +Here is a very simple platform file, containing 3 resources (two hosts +and one link), and explicitly giving the route between the hosts. + +.. literalinclude:: ../../examples/platforms/two_hosts.xml + :language: xml + +The root tag must be ````, and its ``version`` attribute +specifies the used DTD version. When the DTD evolutions introduce +backward-incompatible changes, this number gets updated. Use the +``simgrid_update_xml`` utility to upgrade your platform files on need. + + +Then, every platform element must be located within a given +**networking zone** introduced with the :ref:`pf_tag_zone` tag. Zones +are in charge of the routing: an host wants to communicate with +another host of the same zone, it is the zone's duty to find the list +of links that are involved in the communication. Here, since we use +``routing="Full"``, all routes must be explicitly given using the +:ref:`pf_tag_route` and :ref:`pf_tag_linkctn` tags (this :ref:`routing +model ` is both simple and inefficient :) It is OK to not +specify each and every route between hosts, as long as you don't start +at runtime any communications on the missing routes. + +Any zone may contain sub-zones itself, leading to a hierarchical +decomposition of the platform. This can be more efficient (as the +inter-zone routing gets factorized with :ref:`pf_tag_zoneroute`), and +allows to have more than one routing model in your platform. For +example, you could have a coordinate-based routing for the WAN parts +of your platforms, a full routing within each datacenter, and a highly +optimized routing within each cluster of the datacenter. In this +case, determining the route between two given hosts gets @ref +routing_basics "somewhat more complex" but SimGrid still computes +these routes for you in a time- and space-efficient manner. +Here is an illustration of these concepts: + +.. image:: img/zone_hierarchy.png + +The zone "AS2" models the core of a national network interconnecting a +small flat cluster (AS4) and a larger hierarchical cluster (AS5), a +subset of a LAN (AS6), and a set of peers scattered around the world +(AS7). + +.. todo:: Add more examples, such as the cloud example descibed in + previous paragraph + diff --git a/docs/source/platform_reference.rst b/docs/source/XML_Reference.rst similarity index 99% rename from docs/source/platform_reference.rst rename to docs/source/XML_Reference.rst index 8fd08925ad..87a71812be 100644 --- a/docs/source/platform_reference.rst +++ b/docs/source/XML_Reference.rst @@ -3,7 +3,7 @@ @@ -12,8 +12,8 @@ .. _platform_reference: -DTD Reference -************* +Complete XML Reference +********************** Your platform description should follow the specification presented in the `simgrid.dtd `_ DTD file. The same DTD is used for both platform and deployment files. diff --git a/docs/source/img/graphical-toc.svg b/docs/source/img/graphical-toc.svg index 2ea55419d0..eead0aac53 100644 --- a/docs/source/img/graphical-toc.svg +++ b/docs/source/img/graphical-toc.svg @@ -25,8 +25,8 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="2.8" - inkscape:cx="221.05408" - inkscape:cy="26.288995" + inkscape:cx="205.77445" + inkscape:cy="161.83279" inkscape:document-units="mm" inkscape:current-layer="layer1" showgrid="true" @@ -2326,49 +2326,28 @@ style="display:inline;opacity:0.93999999;fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.67500001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> Simulated Platform - - - Dynamic profiles + inkscape:label="PlatformText2" + id="text1028-1-4-3-0" + y="77.800346" + x="89.268448" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:5.64444447px;line-height:6.61458349px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve">available resources @@ -2387,20 +2366,48 @@ xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111126px;line-height:7.14375019px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" x="88.616463" - y="116.2941" + y="115.23576" id="text818" inkscape:label="XPSetupText">ExperimentalSetup + + + Profiles + (what you test) Application @@ -6101,43 +6108,6 @@ y="90.272514" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.17499995px;line-height:2.91041636px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';stroke-width:0.26458332px" id="tspan2707-0-8" /> - - - Resources - CPU, Links, Disks - Calibration + x="96.944122" + y="126.07596" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;line-height:4.4979167px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:center;text-anchor:middle;stroke-width:0.26458332px">AutomaticCalibration Config Manual @@ -6363,39 +6339,39 @@ inkscape:label="RoutingBox" ry="1.3229153" y="80.53125" - x="95.250008" + x="95.25" height="10.58333" - width="21.16667" + width="22.48958" id="RoutingBox" - style="display:inline;opacity:0.93999999;fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.35277775;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + style="display:inline;opacity:0.93999999;fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.35277772;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> Routing paths @@ -6461,7 +6437,7 @@ @@ -6514,5 +6490,61 @@ id="tspan851" sodipodi:role="line">+ + + + Examples + + + + Reference + diff --git a/docs/source/index.rst b/docs/source/index.rst index 8cecc8de8f..dc00ace130 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -74,8 +74,9 @@ of every page. Bugs in the code should be reported    The SMPI Interface    The MSG Interface Describing the Simulated Platform +    Examples    Modeling Hints -    DTD Reference +    XML Reference Describing the Experimental Scenario    Configuring SimGrid The SimGrid Models diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index bce03f548a..1941bb05f9 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -896,7 +896,8 @@ set(DOC_SOURCES docs/source/outcomes.rst docs/source/platform.rst docs/source/platform_howtos.rst - docs/source/platform_reference.rst + docs/source/Platform_Examples.rst + docs/source/XML_Reference.rst docs/source/Tutorial_Algorithms.rst docs/source/tuto_s4u/deployment1.xml -- 2.20.1