CARLsim  3.0.3
CARLsim: a GPU-accelerated SNN simulator
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Chapter 10: ECJ

CARLsim-ECJ Parameter-Tuning Framework Overview

CARLsim now has a software interface to an evolutionary computation system written in Java (ECJ) (Luke et al., 2006) to provide an automated parameter tuning framework. We found that an automated tuning framework became increasingly useful as our SNN models became more complex. Evolutionary Algorithms (EAs) enable flexible parameter tuning by means of optimizing a generic fitness function. The first version of the automated paramter-tuning framework used an EA library called Evolving Objects (EO) as the EA engine (Carlson et al., 2014). ECJ was chosen to supercede EO because it is under active development (Linux), supports multi-threading, has excellent documentation, and implements a variety of EAs (Luke at al., 2006).

10_ecj.png
Fig. 1. General approach to parameter tuning. ECJ performs the EA and passes the current generation of parameters (red arrow) to CARLsim for evaluation using the parameter tuning interface (PTI) code. CARLsim assigns each parameter set to an SNN and evaluates all the individuals in parallel, passing the fitness values back to ECJ for selection of individuals in the next generation (black arrow).

Source: Beyeler et al., 2015

Fig. 1 shows the general approach of the automated parameter tuning framework. ECJ implements an EA with a parameter file that includes: EA parameters, the number of individuals per generation, and parameter ranges. Each step of the EA is executed by ECJ except for the evaluation of the fitness function, which is completed by CARLsim. CARLsim evaluates the fitness function in parallel by running multiple SNN individuals simultaneously on the GPU, where the bulk of the computations occur. ECJ is written in Java, which is slower than C, but the majority of the execution time is spent running CARLsim’s optimized C++/CUDA code. At the beginning of every generation, the parameters to be tuned are passed from ECJ to CARLsim using standard input/output streams in Linux. CARLsim evaluates individuals in parallel and returns the resulting fitness values to ECJ via standard streams. The tuning framework allows users to tune virtually any SNN parameter, while the fitness functions can be written to depend on the neuronal activity or synaptic weights of the SNN.

Since
v3.0

10.2 Installation

The current version of the CARLsim paramter-tuning framework uses Evolutionary Computations in Java (ECJ) (version 22 or greater is required). For up-to-date installation instructions, please go to the official ECJ website.

10.2.1 Installing ECJ

At the time of writing, installing ECJ 22 on Unix systems involves the following steps.

  • Prerequisites:
    • Verify the version of Java and Ant installed on your system, and make sure to have at least Java OpenJDK 1.7 and Ant1.8:
      $ java -version
      $ ant -version
    • Make sure the environment variable $JAVA_HOME points to the OpenJDK library:
      $ locate java-1.
      /usr/lib/jvm/.java-1.7.0-openjdk-amd64.jinfo
      /usr/lib/jvm/java-1.7.0-openjdk-amd64
      $ export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk-amd64
      You can also place the export statement in your ~/.bashrc so you don't have to run it every time you open a new terminal.
  • Installation:
  • Download the tar.gz or zip file from here and extract the files in a suitable place (e.g., ~/Downloads).
  • Compile the code using the provided Makefile, and move the files to /opt/ecj:
    $ cd ~/Downloads/ecj
    $ make
    $ cd ..
    $ sudo mv ecj /opt
  • Make sure the location of the ECJ package is part of the $CLASSPATH environment variable:
    $ export CLASSPATH=$CLASSPATH:/opt/ecj
    You can also place this command in your ~/.bashrc so you don't have to run it every time you open a new terminal.

You can verify the installation by running (for example) Tutorial 1:

$ cd /opt/ecj/
$ java ec.Evolve -file tutorial1.param

If the installation was successful, you should see the app report evolving fitness values, such as:

Generation 35
Subpop 0 best fitness of generation Fitness: 0.95
Generation 36
Subpop 0 best fitness of generation Fitness: 1.0
Found Ideal Individual
Subpop 0 best fitness of run: Fitness: 1.0
Note
If you see the error "Error: Could not find or load main class ec.Evolve", make sure the $CLASSPATH environment variable exists and points to the right location (see above).

