From d70fbb094c3a4cb6f19caf5177f6aea73e32a9e0 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 7 Oct 2019 20:52:37 +0200 Subject: [PATCH] cosmetics in the doc of the Host energy plugin --- docs/source/Plugins.rst | 12 ++--- src/plugins/host_energy.cpp | 102 ++++++++++++++++++++---------------- 2 files changed, 63 insertions(+), 51 deletions(-) diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst index 01c836bc1a..51e29438c9 100644 --- a/docs/source/Plugins.rst +++ b/docs/source/Plugins.rst @@ -1,5 +1,8 @@ .. _plugins: +SimGrid Plugins +############### + .. raw:: html @@ -12,16 +15,13 @@

-SimGrid Plugins -############### - You can extend SimGrid without modifying it, thanks to our plugin mechanism. This page describes how to write your own plugin, and documents some of the plugins distributed with SimGrid. -- :ref:`Host Energy `: models the energy dissipation of the compute units. -- :ref:`Link Energy `: models the energy dissipation of the network. -- :ref:`Host Load `: monitors the load of the compute units. + - :ref:`Host Energy `: models the energy dissipation of the compute units. + - :ref:`Link Energy `: models the energy dissipation of the network. + - :ref:`Host Load `: monitors the load of the compute units. Defining a Plugin ***************** diff --git a/src/plugins/host_energy.cpp b/src/plugins/host_energy.cpp index 5b3cfca1f0..5867398a0e 100644 --- a/src/plugins/host_energy.cpp +++ b/src/plugins/host_energy.cpp @@ -18,79 +18,91 @@ SIMGRID_REGISTER_PLUGIN(host_energy, "Cpu energy consumption.", &sg_host_energy_ /** @defgroup plugin_host_energy + @rst This is the energy plugin, enabling to account not only for computation time, but also for the dissipated energy in the simulated platform. -To activate this plugin, first call sg_host_energy_plugin_init() before your #MSG_init(), and then use -MSG_host_get_consumed_energy() to retrieve the consumption of a given host. +To activate this plugin, first call :cpp:func:`sg_host_energy_plugin_init()` before your :cpp:func:`MSG_init()`, and then use +:cpp:func:`MSG_host_get_consumed_energy()` to retrieve the consumption of a given host. When the host is on, this energy consumption naturally depends on both the current CPU load and the host energy profile. According to our measurements, the consumption is somehow linear in the amount of cores at full speed, with an -abnormality when all the cores are idle. The full details are in -our scientific paper on that topic. +abnormality when all the cores are idle. The full details are in `our scientific paper `_ +on that topic. As a result, our energy model takes 4 parameters: - - @b Idle: wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to -do. - - @b Epsilon: wattage when all cores are at 0 or epsilon%, but not in Idle state. - - @b AllCores: wattage when all cores of the host are at 100%. - - @b Off: wattage when the host is turned off. + - ``Idle`` wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to do. + - ``Epsilon`` wattage when all cores are at 0 or epsilon%, but not in Idle state. + - ``AllCores`` wattage when all cores of the host are at 100%. + - ``Off`` wattage when the host is turned off. Here is an example of XML declaration: -@code{.xml} - - - - -@endcode +.. code-block:: xml -If the 'Epsilon' parameter is omitted in the XML declaration, 'Idle' is used instead. + + + + -This example gives the following parameters: @b Off is 10 Watts; @b Idle is 100 Watts; @b Epsilon is 120 Watts and @b -AllCores is 200 Watts. +If only two values are given, ``Idle`` is used for the missing ``Epsilon`` value. + +This example gives the following parameters: ``Off`` is 10 Watts; ``Idle`` is 100 Watts; ``Epsilon`` is 120 Watts and +``AllCores`` is 200 Watts. This is enough to compute the wattage as a function of the amount of loaded cores: - - - - - - - - -
@#Cores loadedWattageExplanation
0 (idle) 100 WattsIdle value
0 (not idle) 120 WattsEpsilon value
1 140 Wattslinear extrapolation between Epsilon and AllCores
2 160 Wattslinear extrapolation between Epsilon and AllCores
3 180 Wattslinear extrapolation between Epsilon and AllCores
4 200 WattsAllCores value
+.. raw:: html + + + + + + + + + +
#Cores loadedWattageExplanation
0 (idle) 100 Watts  Idle value
0 (not idle) 120 Watts Epsilon value
1 140 Watts Linear extrapolation between Epsilon and AllCores
2 160 Watts Linear extrapolation between Epsilon and AllCores
3 180 Watts Linear extrapolation between Epsilon and AllCores
4 200 Watts AllCores value
+ +.. raw:: html -### How does DVFS interact with the host energy model? +

How does DVFS interact with the host energy model?

If your host has several DVFS levels (several pstates), then you should give the energetic profile of each pstate level: -@code{.xml} - - - - -@endcode - -This encodes the following values - - - - - -
pstatePerformanceIdleEpsilonAllCores
0100 Mflop/s95 Watts120 Watts200 Watts
150 Mflop/s93 Watts115 Watts170 Watts
220 Mflop/s90 Watts110 Watts150 Watts
+.. code-block:: xml + + + + + + +This encodes the following values: + +.. raw:: html + + + + + + +
pstatePerformanceIdleEpsilonAllCores
0100 Mflop/s95 Watts120 Watts200 Watts
150 Mflop/s93 Watts115 Watts170 Watts
220 Mflop/s90 Watts110 Watts150 Watts
To change the pstate of a given CPU, use the following functions: -#MSG_host_get_nb_pstates(), simgrid#s4u#Host#setPstate(), #MSG_host_get_power_peak_at(). +:cpp:func:`MSG_host_get_nb_pstates()`, :cpp:func:`simgrid::s4u::Host::set_pstate()`, :cpp:func:`MSG_host_get_power_peak_at()`. -### How accurate are these models? +.. raw:: html + +

How accurate are these models?

This model cannot be more accurate than your instantiation: with the default values, your result will not be accurate at all. You can still get accurate energy prediction, provided that you carefully instantiate the model. The first step is to ensure that your timing prediction match perfectly. But this is only the first step of the path, -and you really want to read this paper to see all what you need to do +and you really want to read `this paper `_ to see all what you need to do before you can get accurate energy predictions. + + @endrst */ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(surf_energy, surf, "Logging specific to the SURF energy plugin"); -- 2.20.1