1 files changed, 622 insertions, 0 deletions

diff --git a/Solvers/VIATRA-Solver/org.eclipse.viatra.dse/src/org/eclipse/viatra/dse/api/DesignSpaceExplorer.java b/Solvers/VIATRA-Solver/org.eclipse.viatra.dse/src/org/eclipse/viatra/dse/api/DesignSpaceExplorer.java
new file mode 100644
index 00000000..9cd6e68a
--- /dev/null
+++ b/Solvers/VIATRA-Solver/org.eclipse.viatra.dse/src/org/eclipse/viatra/dse/api/DesignSpaceExplorer.java
@@ -0,0 +1,622 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2014, Miklos Foldenyi, Andras Szabolcs Nagy, Abel Hegedus, Akos Horvath, Zoltan Ujhelyi and Daniel Varro
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-v20.html.
+ * 
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+package org.eclipse.viatra.dse.api;
+
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.Timer;
+import java.util.TimerTask;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import org.apache.log4j.BasicConfigurator;
+import org.apache.log4j.Level;
+import org.apache.log4j.Logger;
+import org.eclipse.emf.common.notify.Notifier;
+import org.eclipse.emf.ecore.EObject;
+import org.eclipse.emf.ecore.EPackage;
+import org.eclipse.viatra.dse.api.strategy.interfaces.IStrategy;
+import org.eclipse.viatra.dse.base.DesignSpaceManager;
+import org.eclipse.viatra.dse.base.GlobalContext;
+import org.eclipse.viatra.dse.designspace.api.DesignSpace;
+import org.eclipse.viatra.dse.designspace.api.IDesignSpace;
+import org.eclipse.viatra.dse.objectives.IGlobalConstraint;
+import org.eclipse.viatra.dse.objectives.IObjective;
+import org.eclipse.viatra.dse.solutionstore.ISolutionNameProvider;
+import org.eclipse.viatra.dse.solutionstore.IdBasedSolutionNameProvider;
+import org.eclipse.viatra.dse.solutionstore.SolutionStore;
+import org.eclipse.viatra.dse.statecode.IStateCoder;
+import org.eclipse.viatra.dse.statecode.IStateCoderFactory;
+import org.eclipse.viatra.dse.statecoding.simple.SimpleStateCoderFactory;
+import org.eclipse.viatra.dse.visualizer.IDesignSpaceVisualizer;
+import org.eclipse.viatra.query.runtime.matchers.util.Preconditions;
+import org.eclipse.viatra.transformation.evm.api.resolver.ConflictResolver;
+import org.eclipse.viatra.transformation.runtime.emf.rules.batch.BatchTransformationRule;
+
+/**
+ * <p>
+ * The {@link DesignSpaceExplorer} is the main API of the <b>Design Space Exploration</b> engine.
+ * </p>
+ * 
+ * <p>
+ * To parameterize the algorithm one must use the following methods after instantiating:
+ * <ul>
+ * <li>{@link #setInitialModel(EObject)} or it's overloads to set the starting model.</li>
+ * <li>{@link #addTransformationRule(BatchTransformationRule)} to define the transformations.</li> <li
+ * {@link #addObjective(IObjective)} to define the objective functions. Use the {@link Objectives} helper class for
+ * instantiating built-in, configurable objectives.</li>
+ * <li>{@link #startExploration(IStrategy)} or it's overloads to start an exploration with the given exploration
+ * strategy. Use the {@link Strategies} helper class for instantiating built-in, configurable exploration strategies.
+ * </li>
+ * </ul>
+ * </p>
+ * 
+ * <p>
+ * <b>Designs Space Exploration</b> 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.
+ * </p>
+ * 
+ * <p>
+ * 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 {@link #addGlobalConstraint(IGlobalConstraint)}.
+ * </p>
+ * 
+ * @author Andras Szabolcs Nagy & Miklos Foldenyi
+ * 
+ */
+public class DesignSpaceExplorer {
+
+    private Notifier model;
+
+    private GlobalContext globalContext = new GlobalContext();
+
+    private final Logger logger = Logger.getLogger(this.getClass());
+
+    private Set<EPackage> metaModelPackages = new HashSet<EPackage>();
+
+    private static final String MODEL_NOT_YET_GIVEN = "The starting model is not given yet. Please call the setInitialModel method first.";
+
+    private boolean deepCopyModel;
+
+    /**
+     * <p>
+     * Creates a {@link DesignSpaceExplorer} object that is able to execute a design space exploration process.
+     * </p>
+     * 
+     * <p>
+     * By default the state coder used is the generic (not meta-model specific) {@link GraphHash}. You can provide your
+     * custom state coder by implementing the {@link IStateCoderFactory} and {@link IStateCoder} interfaces, and passing
+     * the former to the {@link #setStateCoderFactory(IStateCoderFactory)} method.
+     * 
+     */
+    public DesignSpaceExplorer() {
+        setDesignspace(new DesignSpace());
+    }
+
+    /**
+     * Adds a metamodel in the form of {@link EPackage}, which is needed for certain guidance.
+     * 
+     * @param metaModelPackage
+     */
+    public void addMetaModelPackage(EPackage metaModelPackage) {
+        metaModelPackages.add(metaModelPackage);
+    }
+
+    /**
+     * 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.
+     * 
+     * @param model
+     *            The root object of the EMF model.
+     * @param deepCopyModel
+     *            If it is set to true, the exploration will run on a cloned model.
+     */
+    public void setInitialModel(Notifier model, boolean deepCopyModel) {
+        this.model = model;
+        this.deepCopyModel = deepCopyModel;
+    }
+
+    /**
+     * 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.
+     * 
+     * @param model
+     *            The root object of the EMF model.
+     */
+    public void setInitialModel(Notifier model) {
+        setInitialModel(model, true);
+    }
+
+    /**
+     * Defines the initial model of the exploration. The given model won't be cloned, thus the exploration will modify
+     * it.
+     * 
+     * @param model
+     *            The root object of the EMF model. It won't be cloned.
+     */
+    public void setInitialModelUncloned(Notifier model) {
+        setInitialModel(model, false);
+    }
+
+    /**
+     * Adds a {@link BatchTransformationRule}.
+     * 
+     * @param rule
+     *            The transformationRule.
+     */
+    public void addTransformationRule(BatchTransformationRule<?, ?> rule) {
+        Preconditions.checkArgument(rule != null);
+        for (BatchTransformationRule<?, ?> rule2 : globalContext.getTransformations()) {
+            if (rule.getPrecondition().equals(rule2.getPrecondition())) {
+                throw new DSEException(
+                        "Two transformation rule ("
+                                + rule.getName()
+                                + "; "
+                                + rule2.getName()
+                                + ") uses the same LHS VIATRA Query pattern ("
+                                + rule.getPrecondition().getFullyQualifiedName()
+                                + "), which may lead to hash collision."
+                                + " Please wrap the pattern with an other pattern with the 'find' keyword (or duplicate the code), and use that for one of the rules LHS.");
+            }
+        }
+
+        globalContext.getTransformations().add(rule);
+    }
+
+    /**
+     * Adds a global constraint to the exploration process. Please see the {@link IGlobalConstraint} interface and its
+     * implementations for details.
+     * 
+     * @param constraint
+     *            The global constraint.
+     * @see IGlobalConstraint
+     */
+    public void addGlobalConstraint(IGlobalConstraint constraint) {
+        globalContext.getGlobalConstraints().add(constraint);
+    }
+
+    /**
+     * Adds an objective the the exploration process. Please see the {@link IObjective} interface and its
+     * implementations for details.
+     * 
+     * @param objective
+     *            The objective.
+     * @see IObjective
+     */
+    public void addObjective(IObjective objective) {
+        for (IObjective o : globalContext.getObjectives()) {
+            if (o.getName().equals(objective.getName())) {
+                throw new DSEException("Two objectives with the same name cannot be registered:" + o.getName());
+            }
+        }
+        globalContext.getObjectives().add(objective);
+    }
+
+    /**
+     * Sets a {@link IStateCoderFactory} for which will be used for creating {@link IStateCoder}s. The default
+     * implementation is the {@link SimpleStateCoderFactory}, which works well in most of the cases.
+     * 
+     * @param stateCoderFactory
+     *            The factory.
+     */
+    public final void setStateCoderFactory(IStateCoderFactory stateCoderFactory) {
+        globalContext.setStateCoderFactory(stateCoderFactory);
+    }
+
+    /**
+     * 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 {@link Runtime#availableProcessors()}.
+     * 
+     * @param maxNumberOfThreads
+     *            The number of maximum processing threads available to the design space exploration process.
+     */
+    public void setMaxNumberOfThreads(int maxNumberOfThreads) {
+        globalContext.getThreadPool().setMaximumPoolSize(maxNumberOfThreads);
+    }
+
+    /**
+     * Sets the {@link IDesignSpace} implementation that is to be used during the design space exploration process. By
+     * default, the {@link DesignSpace} implementation is used.
+     * 
+     * @param designspace
+     *            The {@link IDesignSpace} implementation.
+     */
+    public final void setDesignspace(IDesignSpace designspace) {
+        globalContext.setDesignSpace(designspace);
+    }
+
+    /**
+     * Sets the solution store for strategies. Please see the {@link SolutionStore} for how to configure it.
+     * 
+     * @param solutionStore
+     *            The parameterized {@link SolutionStore} implementation.
+     */
+    public void setSolutionStore(SolutionStore solutionStore) {
+        globalContext.setSolutionStore(solutionStore);
+    }
+
+    /**
+     * Starts the design space exploration. It returns only when the strategy decides to stop the execution.
+     * 
+     * @param strategy
+     *            The strategy of the exploration.
+     */
+    public void startExploration(IStrategy strategy) {
+        startExploration(strategy, true, -1);
+    }
+
+    /**
+     * Starts the design space exploration asynchronously. Completion of the process can be verified by calling
+     * {@link DesignSpaceExplorer#isDone()}.
+     * 
+     * @param strategy
+     *            The strategy of the exploration.
+     */
+    public void startExplorationAsync(IStrategy strategy) {
+        startExploration(strategy, false, -1);
+    }
+
+    /**
+     * 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.
+     * 
+     * @param strategy
+     *            The strategy of the exploration.
+     * @param timeout
+     *            The number of milliseconds before the exploration is forced to stop.
+     * @return Returns true if the exploration stopped by the timeout.
+     */
+    public boolean startExplorationWithTimeout(IStrategy strategy, long timeout) {
+        return startExploration(strategy, true, timeout);
+    }
+
+    /**
+     * Starts the design space exploration asynchronously with a timeout. Completion of the process can be verified by
+     * calling {@link DesignSpaceExplorer#isDone()}.
+     * 
+     * @param strategy
+     *            The strategy of the exploration.
+     * @param timeout
+     *            The number of milliseconds before the exploration is forced to stop.
+     * @return Returns true if the exploration stopped by the timeout.
+     */
+    public boolean startExplorationAsyncWithTimeout(IStrategy strategy, long timeout) {
+        return startExploration(strategy, false, timeout);
+    }
+
+    /**
+     * Starts the design space exploration. If {@code 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
+     * {@link DesignSpaceExplorer#isDone()}.
+     * 
+     * @param strategy
+     *            The strategy of the exploration.
+     * @param waitForTermination
+     *            True if the method must wait for the engine to stop, i.e. whether to start synchronously.
+     * @param timeout
+     *            The number of milliseconds before the exploration is forced to stop.
+     * @return Returns true if the exploration stopped by the timeout.
+     */
+    public boolean startExploration(IStrategy strategy, boolean waitForTermination, final long timeout) {
+        initExploration(strategy);
+
+        Timer timer = new Timer();
+        final AtomicBoolean wasTimeout = new AtomicBoolean(false);
+
+        if (timeout > 0) {
+            TimerTask timerTask = new TimerTask() {
+                @Override
+                public void run() {
+                    logger.info("Timeout, stopping threads...");
+                    globalContext.stopAllThreads();
+                    wasTimeout.set(true);
+                }
+            };
+            timer.schedule(timerTask, timeout);
+        }
+
+        if (waitForTermination) {
+            waitForTerminaition();
+            timer.cancel();
+        } else {
+            logger.info("Design space exploration started asynchronously.");
+        }
+
+        return wasTimeout.get();
+
+    }
+
+    private void initExploration(IStrategy strategy) {
+        Preconditions.checkArgument(model != null, MODEL_NOT_YET_GIVEN);
+        Preconditions.checkArgument(strategy != null, "A strategy must be given. Use the Strategies helper class.");
+        Preconditions.checkState(!globalContext.getTransformations().isEmpty(),
+                "At least one transformation rule must be added to start the exploration.");
+
+        if (globalContext.getStateCoderFactory() == null) {
+            if (getMetaModelPackages() == null || getMetaModelPackages().isEmpty()) {
+                throw new DSEException("Cannot initialize state coder."
+                        + " Please specifiy the EPackages your model uses with addMetaModelPackage(EPackage)");
+            }
+            globalContext.setStateCoderFactory(new SimpleStateCoderFactory(getMetaModelPackages()));
+        }
+
+        logger.info("DesignSpaceExplorer started exploration.");
+
+        if (deepCopyModel) {
+            globalContext.startFirstThread(strategy, model);
+        } else {
+            globalContext.startFirstThreadWithoutModelClone(strategy, model);
+        }
+    }
+
+    /**
+     * Returns all of the found {@link Solution}s, trajectories. Call it after
+     * {@link DesignSpaceExplorer#startExploration()}. Calling this while the process is running returns the solutions
+     * that have been found <b>so far</b>. The returned {@link Solution} objects may change internal state after they
+     * have been returned, if a shorter trajectory has been found to the referred state.
+     * 
+     * @return The found solutions.
+     */
+    public Collection<Solution> getSolutions() {
+        return globalContext.getSolutionStore().getSolutions();
+    }
+
+    /**
+     * Returns an arbitrary solution trajectory or null if the exploration failed to find any.
+     * 
+     * @return An arbitrary solution trajectory.
+     */
+    public SolutionTrajectory getArbitrarySolution() {
+        Collection<Solution> solutions = getSolutions();
+        if (solutions.isEmpty()) {
+            return null;
+        }
+        return solutions.iterator().next().getArbitraryTrajectory();
+    }
+
+    /**
+     * Returns the number of distinct states the exploration process has visited so far.
+     * 
+     * @return the number of distinct states.
+     */
+    public long getNumberOfStates() {
+        return globalContext.getDesignSpace().getNumberOfStates();
+    }
+
+    /**
+     * Returns the number of distinct transitions the exploration process has discovered (but not necessarily traversed)
+     * so far.
+     * 
+     * @return the number of distinct transitions.
+     */
+    public long getNumberOfTransitions() {
+        return globalContext.getDesignSpace().getNumberOfTransitions();
+    }
+
+    /**
+     * Returns the {@link EPackage}s, which were registered with the
+     * {@link DesignSpaceExplorer#addMetaModelPackage(EPackage)} method.
+     * 
+     * @return The set of meta model packages.
+     */
+    public Set<EPackage> getMetaModelPackages() {
+        return metaModelPackages;
+    }
+
+    /**
+     * Returns true if the {@link IExplorerThread strategy} decided to stop, and all the threads finished their work.
+     * 
+     * @return true if the process has finished, false otherwise.
+     */
+    public boolean isDone() {
+        return globalContext.isDone();
+    }
+
+    /**
+     * Returns the {@link GlobalContext} which holds the configurations such as rule, objectives, etc.
+     * 
+     * @return The global context.
+     */
+    public GlobalContext getGlobalContext() {
+        return globalContext;
+    }
+
+    /**
+     * Registers a design space visualizer. Please see the corresponding interface {@link IDesignSpaceVisualizer}.
+     * 
+     * @see IDesignSpaceVisualizer
+     * 
+     * @param visualizer
+     */
+    public void addDesignSpaceVisulaizer(IDesignSpaceVisualizer visualizer) {
+        globalContext.registerDesignSpaceVisualizer(visualizer);
+    }
+
+    /**
+     * Creates a string containing the state codes of all the found solutions and the found trajectories to these
+     * solutions with fitness values.
+     * 
+     * @return A pretty string with the solutions.
+     */
+    public String toStringSolutions() {
+        StringBuilder sb = new StringBuilder();
+        Collection<Solution> solutions = getSolutions();
+        sb.append("Number of solutions: ");
+        sb.append(solutions.size());
+        sb.append("\n");
+        for (Solution solution : solutions) {
+            sb.append("Solution: ");
+            sb.append(solution.getStateCode());
+            sb.append("\n");
+            for (SolutionTrajectory trajectory : solution.getTrajectories()) {
+                sb.append("  ");
+                sb.append(trajectory.toPrettyString());
+                sb.append("\n");
+            }
+        }
+        return sb.toString();
+    }
+
+    /**
+     * 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.
+     * 
+     * @param conflictResolver
+     */
+    public void setConflictResolver(ConflictResolver conflictResolver) {
+        globalContext.setConflictResolver(conflictResolver);
+    }
+
+    /**
+     * Enumeration for different use cases of logging, including:
+     * <ul>
+     * <li>OFF - no error messages.</li>
+     * <li>WARN - only error and warn messages.</li>
+     * <li>BASIC - logs basic information on how the exploration is going.</li>
+     * <li>VERBOSE_STRATEGY - logs everything the exploration strategy is prepared for.</li>
+     * <li>VERBOSE_FULL - logs every transformation.</li>
+     * </ul>
+     * 
+     * @author Andras Szabolcs Nagy
+     *
+     */
+    public enum DseLoggingLevel {
+        OFF, WARN, BASIC, VERBOSE_STRATEGY, VERBOSE_FULL
+    }
+
+    /**
+     * Changes the level of logging. See {@link DseLoggingLevel} for details.
+     * 
+     * @param dseLoggingLevel
+     */
+    public static void turnOnLogging(DseLoggingLevel dseLoggingLevel) {
+        switch (dseLoggingLevel) {
+        case OFF:
+            Logger.getLogger(DesignSpaceExplorer.class).setLevel(Level.OFF);
+            Logger.getLogger(IStrategy.class).setLevel(Level.OFF);
+            Logger.getLogger(DesignSpaceManager.class).setLevel(Level.OFF);
+            break;
+        case WARN:
+            Logger.getLogger(DesignSpaceExplorer.class).setLevel(Level.WARN);
+            Logger.getLogger(IStrategy.class).setLevel(Level.WARN);
+            Logger.getLogger(DesignSpaceManager.class).setLevel(Level.WARN);
+            break;
+        case BASIC:
+            Logger.getLogger(DesignSpaceExplorer.class).setLevel(Level.INFO);
+            Logger.getLogger(IStrategy.class).setLevel(Level.INFO);
+            Logger.getLogger(DesignSpaceManager.class).setLevel(Level.WARN);
+            break;
+        case VERBOSE_STRATEGY:
+            Logger.getLogger(DesignSpaceExplorer.class).setLevel(Level.DEBUG);
+            Logger.getLogger(IStrategy.class).setLevel(Level.DEBUG);
+            Logger.getLogger(DesignSpaceManager.class).setLevel(Level.WARN);
+            break;
+        case VERBOSE_FULL:
+            Logger.getLogger(DesignSpaceExplorer.class).setLevel(Level.DEBUG);
+            Logger.getLogger(IStrategy.class).setLevel(Level.DEBUG);
+            Logger.getLogger(DesignSpaceManager.class).setLevel(Level.DEBUG);
+            break;
+        default:
+            throw new DSEException("Not supported logging level.");
+        }
+    }
+
+    /**
+     * Changes the level of logging. See {@link DseLoggingLevel} for details.
+     * 
+     * Also configures a basic console appender for log4j.
+     * 
+     * @param dseLoggingLevel
+     */
+    public static void turnOnLoggingWithBasicConfig(DseLoggingLevel dseLoggingLevel) {
+        BasicConfigurator.configure();
+        Logger.getRootLogger().setLevel(Level.WARN);
+        turnOnLogging(dseLoggingLevel);
+    }
+
+    /**
+     * Stops the exploration and waits for termination. It has no effect if the exploration is already terminated or not
+     * even started.
+     */
+    public void stopExploration() {
+        if (globalContext.isDone()) {
+            logger.info("Cannot stop exploration - design space exploration has already finished.");
+        } else if (globalContext.isNotStarted()) {
+            logger.info("Cannot stop exploration - design space exploration has not been started.");
+        } else {
+            globalContext.stopAllThreads();
+            waitForTerminaition();
+        }
+    }
+
+    /**
+     * Stops the exploration asynchronously. It has no effect if the exploration is already terminated or not even
+     * started.
+     */
+    public void stopExplorationAsync() {
+        if (globalContext.isDone()) {
+            logger.info("Cannot stop exploration - design space exploration has already finished.");
+        } else if (globalContext.isNotStarted()) {
+            logger.info("Cannot stop exploration - design space exploration has not been started.");
+        } else {
+            globalContext.stopAllThreads();
+        }
+    }
+
+    /**
+     * Waits for termination.
+     */
+    public void waitForTerminaition() {
+        globalContext.waitForTermination();
+    }
+
+    /**
+     * Serializes all the found solutions by transforming the given initial model.
+     * </p>Files will be named <code>solution[id].xmi</code>.
+     * @param model The initial model.
+     */
+    public void saveModels(Notifier model) {
+        this.saveModels(model, "solution", "xmi");
+    }
+
+    /**
+     * Serializes all the found solutions by transforming the given initial model.
+     * </p>Files will be named <code>solution[id].[extension]</code>.
+     * @param model The initial model.
+     * @param extension The extension of the omitted file.
+     */
+    public void saveModels(Notifier model, String extension) {
+        this.saveModels(model, "solution", extension);
+    }
+
+    /**
+     * Serializes all the found solutions by transforming the given initial model.
+     * </p>Files will be named <code>[fileNamePrefix][id].[extension]</code>.
+     * @param model The initial model.
+     * @param fileNamePrefix The prefix (optionally including a file path) of the omitted file.
+     * @param extension The extension of the omitted file.
+     */
+    public void saveModels(Notifier model, String fileNamePrefix, String extension) {
+        globalContext.getSolutionStore().saveModels(model, new IdBasedSolutionNameProvider(fileNamePrefix, extension));
+    }
+
+    /**
+     * Serializes all the found solutions by transforming the given initial model.
+     * </p>Files will be named using the {@link ISolutionNameProvider}.
+     * @param model The initial model.
+     */
+    public void saveModels(Notifier model, ISolutionNameProvider solutionNameProvider) {
+        globalContext.getSolutionStore().saveModels(model, solutionNameProvider);
+    }
+}