10.2.2 Installing the CARLsim-ECJ Parameter Tuning Interface

After ECJ version 22 or greater has been installed the user then needs to set the ECJ_DIR and ECJ_PTI_DIR environment variables in either the .bashrc file or the user.mk file located in the tools/ecj_pti subdirectory. The ECJ_DIR environment variable points to the current installation location of ECJ. The ECJ_PTI_DIR environment variable points to the desired location of the CARLsim-ECJ PTI code. The code below shows the default values that can be changed in the user.mk file:

#------------------------------------------------------------------------------
# CARLsim/ECJ Parameter Tuning Interface Options
#------------------------------------------------------------------------------
# path of evolutionary computation in java installation for ECJ-PTI CARLsim
# support
ECJ_DIR ?= /opt/ecj
ECJ_PTI_DIR ?= /opt/CARL/carlsim_ecj_pti
Warning
The user should note that the user.mk file in the tools/ecj_pti directory is distinct from the user.mk file in the main carlsim directory and not confuse them. Here we are configuring the user.mk file in the tools/ecj_pti subdirectory.

You can also place this command in your ~/.bashrc so you don't have to run it every time you open a new terminal.

export ECJ_DIR = /opt/ecj
export ECJ_PTI_DIR = /opt/CARL/carlsim_ecj_pti
Note
You may have to open a new shell or $ source ~/.bashrc these variables exported.

Once the environment variables have been set, navigate to tools/ecj_pti and run:

make && sudo make install

This will install the CARLsim-ECJ PTI static library into the location pointed to by ECJ_PTI_DIR.

You can verify the installation by (for example) running Tutorial 5: Parameter Tuning Interface (PTI).

Since
v3.0

10.3 ECJ Usage

In general, users will create their own project directory and model it after the tutorial program found in Tutorial 5: Parameter Tuning Interface (PTI). Users configure a ECJ parameter file and implement a CARLsim fitness evaluation function. ECJ performs the EA utilizing the user-defined parameter file and runs the CARLsim 'main' program every generation to evaluate the fitness for all individuals in parallel. Each individual represents a different SNN with a unique set of parameter values. ECJ outputs the fitness and parameter files to log files every generation. Parameter values from high-fitness SNNs can then be used in SNN modeling and simulation.

First the ECJ configuration file must be edited. Parts of the ECJ configuration file are shown below:

parent.0 = @ec.simple.SimpleEvolutionState simple.params
# Modifications to the Simple EA boiler plate
# =========================
eval = ecjapp.eval.SimpleGroupedEvaluator
generations = 50
pop.subpop.0.size = 10
# Set up our evolutionary algorithm
# =========================
pop.subpop.0.species = ec.vector.FloatVectorSpecies
pop.subpop.0.species.pipe = ec.vector.breed.VectorMutationPipeline
pop.subpop.0.species.pipe.likelihood = 1.0
pop.subpop.0.species.pipe.source.0 = ec.vector.breed.VectorCrossoverPipeline
pop.subpop.0.species.pipe.source.0.likelihood = 0.9
pop.subpop.0.species.pipe.source.0.source.0 = ec.select.TournamentSelection
#pop.subpop.0.species.pipe.source.0.source.0 = ec.es.ESSelection
pop.subpop.0.species.pipe.source.0.source.1 = same
select.tournament.size = 2
pop.subpop.0.species.ind = ec.vector.DoubleVectorIndividual
pop.subpop.0.species.fitness = ec.simple.SimpleFitness
pop.subpop.0.species.genome-size = 4
pop.subpop.0.species.min-gene = 0.0005
pop.subpop.0.species.max-gene = 0.5
pop.subpop.0.species.mutation-type = gauss
pop.subpop.0.species.mutation-stdev = 0.1
pop.subpop.0.species.mutation-bounded = true
pop.subpop.0.species.mutation-prob = 0.4
pop.subpop.0.species.crossover-likelihood =0.4
#pop.subpop.0.species.crossover-prob= 0.9
pop.subpop.0.species.crossover-type = two
# breed options
breed = ec.es.MuPlusLambdaBreeder
breed.elite.0 = 1
breed.reevaluate-elites.0 = false
# evolution strategies options
es.mu.0 = 5
es.lambda.0 = 5
# Termination condition
quit-on-run-complete = true
# Set up external fitness evaluation
# =========================
eval.problem.objective.idealFitnessValue = 0.333
eval.problem = ecjapp.eval.problem.CommandProblem
eval.problem.objective = ecjapp.eval.problem.objective.StringToDoubleObjective
eval.problem.simulationCommand = $carlsim_tuneFiringRatesECJ

