A tuning strategy that uses information collected live from the domain to exclude configurations that knowingly perform worse than other configurations in the current simulation state. More...

#include <RuleBasedTuning.h>

Inheritance diagram for autopas::RuleBasedTuning:

[legend]

Collaboration diagram for autopas::RuleBasedTuning:

[legend]

Public Types
using	PrintTuningErrorFunType = int
	A function type used to print errors found in verify mode.

Public Member Functions
	RuleBasedTuning (const std::set< Configuration > &searchSpace, bool verifyModeEnabled=false, std::string ruleFileName="tuningRules.rule", PrintTuningErrorFunType tuningErrorPrinter={})
	Constructs a RuleBasedTuning strategy.

TuningStrategyOption	getOptionType () const override
	Get this object's associated TuningStrategyOption type.

bool	needsLiveInfo () const override
	Returns whether this tuning strategy wants to get a LiveInfo object passed before a new tuning phase.

void	receiveLiveInfo (const LiveInfo &info) override
	Virtual method that subclasses can override to receive the LiveInfo object before a tuning phase if they return true in needsLiveInfo().

void	addEvidence (const Configuration &configuration, const Evidence &evidence) override
	Notifies the strategy about empirically collected information for the given configuration.

bool	reset (size_t iteration, size_t tuningPhase, std::vector< Configuration > &configQueue, const autopas::EvidenceCollection &evidenceCollection) override
	Reset all internal parameters to the beginning of a new tuning phase.

long	getLifetimeWouldHaveSkippedTuningTime () const

long	getLifetimeTuningTime () const

bool	optimizeSuggestions (std::vector< Configuration > &configQueue, const EvidenceCollection &evidenceCollection) override
	Optimizes the queue of configurations to process.

Public Member Functions inherited from autopas::TuningStrategyInterface
virtual TuningStrategyOption	getOptionType () const =0
	Get this object's associated TuningStrategyOption type.

virtual void	addEvidence (const Configuration &configuration, const Evidence &evidence)
	Notifies the strategy about empirically collected information for the given configuration.

virtual bool	optimizeSuggestions (std::vector< Configuration > &configQueue, const EvidenceCollection &evidenceCollection)=0
	Optimizes the queue of configurations to process.

virtual bool	reset (size_t iteration, size_t tuningPhase, std::vector< Configuration > &configQueue, const autopas::EvidenceCollection &evidenceCollection)=0
	Reset all internal parameters to the beginning of a new tuning phase.

virtual bool	needsLiveInfo () const
	Returns whether this tuning strategy wants to get a LiveInfo object passed before a new tuning phase.

virtual void	receiveLiveInfo (const LiveInfo &info)
	Virtual method that subclasses can override to receive the LiveInfo object before a tuning phase if they return true in needsLiveInfo().

virtual void	rejectConfiguration (const Configuration &configuration, bool indefinitely)
	Notify the strategy about a configuration that is (currently) invalid and thus can potentially be dropped from some internal storage.

virtual bool	needsSmoothedHomogeneityAndMaxDensity () const
	Indicate whether the strategy needs smoothed values of homogeneity and max density.

virtual void	receiveSmoothedHomogeneityAndMaxDensity (double homogeneity, double maxDensity)
	Method to pass smoothed homogeneity and the maximal density to the tuning strategy.

Detailed Description

A tuning strategy that uses information collected live from the domain to exclude configurations that knowingly perform worse than other configurations in the current simulation state.

The remaining configurations are tested consecutively.

This "knowledge" is encoded as rules in a rule file. The rules are defined by the user in a domain specific language, formally described in RuleLanguage.g4, which is parsed by the RuleBasedProgramParser with the help of antlr4. The rules are dynamically loaded and executed as a program for the RuleVM in the beginning of each tuning phase.

Summary of the Rule Language:

The heart of this language are so called configuration orders. Here is one example:

[container="LinkedCells", dataLayout="SoA", newton3="enabled"] >= [container="LinkedCells", dataLayout="AoS",

newton3="enabled"] with same traversal;

This is a rule that states that all configurations that match the pattern to the left of >= are better than all configurations that match the pattern to the right, provided they have the same traversal. The pattern to the left e.g. matches all configuration with container type LinkedCells, data layout SoA and newton3 enabled.

If we want to have this same rule with another container type, e.g. LinkedCellsReferences, we can combine these two using a define_list statement and use that as container type in the rule:

define_list LinkedCellsContainer = "LinkedCells", "LinkedCellsReferences";
[container=LinkedCellsContainer, dataLayout="SoA", newton3="enabled"] >= [container="LinkedCells", dataLayout="AoS",
newton3="enabled"] with same traversal;

Because always applying the same configuration orders would not be very interesting, we can apply them conditionally. For this, all live info collected in the LiveInfo class is available as a variable in the rule program. One example is numParticles. Now let us define a rule which disables all SoA configurations if there are only very few particles, because their AoS counterpart is better:

define lowNumParticlesThreshold = 500;
if numParticles < lowNumParticlesThreshold:
   [dataLayout="AoS"] >= [dataLayout="SoA"] with same container, newton3, traversal, loadEstimator;
endif

At first, we define our threshold as a variable. Variables are always constant and have global visibility. Then, we check if the threshold is not surpassed, and if yes, we apply the configuration order.

