org.jamesframework.ext.analysis

Class Analysis<SolutionType extends org.jamesframework.core.problems.Solution>

java.lang.Object

org.jamesframework.ext.analysis.Analysis<SolutionType>

Type Parameters:

SolutionType - solution type of the analyzed problems

public class Analysis<SolutionType extends org.jamesframework.core.problems.Solution>
extends Object

This analysis class can be used to set up and run an experiment with different search algorithms applied to several problem instances, for example with different data sets, objectives or problem parameters. It can also be used to perform a parameter sweep for a certain algorithm (e.g. for temperatures in parallel tempering, or the tabu list size in tabu search) and to try out different neighbourhood functions.

By default, each algorithm is executed 10 times because most searches are randomized. The number of repeats can be tuned on an overall as well as search specific level. It is advised to perform a sufficient amount of repeats so that stable results are obtained. By default, one additional burn-in run is performed for which no results are tracked. This can also be adjusted on an overall or search specific level.

Author:

Herman De Beukelaer

Constructor Summary

Constructors

Constructor and Description
Analysis() Create an analysis object.

Method Summary

Modifier and Type	Method and Description
Analysis<SolutionType>	addProblem(String ID, org.jamesframework.core.problems.Problem<SolutionType> problem) Add a problem to be analyzed.
Analysis<SolutionType>	addSearch(String ID, SearchFactory<SolutionType> searchFactory) Add a search to be applied to solve the analyzed problems.
int	getNumBurnIn() Get the global number of additional burn-in runs that will be performed for every applied search for which no search specific number of burn-in runs has been set.
int	getNumBurnIn(String searchID) Get the number of additional burn-in runs that will be performed for the search with the given ID.
int	getNumRuns() Get the global number of runs that will be performed for every applied search for which no search specific number of runs has been set.
int	getNumRuns(String searchID) Get the number of runs that will be performed for the search with the given ID.
AnalysisResults<SolutionType>	run() Run the analysis.
Analysis<SolutionType>	setNumBurnIn(int n) Set the global number of additional burn-in runs that will be performed for every applied search for which no search specific number of burn-in runs is set.
Analysis<SolutionType>	setNumBurnIn(String searchID, int n) Set the number of additional burn-in runs to be performed for the given search.
Analysis<SolutionType>	setNumRuns(int n) Set the global number of runs that will be performed for every applied search for which no search specific number of runs is set.
Analysis<SolutionType>	setNumRuns(String searchID, int n) Set the number of runs to be performed for the given search.

Methods inherited from class java.lang.Object

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

Constructor Detail

Analysis

public Analysis()

Create an analysis object. The number of performed runs of each search defaults to 10, plus one additional burn-in run.

Method Detail

getNumRuns

public int getNumRuns()

Get the global number of runs that will be performed for every applied search for which no search specific number of runs has been set. Defaults to 10 and can be changed using setNumRuns(int). To set a search specific numer of runs, use setNumRuns(String, int).

Returns:

number of performed search runs (global setting)

setNumRuns

public Analysis<SolutionType> setNumRuns(int n)

Set the global number of runs that will be performed for every applied search for which no search specific number of runs is set. Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

n - global number of search runs to be performed

Returns:

reference to the analysis object on which this method was called

Throws:

IllegalArgumentException - if n is not strictly positive

getNumBurnIn

public int getNumBurnIn()

Get the global number of additional burn-in runs that will be performed for every applied search for which no search specific number of burn-in runs has been set. Burn-in runs are executed before the actual search runs and not registered in the results, to "warm up" the analysis in order to reduce the influence of just in time compilation (JIT) and on the fly optimizations performed by the JVM.

Defaults to 1 and can be changed using setNumBurnIn(int). To set a search specific number of additional burn-in runs, use setNumBurnIn(String, int).

Returns:

number of performed burn-in runs (global setting)

setNumBurnIn