It's probably easiest to start with this ECJ parameter file and modify it to your project's needs. The particular variables the user needs to edit are:

eval.problem.simulationCommand: which is the name of the carlsim binary ECJ executes every generation to evaluate the fitness function. The $ sign means the path is relative to the location of the parameter file.

generations: number of maximum generations to run.

pop.subpop.0.size: number of individuals in each generation.

pop.subpop.0.species.genome-size: total number of parameters to be tuned in each individual.

pop.subpop.0.species.min-gene: default minimum range value for all parameters to be tuned

pop.subpop.0.species.max-gene: default maximum range value for all parameters to be tuned

To specify the parameter range for each parameter individually, you define min-gene and max.gene values for additional pop.subpop members as is shown in the code below:

pop.subpop.0.species.min-gene.0=0.0004
pop.subpop.0.species.max-gene.0=0.004
pop.subpop.0.species.min-gene.1=0.00005
pop.subpop.0.species.max-gene.1=0.0005
pop.subpop.0.species.min-gene.2=0.01
pop.subpop.0.species.max-gene.2=0.1
pop.subpop.0.species.min-gene.3=0.1
pop.subpop.0.species.max-gene.3=0.2

However,you still need to keep the pop.subpop.0.species.min-gene and pop.subpop.0.species.max-gene in the parameter file.

for more information about the ECJ configuration file, please visit the ECJ homepage.

Users then need to implement their own CARLsim evaluation function. The overall structure is as follows. A specific Experiment class is implemented and inherited from the base Experiment class:

class TuneFiringRatesECJExperiment : public Experiment {

The only class functions functions are the default class constructor and the run function. The run function is where CARLsim code is written and executed. At the final step, the fitness values are output back to ECJ using standard Linux streams.

void run(const ParameterInstances &parameters, std::ostream &outputStream) const {
...
CARLsim* const network = new CARLsim("tuneFiringRatesECJ", GPU_MODE, SILENT);
...
network->setupNetwork();
...
network->runNetwork(runTime,0);
...
for(unsigned int i = 0; i < parameters.getNumInstances(); i++) {
...
outputStream << fitness[i] << endl;
...
}
See Also
Tutorial 5: Parameter Tuning Interface (PTI)
Since
v3.0

References

  • Beyeler, M.*, Carlson, K.D.*, Chou, T.-S.*, Dutt, N., and Krichmar, J.L. (2015). CARLsim 3: A User-Friendly and Highly Optimized Library for the Creation of Neurobiologically Detailed Spiking Neural Networks. Paper presented at: International Joint Conference on Neural Networks (Killarney, Ireland: IEEE Explore). (*co-first authors)
  • Carlson, K. D., Nageswaran, J. M., Dutt, N., Krichmar, J. L., An efficient automated parameter tuning framework for spiking neural networks, Front. Neurosci., vol. 8, no. 10, 2014.
  • Luke, S., Panait, L., Balan, G., Paus, S., Skolicki, Z., Bassett, J., Hubley, R., and Chircop, A., ECJ: A java-based evolutionary computation research system, http://cs. gmu. edu/eclab/projects/ecj, 2006.