org.jamesframework.ext.analysis

## Class Analysis<SolutionType extends Solution>

• Type Parameters:
SolutionType - solution type of the analyzed problems

public class Analysis<SolutionType extends 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

All Methods
Modifier and Type Method and Description
Analysis<SolutionType> addProblem(String ID, 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

public Analysis<SolutionType> addProblem(String ID,
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

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:
JamesRuntimeException - if anything goes wrong during any of the searches due to misconfiguration