public Analysis<SolutionType> setNumBurnIn(int n)

Set the global number of additional burn-in runs that will be performed for every applied search for which no search specific number of burn-in runs is set. Burn-in runs are executed before the actual search runs and not registered in the results, to "warm up" the analysis in order to reduce the influence of just in time compilation (JIT) and on the fly optimizations performed by the JVM.

To set a search specific number of additional burn-in runs, use setNumBurnIn(String, int). Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

n - global number of additional burn-in runs to be performed

Returns:

reference to the analysis object on which this method was called

Throws:

IllegalArgumentException - if n is not strictly positive

getNumRuns

public int getNumRuns(String searchID)

Get the number of runs that will be performed for the search with the given ID. If no specific number of runs has been set for this search using setNumRuns(String, int), the global value obtained from getNumRuns() is returned.

Parameters:

searchID - ID of the search

Returns:

number of runs that will be performed for this search

Throws:

UnknownIDException - if no search with this ID has been added

setNumRuns

public Analysis<SolutionType> setNumRuns(String searchID,
                                         int n)

Set the number of runs to be performed for the given search. This does not affect the number of runs of the other searches. Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

searchID - ID of the search

n - number of runs to be performed for this specific search

Returns:

reference to the analysis object on which this method was called

Throws:

UnknownIDException - if no search with this ID has been added

IllegalArgumentException - if n is not strictly positive

getNumBurnIn

public int getNumBurnIn(String searchID)

Get the number of additional burn-in runs that will be performed for the search with the given ID. If no specific number of burn-in runs has been set for this search using setNumBurnIn(String, int), the global value obtained from getNumBurnIn() is returned. Burn-in runs are executed before the actual search runs and not registered in the results, to "warm up" the analysis in order to reduce the influence of just in time compilation (JIT) and on the fly optimizations performed by the JVM.

Parameters:

searchID - ID of the search

Returns:

number of additional burn-in runs that will be performed for this search

Throws:

UnknownIDException - if no search with this ID has been added

setNumBurnIn

public Analysis<SolutionType> setNumBurnIn(String searchID,
                                           int n)

Set the number of additional burn-in runs to be performed for the given search. This does not affect the number of burn-in runs of the other searches. Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

searchID - ID of the search

n - number of additional burn-in runs to be performed for this specific search

Returns:

reference to the analysis object on which this method was called

Throws:

UnknownIDException - if no search with this ID has been added

IllegalArgumentException - if n is not strictly positive

addProblem

public Analysis<SolutionType> addProblem(String ID,
                                         org.jamesframework.core.problems.Problem<SolutionType> problem)

Add a problem to be analyzed. Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

ID - unique ID of the added problem

problem - problem to be added to the analysis

Returns:

reference to the analysis object on which this method was called

Throws:

DuplicateIDException - if a problem has already been added with the specified ID

NullPointerException - if problem is null

addSearch

public Analysis<SolutionType> addSearch(String ID,
                                        SearchFactory<SolutionType> searchFactory)

Add a search to be applied to solve the analyzed problems. Requires a search factory instead of a plain search as a new instance of the search will be created for every run and for every analyzed problem. Returns a reference to the analysis object on which this method was called so that methods can be chained.

Parameters:

ID - unique ID of the added search

searchFactory - factory that creates a search given the problem to be solved

Returns:

reference to the analysis object on which this method was called

Throws:

DuplicateIDException - if a search has already been added with the specified ID

NullPointerException - if searchFactory is null

run

public AnalysisResults<SolutionType> run()

Run the analysis. The returned results can be accessed directly or written to a JSON file to be loaded into R for analysis and visualization using the james-analysis R package. The analysis progress is logged at INFO level, all log messages being tagged with a marker "analysis".

Returns:

results of the analysis

Throws:

org.jamesframework.core.exceptions.JamesRuntimeException - if anything goes wrong during any of the searches due to misconfiguration