Committing changes to data structures to prevent stochasticity.  The
random leak still remains.
Various changes as mentioned in emails (week of May 30): creation of of
EventProcedure
system; movement of ECJ modules to Oligopoly names; abstraction of
production and pricing stimuli; abstraction of SR in general.  Use of
the Firm as the base of simulations rather than SimpleFirm.

Merge branch 'master' of lists.tism.msu.edu:Agency

Conflicts:
	Agency/src/abce/agency/engine/MarketSimulation.java
	Agency/src/abce/io/simple/EvolvingIOFirm.java
Merge remote-tracking branch 'origin/master' with Matt's changes.

Conflicts:
	Agency/etc/price-evolve.cfg
	Agency/etc/simple-ec-agency.cfg
	Agency/src/abce/agency/Agent.java
	Agency/src/abce/agency/consumer/Consumer.java
	Agency/src/abce/agency/consumer/ReluctantSwitcher.java
	Agency/src/abce/agency/data/CSVReporter.java
	Agency/src/abce/agency/firm/ECJSimpleFirm.java
	Agency/src/abce/agency/firm/Firm.java
	Agency/src/abce/agency/firm/SimpleFirm.java
	Agency/src/abce/agency/firm/sr/ECJSimpleFirmPriceSR.java
	Agency/src/abce/io/simple/ECSimpleMarketSimulation.java
	Agency/src/abce/io/simple/SingleGoodSimulation.java
	Agency/src/abce/io/simple/ecj/SimpleAgencyConfig.java
	Agency/src/abce/io/simple/ecj/SimpleFirmFactoryEvaluator.java
Fixed bug: event_manager in MarketSimulation didn't call its finish
method at the end of the run.
Uncommenting code in MSEventProcedure to finish EPs.
Added forgotten additions to code base (doh!)

Put reorganized {EC,ECJ}Firm pattern in place.
Added simulation root to Oligopoly configuration.  EPs now use the
simulation root as the default output directory.  MarketSimulation also
checks for the simulationRoot directory and creates it if necessary; if
it already exists as a regular file the simulation displays an error and
shuts down.  simulationRoot is no longer final as configuration
information is not available at the start of child class construction
and needs to be set after construction.
Major modifications to Evaluator and Problem setups to provide
EvaluationGrouper functionality and improved concurrency support.

Randomness leak is fixed by changes.

Code Changes
------------

MarketSimulation
~~~~~~~~~~~~~~~~

MarketSimulation should implement Callable rather than runnable to yield
return values and checkable exceptions.  This isn't strictly needed
right now, but we should get in the habit of throwing and handling
exceptions rather than ungracefully shutting down the experiments.  For
example, I (Matt) have been using System.exit(1) to shutdown the JVM in
the event of an unrecoverable exception.  This has the unfortunate
problem of not nicely shutting things down, so resources (such as files)
don't get gracefully flushed and closed.  We will need to come up with a
good system to shut domain models down in the event of unrecoverable
incidents if we want to make sure that we don't corrupt any resources.  


NumericalStimulusNode & SRStimulable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NumericalStimulusNode now implements the SRStimulable interface.  The
interface provides a common means of getting and setting the method path
prior to evaluation.  The reason for this change is listed below.


Evaluation and Problems
~~~~~~~~~~~~~~~~~~~~~~~

The Evaluator should really just decide which individuals get placed
into domain models and handle threading issues.  It shouldn't
instantiate domain models or evaluate fitnesses, which is the job of
Problems in ECJ parlance.  I moved model creation, execution, and
fitness evaluation to a new OligopolyProblem and created a new Evaluator
and ProblemForm for grouped evaluations.  These changes buy us at least
two things: (1) we are now following ECJ's design pattern more closely,
which will make explaining our system much easier and highlight the
novelties of our setup and (2) it will make it easier to create a
spatially aware evaluator and other types of Evaluators since it
separates out model concerns from individual picking concerns.  Our
setup is novel (or at least interesting) because we create a domain
problem (the oligopoly, simternet) which emits a second set of problems
(StimulusResponseProblems).  The domain-emitted problems provide a
generic means of creating a faceted view of the domain model for the EC
representations to use.  This code change codifies that explanation in
our codebase.  Since ECJ does not provide a spatially aware
CompetitiveEvaluator, we will have to create one.  The separation of the
domain concerns makes this much easier as all evaluators simply need to
know how to use a variant of the ECJ GroupedProblemForm interface to
evaluate representations in our domain model.


