org.eclipse.viatra.dse.api

Class DesignSpaceExplorer

java.lang.Object

org.eclipse.viatra.dse.api.DesignSpaceExplorer

public class DesignSpaceExplorer
extends java.lang.Object

The DesignSpaceExplorer is the main API of the Design Space Exploration engine.

To parameterize the algorithm one must use the following methods after instantiating:

• #setInitialModel(EObject) or it's overloads to set the starting model.
• addTransformationRule(BatchTransformationRule) to define the transformations.
• addObjective(IObjective) to define the objective functions. Use the Objectives helper class for instantiating built-in, configurable objectives.
• startExploration(IStrategy) or it's overloads to start an exploration with the given exploration strategy. Use the Strategies helper class for instantiating built-in, configurable exploration strategies.

Designs Space Exploration is the process of finding a sequence (or sequences) of predefined transformation rules ("transitions") that, if applied in order on the starting model, results in a new model state that fulfills the hard (or goal) constraints and is near optimal with respect to the objectives.

An extension to this paradigm is the introduction of global constraints, which guarantees, that no sequence will be returned, which if executed, results in an intermediate model state that violates the specified global constraints, including the final state. You can add constraints by invoking addGlobalConstraint(IGlobalConstraint).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DesignSpaceExplorer.DseLoggingLevel Enumeration for different use cases of logging, including: OFF - no error messages. WARN - only error and warn messages. BASIC - logs basic information on how the exploration is going. VERBOSE_STRATEGY - logs everything the exploration strategy is prepared for. VERBOSE_FULL - logs every transformation.

Constructor Summary

Constructors

Constructor and Description
DesignSpaceExplorer() Creates a DesignSpaceExplorer object that is able to execute a design space exploration process.

Method Summary

Modifier and Type	Method and Description
void	addDesignSpaceVisulaizer(IDesignSpaceVisualizer visualizer) Registers a design space visualizer.
void	addGlobalConstraint(IGlobalConstraint constraint) Adds a global constraint to the exploration process.
void	addMetaModelPackage(org.eclipse.emf.ecore.EPackage metaModelPackage) Adds a metamodel in the form of EPackage, which is needed for certain guidance.
void	addObjective(IObjective objective) Adds an objective the the exploration process.
void	addTransformationRule(BatchTransformationRule<?,?> rule) Adds a BatchTransformationRule.
SolutionTrajectory	getArbitrarySolution() Returns an arbitrary solution trajectory or null if the exploration failed to find any.
GlobalContext	getGlobalContext() Returns the GlobalContext which holds the configurations such as rule, objectives, etc.
java.util.Set<org.eclipse.emf.ecore.EPackage>	getMetaModelPackages() Returns the EPackages, which were registered with the addMetaModelPackage(EPackage) method.
long	getNumberOfStates() Returns the number of distinct states the exploration process has visited so far.
long	getNumberOfTransitions() Returns the number of distinct transitions the exploration process has discovered (but not necessarily traversed) so far.
java.util.Collection<Solution>	getSolutions() Returns all of the found Solutions, trajectories.
boolean	isDone() Returns true if the strategy decided to stop, and all the threads finished their work.
void	saveModels(org.eclipse.emf.common.notify.Notifier model) Serializes all the found solutions by transforming the given initial model.
void	saveModels(org.eclipse.emf.common.notify.Notifier model, ISolutionNameProvider solutionNameProvider) Serializes all the found solutions by transforming the given initial model.
void	saveModels(org.eclipse.emf.common.notify.Notifier model, java.lang.String extension) Serializes all the found solutions by transforming the given initial model.
void	saveModels(org.eclipse.emf.common.notify.Notifier model, java.lang.String fileNamePrefix, java.lang.String extension) Serializes all the found solutions by transforming the given initial model.
void	setConflictResolver(ConflictResolver conflictResolver) A conflict resolver can filter rule activations the DSE engine will see.
void	setDesignspace(IDesignSpace designspace) Sets the IDesignSpace implementation that is to be used during the design space exploration process.
void	setInitialModel(org.eclipse.emf.common.notify.Notifier model) Defines the initial model of the exploration.
void	setInitialModel(org.eclipse.emf.common.notify.Notifier model, boolean deepCopyModel) Defines the initial model of the exploration, and whether it is supposed to be used to execute the DSE process or it should be cloned.
void	setInitialModelUncloned(org.eclipse.emf.common.notify.Notifier model) Defines the initial model of the exploration.
void	setMaxNumberOfThreads(int maxNumberOfThreads) Defines the maximum processing threads that the design space exploration can use.
void	setSolutionStore(SolutionStore solutionStore) Sets the solution store for strategies.
void	setStateCoderFactory(IStateCoderFactory stateCoderFactory) Sets a IStateCoderFactory for which will be used for creating IStateCoders.
void	startExploration(IStrategy strategy) Starts the design space exploration.
boolean	startExploration(IStrategy strategy, boolean waitForTermination, long timeout) Starts the design space exploration.
void	startExplorationAsync(IStrategy strategy) Starts the design space exploration asynchronously.
boolean	startExplorationAsyncWithTimeout(IStrategy strategy, long timeout) Starts the design space exploration asynchronously with a timeout.
boolean	startExplorationWithTimeout(IStrategy strategy, long timeout) Starts the design space exploration with a timeout.
void	stopExploration() Stops the exploration and waits for termination.
void	stopExplorationAsync() Stops the exploration asynchronously.
java.lang.String	toStringSolutions() Creates a string containing the state codes of all the found solutions and the found trajectories to these solutions with fitness values.
static void	turnOnLogging(DesignSpaceExplorer.DseLoggingLevel dseLoggingLevel) Changes the level of logging.
static void	turnOnLoggingWithBasicConfig(DesignSpaceExplorer.DseLoggingLevel dseLoggingLevel) Changes the level of logging.
void	waitForTerminaition() Waits for termination.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DesignSpaceExplorer

