#include <PowerBalancerAgent.hpp>

Inheritance diagram for geopm::PowerBalancerAgent:

Collaboration diagram for geopm::PowerBalancerAgent:

[legend]

Classes
class	LeafRole

class	MeasureRuntimeStep

class	ReduceLimitStep

class	Role

class	RootRole

class	SendDownLimitStep

class	Step

class	TreeRole

Public Member Functions
	PowerBalancerAgent (PlatformIO &platform_io, const PlatformTopo &platform_topo, std::shared_ptr< SampleAggregator > sample_agg, std::vector< std::shared_ptr< PowerBalancer > > power_balancer, double min_power, double max_power)

	PowerBalancerAgent ()

virtual	~PowerBalancerAgent ()

void	init (int level, const std::vector< int > &fan_in, bool is_level_root) override
	Set the level where this Agent is active and push signals/controls for that level. More...

void	validate_policy (std::vector< double > &policy) const override
	Called by Controller to validate incoming policy values and configure defaults requested in incoming policy. Policy sender can request default value with 'NaN' at the desired offset in the policy vector. Returned policy should not contain 'NaN's and be consumeable by descend and adjust_platform. More...

void	split_policy (const std::vector< double > &in_policy, std::vector< std::vector< double > > &out_policy) override
	Called by Controller to split policy for children at next level down the tree. More...

bool	do_send_policy (void) const override
	Called by Controller to determine if new policy values should be sent down the tree to the Agent's children. More...

void	aggregate_sample (const std::vector< std::vector< double > > &in_sample, std::vector< double > &out_sample) override
	Aggregate samples from children for the next level up the tree. More...

bool	do_send_sample (void) const override

void	adjust_platform (const std::vector< double > &in_policy) override
	Adjust the platform settings based the policy from above. More...

bool	do_write_batch (void) const override
	Called by the Controller to decide whether to call write_batch() to update platform controls. More...

void	sample_platform (std::vector< double > &out_sample) override
	Read signals from the platform and interpret/aggregate these signals to create a sample which can be sent up the tree. More...

void	wait (void) override
	Called by Controller to wait for sample period to elapse. This controls the cadence of the Controller main loop. More...

std::vector< std::pair< std::string, std::string > >	report_header (void) const override
	Custom fields that will be added to the report header when this agent is used. More...

std::vector< std::pair< std::string, std::string > >	report_host (void) const override
	Custom fields for the host section of the report. More...

std::map< uint64_t, std::vector< std::pair< std::string, std::string > > >	report_region (void) const override
	Custom fields for each region in the report. More...

std::vector< std::string >	trace_names (void) const override
	Column headers to be added to the trace. More...

std::vector< std::function< std::string(double)> >	trace_formats (void) const override
	Returns format string for each column added to the trace. More...

void	trace_values (std::vector< double > &values) override
	Called by Controller to get latest values to be added to the trace. More...

void	enforce_policy (const std::vector< double > &policy) const override
	Enforce the policy one time with PlatformIO::write_control(). Called to enforce static policies in the absence of a Controller. More...

Public Member Functions inherited from geopm::Agent
	Agent ()=default

virtual	~Agent ()=default

Static Public Member Functions
static std::string	plugin_name (void)

static std::unique_ptr< Agent >	make_plugin (void)

static std::vector< std::string >	policy_names (void)

static std::vector< std::string >	sample_names (void)

static std::string	format_step_count (double step)

Static Public Member Functions inherited from geopm::Agent
static std::vector< std::string >	agent_names (void)

static std::unique_ptr< Agent >	make_unique (const std::string &agent_name)

static int	num_policy (const std::map< std::string, std::string > &dictionary)
	Used to look up the number of values in the policy vector sent down the tree for a specific Agent. This should be called with the dictionary returned by agent_factory().dictionary(agent_name) for the Agent of interest. More...

static int	num_policy (const std::string &agent_name)
	Used to look up the number of values in the policy vector sent down the tree for a specific Agent. More...

static int	num_sample (const std::map< std::string, std::string > &dictionary)
	Used to look up the number of values in the sample vector sent up the tree for a specific Agent. This should be called with the dictionary returned by agent_factory().dictionary(agent_name) for the Agent of interest. More...

