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:

• Actor::on_creation Actor::on_suspend Actor::on_resume Actor::on_sleep Actor::on_wake_up Actor::on_migration_start Actor::on_migration_end Actor::on_termination Actor::on_destruction

• Comm::on_sender_start Comm::on_receiver_start Comm::on_completion

• Engine::on_platform_creation Engine::on_platform_created Engine::on_time_advance Engine::on_simulation_end Engine::on_deadlock

• Exec::on_start Exec::on_completion

• Host::on_creation Host::on_destruction Host::on_state_change Host::on_speed_change

• Link::on_creation Link::on_destruction Link::on_state_change Link::on_speed_change Link::on_communicate Link::on_communication_state_change

• Netzone::on_creation Netzone::on_seal Netzone::on_route_creation

• VirtualMachine::on_start VirtualMachine::on_started VirtualMachine::on_suspend VirtualMachine::on_resume VirtualMachine::on_migration_start VirtualMachine::on_migration_end

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:

#Cores loaded	Wattage	Explanation
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:

pstate	Performance	Idle	Epsilon	AllCores
0	100 Mflop/s	95 Watts	120 Watts	200 Watts
1	50 Mflop/s	93 Watts	115 Watts	170 Watts
2	20 Mflop/s	90 Watts	110 Watts	150 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.

Link Energy Plugin

group Plugin_link_energy

This is the link energy plugin, accounting for the dissipated energy in the simulated platform.

The energy consumption of a link depends directly on its current traffic load. Specify that consumption in your platform file as follows:

<link id="SWITCH1" bandwidth="125Mbps" latency="5us" sharing_policy="SHARED" >
<prop id="wattage_range" value="100.0:200.0" />
<prop id="wattage_off" value="10" />
</link>

The first property means that when your link is switched on, but without anything to do, it will dissipate 100 Watts. If it’s fully loaded, it will dissipate 200 Watts. If its load is at 50%, then it will dissipate 150 Watts. The second property means that when your host is turned off, it will dissipate only 10 Watts (please note that these values are arbitrary).

To simulate the energy-related elements, first call the simgrid::energy::sg_link_energy_plugin_init() before your #MSG_init(), and then use the following function to retrieve the consumption of a given link: sg_link_get_consumed_energy().

Functions

void sg_link_energy_plugin_init()

Enable energy plugin.

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

double sg_link_get_consumed_energy(sg_link_t link)

Returns the total energy consumed by the link 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.

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:

• simgrid::s4u::Host::on_creation: Attach a new extension to the newly created host.

• simgrid::s4u::Exec::on_start: Make note that a new execution started, increasing the load.

• simgrid::s4u::Exec::on_completion: Make note that an execution completed, decreasing the load.

• simgrid::s4u::Host::on_state_change: Do what is appropriate when the host gets suspended, turned off or similar.

• simgrid::s4u::Host::on_speed_change: Do what is appropriate when the DVFS is modified.

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.