public DesignSpaceExplorer()

Creates a DesignSpaceExplorer object that is able to execute a design space exploration process.

By default the state coder used is the generic (not meta-model specific) GraphHash. You can provide your custom state coder by implementing the IStateCoderFactory and IStateCoder interfaces, and passing the former to the setStateCoderFactory(IStateCoderFactory) method.

Method Detail

addMetaModelPackage

public void addMetaModelPackage(org.eclipse.emf.ecore.EPackage metaModelPackage)

Adds a metamodel in the form of EPackage, which is needed for certain guidance.

Parameters:

metaModelPackage -

setInitialModel

public void setInitialModel(org.eclipse.emf.common.notify.Notifier model,
                            boolean deepCopyModel)

Defines the initial model of the exploration, and whether it is supposed to be used to execute the DSE process or it should be cloned. Please note, that in multithreaded mode any subsequent threads will be working on cloned models.

Parameters:

model - The root object of the EMF model.

deepCopyModel - If it is set to true, the exploration will run on a cloned model.

setInitialModel

public void setInitialModel(org.eclipse.emf.common.notify.Notifier model)

Defines the initial model of the exploration. The model will be cloned, which is desired in most cases as the given model won't be changed.

Parameters:

model - The root object of the EMF model.

setInitialModelUncloned

public void setInitialModelUncloned(org.eclipse.emf.common.notify.Notifier model)

Defines the initial model of the exploration. The given model won't be cloned, thus the exploration will modify it.

Parameters:

model - The root object of the EMF model. It won't be cloned.

addTransformationRule

public void addTransformationRule(BatchTransformationRule<?,?> rule)

Adds a BatchTransformationRule.

Parameters:

rule - The transformationRule.

addGlobalConstraint

public void addGlobalConstraint(IGlobalConstraint constraint)

Adds a global constraint to the exploration process. Please see the IGlobalConstraint interface and its implementations for details.

Parameters:

constraint - The global constraint.

See Also:

IGlobalConstraint

addObjective

public void addObjective(IObjective objective)

Adds an objective the the exploration process. Please see the IObjective interface and its implementations for details.

Parameters:

objective - The objective.

See Also:

IObjective

setStateCoderFactory

public final void setStateCoderFactory(IStateCoderFactory stateCoderFactory)

Sets a IStateCoderFactory for which will be used for creating IStateCoders. The default implementation is the SimpleStateCoderFactory, which works well in most of the cases.

Parameters:

stateCoderFactory - The factory.

setMaxNumberOfThreads

public void setMaxNumberOfThreads(int maxNumberOfThreads)

Defines the maximum processing threads that the design space exploration can use. Note, that this is only limiting the threads doing the actual calculation. By default this value will be set to the number of logical processors (including HyperThreading) in the computer, reported by Runtime.availableProcessors().

Parameters:

maxNumberOfThreads - The number of maximum processing threads available to the design space exploration process.

setDesignspace

public final void setDesignspace(IDesignSpace designspace)

Sets the IDesignSpace implementation that is to be used during the design space exploration process. By default, the DesignSpace implementation is used.

Parameters:

designspace - The IDesignSpace implementation.

setSolutionStore

public void setSolutionStore(SolutionStore solutionStore)

Sets the solution store for strategies. Please see the SolutionStore for how to configure it.

Parameters:

solutionStore - The parameterized SolutionStore implementation.

startExploration

public void startExploration(IStrategy strategy)

Starts the design space exploration. It returns only when the strategy decides to stop the execution.

Parameters:

strategy - The strategy of the exploration.

startExplorationAsync

public void startExplorationAsync(IStrategy strategy)

Starts the design space exploration asynchronously. Completion of the process can be verified by calling isDone().

Parameters:

strategy - The strategy of the exploration.

startExplorationWithTimeout

public boolean startExplorationWithTimeout(IStrategy strategy,
                                           long timeout)

Starts the design space exploration with a timeout. It returns only when the strategy decides to stop the execution or the given timeout is elapsed.

Parameters:

strategy - The strategy of the exploration.

timeout - The number of milliseconds before the exploration is forced to stop.

Returns:

Returns true if the exploration stopped by the timeout.

startExplorationAsyncWithTimeout

public boolean startExplorationAsyncWithTimeout(IStrategy strategy,
                                                long timeout)

