com.rubecula.darwin.evolution
Class Evolution_

java.lang.Object
  net.sf.tostring0.AToString
      com.rubecula.darwin.evolution.Evolver_
          com.rubecula.darwin.evolution.Evolution_

All Implemented Interfaces:

com.rubecula.beanpot.Configurable, Evolution, Evolver, Clocked, java.lang.Runnable, net.sf.tostring0.IToString

Direct Known Subclasses:

Evolution_Timed

public abstract class Evolution_
extends Evolver_
implements Evolution

This class is the base implementation of the Evolution_ interface. It is what drives the evolution of a set of Evolvable objects. That is to say that it drives the running of a genetic algorithm, or genetic program. It can run in automatic mode (initiated by a call to start(int, boolean), or in manual mode (steps, each invoked by calling next(). Although not a singleton in the strict sense, there will normally only be one of these objects. FIXME application does not terminate cleanly when the rate of evolution is too fast (the evolution terminates appropriately but a task is left hanging so that the JVM doesn't release the executable).

Author:

Robin Hillyard

Field Summary

protected static int	_waitPeriod Period between checks to see if the run method has completed (in milliseconds).
static int	MILLISECS_PER_SECOND 1000

Fields inherited from class com.rubecula.darwin.evolution.Evolver_

LOG

Fields inherited from interface net.sf.tostring0.IToString

ANGBR_OPEN, ANGBRA_CLSE, BRA_CLSE, BRA_OPEN, BRCE_OPEN, BRCS_CLSE, COLON, LIST_SEPARATOR, MAX_ELEMENTS_DEFAULT, S_MT, S_PERCENT, SEPARATOR, SPACE

Constructor Summary

protected

Evolution_()

Method Summary

protected boolean	cancelEvents() TEST
protected void	finalize()
long	getClock()
static java.lang.String	getElapsedTime(long millisecs) Method to create a String which appropriately represents the accuracy of the elapsed time.
protected java.util.concurrent.ScheduledExecutorService	getEventExecutor()
protected EvolutionTask	getEvolutionTask()
protected java.lang.Object	getUi() TEST
boolean	isActive(boolean ignoreEvents)
boolean	isPaused()
protected boolean	isWaitUntilComplete()
boolean	next() Create a new EvolutionTask and run it.
void	pause() TEST
void	postConfigure(java.lang.Object data) Do nothing - override if you need something doing
void	preConfigure(java.lang.Object data) Method to pre-configure the Evolution object when it is used as part of an application, as opposed to being in an applet.
void	resume() TEST
void	run() By default, the run method for an Evolution_ object starts the evolution going at the rate of one tick per second.
java.util.concurrent.Future<?>	scheduleEvent(long millisecs, java.lang.Runnable event) Schedule an arbitrary event for execution after a specific number of milliseconds.
protected void	setEvolutionTask(EvolutionTask evolutionTask)
void	setUi(java.lang.Object ui) Called by reflection (during configuration).
void	setWaitUntilComplete(boolean waitUntilComplete) Called by reflection (during configuration).
boolean	shutdown() A terminal shut-down of the Evolution process (including both evolution and scheduled events).
protected void	start(int rate, boolean run) This method starts a new evolution with generations potentially occurring at given rate (in milliseconds) [a particular Evolvable object might not undergo a new generation for every "tick" of this evolutionary clock.] The result of calling ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit) results in a new thread being started with the name formed from EvolutionThreadFactory#namePrefix, space and a sequence number.
protected void	startAndWait(int rate, boolean run, boolean stopFirst)
boolean	stop() XXX the following comment seems totally wrong.
protected boolean	stopExecutor(java.util.concurrent.ScheduledExecutorService executor, int timeoutSeconds) Shutdown the given executor and wait for the tasks to terminate
boolean	stoppable()
boolean	waitUntilComplete(int delay) Wait for this Evolution to become inactive, then return.

Methods inherited from class com.rubecula.darwin.evolution.Evolver_

addEvolvable, addEvolvable, addListener, addVisualizableListener, cleanup, getClockWatcher, getEvolvableKeys, getEvolvables, getListeners, getVisualizableListeners, init, putEvolvable, removeEvolvable, seedEvolvables, setClockWatcher, setEvolvables, setListeners, setVisualizableListeners, showTime, showTime

Methods inherited from class net.sf.tostring0.AToString

toString, toString, toStringBrief, toStringId

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.rubecula.darwin.evolution.Evolver

addEvolvable, addEvolvable, addListener, cleanup, getClockWatcher, getEvolvableKeys, init, removeEvolvable, seedEvolvables, setClockWatcher

Field Detail

MILLISECS_PER_SECOND

public static final int MILLISECS_PER_SECOND

1000

See Also:

Constant Field Values

_waitPeriod

protected static int _waitPeriod

Period between checks to see if the run method has completed (in milliseconds). Can be set by subclasses if desired.

Constructor Detail

Evolution_

protected Evolution_()

Method Detail

getElapsedTime

public static java.lang.String getElapsedTime(long millisecs)

Method to create a String which appropriately represents the accuracy of the elapsed time.

Parameters:

millisecs -

Returns:

a String which shows the elapsed time and the accuracy of same.

getClock

public long getClock()

Specified by:

getClock in interface Clocked

Overrides:

getClock in class Evolver_

Returns:

the number of ticks since this Generator was started, or null if this evolution has not been started.

isActive

public boolean isActive(boolean ignoreEvents)
                 throws EvolutionException

Specified by:

isActive in interface Evolution

Parameters:

ignoreEvents - XXX

Returns:

true if this evolution is currently active (with valid timer, task and evolvables).

Throws:

EvolutionException

See Also:

Evolution.isActive(boolean)

isPaused

public boolean isPaused()

Specified by:

isPaused in interface Evolution

Returns:

true if EvolutionTask.isPaused() returns true for the evolutionTask (if evolutionTask is null then return true. XXX is this OK?

See Also:

EvolutionTask.isPaused()

next

public boolean next()
             throws EvolutionException

Create a new EvolutionTask and run it. This method has works quite differently in the two different modes (manual versus auto). When this Evolution is in auto mode, we is intended for manual stepping of the evolutionary process.

Specified by:

next in interface Evolver

Overrides:

next in class Evolver_

Returns:

true if there are evolvables still to evolve.

Throws:

EvolutionException

See Also:

Evolver.next()

pause

public void pause()
           throws EvolutionException

TEST

Specified by:

pause in interface Evolution

Throws:

EvolutionException

See Also:

Evolution.pause()

postConfigure

public void postConfigure(java.lang.Object data)

Description copied from class: Evolver_

Do nothing - override if you need something doing

Specified by:

postConfigure in interface com.rubecula.beanpot.Configurable

Overrides:

postConfigure in class Evolver_

See Also:

Evolver_.postConfigure(java.lang.Object)

preConfigure

public void preConfigure(java.lang.Object data)

Method to pre-configure the Evolution object when it is used as part of an application, as opposed to being in an applet.

Specified by:

preConfigure in interface com.rubecula.beanpot.Configurable

Overrides:

preConfigure in class Evolver_

See Also:

Evolver_.preConfigure(java.lang.Object)

resume

public void resume()
            throws EvolutionException

TEST

Specified by:

resume in interface Evolution

Throws:

EvolutionException

See Also:

Evolution.resume()

run

public void run()

By default, the run method for an Evolution_ object starts the evolution going at the rate of one tick per second. First, start a new repeating task with parameters MILLISECS_PER_SECOND and true. Then, if isWaitUntilComplete() returns true, we invoke waitUntilComplete(int) with the value of #_waitPeriod. Thus, if you do not want to wait for the evolution to finish, simply invoke setWaitUntilComplete(boolean) with false before calling run. NOTE: this method may be overridden by sub-classes.

Specified by:

run in interface java.lang.Runnable

See Also:

Runnable.run()

scheduleEvent

public java.util.concurrent.Future<?> scheduleEvent(long millisecs,
                                                    java.lang.Runnable event)

Description copied from interface: Evolution

Schedule an arbitrary event for execution after a specific number of milliseconds. The event will fire is scheduled independently of any new generations (and will run in a different thread). Typically, this will be used to change a property in the environment at a certain time. TODO consider implementing in such a way that we can specify a certain number of ticks (the ability to pause/resume makes this complex).

Specified by:

scheduleEvent in interface Evolution

Parameters:

millisecs - the number of millisecs before the event is to be run.

event - the event to be run.

Returns:

the future which is returned by the scheduler for the event.

See Also:

Evolution.scheduleEvent(long, java.lang.Runnable)

setUi

public void setUi(java.lang.Object ui)

Called by reflection (during configuration).

Parameters:

ui -

setWaitUntilComplete

public void setWaitUntilComplete(boolean waitUntilComplete)

Called by reflection (during configuration).

Parameters:

waitUntilComplete - the waitUntilComplete to set

shutdown

public boolean shutdown()
                 throws EvolutionException

A terminal shut-down of the Evolution process (including both evolution and scheduled events). Subsequent calls to this Evolution object will not succeed. Compare pause() and stop().

Specified by:

shutdown in interface Evolution

Returns:

the result of calling ExecutorService.awaitTermination(long, TimeUnit) which, roughly speaking, will be true if everything shut down in an orderly fashion.

Throws:

EvolutionException

See Also:

Evolution.stop()

stop

public boolean stop()
             throws EvolutionException

XXX the following comment seems totally wrong. A temporary stop of the Evolution process (scheduled events are not affected).

Specified by:

stop in interface Evolution

Returns:

the result of calling stopExecutor(ScheduledExecutorService, int) which, roughly speaking, will be true if everything shut down in an orderly fashion.

Throws:

EvolutionException

See Also:

Evolution.stop()

stoppable

public boolean stoppable()

Specified by:

stoppable in interface Evolution

Returns:

true if we have permission to stop this Evolution.

waitUntilComplete

public boolean waitUntilComplete(int delay)
                          throws EvolutionException

Wait for this Evolution to become inactive, then return.

Specified by:

waitUntilComplete in interface Evolution

Parameters:

delay - delay between tests (in milliseconds)

Returns:

true if the evolution is complete.

Throws:

EvolutionException

cancelEvents

protected boolean cancelEvents()

TEST

Returns:

true if the event was properly canceled.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getEventExecutor

protected java.util.concurrent.ScheduledExecutorService getEventExecutor()

getEvolutionTask

protected EvolutionTask getEvolutionTask()

Returns:

the evolutionTask

getUi

protected java.lang.Object getUi()

TEST

Returns:

the UI for this object, as defined by setUi(Object).

isWaitUntilComplete

protected boolean isWaitUntilComplete()

Returns:

the waitUntilComplete

setEvolutionTask

protected void setEvolutionTask(EvolutionTask evolutionTask)

Parameters:

evolutionTask - the evolutionTask to set

start

protected void start(int rate,
                     boolean run)

This method starts a new evolution with generations potentially occurring at given rate (in milliseconds) [a particular Evolvable object might not undergo a new generation for every "tick" of this evolutionary clock.] The result of calling ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit) results in a new thread being started with the name formed from EvolutionThreadFactory#namePrefix, space and a sequence number.

Parameters:

rate - the rate of ticking, in milliseconds

run - whether to start in the run state (or otherwise in the paused state).

startAndWait

protected void startAndWait(int rate,
                            boolean run,
                            boolean stopFirst)

Parameters:

rate -

run -

stopFirst - XXX

stopExecutor

protected boolean stopExecutor(java.util.concurrent.ScheduledExecutorService executor,
                               int timeoutSeconds)
                        throws EvolutionException

Shutdown the given executor and wait for the tasks to terminate

Parameters:

executor -

timeoutSeconds - the number of seconds to wait for tasks to shutdown.

Returns:

the result of calling ExecutorService.awaitTermination(long, TimeUnit)

Throws:

EvolutionException