EvolutionState (ecj 26 API)

java.lang.Object
- ec.EvolutionState

All Implemented Interfaces:: Setup, Singleton, Serializable

Direct Known Subclasses:: SimpleEvolutionState, SingleStateEvolutionState, SteadyStateEvolutionState

public class EvolutionState
extends Object
implements Singleton

An EvolutionState object is a singleton object which holds the entire state of an evolutionary run. By serializing EvolutionState, the entire run can be checkpointed out to a file.

The EvolutionState instance is passed around in a lot of methods, so objects can read from the parameter database, pick random numbers, and write to the output facility.

EvolutionState is a unique object in that it calls its own setup(...) method, from run(...).

An EvolutionState object contains quite a few objects, including:

Objects you may safely manipulate during the multithreaded sections of a run:
- MersenneTwisterFast random number generators (one for each evaluation or breeding thread -- use the thread number you were provided to determine which random number generator to use)
- The ParameterDatabase
- The Output facility for writing messages and logging
Singleton objects:
- The Initializer.
- The Finisher.
- The Breeder.
- The Evaluator.
- The Statistics facility.
- The Exchanger.
The current evolution state:
- The generation number.
- The population.
- The maximal number of generations.
Auxillary read-only information:
- The prefix to begin checkpoint file names with.
- Whether to quit upon finding a perfect individual.
- The number of breeding threads to spawn.
- The number of evaluation threads to spawn.
A place to stash pointers to static variables so they'll get serialized:
- Statics

Parameters

