Package ec

# Class Evolve

java.lang.Object
ec.Evolve

public class Evolve extends Object
Evolve is the main entry class for an evolutionary computation run.

An EC run is done with one of two argument formats:

`java ec.Evolve -file` parameter_file [`-p` parameter=value]*

This starts a new evolutionary run, using the parameter file parameter_file. The user can provide optional overriding parameters on the command-line with the `-p` option.

`java ec.Evolve -checkpoint` checkpoint_file

This starts up an evolutionary run from a previous checkpoint file.

The basic Evolve class has a main() loop with a simple job iteration facility. If you'd like to run the evolutionary system four times, each with a different random seed, you might do:

`java ec.Evolve -file` parameter_file `-p jobs=4`

Here, Evolve will run the first time with the random seed equal to whatever's specified in your file, then job#2 will be run with the seed + 1, job#3 with the seed + 2, and job#4 with the seed + 3. If you have multiple seeds, ECJ will try to make sure they're all different even across jobs by adding the job number * numberOfSeeds to each of them. This means that if you're doing multiple jobs with multiple seeds, you should probably set seed.0 to x, seed.1 to x+1, seed.2 to x+2, etc. for best results. It also works if seed.0 is x, seed.1 is y (a number much bigger than x), seed.2 is z (a number much bigger than y) etc. If you set seed.0=time etc. for multiple jobs, the values of each seed will be set to the current time that the job starts plus the job number * numberOfSeeds. As current time always goes up, this shouldn't be an issue. However it's theoretically possible that if you checkpoint and restart on another system with a clock set back in time, you could get the same seed in a later job.

main() has been designed to be modified. The comments for the Evolve.java file contain a lot discussion of how ECJ's main() bootstraps the EvolutionState object and runs it, plus a much simpler example of main() and explanations for how main() works.

Parameters

