View source for KEcoLab/User Docs/Usage Scenario Script

<h1>What is a Usage Scenario Script? </h1>

A usage scenario script comprises a set of shell command files designed to measure the energy and hardware consumption of software across different operational modes: idle, baseline and sus. Each of these modes will have a separate usage scenario script to emulate user input.

<h1> Why is it Used? </h1>

The primary purpose of a usage scenario script is to characterize software performance under various conditions. This involves analyzing how resource consumption (CPU, memory, disk I/O, network), response times, and other key metrics vary depending on the software's state (idle, baseline, sus).

These scripts serve to automate user actions. By using these scripts in conjunction with the power meter, developers can efficiently gather comprehensive performance characteristics. This process is crucial for assessing the software's overall efficiency and identifying areas for optimization, which directly correlates with reducing its environmental footprint.

<h1> Script Creation </h1>

<ol>
<li> Create a folder and name it in the format reflective of its flatpak name as available on flathub. For eg for okular, it is <code>org.kde.okular</code> </li>

<li> The folder name and the Merge Request title should be the same. </li>

<li> The folder should contain the following files. 
<ul>
<li> log_baseline.sh </li>
<li> log_idle.sh </li>
<li> log_sus.sh </li>
<li> configuration.sh </li>
</ul>
</li>

</ol>

NOTE:- every application has a different naming scheme, <code> org.kde.<software_name> </code> is usually for kde applications, for non kde applications the naming scheme would be different.

<h1> Files in the Folder </h1>

<ul>

<li> '''log_baseline.sh (Operating System only)'''</li>
<ul>
<li>  This is a baseline scenario script. To establish the baseline, a scenario is measured in which the Operating System is running but no actions are taken.  </li>
<li>  For the baseline scenario script template, check this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_baseline.sh link]. </li>
</ul>

<li> '''log_idle.sh (OS + Application while Idle)''' </li>
<ul>
<li>  This is an idle mode scenario script. To establish the energy consumption and hardware performance data of the application while idle, a scenario is measured in which the application under consideration is opened but no action is taken.  </li>
<li>  For the idle scenario script template, follow this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_idle.sh link]. </li>

</ul>

'''Important''' 

The baseline and idle mode must be run for the same time needed to carry out the standard usage scenario. Since the power consumption for the baseline and idle scenario is relatively uniform, 10 repetitions for each is considered sufficient to obtain a representative sample.

<li> '''log_sus.sh (OS + Application in Use)'''  </li>
<ul>
<li>  This file is for standard usage scenarios. To measure the energy consumption and hardware performance data of the application in use, the standard usage scenario should be run.   </li>
<li>  The measurement of the standard usage scenario should be repeated 30 times, which will take several hours to complete. The higher number of repetitions is necessary to obtain a representative sample as the energy consumption and performance data may vary across measurements.  </li>
<li>  Follow this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_sus.sh link]for the standard usage scenario script template. </li>
</ul>

<li> '''configuration.sh (Optional)'''  </li>
<ul>
<li>  This script adds the option to add user configurations such as shortcuts, which might be used to make the automation process easier.  </li>
<li>  Check out this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/configuration.sh link] for the configuration script template. </li>
</ul>
</ul>