MOEA Framework 2.12
API Specification

org.moeaframework
Class Instrumenter

java.lang.Object
  extended by org.moeaframework.Instrumenter

public class Instrumenter
extends Object

Instruments algorithms with Collectors which record information about the runtime behavior of algorithms. First, the instrumenter walks the object graph of an algorithm to determine its composition. Upon finding objects which can be instrumented, it attaches the corresponding collector. Next, the instrumenter returns an InstrumentedAlgorithm, which orchestrates the collection of runtime information as the algorithm is executed. Lastly, the InstrumentedAlgorithm stores the runtime information, which can subsequently be accessed and analyzed.

   Instrumenter instrumenter = new Instrumenter()
     .withProblem(problemName)
     .attachAll();
 
   Executor executor = new Executor()
     .withProblem(problemName)
     .withAlgorithm(algorithmName)
     .withMaxEvaluations(numberOfEvaluations)
     .withInstrumenter(instrumenter)
     .run();
 
   Accumulator accumulator = instrumenter.getLastAccumulator();
 


Constructor Summary
Instrumenter()
          Constructs a new instrumenter instance, initially with no collectors.
 
Method Summary
 Instrumenter addAllowedPackage(String packageName)
          Deprecated. has no effect
 Instrumenter attach(Collector collector)
          Includes the specified collector when instrumenting algorithms.
 Instrumenter attachAdaptiveMultimethodVariationCollector()
          Includes the adaptive multimethod variation collector when instrumenting algorithms.
 Instrumenter attachAdaptiveTimeContinuationCollector()
          Includes the adaptive time continuation collector when instrumenting algorithms.
 Instrumenter attachAdditiveEpsilonIndicatorCollector()
          Includes the additive ε-indicator collector when instrumenting algorithms.
 Instrumenter attachAll()
          Includes all collectors when instrumenting algorithms.
 Instrumenter attachAllMetricCollectors()
          Includes all indicator collectors when instrumenting algorithms.
 Instrumenter attachApproximationSetCollector()
          Includes the approximation set collector when instrumenting algorithms.
 Instrumenter attachContributionCollector()
          Includes the contribution collector when instrumenting algorithms.
 Instrumenter attachElapsedTimeCollector()
          Includes the elapsed time collector when instrumenting algorithms.
 Instrumenter attachEpsilonProgressCollector()
          Includes the ε-progress collector when instrumenting algorithms.
 Instrumenter attachGenerationalDistanceCollector()
          Includes the generational distance collector when instrumenting algorithms.
 Instrumenter attachHypervolumeCollector()
          Includes the hypervolume collector when instrumenting algorithms.
 Instrumenter attachInvertedGenerationalDistanceCollector()
          Includes the inverted generational distance collector when instrumenting algorithms.
 Instrumenter attachPopulationSizeCollector()
          Includes the population size collector when instrumenting algorithms.
 Instrumenter attachR1Collector()
          Includes the R1 collector when instrumenting algorithms.
 Instrumenter attachR2Collector()
          Includes the R2 collector when instrumenting algorithms.
 Instrumenter attachR3Collector()
          Includes the R3 collector when instrumenting algorithms.
 Instrumenter attachSpacingCollector()
          Includes the spacing collector when instrumenting algorithms.
 List<String> getAllowedPackages()
          Deprecated. has no effect
 Accumulator getLastAccumulator()
          Returns the accumulator from the last instrumented algorithm.
 NondominatedPopulation getReferenceSet()
          Returns the reference set used by this builder.
 InstrumentedAlgorithm instrument(Algorithm algorithm)
          Instruments the specified algorithm, returning an InstrumentedAlgorithm to be used to execute the algorithm and store the data produced by any attached instruments.
protected  void instrument(InstrumentedAlgorithm algorithm, List<Collector> collectors, Set<Object> visited, Stack<Object> parents, Object object, Class<?> type)
          Recursively walks the object graph to 1) determine the nesting of objects to help determine which objects are to be instrumented; and 2) attach the collectors to any matching objects.
 Instrumenter removeAllowedPackage(String packageName)
          Deprecated. has no effect
 Instrumenter usingProblemFactory(ProblemFactory problemFactory)
          Sets the problem factory used by this builder.
 Instrumenter withEpsilon(double... epsilon)
          Sets the ε values used by this builder, specifying the archive returned by newArchive().
 Instrumenter withFrequency(int frequency)
          Sets the frequency that data is collected.
 Instrumenter withFrequencyType(PeriodicAction.FrequencyType frequencyType)
          Indicates if the frequency is defined in terms of the number of evaluations or number of steps (iterations).
 Instrumenter withProblem(Problem problemInstance)
          Sets the problem instance used by this builder.
 Instrumenter withProblem(String problemName)
          Sets the problem used by this builder.
 Instrumenter withProblemClass(Class<?> problemClass, Object... problemArguments)
          Sets the problem used by this builder.
 Instrumenter withProblemClass(String problemClassName, Object... problemArguments)
          Sets the problem used by this builder.
 Instrumenter withReferenceSet(File referenceSetFile)
          Sets the file containing the reference set to be used by this builder.
 Instrumenter withSameProblemAs(org.moeaframework.ProblemBuilder builder)
          Configures this builder to use the same problem, reference set, ε values and ProblemFactory as the specified instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Instrumenter