Starts the design space exploration asynchronously with a timeout. Completion of the process can be verified by calling isDone().

Parameters:

strategy - The strategy of the exploration.

timeout - The number of milliseconds before the exploration is forced to stop.

Returns:

Returns true if the exploration stopped by the timeout.

startExploration

public boolean startExploration(IStrategy strategy,
                                boolean waitForTermination,
                                long timeout)

Starts the design space exploration. If waitForTermination is true, then it returns only when the strategy decides to stop the execution or there was a timeout, otherwise when the exploration process is started it returns immediately. In this case, process completion can be verified by calling isDone().

Parameters:

strategy - The strategy of the exploration.

waitForTermination - True if the method must wait for the engine to stop, i.e. whether to start synchronously.

timeout - The number of milliseconds before the exploration is forced to stop.

Returns:

Returns true if the exploration stopped by the timeout.

getSolutions

public java.util.Collection<Solution> getSolutions()

Returns all of the found Solutions, trajectories. Call it after DesignSpaceExplorer#startExploration(). Calling this while the process is running returns the solutions that have been found so far. The returned Solution objects may change internal state after they have been returned, if a shorter trajectory has been found to the referred state.

Returns:

The found solutions.

getArbitrarySolution

public SolutionTrajectory getArbitrarySolution()

Returns an arbitrary solution trajectory or null if the exploration failed to find any.

Returns:

An arbitrary solution trajectory.

getNumberOfStates

public long getNumberOfStates()

Returns the number of distinct states the exploration process has visited so far.

Returns:

the number of distinct states.

getNumberOfTransitions

public long getNumberOfTransitions()

Returns the number of distinct transitions the exploration process has discovered (but not necessarily traversed) so far.

Returns:

the number of distinct transitions.

getMetaModelPackages

public java.util.Set<org.eclipse.emf.ecore.EPackage> getMetaModelPackages()

Returns the EPackages, which were registered with the addMetaModelPackage(EPackage) method.

Returns:

The set of meta model packages.

isDone

public boolean isDone()

Returns true if the strategy decided to stop, and all the threads finished their work.

Returns:

true if the process has finished, false otherwise.

getGlobalContext

public GlobalContext getGlobalContext()

Returns the GlobalContext which holds the configurations such as rule, objectives, etc.

Returns:

The global context.

addDesignSpaceVisulaizer

public void addDesignSpaceVisulaizer(IDesignSpaceVisualizer visualizer)

Registers a design space visualizer. Please see the corresponding interface IDesignSpaceVisualizer.

Parameters:

visualizer -

See Also:

IDesignSpaceVisualizer

toStringSolutions

public java.lang.String toStringSolutions()

Creates a string containing the state codes of all the found solutions and the found trajectories to these solutions with fitness values.

Returns:

A pretty string with the solutions.

setConflictResolver

public void setConflictResolver(ConflictResolver conflictResolver)

A conflict resolver can filter rule activations the DSE engine will see. The primary use of this is symmetry reduction. This function is subject to change for better API.

Parameters:

conflictResolver -

turnOnLogging

public static void turnOnLogging(DesignSpaceExplorer.DseLoggingLevel dseLoggingLevel)

Changes the level of logging. See DesignSpaceExplorer.DseLoggingLevel for details.

Parameters:

dseLoggingLevel -

turnOnLoggingWithBasicConfig

public static void turnOnLoggingWithBasicConfig(DesignSpaceExplorer.DseLoggingLevel dseLoggingLevel)

Changes the level of logging. See DesignSpaceExplorer.DseLoggingLevel for details. Also configures a basic console appender for log4j.

Parameters:

dseLoggingLevel -

stopExploration

public void stopExploration()

Stops the exploration and waits for termination. It has no effect if the exploration is already terminated or not even started.

stopExplorationAsync

public void stopExplorationAsync()

Stops the exploration asynchronously. It has no effect if the exploration is already terminated or not even started.

waitForTerminaition

public void waitForTerminaition()

Waits for termination.

saveModels

public void saveModels(org.eclipse.emf.common.notify.Notifier model)

Serializes all the found solutions by transforming the given initial model.

Files will be named solution[id].xmi.

Parameters:

model - The initial model.

saveModels

public void saveModels(org.eclipse.emf.common.notify.Notifier model,
                       java.lang.String extension)

Serializes all the found solutions by transforming the given initial model.

Files will be named solution[id].[extension].

Parameters:

model - The initial model.

extension - The extension of the omitted file.

saveModels

public void saveModels(org.eclipse.emf.common.notify.Notifier model,
                       java.lang.String fileNamePrefix,
                       java.lang.String extension)

Serializes all the found solutions by transforming the given initial model.

Files will be named [fileNamePrefix][id].[extension].

Parameters:

model - The initial model.

fileNamePrefix - The prefix (optionally including a file path) of the omitted file.

extension - The extension of the omitted file.

saveModels

public void saveModels(org.eclipse.emf.common.notify.Notifier model,
                       ISolutionNameProvider solutionNameProvider)

Serializes all the found solutions by transforming the given initial model.

Files will be named using the ISolutionNameProvider.

Parameters:

model - The initial model.