`jobs` int >= 1 (default) | (The number of jobs to iterate. The current job number (0...jobs-1) will be added to each seed UNLESS the seed is loaded from the system time. The job number also gets added as a prefix (if the number of jobs is more than 1)).
`nostore` bool = `true` or `false` (default) | (should the ec.util.Output facility not store announcements in memory?)
`flush` bool = `true` or `false` (default) | (should I flush all output as soon as it's printed (useful for debugging when an exception occurs))
`evalthreads` int >= 1 | (the number of threads to spawn for evaluation)
`breedthreads` int >= 1 | (the number of threads to spawn for breeding)
`seed.`n int != 0, or string = `time` | (the seed for random number generator #n. n should range from 0 to Max(evalthreads,breedthreads)-1. If value is `time`, then the seed is based on the system clock plus n.)
`state` classname, inherits and != ec.EvolutionState | (the EvolutionState object class)
`print-accessed-params` bool = `true` or `false` (default) | (at the end of a run, do we print out a list of all the parameters requested during the run?)
`print-used-params` bool = `true` or `false` (default) | (at the end of a run, do we print out a list of all the parameters actually used during the run?)
`print-unaccessed-params` bool = `true` or `false` (default) | (at the end of a run, do we print out a list of all the parameters NOT requested during the run?)
`print-unused-params` bool = `true` or `false` (default) | (at the end of a run, do we print out a list of all the parameters NOT actually used during the run?)
`print-all-params` bool = `true` or `false` (default) | (at the end of a run, do we print out a list of all the parameters stored in the parameter database?)

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `A_AT`
  The argument indicating the class where the resource is relative to.
  `static final String`
  `A_CHECKPOINT`
  The argument indicating that we're starting up from a checkpoint file.
  `static final String`
  `A_FILE`
  The argument indicating that we're starting fresh from a new parameter file.
  `static final String`
  `A_FROM`
  The argument indicating that we're starting fresh from a parameter file stored in a jar file or as some resource.
  `static final String`
  `A_HELP`
  The argument indicating a request to print out the help message.
  `static final String`
  `P_BREEDTHREADS`
  breedthreads parameter
  `static final String`
  `P_EVALTHREADS`
  evalthreads parameter
  `static final String`
  `P_PRINTACCESSEDPARAMETERS`
  `static final String`
  `P_PRINTALLPARAMETERS`
  `static final String`
  `P_PRINTUNACCESSEDPARAMETERS`
  `static final String`
  `P_PRINTUNUSEDPARAMETERS`
  `static final String`
  `P_PRINTUSEDPARAMETERS`
  `static final String`
  `P_SEED`
  seed parameter
  `static final String`
  `P_SILENT`
  Should we muzzle stdout and stderr?
  `static final String`
  `P_STATE`
  state parameter
  `static final String`
  `V_SEED_TIME`
  'time' seed parameter value
  `static final String`
  `V_THREADS_AUTO`
  'auto' thread parameter value

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Evolve()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Output`
  `buildOutput()`
  Constructs and sets up an Output object which always issues errors in the traditional fashion rather than throwing them.
  `static Output`
  `buildOutput(boolean throwsErrors)`
  Constructs and sets up an Output object.
  `static void`
  `checkForHelp(String[] args, String classname, boolean checkpoint)`
  Optionally prints the help message.
  `static void`
  `cleanup(EvolutionState state)`
  Begins a fresh evolutionary run with a given state.
  `static int`
  `determineSeed(Output output, ParameterDatabase parameters, Parameter seedParameter, long currentTime, int offset, boolean auto)`
  Loads a random generator seed.
  `static int`
  `determineThreads(Output output, ParameterDatabase parameters, Parameter threadParameter)`
  Loads the number of threads.
  `static EvolutionState`
  `initialize(ParameterDatabase parameters, int randomSeedOffset)`
  Initializes an evolutionary run given the parameters and a random seed adjustment (added to each random seed).
  `static EvolutionState`
  `initialize(ParameterDatabase parameters, int randomSeedOffset, Output output)`
  Initializes an evolutionary run given the parameters and a random seed adjustment (added to each random seed), with the Output pre-constructed.
  `static ParameterDatabase`
  `loadParameterDatabase(String[] args)`
  Loads a ParameterDatabase from checkpoint if "-params" is in the command-line arguments.
  `static void`
  `main(String[] args)`
  Top-level evolutionary loop.
  `static EvolutionState`
  `possiblyRestoreFromCheckpoint(String[] args)`
  Restores an EvolutionState from checkpoint if "-checkpoint FILENAME" is in the command-line arguments.
  `static MersenneTwisterFast`
  `primeGenerator(MersenneTwisterFast generator)`
  Primes the generator.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### P_PRINTACCESSEDPARAMETERS

    public static final String P_PRINTACCESSEDPARAMETERS
    See Also:
      - Constant Field Values

  - ### P_PRINTUSEDPARAMETERS

    public static final String P_PRINTUSEDPARAMETERS
    See Also:
      - Constant Field Values

  - ### P_PRINTALLPARAMETERS

    public static final String P_PRINTALLPARAMETERS
    See Also:
      - Constant Field Values

  - ### P_PRINTUNUSEDPARAMETERS

    public static final String P_PRINTUNUSEDPARAMETERS
    See Also:
      - Constant Field Values

  - ### P_PRINTUNACCESSEDPARAMETERS

    public static final String P_PRINTUNACCESSEDPARAMETERS
    See Also:
      - Constant Field Values

  - ### A_CHECKPOINT

    public static final String A_CHECKPOINT
    The argument indicating that we're starting up from a checkpoint file.
    See Also:
      - Constant Field Values

  - ### A_FILE

    public static final String A_FILE
    The argument indicating that we're starting fresh from a new parameter file.
    See Also:
      - Constant Field Values

  - ### A_FROM

    public static final String A_FROM
    The argument indicating that we're starting fresh from a parameter file stored in a jar file or as some resource.
    See Also:
      - Constant Field Values

  - ### A_AT

    public static final String A_AT
    The argument indicating the class where the resource is relative to.
    See Also:
      - Constant Field Values

  - ### A_HELP

    public static final String A_HELP
    The argument indicating a request to print out the help message.
    See Also:
      - Constant Field Values

  - ### P_EVALTHREADS

    public static final String P_EVALTHREADS
    evalthreads parameter
    See Also:
      - Constant Field Values

  - ### P_BREEDTHREADS

    public static final String P_BREEDTHREADS
    breedthreads parameter
    See Also:
      - Constant Field Values

  - ### P_SEED

    public static final String P_SEED
    seed parameter
    See Also:
      - Constant Field Values

  - ### V_SEED_TIME

    public static final String V_SEED_TIME
    'time' seed parameter value
    See Also:
      - Constant Field Values

  - ### P_STATE

    public static final String P_STATE
    state parameter
    See Also:
      - Constant Field Values

  - ### V_THREADS_AUTO

    public static final String V_THREADS_AUTO
    'auto' thread parameter value
    See Also:
      - Constant Field Values

  - ### P_SILENT

    public static final String P_SILENT
    Should we muzzle stdout and stderr?
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Evolve

    public Evolve()

- ## Method Details

  - ### checkForHelp

    public static void checkForHelp(String[] args, String classname, boolean checkpoint)
    Optionally prints the help message.

  - ### possiblyRestoreFromCheckpoint

    public static EvolutionState possiblyRestoreFromCheckpoint(String[] args)
    Restores an EvolutionState from checkpoint if "-checkpoint FILENAME" is in the command-line arguments.

  - ### loadParameterDatabase

    public static ParameterDatabase loadParameterDatabase(String[] args)
    Loads a ParameterDatabase from checkpoint if "-params" is in the command-line arguments.

  - ### determineThreads

    public static int determineThreads(Output output, ParameterDatabase parameters, Parameter threadParameter)
    Loads the number of threads.

  - ### primeGenerator

    public static MersenneTwisterFast primeGenerator(MersenneTwisterFast generator)
    Primes the generator. Mersenne Twister seeds its first 624 numbers using a basic linear congruential generator; thereafter it uses the MersenneTwister algorithm to build new seeds. Those first 624 numbers are generally just fine, but to be extra safe, you can prime the generator by calling nextInt() on it some (N>1) * 624 times. This method does exactly that, presently with N=2.

  - ### determineSeed

    public static int determineSeed(Output output, ParameterDatabase parameters, Parameter seedParameter, long currentTime, int offset, boolean auto)
    Loads a random generator seed. First, the seed is loaded from the seedParameter. If the parameter is V_SEED_TIME, the seed is set to the currentTime value. Then the seed is incremented by the offset. This method is broken out of initialize(...) primarily to share code with ec.eval.MasterProblem.

  - ### buildOutput

    public static Output buildOutput()
    Constructs and sets up an Output object which always issues errors in the traditional fashion rather than throwing them.

  - ### buildOutput

    public static Output buildOutput(boolean throwsErrors)
    Constructs and sets up an Output object.

  - ### initialize

    public static EvolutionState initialize(ParameterDatabase parameters, int randomSeedOffset)
    Initializes an evolutionary run given the parameters and a random seed adjustment (added to each random seed). The adjustment offers a convenient way to change the seeds of the random number generators each time you do a new evolutionary run. You are of course welcome to replace the random number generators after initialize(...) but before startFresh(...)

    This method works by first setting up an Output (using buildOutput), then calling initialize(ParameterDatabase, seed, output)

  - ### initialize

    public static EvolutionState initialize(ParameterDatabase parameters, int randomSeedOffset, Output output)
    Initializes an evolutionary run given the parameters and a random seed adjustment (added to each random seed), with the Output pre-constructed. The adjustment offers a convenient way to change the seeds of the random number generators each time you do a new evolutionary run. You are of course welcome to replace the random number generators after initialize(...) but before startFresh(...)

  - ### cleanup

    public static void cleanup(EvolutionState state)
    Begins a fresh evolutionary run with a given state. The state should have been provided by initialize(...). The jobPrefix is added to the front of output and checkpoint filenames. If it's null, nothing is added to the front.

  - ### main

    public static void main(String[] args)
    Top-level evolutionary loop.