static int	num_sample (const std::string &agent_name)
	Used to look up the number of values in the sample vector sent up the tree for a specific Agent. More...

static std::vector< std::string >	policy_names (const std::map< std::string, std::string > &dictionary)
	Used to look up the names of values in the policy vector sent down the tree for a specific Agent. This should be called with the dictionary returned by agent_factory().dictionary(agent_name) for the Agent of interest. More...

static std::vector< std::string >	policy_names (const std::string &agent_name)
	Used to look up the names of values in the policy vector sent down the tree for a specific Agent. More...

static std::vector< std::string >	sample_names (const std::map< std::string, std::string > &dictionary)
	Used to look up the names of values in the sample vector sent up the tree for a specific Agent. This should be called with the dictionary returned by agent_factory().dictionary(agent_name) for the Agent of interest. More...

static std::vector< std::string >	sample_names (const std::string &agent_name)
	Used to look up the names of values in the sample vector sent up the tree for a specific Agent. More...

static std::map< std::string, std::string >	make_dictionary (const std::vector< std::string > &policy_names, const std::vector< std::string > &sample_names)
	Used to create a correctly-formatted dictionary for an Agent at the time the Agent is registered with the factory. Concrete Agent classes may provide policy_names() and sample_names() methods to provide the vectors to be passed to this method. More...

static void	aggregate_sample (const std::vector< std::vector< double > > &in_sample, const std::vector< std::function< double(const std::vector< double > &)> > &agg_func, std::vector< double > &out_sample)
	Generically aggregate a vector of samples given a vector of aggregation functions. This helper method applies a different aggregation function to each sample element while aggregating across child samples. More...

Protected Attributes
PlatformIO &	m_platform_io

const PlatformTopo &	m_platform_topo

std::shared_ptr< SampleAggregator >	m_sample_agg

std::shared_ptr< Role >	m_role

std::vector< std::shared_ptr< PowerBalancer > >	m_power_balancer

struct geopm_time_s	m_last_wait

const double	M_WAIT_SEC

double	m_power_tdp

bool	m_do_send_sample

bool	m_do_send_policy

bool	m_do_write_batch

const double	M_MIN_PKG_POWER_SETTING

const double	M_MAX_PKG_POWER_SETTING

const double	M_TIME_WINDOW

Additional Inherited Members
Static Public Attributes inherited from geopm::Agent
static const std::string	M_PLUGIN_PREFIX = "libgeopmagent_"

Member Enumeration Documentation

◆ m_policy_e

enum geopm::PowerBalancerAgent::m_policy_e

Enumerator
M_POLICY_POWER_PACKAGE_LIMIT_TOTAL	The power cap enforced on average over all nodes running the application. This has value 0.0 except in two cases. In the first case this is the M_SEND_DOWN_LIMIT step at the beginning of the application run. This value will also be non-zero in the case where the resource mananger has requested a new budget for the application, and thus, the algorithm must be restarted at step M_SEND_DOWN_LIMIT.
M_POLICY_STEP_COUNT	Step that the root is providing a policy for. The parent has received a sample matching this step in the last walk up the tree, except in the case where the root Agent has recently been updated with a new policy; in this case the step will be M_SEND_DOWN_LIMIT and the policy indexed by M_POLICY_POWER_CAP will have a non-zero value.
M_POLICY_MAX_EPOCH_RUNTIME	The largest runtime reported by any leaf agent since the last redistribution of power. This will have value 0.0 until all leaf agents have reported a runtime to the root agent.
M_POLICY_POWER_SLACK	This value is updated in step M_STEP_ADJUST_LIMIT to the amount that each leaf agent should increase their power limit by calling: power_cap(current_limit + slack) by before starting the algorithm over again at step M_STEP_MEASURE_RUNTIME. For all other steps this value is 0.0.
M_NUM_POLICY	Number of steps in each iteration of the balancing algorithm.

◆ m_sample_e

enum geopm::PowerBalancerAgent::m_sample_e