public Instrumenter()
Constructs a new instrumenter instance, initially with no collectors.

Method Detail

getLastAccumulator

public Accumulator getLastAccumulator()
Returns the accumulator from the last instrumented algorithm. The accumulator will be filled with the runtime information as the algorithm is executed.

Returns:
the accumulator from the last instrumented algorithm

addAllowedPackage

@Deprecated
public Instrumenter addAllowedPackage(String packageName)
Deprecated. has no effect

Allows this instrumenter to visit classes in the given package. Some Java classes can not be readily visited/discovered by this instrumenter, possibly resulting in a NullPointerException or a SecurityException. Therefore, the instrumenter can only visit classes explicitly allowed by the user. By default, org.moeaframework is allowed.

Parameters:
packageName - a package name or the package name prefix
Returns:
a reference to this instrumenter

removeAllowedPackage

@Deprecated
public Instrumenter removeAllowedPackage(String packageName)
Deprecated. has no effect

Removes one of the packages this instrumenter is allowed to visit. Note that the given string must match the string passed to addAllowedPackage(String).

Parameters:
packageName - the package name or package name prefix to remove
Returns:
a reference to this instrumenter

getAllowedPackages

@Deprecated
public List<String> getAllowedPackages()
Deprecated. has no effect

Returns all packages this instrumenter is allowed to visit.

Returns:
the list of allowed package names

withFrequency

public Instrumenter withFrequency(int frequency)
Sets the frequency that data is collected.

Parameters:
frequency - the frequency
Returns:
a reference to this instrumenter

withFrequencyType

public Instrumenter withFrequencyType(PeriodicAction.FrequencyType frequencyType)
Indicates if the frequency is defined in terms of the number of evaluations or number of steps (iterations).

Parameters:
frequencyType - the frequency type, either EVALUATIONS or STEPS
Returns:
a reference to this instrumenter

attach

public Instrumenter attach(Collector collector)
Includes the specified collector when instrumenting algorithms.

Parameters:
collector - the collector to include when instrumenting algorithms
Returns:
a reference to this instrumenter

attachHypervolumeCollector

public Instrumenter attachHypervolumeCollector()
Includes the hypervolume collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachGenerationalDistanceCollector

public Instrumenter attachGenerationalDistanceCollector()
Includes the generational distance collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachInvertedGenerationalDistanceCollector

public Instrumenter attachInvertedGenerationalDistanceCollector()
Includes the inverted generational distance collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachSpacingCollector

public Instrumenter attachSpacingCollector()
Includes the spacing collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachAdditiveEpsilonIndicatorCollector

public Instrumenter attachAdditiveEpsilonIndicatorCollector()
Includes the additive ε-indicator collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachContributionCollector

public Instrumenter attachContributionCollector()
Includes the contribution collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachR1Collector

public Instrumenter attachR1Collector()
Includes the R1 collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachR2Collector

public Instrumenter attachR2Collector()
Includes the R2 collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachR3Collector

public Instrumenter attachR3Collector()
Includes the R3 collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachAllMetricCollectors

public Instrumenter attachAllMetricCollectors()
Includes all indicator collectors when instrumenting algorithms. This includes hypervolume, generational distance, inverted generational distance, spacing, additive ε-indicator, contribution, and the R1, R2, and R3 indicators.

Returns:
a reference to this instrumenter

attachEpsilonProgressCollector

public Instrumenter attachEpsilonProgressCollector()
Includes the ε-progress collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachAdaptiveMultimethodVariationCollector

public Instrumenter attachAdaptiveMultimethodVariationCollector()
Includes the adaptive multimethod variation collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachAdaptiveTimeContinuationCollector

public Instrumenter attachAdaptiveTimeContinuationCollector()
Includes the adaptive time continuation collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachElapsedTimeCollector

public Instrumenter attachElapsedTimeCollector()
Includes the elapsed time collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachApproximationSetCollector

public Instrumenter attachApproximationSetCollector()
Includes the approximation set collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachPopulationSizeCollector

public Instrumenter attachPopulationSizeCollector()
Includes the population size collector when instrumenting algorithms.

Returns:
a reference to this instrumenter

attachAll