A larger example file is stored in /examples/md-flexible/input/tuningRules.rule.

Additionally, the class supports a so called "verify mode" where full search is performed and the given rules are checked for correctness.

Due to the compilation cost of ANTLR and issues with compiling the bundled dependency uuid on some machines, this tuning strategy can be disabled with the CMake option AUTOPAS_ENABLE_RULES_BASED_AND_FUZZY_TUNING=OFF.

Constructor & Destructor Documentation

◆ RuleBasedTuning()

autopas::RuleBasedTuning::RuleBasedTuning	(	const std::set< Configuration > &	searchSpace,
		bool	verifyModeEnabled = `false`,
		std::string	ruleFileName = `"tuningRules.rule"`,
		RuleBasedTuning::PrintTuningErrorFunType	tuningErrorPrinter = `{}`
	)

explicit

Constructs a RuleBasedTuning strategy.

Parameters

searchSpace	Set of all allowed configurations.
verifyModeEnabled	If verify mode should be enabled. False by default.
ruleFileName	The name of the file where the rules are stored.
tuningErrorPrinter	The function to call in verify mode if errors are found.

Member Function Documentation

◆ addEvidence()

void autopas::RuleBasedTuning::addEvidence	(	const Configuration &	configuration,
		const Evidence &	evidence
	)

overridevirtual

Notifies the strategy about empirically collected information for the given configuration.

All evidence is stored centrally in the AutoTuner and its EvidenceCollection is passed to the tuning strategies during optimization.

Implementing this function is only necessary if the tuning strategy processes evidence differently than EvidenceCollection.

Parameters

configuration	Configuration used to obtain the evidence.
evidence	Measurement and when it was taken.

Reimplemented from autopas::TuningStrategyInterface.

◆ getLifetimeTuningTime()

long autopas::RuleBasedTuning::getLifetimeTuningTime ( ) const

Returns: the total time spent trialling configurations suggested by this tuning strategy.

◆ getLifetimeWouldHaveSkippedTuningTime()

long autopas::RuleBasedTuning::getLifetimeWouldHaveSkippedTuningTime ( ) const

Returns: the total time that would have been skipped if verify mode was disabled and thus some configurations would have been skipped due to the rules.

◆ getOptionType()

TuningStrategyOption autopas::RuleBasedTuning::getOptionType ( ) const

overridevirtual

Get this object's associated TuningStrategyOption type.

Returns: TuningStrategyOption

Implements autopas::TuningStrategyInterface.

◆ needsLiveInfo()

bool autopas::RuleBasedTuning::needsLiveInfo ( ) const

overridevirtual

Returns whether this tuning strategy wants to get a LiveInfo object passed before a new tuning phase.

Returns: True, if this tuning strategy wants a LiveInfo object passed before a new tuning phase via receiveLiveInfo().

Reimplemented from autopas::TuningStrategyInterface.

◆ optimizeSuggestions()

bool autopas::RuleBasedTuning::optimizeSuggestions	(	std::vector< Configuration > &	configQueue,
		const EvidenceCollection &	evidenceCollection
	)

overridevirtual

Optimizes the queue of configurations to process.

This function is called once before each iteration in a tuning phase so all tuning strategies can give their input on which configuration to try next. This is done by reordering configQueue so that the next configuration to try is at the end (FIFO).

Parameters

configQueue	Queue of configurations to be tested. The tuning strategy should edit this queue.
evidenceCollection	All collected evidence until now.

Returns: boolean value to signal if the tuning strategy has intentionally wiped the config queue

Implements autopas::TuningStrategyInterface.

◆ receiveLiveInfo()

void autopas::RuleBasedTuning::receiveLiveInfo ( const LiveInfo & info )

overridevirtual

Virtual method that subclasses can override to receive the LiveInfo object before a tuning phase if they return true in needsLiveInfo().

Parameters

info	A new LiveInfo object that has already gathered its information.

Reimplemented from autopas::TuningStrategyInterface.

◆ reset()

bool autopas::RuleBasedTuning::reset	(	size_t	iteration,
		size_t	tuningPhase,
		std::vector< Configuration > &	configQueue,
		const autopas::EvidenceCollection &	evidenceCollection
	)

overridevirtual

Reset all internal parameters to the beginning of a new tuning phase.

This can also mean to reorder the configQueue to some initially expected state.

Parameters

iteration	Gives the current iteration to the tuning strategy.
tuningPhase	Gives the current tuning phase to the tuning strategy.
configQueue	Queue of configurations to be tested. The tuning strategy should edit this queue.
evidenceCollection	All collected evidence until now.

Returns: boolean value to signal if the tuning strategy has intentionally wiped the config queue

Implements autopas::TuningStrategyInterface.

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

autopas/tuning/tuningStrategy/ruleBasedTuning/RuleBasedTuning.h
autopas/tuning/tuningStrategy/ruleBasedTuning/RuleBasedTuning.cpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RuleBasedTuning()

Member Function Documentation

◆ addEvidence()

◆ getLifetimeTuningTime()

◆ getLifetimeWouldHaveSkippedTuningTime()

◆ getOptionType()

◆ needsLiveInfo()

◆ optimizeSuggestions()

◆ receiveLiveInfo()

◆ reset()