Enumerator
M_SAMPLE_STEP_COUNT	The the step counter that is currently in execution. Note that the step is equal to the step counter modulo M_NUM_STEP and is reset each time a new power cap is provided by sending a policy with a non-zero M_POLICY_POWER_CAP field.
M_SAMPLE_MAX_EPOCH_RUNTIME	Maximum expected runtime for any node below.
M_SAMPLE_SUM_POWER_SLACK	The sum of all slack power available from children below the agent.
M_SAMPLE_MIN_POWER_HEADROOM	Smallest difference between maximum power limit and current power limit for any node below.
M_NUM_SAMPLE	Number of elements in a sample vector.

◆ m_step_e

enum geopm::PowerBalancerAgent::m_step_e

Enumerator
M_STEP_SEND_DOWN_LIMIT	On first iteration send down resource manager average limit requested, otherwise send down average excess power.
M_STEP_MEASURE_RUNTIME	Measure epoch runtime several times and apply median filter. Aggregate epoch runtime up tree by applying maximum filter to measured values. Propagate down from root the longest recorded runtime from any node.
M_STEP_REDUCE_LIMIT	Decrease power limit on all nodes (other than the slowest) until epoch runtime matches the slowest. Aggregate amount power limit was reduced in last step up the tree with sum filter. (Go to M_STEP_SEND_DOWN_LIMIT next).
M_NUM_STEP	Number of steps in process.

◆ m_trace_sample_e

enum geopm::PowerBalancerAgent::m_trace_sample_e

Enumerator
M_TRACE_SAMPLE_POLICY_POWER_PACKAGE_LIMIT_TOTAL
M_TRACE_SAMPLE_POLICY_STEP_COUNT
M_TRACE_SAMPLE_POLICY_MAX_EPOCH_RUNTIME
M_TRACE_SAMPLE_POLICY_POWER_SLACK
M_TRACE_SAMPLE_ENFORCED_POWER_LIMIT
M_TRACE_NUM_SAMPLE

Constructor & Destructor Documentation

◆ PowerBalancerAgent() [1/2]

geopm::PowerBalancerAgent::PowerBalancerAgent	(	PlatformIO &	platform_io,
		const PlatformTopo &	platform_topo,
		std::shared_ptr< SampleAggregator >	sample_agg,
		std::vector< std::shared_ptr< PowerBalancer > >	power_balancer,
		double	min_power,
		double	max_power
	)

◆ PowerBalancerAgent() [2/2]

geopm::PowerBalancerAgent::PowerBalancerAgent ( )

◆ ~PowerBalancerAgent()

geopm::PowerBalancerAgent::~PowerBalancerAgent ( )

virtualdefault

Member Function Documentation

◆ adjust_platform()

void geopm::PowerBalancerAgent::adjust_platform ( const std::vector< double > & in_policy )

overridevirtual

Adjust the platform settings based the policy from above.

Parameters

[in] policy Settings for each control in the policy.

Implements geopm::Agent.

◆ aggregate_sample()

void geopm::PowerBalancerAgent::aggregate_sample	(	const std::vector< std::vector< double > > &	in_sample,
		std::vector< double > &	out_sample
	)

overridevirtual

Aggregate samples from children for the next level up the tree.

Parameters

[in]	in_sample	Vector of sample vectors, one from each child.
[out]	out_sample	Aggregated sample values to be sent up to the parent.

Implements geopm::Agent.

◆ do_send_policy()

bool geopm::PowerBalancerAgent::do_send_policy ( void ) const

overridevirtual

Called by Controller to determine if new policy values should be sent down the tree to the Agent's children.

Returns: True if the policy has been updated since last call.

Implements geopm::Agent.

◆ do_send_sample()

bool geopm::PowerBalancerAgent::do_send_sample ( void ) const

overridevirtual

Returns: True if new samples were read since last call.

Implements geopm::Agent.

◆ do_write_batch()

bool geopm::PowerBalancerAgent::do_write_batch ( void ) const

overridevirtual

Called by the Controller to decide whether to call write_batch() to update platform controls.

Returns: True if platform was adjusted, false otherwise.

Implements geopm::Agent.

◆ enforce_policy()

void geopm::PowerBalancerAgent::enforce_policy ( const std::vector< double > & policy ) const

overridevirtual

Enforce the policy one time with PlatformIO::write_control(). Called to enforce static policies in the absence of a Controller.

Reimplemented from geopm::Agent.

◆ format_step_count()