To facilitate a way of populating and evaluating models in a manner that
fits our Simternet work (and creates a means of trying to detect and
handle exceptions), I created a series of new classes that modify
pre-existing ECJ methods.  Specifically:

- GroupedEvaluator handles the creation and execution of Problems.

- EvaluationGrouper creates groups of individuals to be evaluated and
decides which individuals get their fitnesses updated.

- CallableGroupProblemForm is an interface that evaluates individuals
using EvaluationGroups created by EvaluationGrouper.


The new GroupedEvaluator creates, excecutes, and handles problems with
all problems.  For this project, I'm implementing a new type of Problem
interfaced called CallableGroupProblem.  The combination of these
classes works as follows:

1. ECJ calls the evaluator, in this case GroupedEvaluator.

#. GroupedEvaluator prepares the CallableGroupProblem.  In the case of
the OligopolyProblem, we *must* set all method paths prior to
evaluation.  This is because if any Individual is not fully determined
by evaluation time, then it can only be used in a single evaluation
without causing a race condition.  This is because any unbound Stimulus
node will be set by the domain model that calls it.  Originally, paths
were set on the first call to eval; this is still the case without any
intervention.  But, if we want independent or aggregated fitness
measures (see below), we need to relax the one-generation one-problem
evaluation condition.

#. GroupedEvaluator initializes an EvaluationGrouper through its
prepareGrouper(...) interface.

#. The EvaluationGrouper returns sets of EvaluationGroups to be
evaluated together via its next() method.  When there are no more groups
to evaluate, next() returns null.