public Instrumenter attachAll()
Includes all collectors when instrumenting algorithms.

Returns:
a reference to this instrumenter

withSameProblemAs

public Instrumenter withSameProblemAs(org.moeaframework.ProblemBuilder builder)
Configures this builder to use the same problem, reference set, ε values and ProblemFactory as the specified instance.

Parameters:
builder - the instance whose problem, reference set, ε values and ProblemFactory are to be copied
Returns:
a reference to this builder

usingProblemFactory

public Instrumenter usingProblemFactory(ProblemFactory problemFactory)
Sets the problem factory used by this builder.

Parameters:
problemFactory - the problem factory
Returns:
a reference to this builder

withProblem

public Instrumenter withProblem(String problemName)
Sets the problem used by this builder.

Parameters:
problemName - the problem name
Returns:
a reference to this builder

withProblem

public Instrumenter withProblem(Problem problemInstance)
Sets the problem instance used by this builder. Until the other withProblem methods, using a problem instance will not close the problem. It is the responsibility of the user to ensure any problems holding resources are properly closed.

Parameters:
problemInstance - the problem instance
Returns:
a reference to this builder

withProblemClass

public Instrumenter withProblemClass(Class<?> problemClass,
                                     Object... problemArguments)
Sets the problem used by this builder. Instances of the problem are created using the Class.newInstance() method. Ensure the problem class satisfies all the conditions of newInstance(), otherwise exceptions may be thrown when attempting to create an instance of the problem.

Parameters:
problemClass - the problem class
problemArguments - the arguments passed to the problem constructor
Returns:
a reference to this builder

withProblemClass

public Instrumenter withProblemClass(String problemClassName,
                                     Object... problemArguments)
                              throws ClassNotFoundException
Sets the problem used by this builder. Instances of the problem are created using the Class.newInstance() method. Ensure the problem class satisfies all the conditions of newInstance(), otherwise exceptions may be thrown when attempting to create an instance of the problem.

Parameters:
problemClassName - the problem class name
problemArguments - the arguments passed to the problem constructor
Returns:
a reference to this builder
Throws:
ClassNotFoundException - if the specified problem class name could not be found

withReferenceSet

public Instrumenter withReferenceSet(File referenceSetFile)
Sets the file containing the reference set to be used by this builder. If not specified, the reference set should be aggregated from all individual approximation sets.

Parameters:
referenceSetFile - the reference set file
Returns:
a reference to this builder

withEpsilon

public Instrumenter withEpsilon(double... epsilon)
Sets the ε values used by this builder, specifying the archive returned by newArchive().

Parameters:
epsilon - the ε values
Returns:
a reference to this builder

getReferenceSet

public NondominatedPopulation getReferenceSet()
Returns the reference set used by this builder. The reference set is generated as follows:
  1. If withReferenceSet(File) has been set, the contents of the reference set file are returned;
  2. If the problem factory provides a reference set via the ProblemFactory.getReferenceSet(String) method, this reference set is returned;
  3. Otherwise, an exception is thrown.

Returns:
the reference set used by this builder

instrument

protected void instrument(InstrumentedAlgorithm algorithm,
                          List<Collector> collectors,
                          Set<Object> visited,
                          Stack<Object> parents,
                          Object object,
                          Class<?> type)
Recursively walks the object graph to 1) determine the nesting of objects to help determine which objects are to be instrumented; and 2) attach the collectors to any matching objects.

In order to avoid cycles in the object graph, objects are only traversed the first time they are encountered. If an object appears multiple times in the object graph, the instrument method will only be invoked once.

When generating the nesting of objects, anonymous classes are given the placeholder type "(Anonymous)", without quotes. While the contents of arrays and Collections are listed in the nesting, the array/collection object itself is not listed. For example, the nesting will show CompoundVariation >> PM instead of CompoundVariation >> ArrayList >> Object[] >> PM.

This method is reentrant.

Parameters:
algorithm - the instrumented algorithm
collectors - the collectors to be attached
visited - the set of visited objects, which may include the current object when traversing its superclasses
parents - the objects in which the current object is contained
object - the current object undergoing reflection
type - the superclass whose members are being reflected; or null if the base type is to be used

instrument

public InstrumentedAlgorithm instrument(Algorithm algorithm)
Instruments the specified algorithm, returning an InstrumentedAlgorithm to be used to execute the algorithm and store the data produced by any attached instruments.

Parameters:
algorithm - the algorithm to instrument
Returns:
the instrumented algorithm
Throws:
IllegalArgumentException - if no reference set is available or could not be loaded

MOEA Framework 2.12
API Specification

Copyright 2009-2016 MOEA Framework. All rights reserved.
Licensed under the GNU Lesser General Public License.
Return to the MOEA Framework homepage. Visit us on Github!