org.moeaframework
Class Instrumenter

java.lang.Object
  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) Allows this instrumenter to visit classes in the given package.
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() Returns all packages this instrumenter is allowed to visit.
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) Removes one of the packages this instrumenter is allowed to visit.
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, in evaluations, that data is collected.
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

public Instrumenter addAllowedPackage(String packageName)

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

public Instrumenter removeAllowedPackage(String packageName)

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

public List<String> getAllowedPackages()

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, in evaluations, that data is collected.

Parameters:

frequency - the frequency

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

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