Improves the documentation

docs/expetator.benchmarks.rst

@@ -28,7 +28,7 @@ Available benchmarks
 
 Example of use of an available benchmark :
 
-.. code-block:: C
+.. code-block:: python
 
     import expetator.experiment as experiment
     from expetator.benchmarks import SleepBench

docs/expetator.leverages.rst

-expetator.leverages package
-===========================
+Leverages
+=========
+
+Available leverages
+-------------------
+
+Most of these leverages only work on Grid5000, and some only on some servers (with GPU for Gpu* for example)
 
 .. autoclass:: expetator.leverages.Dvfs
 
@@ -15,5 +20,115 @@ expetator.leverages package
 
 .. autoclass:: expetator.leverages.Powercap
 
-.. autoclass:: expetator.leverages.Template
+Example of use of an available leverages :
+
+.. code-block:: python
+
+    import expetator.experiment as experiment
+    from expetator.benchmarks import SleepBench
+    from expetator.leverages import Dvfs
+
+    experiment.run_experiment("/tmp/dvfs_demo",
+                              [ SleepBench(default_time=2) ],
+			      leverages = [ Dvfs(baseline=True) ],
+                             )
+
+The result will be in a file **/tmp/dvfs_demo_${HOST}_${TIMESTAMP_START}**
+
+	       
+How to make your own leverage
+-----------------------------
+
+A leverages has an internal list of available state (obtained through the **available_states** member). A state can be a tuple
+
+A classical template would be:
+
+.. code-block:: python
+		
+    class Template:
+        'Template for leverages'
+        def __init__(self):
+            'Initializes the internal variables using parameters'
+            pass
+
+        def build(self, executor):
+            'Builds the executable and acquire data on the system'
+            self.executor = executor
+            pass
+    
+        def available_states(self):
+            'Returns all the possible states as a list'
+            return [None]
+
+        def start(self, state):
+            'Sets the right state on all hosts'
+            pass
+        
+        def stop(self, output_file=None):
+            'Reverts to the standard state on all nodes and saves some info in the right directory'
+            pass
+            
+        def get_state(self):
+            'Returns the current state'
+            return None
+
+        def state_to_str(self):
+            '''Converts the current state in a string
+	    If there are several values, they are separated by a white-space'''
+            return 'None'
+
+        def get_labels(self):
+            'Returns the labels for the leverage as a tuple'
+            return ('Template')
+
+Example of leverage
+-------------------
+
+Here is an example of a simple leverage that will change the sound ouput level
+
+.. code-block:: python
+		
+    import expetator.experiment as experiment
+    from expetator.benchmarks import SleepBench
+
+    class SoundLevel:
+
+        def __init__(self, levels = [20, 70]):
+            self.levels = levels
+
+        def build(self, executor):
+            'Builds the executable and acquire data on the system'
+            self.executor = executor
+            pass
+    
+        def available_states(self):
+            'Returns all the possible states as a list'
+            return self.levels
+
+        def start(self, state):
+            'Sets the right state on all hosts'
+	    self.executor.hosts('pactl set-sink-volume @DEFAULT_SINK@ '+str(state)+'%')
+	    self.state = state
+            pass
+        
+        def stop(self, output_file=None):
+            'Reverts to the standard state on all nodes and saves some info in the right directory'
+            pass
+            
+        def get_state(self):
+            'Returns the current state'
+            return self.state
+
+        def state_to_str(self):
+            'Converts the current state in a string'
+            return str(self.state)
+
+        def get_labels(self):
+            'Returns the labels for the leverage'
+            return ('level')
 
+    if __name__ == "__main__":
+        experiment.run_experiment(
+            "/tmp/sound_demo", [SleepBench(default_time=2)],
+	    leverages=[SoundLevel()],
+        )

docs/expetator.monitors.rst

-expetator.monitors package
-==========================
+Monitors
+========
+
+Available monitors
+------------------
 
 .. autoclass:: expetator.monitors.kwollect.Power
 
@@ -8,3 +11,94 @@ expetator.monitors package
 .. autoclass:: expetator.monitors.mojitos.Mojitos
 	       
 .. autoclass:: expetator.monitors.powergpu.Power