std::string geopm::PowerBalancerAgent::format_step_count ( double step )

static

◆ init()

void geopm::PowerBalancerAgent::init	(	int	level,
		const std::vector< int > &	fan_in,
		bool	is_level_root
	)

overridevirtual

Set the level where this Agent is active and push signals/controls for that level.

Parameters

[in]	level	Level of the tree where this agent is active. Note that only agents at level zero execute sample_platform() and adjust_platform().
[in]	fan_in	Vector over level giving the the number of Agents that report to each root Agent operating at the level.
[in]	is_level_root	True if the agent plays the role of root of the level. Only root agents for a level execute ascend() and descend().

Implements geopm::Agent.

◆ make_plugin()

std::unique_ptr< Agent > geopm::PowerBalancerAgent::make_plugin ( void )

static

◆ plugin_name()

std::string geopm::PowerBalancerAgent::plugin_name ( void )

static

◆ policy_names()

std::vector< std::string > geopm::PowerBalancerAgent::policy_names ( void )

static

◆ report_header()

std::vector< std::pair< std::string, std::string > > geopm::PowerBalancerAgent::report_header ( void ) const

overridevirtual

Custom fields that will be added to the report header when this agent is used.

Implements geopm::Agent.

◆ report_host()

std::vector< std::pair< std::string, std::string > > geopm::PowerBalancerAgent::report_host ( void ) const

overridevirtual

Custom fields for the host section of the report.

Implements geopm::Agent.

◆ report_region()

std::map< uint64_t, std::vector< std::pair< std::string, std::string > > > geopm::PowerBalancerAgent::report_region ( void ) const

overridevirtual

Custom fields for each region in the report.

Implements geopm::Agent.

◆ sample_names()

std::vector< std::string > geopm::PowerBalancerAgent::sample_names ( void )

static

◆ sample_platform()

void geopm::PowerBalancerAgent::sample_platform ( std::vector< double > & out_sample )

overridevirtual

Read signals from the platform and interpret/aggregate these signals to create a sample which can be sent up the tree.

Parameters

[out] sample Vector of agent specific sample values to be sent up the tree.

Implements geopm::Agent.

◆ split_policy()

void geopm::PowerBalancerAgent::split_policy	(	const std::vector< double > &	in_policy,
		std::vector< std::vector< double > > &	out_policy
	)

overridevirtual

Called by Controller to split policy for children at next level down the tree.

Parameters

[in]	in_policy	Policy values from the parent.
[out]	out_policy	Vector of policies to be sent to each child.

Implements geopm::Agent.

◆ trace_formats()

std::vector< std::function< std::string(double)> > geopm::PowerBalancerAgent::trace_formats ( void ) const

overridevirtual

Returns format string for each column added to the trace.

Reimplemented from geopm::Agent.

◆ trace_names()

std::vector< std::string > geopm::PowerBalancerAgent::trace_names ( void ) const

overridevirtual

Column headers to be added to the trace.

Implements geopm::Agent.

◆ trace_values()

void geopm::PowerBalancerAgent::trace_values ( std::vector< double > & values )

overridevirtual

Called by Controller to get latest values to be added to the trace.

Implements geopm::Agent.

◆ validate_policy()

void geopm::PowerBalancerAgent::validate_policy ( std::vector< double > & policy ) const

overridevirtual

Called by Controller to validate incoming policy values and configure defaults requested in incoming policy. Policy sender can request default value with 'NaN' at the desired offset in the policy vector. Returned policy should not contain 'NaN's and be consumeable by descend and adjust_platform.

Parameters

[in,out] policy Policy replace NaN's with defaults. If a value of policy is not NaN but the value is not supported by the Agent the method will throw a geopm::Exception with error code GEOPM_ERROR_INVALID.

Implements geopm::Agent.

◆ wait()

void geopm::PowerBalancerAgent::wait ( void )

overridevirtual

Called by Controller to wait for sample period to elapse. This controls the cadence of the Controller main loop.

Implements geopm::Agent.

Member Data Documentation

◆ m_do_send_policy

bool geopm::PowerBalancerAgent::m_do_send_policy

protected

◆ m_do_send_sample

bool geopm::PowerBalancerAgent::m_do_send_sample