#. The GroupedEvaluator assigns each EvaluationGroup to a queue
associated with each thread (this is done as part of #3).

#. The GroupedEvaluator calls its evaluate(...) method.  This method
creates a thread for each EvaluationGroup queue it receives.  Each
thread executes an GroupedEvaluatorAssistant, which receives a thread
number assignment.

#. The GroupedEvaluatorAssistant invokes the call method on an instance
of CallableGroupProblem.  If the problem's execution time exceeds a set
value (set via the problem's "timeout_sec"), then the execution is
aborted and an exception is thrown.  The exception is handled in the
GroupedEvaluatorAssistant's evaluate(...) method.

#.  If problem execution is successful, statistics about how long the
problem took to evaluate is collected.

#.  GroupedEvaluator displays the problem evaluation timing statistics.


The GroupedProblemForm, Groupedevaluator, and EvaluationGroupers that we
create for the Oligopoly can also be used in Simternet.

Right now the only EvaluationGrouper I have created is called
PrimarySPFixedSizeEvalGrouper.  This Grouper systematically evaluates
the fitnesses of all individuals in a population *independently* of all
other individuals.  This type of setup increases the time it takes to
evaluate a generation as our previous setup created chunks of agents
whose fitnesses were evaluated simultaneously.  Individuals were only
evaluated in a single chunk per generation.  There are two reasons I'd
like to get away from that setup: pseudo-replication and having a common
way to evaluate non-spatial (mass action) and spatial populations. 
Pseudo-replication may be an issue since fitnesses are not evaluated
independently for each individual in the current chunking setup. Instead
of getting N independent fitness measures, one for each member of a
subpopulation we are getting N conditional fitness measures from M
experiments.  Later on, this type of dependence may make it difficult to
draw statistical inferences.  As for spatially-aware evaluators, much of
the machinery needed to make a -threaded version of independent
evaluation is needed for multi-threaded spatially-aware evaluation.
Concurrency is required for a multi-threaded spatially-aware because
individual "chunks" need to be composed of Individuals "next to" each
other, and there is the possibility that an individual from one chunk
would have an overlapping individual from a neighboring chunk.

I've done some code re-arrangement and created a new configuration file
to handle the GroupedProblem setup.  I want to discuss the changes in
this document before making such a radical alteration.  

There are a few other changes:

- Timeout information is now stored in the configuration as
"eval.problem.timeout_sec" or "problem.timeout_sec"
- Parameter base of the domain instance for configuration is stored as
"eval.problem.name" or "problem.name" (e.g. oligopoly)
- I continue to clarify the distinction in code-based names between
Agency and Oligopoly


Known Issues
~~~~~~~~~~~~

We should make sure that nothing in the
GPIndividuals change during domain execution without explicit
coordination of the Evaluator or Problem.  Fitnesses, for example, can
change during domain execution but the Evaluator/EvaluationGrouper
should ensure that all individuals that will have their fitnesses
updated will either be part of the same thread queue or will only be
updated only once per generation.  More complex fitness aggregations
could be handled by introducing a synchrnoized Fitness object in the
future to remove these restrictions.

ECJProdPriceFirm should really have some type of shared-object that they
use to avoid having many potentially many agents needing to know
independently about the EvolutionState and current evaluation thread
number (required for GPTree evaluation).

The generation-time event manager needs to be put into the new evaluator
(or problem) in one of the pre-processing methods.
Separating out concerns of Problems for portability between evaluation
domains and representations.

MASProblem will be the base CallableGroupProblemForm for Multi Agent
Simulations using SR.  GPIndividual specific material is now in its
child class GPMASProblem, and the actual Oligopoly domain material is in
the OligopolyProblem, a child of GPMASProblem.
Adding eset and dset flags; restoring domain events

Altering default configuration from the command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added eset and dset flags to override Parameter database settings in the
config file for ECJ and the domain model, respectively.  The overrides
to ECJ's parameter database are made in the EPSimpleEvolutionState
class; the overrides to the domain model configuration are prepared in
the Problem's prepareEvaluator method and actually overriden after model
creation in the OligopolyProblem code.

As a precaution against configuration loss, the actual configuration
used by both components needs to be stored, either to the standard
output as part of a run log or to a dedicated configuration log.  Right
now this is done by displaying the command line arguments to stderr when
collecting eset and dset changes.

In order to get the domain model configured correctly via dset,
initialization needs to be delayed.  The constructor to
OligopolySimulation now just initializes a bare-bones (seed only)
version of MarketSimulation and loads and registers the configuration
file.  A separate initialize() step is called prior to model execution. 
This allows for the OligopolyProblem to modify the model's configuration
files prior to initialization.  Some final attributes needed to be
removed from some members since their initialization is no longer done
in the constructor.


Adding Domain Event Handling Back
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The hooks to set domain model events was temporarily removed.  I have
just added it back.  There at least two places where domain events
descriptions could reside prior to being placed into the domain model:
either in the problem instance or the EvolutionState.  I chose to go
with the latter again since I didn't want a static member handling
shared information between problems, worrying about concurrency since
Problem evaluation is multi-threaded.  The main evolution loop where the
other ECJ events are hooked in is part of the single-threaded portion of
the ECJ code.  So, as before, domain events are created by triggering a
specially created EventProcedure that fills in the domain_events member
of EPSimpleEvolutionState.  The problems use this array to configure the
domain model.

ECJEventProcedureManager now has a toString() method to display the
current state of its queues.
Adding spatial primary subpop eval grouper; rename existing non-spatial
version.

The new SpatialPrimaryFSEvalGrouper will only group Individuals in the
primary subpopulation together if they are local to one another via the
Space interface.  Subpopulations that do not implement Space will throw
a runtime error if they are used as primary_subpopulations.  Individuals
outside of the primary subpopulation are still chosen at random.
Adding missing generation setting to OligopoplySimulation.
Adding FileManager; updating reporting procedures

There are two ways I can think of to deal with reporting: take a static
approach like log4j or pass around file handles via a file manager. 
Since it is easy to implement, I went ahead and added in a
FileManager to EPSimpleEvolutionState that gets shared with the domain
problems.  Procedures simply request a file by path name (or with
initialization arguments); if the file is already open then the file is
returned or a new file is created / exception thrown if the file cannot
be created.  This make the use of files pretty easy and provides a
single way of retrieving the file regardless if the file is open,
exists, or not.

DelimitedOutFile out = state.file_manager.getDelimitedOutFile(path,
format)

OligopolySimulation gets its file manager set by OligopolyProblem prior
to model initialization.  The Procedures that perform output access the
file manager via the OligopolySimulation object that is passed while
processing an event and its context.

The main issue (though it's not horrible by any stretch) is that files,
once open, need to remain open until the end of the simulation.  This is
because there are no policies in place to decide whether or not a file
should be overwritten or appended.  Instead, the default is that if a
file exists prior to its first opening, the file is replaced.  That file
then remains open and accessible through the file manager until the end
of the experiment to prevent overwriting.
Adding final attribute to MSEventProcedureManager's EVENT_STEP.
Added fitness to EvaluationGroup for statistics collection.

FileManager
-----------
Make sure that active_files are not stored on serialization.  The member
is now marked as transient and initialized to empty on deserialization.

EvaluationGroup
---------------
Fitness values are now stored with the group.  These fitnesses are set
by the OligopolyProblem but are not used during selection.  Their
primary purpose is to allow fitnesses that won't be used for selection
to be passed back from the Problems for data collection.

OligopolyProblem
----------------
Modified to set fitnesses in EvaluationGroup, not just with the
individual.

MASProblem
----------
Added the ability to clone the problem.
FileManager
-----------
Fixed problem with root_directory not being set during initialization.


EvaluationGroup
---------------
Added a member "last_results" that will store the last array of
EvaluationGroups (with fitnesses) so they can be processed outside of
evaluate. 

Added a reset method to clear last_results.


OligopolyProblem
----------------
Removed all references to AgencyGPIndividual.


AgencyGPIndividual
------------------
Removed entirely.


ECJEvolvableAgent
-----------------
Switched register member to use GPIndividual rather than
AgencyGPIndividual.


ECJPriceProdFirm
----------------
Switched register member to match new ECJEvolvableAgent signature.


TaggedIndividual
----------------
Created an interface to store a byte of information along with an
individual. The idea behind this is that origin information could be
stored in the tag when we're using individuals from multiple
populations.


TaggedGPIndividual
------------------
GPIndividual implementing TaggedIndividual interface.   


mass-priceprod-evolve.cfg
-------------------------
Changed subpopulation 0's individual to TaggedGPIndividual.
Bugfix:  Added VM hook to flush & close output files on VM exit. 
Without this, GZ files are corrupt.
Initial commit of iterated cournot simulation
Bug fix for GPFalse; added Debugger; added node value debugging; added
EvaluationGrouperDefaults


GPFalse
-------
Bug fix: GPFalse sadly returned true.


Debugger
--------

Inspired by Simternet's debug system, I created a Debugger class for
ECJ.  The debugger "events" differs from normal events in the following
ways:

+ They are compile-time established using final static members to
disable entire code trees.

+ There is no context evaluation system.  It's up to the individual code
blocks to determine whether or not they should trigger.

+ They are to be used only for debugging if possible.


EPSimpleEvolutionState
----------------------

Now includes a debugger object to set debug parameters.  It is created
at both startFresh and startFromCheckPoint.  It can be configured via
the parameter database.



GPNodeDebug
-----------

GPNodeDebug contains a single method for writing node value information
to a file.  With the exception of Response (because of the complexity of
its output), all other terminal and operator GPNodes have the ability to
log their results.  There is no performance hit for this capability
since the compiler shouldn't include unreachable code; the conditional
used in the test is a static final member stored in Debugger.

Currently, the only debug setting is for DEBUG_NODE_VALUES to randomly
sample the values returned by nodes and log them to an output file
controlled by the EvolutionState's file manager.  Configurable
parameters include when the event should be triggered (by a modulo) and
how nodes should be sampled (currently probabilistically).  The file
name can also be changed in the future, but I didn't write that code in.

The main purpose of the GPNodeDebug is to see what numbers and values
are being produced as well as how often different nodes are being used.


EvaluationGrouperDefaults
-------------------------

Added to make EvaluationGrouper more ECJ-like in its design.


mass-priceprod-evolve.cfg
--------------------------
Added debug block
Merge remote-tracking branch 'origin/master'