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 Load: monitors the load of the compute units.

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

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

  • WiFi Energy: models the energy dissipation of wifi links.

  • Battery: models batteries that get discharged by the energy consumption of a given host.

  • Solar Panel: models solar panels which energy production depends on the solar irradiance.

  • Chiller: models chillers which dissipate heat by consuming energy.

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.

template<class R, class ...P>
class simgrid::xbt::signal<R(P...)>

A signal/slot mechanism, where you can attach callbacks to a given signal, and then fire the signal.

The template parameter is the function signature of the signal (the return value currently ignored).

template<class R, class ...P>
simgrid::xbt::signal<R(P...)>::operator()(P... args)

Fire that signal, invoking all callbacks.

Existing signals

Existing Plugins

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

Host Energy

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 loading your platform, and then use sg_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 loadedWattageExplanation
0 (idle) 100 Watts Idle 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

Here is how it looks graphically:

_images/plugin-energy.svg

As you can see, the Epsilon parameter allows to freely specify the slope you want, while using the 2 parameters version of the model (with only Idle and AllCores) requires that the Idle value is on the extension of the line crossing the consumption you mesure for each core amount. Please note that specifying the consumption for each core amount separately was not a solution because parallel tasks can use an amount of cores that is not an integer. The good news is that it was not necessary, as our experiments (detailed in the paper) show that the proposed linear model is sufficient to capture reality.

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: sg_host_get_nb_pstates(), simgrid::s4u::Host::set_pstate(), sg_host_get_pstate_speed().

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 loading your platform.

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(const_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(const_sg_host_t host)

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

double sg_host_get_idle_consumption_at(const_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(const_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(const_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(const_sg_host_t host, int pstate)

Returns the power slope at the given pstate.

double sg_host_get_current_consumption(const_sg_host_t host)

Returns the current consumption of the host.

WiFi Energy

group plugin_link_energy_wifi

This is the WiFi energy plugin, accounting for the dissipated energy of WiFi links.

Functions

void sg_wifi_energy_plugin_init()

Initialize the wifi energy plugin.

Host Load

group plugin_host_load

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(const_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(const_sg_host_t host)

Returns the current load of that host.

double sg_host_get_idle_time(const_sg_host_t host)

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

double sg_host_get_total_idle_time(const_sg_host_t host)

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

double sg_host_get_computed_flops(const_sg_host_t host)

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

void sg_host_load_reset(const_sg_host_t host)

Resets the idle time and flops amount of that host.

File System

group plugin_filesystem

This adds the notion of Files on top of the storage notion that provided by the core of SimGrid. Activate this plugin at will.

Typedefs

typedef s4u_File *sg_file_t

Pointer to a SimGrid file object

typedef const s4u_File *const_sg_file_t

Constant pointer to a SimGrid file object

Functions

void sg_storage_file_system_init()

Initialize the file system plugin.

See the examples in I/O on Disks and Files.

const char *sg_file_get_name(const_sg_file_t fd)

Retrieves the path to the file

sg_size_t sg_file_get_size(const_sg_file_t fd)

Retrieves the size of the file

void *sg_file_get_data(const_sg_file_t fd)

Retrieves the user data associated with the file

void sg_file_set_data(sg_file_t fd, void *data)

Changes the user data associated with the file

void sg_file_seek(sg_file_t fd, sg_offset_t offset, int origin)

Set the file position indicator in the sg_file_t by adding offset bytes to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).

Parameters:

  • fd – : file object that identifies the stream

  • offset – : number of bytes to offset from origin

  • origin – : Position used as reference for the offset. It is specified by one of the following constants defined in <stdio.h> exclusively to be used as arguments for this function (SEEK_SET = beginning of file, SEEK_CUR = current position of the file pointer, SEEK_END = end of file)

int sg_file_rcopy(sg_file_t file, sg_host_t host, const char *fullpath)

Copy a file to another location on a remote host.

Parameters:

  • file – : the file to move

  • host – : the remote host where the file has to be copied

  • fullpath – : the complete path destination on the remote host

Returns:

If successful, the function returns 0. Otherwise, it returns -1.

int sg_file_rmove(sg_file_t file, sg_host_t host, const char *fullpath)

Move a file to another location on a remote host.

Parameters:

  • file – : the file to move

  • host – : the remote host where the file has to be moved

  • fullpath – : the complete path destination on the remote host

Returns:

If successful, the function returns 0. Otherwise, it returns -1.

sg_size_t write(sg_size_t size, bool write_inside = false)

Write into a file (local or remote)

Simulates a write action. Returns the size of data actually written.

Parameters:

  • size – of the file to write

  • write_inside –

Returns:

the number of bytes successfully write or -1 if an error occurred

class File : public xbt::Extendable<File>
#include <file_system.h>

A simulated file.

Used to simulate the time it takes to access to a file, but does not really store any information.

They are located on simgrid::s4u::Disk that are accessed from a given simgrid::s4u::Host

Battery

group plugin_battery

This is the battery plugin, enabling management of batteries.

Batteries

A battery has an initial State of Charge \(SoC\), a nominal charge power, a nominal discharge power, a charge efficiency \(\eta_{charge}\), a discharge efficiency \(\eta_{discharge}\), an initial capacity \(C_{initial}\) and a number of cycle \(N\).

The nominal charge(discharge) power is the maximum power the Battery can consume(provide), before application of the charge(discharge) efficiency factor. For instance, if a load provides(consumes) 100W to(from) the Battery with a nominal charge(discharge) power of 50W and a charge(discharge) efficiency of 0.9, the Battery will only gain(provide) 45W.

We distinguish the energy provided \(E_{provided}\) / consumed \(E_{consumed}\) from the energy lost \(E_{lost}\) / gained \(E_{gained}\). The energy provided / consumed shows the external point of view, and the energy lost / gained shows the internal point of view:

\[ \begin{align}\begin{aligned}E_{lost} = {E_{provided} \over \eta_{discharge}}\\E_{gained} = E_{consumed} \times \eta_{charge}\end{aligned}\end{align} \]

For instance, if you apply a load of 100W to a battery for 10s with a discharge efficiency of 0.8, the energy provided will be equal to 10kJ, and the energy lost will be equal to 12.5kJ.

All the energies are positive, but loads connected to a Battery may be positive or negative, as explained in the next section.

Use the battery reduces its State of Health \(SoH\) and its capacity \(C\) linearly in consequence:

\[ \begin{align}\begin{aligned}SoH = 1 - {E_{lost} + E_{gained} \over E_{budget}}\\C = C_{initial} \times SoH\end{aligned}\end{align} \]

With:

\[E_{budget} = C_{initial} \times N \times 2\]

Plotting the output of the example “battery-degradation” highlights the linear decrease of the \(SoH\) due to a continuous use of the battery alternating between charge and discharge:

_images/battery_degradation.svg

The natural depletion of batteries over time is not taken into account.

Loads & Hosts

You can add named loads to a battery. Those loads may be positive and consume energy from the battery, or negative and provide energy to the battery. You can also connect hosts to a battery. Theses hosts will consume their energy from the battery until the battery is empty or until the connection between the hosts and the battery is set inactive.

Handlers

You can schedule handlers that will happen at specific SoC of the battery and trigger a callback. Theses handlers may be recurrent, for instance you may want to always set all loads to zero and deactivate all hosts connections when the battery reaches 20% SoC.

Connector

A Battery can act as a connector to connect Solar Panels direcly to loads. Such Battery is created without any parameter, cannot store energy and has a transfer efficiency of 100%.

Functions

inline double get_state_of_charge()

Note

For Battery::Handler objects

Returns:

The state of charge at which the Handler will happen.

inline Flow get_flow()

Note

For Battery::Handler objects

Returns:

The flow in which the Handler will happen, either when the Battery is charging or discharging.

inline double get_time_delta()

Note

For Battery::Handler objects

Returns:

The time delta until the Handler happen. -1 means that is will never happen with the current state the Battery, for instance when there is no load connected to the Battery.

inline std::function<void()> get_callback()

Note

For Battery::Handler objects

Returns:

The callback to trigger when the Handler happen.

inline Persistancy get_persistancy()

Note

For Battery::Handler objects

Returns:

true if its a recurrent Handler.

static BatteryPtr init()

Init a Battery with this constructor makes it only usable as a connector. A connector has no capacity and only delivers as much power as it receives with a transfer efficiency of 100%.

Returns:

A BatteryPtr pointing to the new Battery.

static BatteryPtr init(const std::string &name, double state_of_charge, double nominal_charge_power_w, double nominal_discharge_power_w, double charge_efficiency, double discharge_efficiency, double initial_capacity_wh, int cycles)
Parameters:

  • name – The name of the Battery.

  • state_of_charge – The initial state of charge of the Battery [0,1].

  • nominal_charge_power_w – The maximum power absorbed by the Battery in W (<= 0).

  • nominal_discharge_power_w – The maximum power delivered by the Battery in W (>= 0).

  • charge_efficiency – The charge efficiency of the Battery [0,1].

  • discharge_efficiency – The discharge efficiency of the Battery [0,1].

  • initial_capacity_wh – The initial capacity of the Battery in Wh (>0).

  • cycles – The number of charge-discharge cycles until complete depletion of the Battery capacity.

Returns:

A BatteryPtr pointing to the new Battery.

void set_load(const std::string &name, double power_w)
Parameters:

  • name – The name of the load

  • power_w – Power of the load in W. A positive value discharges the Battery while a negative value charges it.

void set_load(const std::string &name, bool active)
Parameters:

  • name – The name of the load

  • active – Status of the load. If false then the load is ignored by the Battery.

void connect_host(s4u::Host *host, bool active = true)

Connect a Host to the Battery with the status active. As long as the status is true the Host takes its energy from the Battery. To modify this status connect again the same Host with a different status.

Warning

Do NOT connect the same Host to multiple Batteries with the status true at the same time. In this case all Batteries would have the full consumption from this Host.

Parameters:

  • host – The Host to connect.

  • active – Status of the connected Host (default true).

double get_state_of_charge()
Returns:

The state of charge of the battery.

double get_state_of_health()
Returns:

The state of health of the Battery.

double get_capacity()
Returns:

The current capacity of the Battery.

double get_energy_provided()

Note

It is the energy provided from an external point of view, after application of the discharge efficiency. It means that the Battery lost more energy than it has provided.

Returns:

The energy provided by the Battery.

double get_energy_consumed()

Note

It is the energy consumed from an external point of view, before application of the charge efficiency. It means that the Battery consumed more energy than is has absorbed.

Returns:

The energy consumed by the Battery.

double get_energy_stored(std::string unit = "J")
Parameters:

unit – Valid units are J (default) and Wh.

Returns:

Energy stored in the Battery.

std::shared_ptr<Handler> schedule_handler(double state_of_charge, Flow flow, Handler::Persistancy p, std::function<void()> callback)

Schedule a new Handler.

Parameters:

  • state_of_charge – The state of charge at which the Handler will happen.

  • flow – The flow in which the Handler will happen, either when the Battery is charging or discharging.

  • callback – The callable to trigger when the Handler happen.

  • p – If the Handler is recurrent or unique.

Returns:

A shared pointer of the new Handler.

std::vector<std::shared_ptr<Handler>> get_handlers()
Returns:

A vector containing the Handlers associated to the Battery.

void delete_handler(std::shared_ptr<Handler> handler)

Remove an Handler from the Battery.

Solar Panel

group plugin_solar_panel

This is the solar panel plugin, enabling management of solar panels on hosts.

This plugin allows the use of solar panels to generate power during simulation depending on size, solar irradiance and conversion factor.

The power model is taken from the paper “Reinforcement Learning Based Load Balancing for Geographically Distributed Data Centres” by Max Mackie et. al.

Solar Panel

A solar panel has an area \(A\) in m², a conversion efficiency \(\eta\) and a solar irradiance \(S\) in W/m². The power generated \(P\) in W by a solar panel is given by the following equation:

\[P = A \times \eta \times S\]

Typedefs

using SolarPanelPtr = boost::intrusive_ptr<SolarPanel>

Functions

static SolarPanelPtr init(const std::string &name, double area_m2, double conversion_efficiency, double solar_irradiance_w_per_m2, double min_power_w, double max_power_w)
Parameters:

  • name – The name of the Solar Panel.

  • area_m2 – The area of the Solar Panel in m² (> 0).

  • conversion_efficiency – The conversion efficiency of the Solar Panel [0,1].

  • solar_irradiance_w_per_m2 – The solar irradiance of the Solar Panel in W/m² (> 0).

  • min_power_w – The minimal power delivered by the Solar Panel in W (> 0 and < max_power_w).

  • max_power_w – The maximal power delivered by the Solar Panel in W (> 0 and > min_power_w).

Returns:

A SolarPanelPtr pointing to the new SolarPanel.

SolarPanelPtr set_name(std::string name)
Parameters:

name – The new name of the Solar Panel.

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

SolarPanelPtr set_area(double area_m2)
Parameters:

area_m2 – The new area of the Solar Panel in m².

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

SolarPanelPtr set_conversion_efficiency(double e)
Parameters:

e – The new convesion efficiency of the Solar Panel.

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

SolarPanelPtr set_solar_irradiance(double solar_irradiance_w_per_m2)
Parameters:

solar_irradiance_w_per_m2 – The new solar irradiance of the Solar Panel in W/m².

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

SolarPanelPtr set_min_power(double power_w)
Parameters:

power_w – The new minimal power of the Solar Panel in W.

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

SolarPanelPtr set_max_power(double power_w)
Parameters:

power_w – The new maximal power of the Solar Panel in W.

Returns:

A SolarPanelPtr pointing to the modified SolarPanel.

Chiller

group plugin_chiller

This is the chiller plugin, enabling management of chillers.

Chiller

A chiller is placed inside a room with several machines. The role of the chiller is to keep the temperature of the room below a threshold. This plugin and its equations are based on the paper “Co-simulation of FMUs and Distributed Applications with SimGrid” by Camus et al. (https://hal.science/hal-01762540).

The heat generated inside the room \(Q_{room}\) depends on the heat from the machines \(Q_{machines}\) and from the heat of the other devices, such as lighing, accounted using a factor \(\alpha\) such as:

\[Q_{room} = (1 + \alpha) \times Q_{machines}\]

This energy heats the input temperature \(T_{in}\) and gives an output temperature \(T_{out}\) based on the mass of air inside the room \(m_{air}\) and its specific heat \(C_{p}\):

\[T_{out} = T_{in} + {Q_{room} \over m_{air} \times C_{p}}\]

If the output temperature is above the goal temperature \(T_{goal}\) the chiller compensates the excessive heat using electrical energy \(Q_{cooling}\) depending on its cooling efficiency \(\eta_{cooling}\) :

\[Q_{cooling} = (T_{out} - T_{goal}) \times m_{air} \times C_{p} / \eta_{cooling}\]

The chiller has a power threshold that cannot be exceeded. If the power needed is above this threshold, or if the chiller is not active, the temperature of the room increases.

Typedefs

using ChillerPtr = boost::intrusive_ptr<Chiller>

Functions

static ChillerPtr init(const std::string &name, double air_mass_kg, double specific_heat_j_per_kg_per_c, double alpha, double cooling_efficiency, double initial_temp_c, double goal_temp_c, double max_power_w)
Parameters:

  • name – The name of the Chiller.

  • air_mass_kg – The air mass of the room managed by the Chiller in kg (> 0).

  • specific_heat_j_per_kg_per_c – The specific heat of air in J per kg per °C (> 0).

  • alpha – The ratio of the other devices in the total heat dissipation (e.g. lighting, Power Distribution Unit) (>= 0).

  • cooling_efficiency – The cooling efficiency of the Chiller [0, 1].

  • initial_temp_c – The initial temperature of the room managed by the Chiller.

  • goal_temp_c – The goal temperature of the room. The Chiller is idle below this temperature.

  • max_power_w – The maximal power delivered by the Chiller in W (> 0). If this power is reached the room temperature will raise above the goal temperature.

Returns:

A ChillerPtr pointing to the new Chiller.

ChillerPtr set_name(std::string name)
Parameters:

name – The new name of the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_air_mass(double air_mass_kg)
Parameters:

air_mass_kg – The new air mass of the Chiller in kg.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_specific_heat(double specific_heat_j_per_kg_per_c)
Parameters:

specific_heat_j_per_kg_per_c – The specific heat of the Chiller in J per kg per °C.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_alpha(double alpha)
Parameters:

alpha – The new alpha of the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_cooling_efficiency(double cooling_efficiency)
Parameters:

cooling_efficiency – The new coolingefficiency of the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_goal_temp(double goal_temp_c)
Parameters:

goal_temp_c – The new goal temperature of the Chiller in °C.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_max_power(double max_power_w)
Parameters:

max_power_w – The new maximal power of the Chiller in W.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr set_active(bool active)
Parameters:

active – The new active status of the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr add_host(simgrid::s4u::Host *host)
Parameters:

host – The host to add to the room managed by the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

ChillerPtr remove_host(simgrid::s4u::Host *host)
Parameters:

host – The host to remove from the room managed by the Chiller.

Returns:

A ChillerPtr pointing to the modified Chiller.

double get_time_to_goal_temp() const
Returns:

The time to reach to goal temp, assuming that the system remain in the same state.