protected

◆ m_do_write_batch

bool geopm::PowerBalancerAgent::m_do_write_batch

protected

◆ m_last_wait

struct geopm_time_s geopm::PowerBalancerAgent::m_last_wait

protected

◆ M_MAX_PKG_POWER_SETTING

const double geopm::PowerBalancerAgent::M_MAX_PKG_POWER_SETTING

protected

◆ M_MIN_PKG_POWER_SETTING

const double geopm::PowerBalancerAgent::M_MIN_PKG_POWER_SETTING

protected

◆ m_platform_io

PlatformIO& geopm::PowerBalancerAgent::m_platform_io

protected

◆ m_platform_topo

const PlatformTopo& geopm::PowerBalancerAgent::m_platform_topo

protected

◆ m_power_balancer

std::vector<std::shared_ptr<PowerBalancer> > geopm::PowerBalancerAgent::m_power_balancer

protected

◆ m_power_tdp

double geopm::PowerBalancerAgent::m_power_tdp

protected

◆ m_role

std::shared_ptr<Role> geopm::PowerBalancerAgent::m_role

protected

◆ m_sample_agg

std::shared_ptr<SampleAggregator> geopm::PowerBalancerAgent::m_sample_agg

protected

◆ M_TIME_WINDOW

const double geopm::PowerBalancerAgent::M_TIME_WINDOW

protected

◆ M_WAIT_SEC

const double geopm::PowerBalancerAgent::M_WAIT_SEC

protected

The documentation for this class was generated from the following files:

src/PowerBalancerAgent.hpp
src/PowerBalancerAgent.cpp

Public Types
enum	m_policy_e { M_POLICY_POWER_PACKAGE_LIMIT_TOTAL, M_POLICY_STEP_COUNT, M_POLICY_MAX_EPOCH_RUNTIME, M_POLICY_POWER_SLACK, M_NUM_POLICY }

enum	m_sample_e { M_SAMPLE_STEP_COUNT, M_SAMPLE_MAX_EPOCH_RUNTIME, M_SAMPLE_SUM_POWER_SLACK, M_SAMPLE_MIN_POWER_HEADROOM, M_NUM_SAMPLE }

enum	m_trace_sample_e { M_TRACE_SAMPLE_POLICY_POWER_PACKAGE_LIMIT_TOTAL, M_TRACE_SAMPLE_POLICY_STEP_COUNT, M_TRACE_SAMPLE_POLICY_MAX_EPOCH_RUNTIME, M_TRACE_SAMPLE_POLICY_POWER_SLACK, M_TRACE_SAMPLE_ENFORCED_POWER_LIMIT, M_TRACE_NUM_SAMPLE }

enum	m_step_e { M_STEP_SEND_DOWN_LIMIT = 0L, M_STEP_MEASURE_RUNTIME, M_STEP_REDUCE_LIMIT, M_NUM_STEP }

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Member Enumeration Documentation

◆ m_policy_e

◆ m_sample_e

◆ m_step_e

◆ m_trace_sample_e

Constructor & Destructor Documentation

◆ PowerBalancerAgent() [1/2]

◆ PowerBalancerAgent() [2/2]

◆ ~PowerBalancerAgent()

Member Function Documentation

◆ adjust_platform()

◆ aggregate_sample()

◆ do_send_policy()

◆ do_send_sample()

◆ do_write_batch()

◆ enforce_policy()

◆ format_step_count()

◆ init()

◆ make_plugin()

◆ plugin_name()

◆ policy_names()

◆ report_header()

◆ report_host()

◆ report_region()

◆ sample_names()

◆ sample_platform()

◆ split_policy()

◆ trace_formats()

◆ trace_names()

◆ trace_values()

◆ validate_policy()

◆ wait()

Member Data Documentation

◆ m_do_send_policy

◆ m_do_send_sample

◆ m_do_write_batch

◆ m_last_wait

◆ M_MAX_PKG_POWER_SETTING

◆ M_MIN_PKG_POWER_SETTING

◆ m_platform_io

◆ m_platform_topo

◆ m_power_balancer

◆ m_power_tdp

◆ m_role

◆ m_sample_agg

◆ M_TIME_WINDOW

◆ M_WAIT_SEC