+
+
+Example of use of an available benchmark :
+
+.. code-block:: python
+
+    import expetator.experiment as experiment
+    from expetator.benchmarks import SleepBench
+    from expetator.monitors import Mojitos
+
+    experiment.run_experiment("/tmp/mojitos_demo",
+                              [ SleepBench(default_time=2) ],
+			      monitors = [ Mojitos(sensor_set={'user'})]
+                             )
+
+The result will be in a file **/tmp/mojitos_demo_${HOST}_${TIMESTAMP_START}** and directories starting with **/tmp/mojitos_demo_${HOST}_${TIMESTAMP_START}_\***
+	       
+How to make your own monitor
+----------------------------
+
+A monitor is an object with the following properties
+ * The constructor can take parameters (such as the elements to monitor or the frequency)
+ * The **build** method must build, configure, install packages using **executor**. Resulting binaries must be put in **/tmp/bin** which will be copied on all nodes
+ * The **start** method must start the monitor while the **stop** one must stop it. These two methods must be fast and run the processes in background
+ * The **save** method is invocated later when all monitors are stoped anc is used to retrive the data.
+
+
+All monitors will **start** in parallel just prior running the benchmark and will **stop** just after.
+
+Example of monitor
+------------------
+
+Here is an example of a simple benchmark in a file **demo_monitor.py**
+
+.. code-block:: python
+
+    import os
+
+    import expetator.experiment as experiment
+    from  expetator.benchmarks import SleepBench
+
+    class DemoMonitor:
+        def __init__(self, c_code = 'monitor.c'):
+            self.c_code = c_code
+            self.executor = None
+            self.cmd_line = None
+
+        def build(self, executor):
+            executor.local('gcc -o /tmp/bin/monitor %s' % self.c_code)
+            self.executor = executor
+            self.cmdline = '/tmp/bin/monitor > /dev/shm/mon &'
+    
+        def start(self):
+            'Starts the monitoring right before the benchmark'
+            self.executor.hosts(self.cmdline)
+
+        def stop(self):
+            'Stops the monitoring right before the benchmark'
+            self.executor.hosts('killall monitor')
+
+        def save(self, experiment, benchname, beg_time):
+            'Save the results when time is no more critical'
+            directory = experiment.output_file+'_monitoring_demo'
+            os.makedirs(directory, exist_ok=True)
+            if len(self.executor.hostnames) > 1:
+                for hostname in self.executor.hostnames:
+                    self.executor.local('oarcp %s:/dev/shm/mon %s/%s_%s_%s' %
+                                        (hostname, directory, hostname, benchname, beg_time))
+            else:
+                self.executor.local('cp /dev/shm/mon %s/%s_%s_%s' %
+                                        (directory, 'localhost', benchname, beg_time))
+
+    if __name__ == "__main__":
+        experiment.run_experiment(
+            "/tmp/demo", [SleepBench(default_time=2)],
+    	    monitors=[DemoMonitor()],
+        )
+
+With the following benchmark code in a file **monitor.c** in the same directory
+
+.. code-block:: C
+
+    #include <stdio.h>
+    #include <unistd.h>
+
+    int main() {
+        for(unsigned int i=0; ; i++) {
+            sleep(.1);
+            printf("%d\n", i);
+        }
+    }

expetator/monitors/__init__.py

+from expetator.monitors.kwollect import Power as Kwollect
+from expetator.monitors.lperf import Lperf
+from expetator.monitors.mojitos import Mojitos
+from expetator.monitors.powergpu import Power as PowerGpu

expetator/monitors/mojitos.py

@@ -93,7 +93,7 @@ class Mojitos:
             self.cmdline += ' -r'
         if self.load:
             self.cmdline += ' -u'
-        self.cmdline += ' -o /dev/shm/monitoring &'
+        self.cmdline += ' -o /dev/shm/monitoring_moj &'
 
 
     def start(self):
@@ -110,8 +110,8 @@ class Mojitos:
         os.makedirs(filename_moj, exist_ok=True)
         if len(self.executor.hostnames) > 1:
             for hostname in self.executor.hostnames:
-                self.executor.local('oarcp %s:/dev/shm/monitoring %s/%s_%s_%s' %
+                self.executor.local('oarcp %s:/dev/shm/monitoring_moj %s/%s_%s_%s' %
                                     (hostname, filename_moj, hostname, benchname, beg_time))
         else:
-            self.executor.local('cp /dev/shm/monitoring %s/%s_%s_%s' %
+            self.executor.local('cp /dev/shm/monitoring_moj %s/%s_%s_%s' %
                                     (filename_moj, 'localhost', benchname, beg_time))