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

    All Methods Static Methods Instance Methods Concrete Methods
    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 `EPackage`s, 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 `Solution`s, 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 `IStateCoder`s.
    `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 `IStateCoder`s. 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 `Solution`s, 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 `EPackage`s, 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.