# 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:

• Host Energy: models the energy dissipation of the compute units.

• Link Energy: models the energy dissipation of the network.

• Host Load: monitors the load of the compute units.

You can activate these plugins with the –cfg=plugin command line option, for example with --cfg=plugin:host_energy. You can get the full list of existing plugins with --cfg=plugin:help.

## Defining a Plugin¶

A plugin can get some additional code executed within the SimGrid kernel, and attach the data needed by that code to the SimGrid objects.

The host load plugin in src/plugins/host_load.cpp constitutes a good introductory example. It defines a class HostLoad that is meant to be attached to each host. This class contains a EXTENSION_ID field that is mandatory to our extension mechanism. Then, the function sg_host_load_plugin_init initializes the plugin. It first calls simgrid::s4u::Host::extension_create() to register its extension to the s4u::Host objects, and then attaches some callbacks to signals.

You can attach your own extension to most kinds of s4u object: Actors, Disks, Hosts and Links. If you need to extend another kind of objects, please let us now.

Partial list of existing signals in s4u:

## Existing Plugins¶

Only the major plugins are described here. Please check in src/plugins to explore the other ones.

### Host Energy Plugin¶

group Plugin_host_energy

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.

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.

As a result, our energy model takes 4 parameters:

• 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:

<host id="HostA" speed="100.0Mf" core="4">
<prop id="wattage_per_state" value="100.0:120.0:200.0" />
<prop id="wattage_off" value="10" />
</host>


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:

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

#### 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:

<host id="HostC" speed="100.0Mf,50.0Mf,20.0Mf" core="4">
<prop id="wattage_per_state"
value="95.0:120.0:200.0, 93.0:115.0:170.0, 90.0:110.0:150.0" />
<prop id="wattage_off" value="10" />
</host>


This encodes the following values:

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::set_pstate(), MSG_host_get_power_peak_at().

#### 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 before you can get accurate energy predictions.

Functions

void sg_host_energy_plugin_init()

Enable host energy plugin.

Enable energy plugin to get joules consumption of each cpu. Call this function before #MSG_init().

void sg_host_energy_update_all()

updates the consumption of all hosts

After this call, sg_host_get_consumed_energy() will not interrupt your process (until after the next clock update).

double sg_host_get_consumed_energy(sg_host_t host)

Returns the total energy consumed by the host so far (in Joules)

Please note that since the consumption is lazily updated, it may require a simcall to update it. The result is that the actor requesting this value will be interrupted, the value will be updated in kernel mode before returning the control to the requesting actor.

double sg_host_get_idle_consumption(sg_host_t host)

Get the amount of watt dissipated when the host is idling.

double sg_host_get_idle_consumption_at(sg_host_t host, int pstate)

Get the amount of watt dissipated at the given pstate when the host is idling.

double sg_host_get_wattmin_at(sg_host_t host, int pstate)

Get the amount of watt dissipated at the given pstate when the host is at 0 or epsilon% CPU usage.

double sg_host_get_wattmax_at(sg_host_t host, int pstate)

Returns the amount of watt dissipated at the given pstate when the host burns CPU at 100%.

double sg_host_get_power_range_slope_at(sg_host_t host, int pstate)

Returns the power slope at the given pstate.

double sg_host_get_current_consumption(sg_host_t host)

Returns the current consumption of the host.

### Host Load Plugin¶

group Plugin_host_load

Simple plugin that monitors the current load for each host.

In addition, this constitutes a good introductory example on how to write a plugin. It attaches an extension to each host to store some data, and places callbacks in the following signals:

Note that extensions are automatically destroyed when the host gets destroyed.

Functions

void sg_host_load_plugin_init()

Initializes the HostLoad plugin.

double sg_host_get_current_load(sg_host_t host)

Returns the current load of that host, as a ratio = achieved_flops / (core_current_speed * core_amount)

double sg_host_get_avg_load(sg_host_t host)

Returns the current load of that host.

double sg_host_get_idle_time(sg_host_t host)

Returns the time this host was idle since the last reset.

double sg_host_get_total_idle_time(sg_host_t host)

Returns the time this host was idle since the beginning of the simulation.

double sg_host_get_computed_flops(sg_host_t host)

Returns the amount of flops computed by that host since the last reset.

void sg_host_load_reset(sg_host_t host)

Resets the idle time and flops amount of that host.