`generations` int >= 1 or undefined	(maximal number of generations to run. Either this or evaluations must be set, but not both.)
`evaluations` int >= 1 or undefined	(maximal number of evaluations to run (in subpopulation 0). Either this or generations must be set, but not both.)
`checkpoint-modulo` int >= 1	(how many generations should pass before we do a checkpoint? The definition of "generations" depends on the particular EvolutionState implementation you're using)
`checkpoint` bool = `true` or `false` (default)	(should we checkpoint?)
`prefix` String	(the prefix to prepend to checkpoint files -- see ec.util.Checkpoint)
`checkpoint-directory` File (default is empty)	(directory where the checkpoint files should be located)
`quit-on-run-complete` bool = `true` or `false` (default)	(do we prematurely quit the run when we find a perfect individual?)
`init` classname, inherits and != ec.Initializer	(the class for initializer)
`finish` classname, inherits and != ec.Finisher	(the class for finisher)
`breed` classname, inherits and != ec.Breeder	(the class for breeder)
`eval` classname, inherits and != ec.Evaluator	(the class for evaluator)
`stat` classname, inherits or = ec.Statistics	(the class for statistics)
`exch` classname, inherits and != ec.Exchanger	(the class for exchanger)

Parameter bases

`init`	initializer
`finish`	finisher
`breed`	breeder
`eval`	evaluator
`stat`	statistics
`exch`	exchanger

Version:: 1.0
Author:: Sean Luke
See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`Breeder`	`breeder` The population breeder, a singleton object.
`int`	`breedthreads` The requested number of threads to be used in breeding, excepting perhaps a "parent" thread which gathers the other threads.
`static int`	`C_STARTED_FRESH` "The population has started fresh (not from a checkpoint)."
`static int`	`C_STARTED_FROM_CHECKPOINT` "The population started from a checkpoint."
`boolean`	`checkpoint` Should we checkpoint at all?
`File`	`checkpointDirectory` The requested directory where checkpoints should be located.
`int`	`checkpointModulo` The requested number of generations that should pass before we write out a checkpoint file.
`String`	`checkpointPrefix` The requested prefix to start checkpoint filenames, not including a following period.
`HashMap[]`	`data` An array of HashMaps, indexed by the thread number you were given (or, if you're not in a multithreaded area, use 0).
`int`	`evalthreads` The requested number of threads to be used in evaluation, excepting perhaps a "parent" thread which gathers the other threads.
`int`	`evaluations` The current number of evaluations which have transpired so far in the run.
`Evaluator`	`evaluator` The population evaluator, a singleton object.
`Exchanger`	`exchanger` The population exchanger, a singleton object.
`Finisher`	`finisher` The population finisher, a singleton object.
`int`	`generation` The current generation of the population in the run.
`Initializer`	`initializer` The population initializer, a singleton object.
`long`	`innovationNumber` Global birthday tracker number for genes in representations such as NEAT.
`Object[]`	`job` Current job iteration variables, set by Evolve.
`(package private) Object[]`	`lock`
`long`	`numEvaluations` The number of evaluations the evolutionary computation system will run until it ends (up to the next generation boundary), or UNDEFINED
`int`	`numGenerations` The number of generations the evolutionary computation system will run until it ends, or UNDEFINED
`Output`	`output` The output and logging facility (threadsafe).
`static String`	`P_BREEDER`
`static String`	`P_CHECKPOINT`
`static String`	`P_CHECKPOINTDIRECTORY`
`static String`	`P_CHECKPOINTMODULO`
`static String`	`P_CHECKPOINTPREFIX`
`(package private) static String`	`P_CHECKPOINTPREFIX_OLD`
`static String`	`P_EVALUATIONS`
`static String`	`P_EVALUATOR`
`static String`	`P_EXCHANGER`
`static String`	`P_FINISHER`
`static String`	`P_GENERATIONS`
`static String`	`P_INITIALIZER`
`static String`	`P_INNOVATIONNUMBER`
`static String`	`P_QUITONRUNCOMPLETE`
`static String`	`P_STATISTICS`
`ParameterDatabase`	`parameters` The parameter database (threadsafe).
`Population`	`population` The current population.
`boolean`	`quitOnRunComplete` Whether or not the system should prematurely quit when Evaluator returns true for runComplete(...) (that is, when the system found an ideal individual.
`static int`	`R_FAILURE` "The evolution run has quit, failing to find a perfect individual."
`static int`	`R_NOTDONE` "The evolution run has not quit
`static int`	`R_SUCCESS` "The evolution run has quit, finding a perfect individual."
`MersenneTwisterFast[]`	`random` An array of random number generators, indexed by the thread number you were given (or, if you're not in a multithreaded area, use 0).
`int`	`randomSeedOffset` An amount to add to each random number generator seed to "offset" it -- often this is simply the job number.
`String[]`	`runtimeArguments` The original runtime arguments passed to the Java process.
`private static long`	`serialVersionUID`
`Statistics`	`statistics` The population statistics, a singleton object.
`static int`	`UNDEFINED`

Constructor Summary

Constructors
Constructor and Description
`EvolutionState()` This will be called to create your evolution state; immediately after the constructor is called, the parameters, random, and output fields will be set for you.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`evolve()`
`void`	`finish(int result)`
`void`	`incrementEvaluations(int val)`
`void`	`resetFromCheckpoint()` This method is called after a checkpoint is restored from but before the run starts up again.
`void`	`run(int condition)` Starts the run.
`void`	`setup(EvolutionState state, Parameter base)` Unlike for other setup() methods, ignore the base; it will always be null.
`void`	`startFresh()`
`void`	`startFromCheckpoint()`
`(package private) void`	`synchronizedIncrementEvaluations(int val)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - serialVersionUID
```
private static final long serialVersionUID
```
    See Also:
    
    Constant Field Values
  - parameters
```
public ParameterDatabase parameters
```
    The parameter database (threadsafe). Parameter objects are also threadsafe. Nonetheless, you should generally try to treat this database as read-only.
  - random
```
public MersenneTwisterFast[] random
```
    An array of random number generators, indexed by the thread number you were given (or, if you're not in a multithreaded area, use 0). These generators are not threadsafe in and of themselves, but if you only use the random number generator assigned to your thread, as was intended, then you get random numbers in a threadsafe way. These generators must each have a different seed, of course.
  - data
```
public HashMap[] data
```
    An array of HashMaps, indexed by the thread number you were given (or, if you're not in a multithreaded area, use 0). This allows you to store per-thread specialized information (typically keyed with a string).
  - output
```
public Output output
```
    The output and logging facility (threadsafe). Keep in mind that output in Java is expensive.
  - breedthreads
```
public int breedthreads
```
    The requested number of threads to be used in breeding, excepting perhaps a "parent" thread which gathers the other threads. If breedthreads = 1, then the system should not be multithreaded during breeding. Don't modify this during a run.
  - evalthreads
```
public int evalthreads
```
    The requested number of threads to be used in evaluation, excepting perhaps a "parent" thread which gathers the other threads. If evalthreads = 1, then the system should not be multithreaded during evaluation. Don't modify this during a run.
  - checkpoint
```
public boolean checkpoint
```
    Should we checkpoint at all?
  - checkpointDirectory
```
public File checkpointDirectory
```
    The requested directory where checkpoints should be located. This must be a directory, not a file. You probably shouldn't modify this during a run.
  - checkpointPrefix
```
public String checkpointPrefix
```
    The requested prefix to start checkpoint filenames, not including a following period. You probably shouldn't modify this during a run.
  - checkpointModulo
```
public int checkpointModulo
```
    The requested number of generations that should pass before we write out a checkpoint file.
  - randomSeedOffset
```
public int randomSeedOffset
```
    An amount to add to each random number generator seed to "offset" it -- often this is simply the job number. If you are using more random number generators internally than the ones initially created for you in the EvolutionState, you might want to create them with the seed value of seedParameter+randomSeedOffset. At present the only such class creating additional generators is ec.eval.MasterProblem.
  - quitOnRunComplete
```
public boolean quitOnRunComplete
```
    Whether or not the system should prematurely quit when Evaluator returns true for runComplete(...) (that is, when the system found an ideal individual.
  - job
```
public Object[] job
```
    Current job iteration variables, set by Evolve. The default version simply sets this to a single Object[1] containing the current job iteration number as an Integer (for a single job, it's 0). You probably should not modify this inside an evolutionary run.
  - runtimeArguments
```
public String[] runtimeArguments
```
    The original runtime arguments passed to the Java process. You probably should not modify this inside an evolutionary run.
  - UNDEFINED
```
public static final int UNDEFINED
```
    See Also:
    
    Constant Field Values
  - generation
```
public int generation
```
    The current generation of the population in the run. For non-generational approaches, this probably should represent some kind of incrementing value, perhaps the number of individuals evaluated so far. You probably shouldn't modify this.
  - evaluations
```
public int evaluations
```
    The current number of evaluations which have transpired so far in the run. This is only updated on a generational boundary.
  - numGenerations
```
public int numGenerations
```
    The number of generations the evolutionary computation system will run until it ends, or UNDEFINED
  - numEvaluations
```
public long numEvaluations
```
    The number of evaluations the evolutionary computation system will run until it ends (up to the next generation boundary), or UNDEFINED
  - population
```
public Population population
```
    The current population. This is not a singleton object, and may be replaced after every generation in a generational approach. You should only access this in a read-only fashion.
  - initializer
```
public Initializer initializer
```
    The population initializer, a singleton object. You should only access this in a read-only fashion.
  - finisher
```
public Finisher finisher
```
    The population finisher, a singleton object. You should only access this in a read-only fashion.
  - breeder
```
public Breeder breeder
```
    The population breeder, a singleton object. You should only access this in a read-only fashion.
  - evaluator
```
public Evaluator evaluator
```
    The population evaluator, a singleton object. You should only access this in a read-only fashion.
  - statistics
```
public Statistics statistics
```
    The population statistics, a singleton object. You should generally only access this in a read-only fashion.
  - exchanger
```
public Exchanger exchanger
```
    The population exchanger, a singleton object. You should only access this in a read-only fashion.
  - innovationNumber
```
public long innovationNumber
```
    Global birthday tracker number for genes in representations such as NEAT. Accessed and modified during run time
  - C_STARTED_FRESH
```
public static final int C_STARTED_FRESH
```
    "The population has started fresh (not from a checkpoint)."
    
    See Also:
    
    Constant Field Values
  - C_STARTED_FROM_CHECKPOINT
```
public static final int C_STARTED_FROM_CHECKPOINT
```
    "The population started from a checkpoint."
    
    See Also:
    
    Constant Field Values
  - R_SUCCESS
```
public static final int R_SUCCESS
```
    "The evolution run has quit, finding a perfect individual."
    
    See Also:
    
    Constant Field Values
  - R_FAILURE
```
public static final int R_FAILURE
```
    "The evolution run has quit, failing to find a perfect individual."
    
    See Also:
    
    Constant Field Values
  - R_NOTDONE
```
public static final int R_NOTDONE
```
    "The evolution run has not quit
    
    See Also:
    
    Constant Field Values
  - P_INITIALIZER
```
public static final String P_INITIALIZER
```
    See Also:
    
    Constant Field Values
  - P_FINISHER
```
public static final String P_FINISHER
```
    See Also:
    
    Constant Field Values
  - P_BREEDER
```
public static final String P_BREEDER
```
    See Also:
    
    Constant Field Values
  - P_EVALUATOR
```
public static final String P_EVALUATOR
```
    See Also:
    
    Constant Field Values
  - P_STATISTICS
```
public static final String P_STATISTICS
```
    See Also:
    
    Constant Field Values
  - P_EXCHANGER
```
public static final String P_EXCHANGER
```
    See Also:
    
    Constant Field Values
  - P_GENERATIONS
```
public static final String P_GENERATIONS
```
    See Also:
    
    Constant Field Values
  - P_EVALUATIONS
```
public static final String P_EVALUATIONS
```
    See Also:
    
    Constant Field Values
  - P_QUITONRUNCOMPLETE
```
public static final String P_QUITONRUNCOMPLETE
```
    See Also:
    
    Constant Field Values
  - P_CHECKPOINTPREFIX
```
public static final String P_CHECKPOINTPREFIX
```
    See Also:
    
    Constant Field Values
  - P_CHECKPOINTMODULO
```
public static final String P_CHECKPOINTMODULO
```
    See Also:
    
    Constant Field Values
  - P_CHECKPOINTDIRECTORY
```
public static final String P_CHECKPOINTDIRECTORY
```
    See Also:
    
    Constant Field Values
  - P_CHECKPOINT
```
public static final String P_CHECKPOINT
```
    See Also:
    
    Constant Field Values
  - P_INNOVATIONNUMBER
```
public static final String P_INNOVATIONNUMBER
```
    See Also:
    
    Constant Field Values
  - P_CHECKPOINTPREFIX_OLD
```
static final String P_CHECKPOINTPREFIX_OLD
```
    See Also:
    
    Constant Field Values
  - lock
```
Object[] lock
```
- Constructor Detail
  - EvolutionState
```
public EvolutionState()
```
    This will be called to create your evolution state; immediately after the constructor is called, the parameters, random, and output fields will be set for you. The constructor probably won't be called ever if restoring (deserializing) from a checkpoint.
- Method Detail
  - setup
```
public void setup(EvolutionState state,
                  Parameter base)
```
    Unlike for other setup() methods, ignore the base; it will always be null.
    
    Specified by:
    
    setup in interface Setup
    
    See Also:
    
    Prototype.setup(EvolutionState,Parameter)
  - resetFromCheckpoint
```
public void resetFromCheckpoint()
                         throws IOException
```
    This method is called after a checkpoint is restored from but before the run starts up again. You might use this to set up file pointers that were lost, etc.
    
    Throws:
    
    IOException
  - finish
```
public void finish(int result)
```
  - startFromCheckpoint
```
public void startFromCheckpoint()
```
  - startFresh
```
public void startFresh()
```
  - evolve
```
public int evolve()
           throws InternalError
```
    Throws:
    
    InternalError
  - synchronizedIncrementEvaluations
```
void synchronizedIncrementEvaluations(int val)
```
  - incrementEvaluations
```
public void incrementEvaluations(int val)
```
  - run
```
public void run(int condition)
```
    Starts the run. condition indicates whether or not the run was restarted from a checkpoint (C_STARTED_FRESH vs C_STARTED_FROM_CHECKPOINT). At the point that run(...) has been called, the parameter database has already been set up, as have the random number generators, the number of threads, and the Output facility. This method should call this.setup(...) to set up the EvolutionState object if condition equals C_STARTED_FRESH.

Class EvolutionState

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

parameters

random

data

output

breedthreads

evalthreads

checkpoint

checkpointDirectory

checkpointPrefix

checkpointModulo

randomSeedOffset

quitOnRunComplete

job

runtimeArguments

UNDEFINED

generation

evaluations

numGenerations

numEvaluations

population

initializer

finisher

breeder

evaluator

statistics

exchanger

innovationNumber

C_STARTED_FRESH

C_STARTED_FROM_CHECKPOINT

R_SUCCESS

R_FAILURE

R_NOTDONE

P_INITIALIZER

P_FINISHER

P_BREEDER

P_EVALUATOR

P_STATISTICS

P_EXCHANGER

P_GENERATIONS

P_EVALUATIONS

P_QUITONRUNCOMPLETE

P_CHECKPOINTPREFIX

P_CHECKPOINTMODULO

P_CHECKPOINTDIRECTORY

P_CHECKPOINT

P_INNOVATIONNUMBER

P_CHECKPOINTPREFIX_OLD

lock

Constructor Detail

EvolutionState

Method Detail

setup

resetFromCheckpoint

finish

startFromCheckpoint

startFresh

evolve

synchronizedIncrementEvaluations

incrementEvaluations

run