File:           readme.txt
Author:         Justin Basilico
Course:         PO CS 152: Neural Networks
Assignment:     Final Project
Updated:        2001.12.19
Created:        2001.12.19

DESCRIPTION:

This project contains code for evolving sigma-pi networks that simulate other
simple feed-forward networks. The main program is implemented in the
NetworkEvolver.java file, which is the program that runs the genetic algorithm
for evolving the sigma-pi networks. Two utility programs are also provided,
DatasetCreator which creates the datasets of random networks to simulate for
the NetworkEvolver program to read, and NetworkTester, which tests saved
networks from the NetworkEvolver against a dataset created by the
DatasetCreator.

This file explains how to compile and run each of these three programs and
also provides the exact syntax of how to replicate each of the experiments
that are described in the write-up for the project.

HOW TO COMPILE:

To compile all of the three program classes and the classes that they depend
on, just do:

    javac NetworkEvolver.java
    javac DatasetCreator.java
    javac NetworkTester.java

HOW TO RUN:

All of the programs have the same basic syntax to run, which is:

    java NetworkEvolver <parameters>
    java DatasetCreator <parameters>
    java NetworkTester  <parameters>

The parameters accepted by each program, along with a description of what they
do is provided below.


NETWORK EVOLVER:

This program implements the genetic algorithm for evolving sigma-pi networks
that are simulators for other networks. The basic idea is that it creates
chromosomes that represent the connectivity of the sigma-pi network and tests
each chromosome by loading it into a sigma-pi network and against a specified
dataset of random networks. The fitness of a chromosome is its average mean
squared error across the whole dataset, so a smaller fitness value means a
better chromosome. The program runs for the specified number of generations
and after each generation, the fitness of the best chromosome in the current
population and the average fitness of the chromosomes in the population is
output. To create the next generation from the current one, first the top 5%
of chromosomes are copied into the next generation directly. For the rest,
rank selection is used to select two chromosomes, which are crossed over at
the bit level with given probability of being swapped. Then one of the two
children is selected and mutated with the given mutation rate, which is the
chance that any one bit in the chromosome will flip. Every 100 generations the
best chromosome is loaded into a sigma-pi network and that network is output.
Also, if specified, this network will be saved into a specified file after
every given number of generations. The goal of the network evolver is to
get a chromosome whose best fitness is 0.0.

The program accepts the following parameters:

-e <experiment number>
This parameter specifies which experiment (1, 2, or 3) should be run. The
first experiment evolves a sigma-pi network that simulates a 2-1 network. The
second experiment evolves a simulator for a 2-2 network. The third evolves one
for a 2-2-1 network. The experiment number must be specified on the command-
line and it must be either 1,2, or 3. Also, make sure that the experiment
agrees with the dataset being used (which means the dataset was created for
the proper network size).

-p <population size>
This parameter specifies the size of the population to run the genetic
algorithm with. It is the number of chromosomes in the population that is
being evolved. It must be at least 1. The default is 200.

-g <number of generations>
This parameter specifies the number of generations to run the genetic
algorithm for to evolve the sigma-pi simulator networks. It must be at least
1. The default is 100.

-m <mutation rate per bit>
This parameter specifies the value for the mutation rate per bit in the
chromosome. The mutation rate must be between 0.0 and 1.0. It is really just
the percent chance any one bit will flip at each generation. The default value
is 0.01. It is suggested that the rate be kept small for the algorithm to work
properly.

-c <crossover rate per bit>
This parameter specifies the value for the crossover rate per bit in the
chromosome. The crossover rate must also be between 0.0 and 1.0. The crossover
between two chromosomes is done by just basically using a bit mask, and this
is the probability that any one bit will be crossed over. The default is 0.1.

-d <dataset file>
This parameter specifies the file that contains the dataset that the program
is going to use to test the evolved networks in the fitness function. This
parameter must be specified and the given file must be a proper file that was
created by the DatasetCreator program (or something similar) that creates
valid networks to be simulated. It is assumed that the proper dataset is given
with the experiment number. If it is not, strange results might occur. Also,
the dataset file should exist and contain some data.

-r <random number seed>
This parameter specifies the seed value for the random number generator, which
is a long value. If no random number seed is specified, then the value
returned by System.currentTimeMillis() is used.

-n <network save file>
This parameter specifies where the SigmaPiNetwork object corresponding to the
best member of the population will be stored at the end of the algorithm and
possibly every specified number of epochs. If no file is specified, then it
will not be saved. The default is to have no such file.

-s <network save epochs>
This parameters specifies how many epochs should pass between each save of the
best SigmaPiNetwork that has been created yet, using the given network save
file name. It must be a positive integer The default is 100.

-h
If this parameter is given, a help message about the usage of this program
will be output.

Example:
    java NetworkEvolver -e 1 -d experiment_1.txt -g 50 -p 100 -n network_1.net
                        -m 0.05 -c 0.2 -s 25
    This will run the first experiment using the dataset in "experiment_1.txt"
    for 50 generations with a population of 100, a mutation rate of 0.05, and
    a crossover rate of 0.2. It will save the best network into the file
    "network_1.net" every 25 epochs.
    
This program is used in the project for running the genetic algorithm. For
more information, see "NetworkEvolver.java".


DATASET CREATOR:

This program is for creating the datasets of random simple, fully-connected,
feed-forward networks that the sigma-pi networks are to try and simulate in
the NetworkEvolver program. In particular, it creates the specified number of
random networks with random weight values and turns them into an input vector
where the first units are the inputs to the network and the rest are the
weights of that network. The output associated with the input is the output
that the random network produces on the random input, since the sigma-pi
networks are trying to simulate these networks. For each weight in the network
of the specified architecture it randomly assigns a value between -5.0 and 5.0
and for each input it assigns a value between -1.0 and 1.0. The dataset is
written into a file specified by the user. The format of the file is that it
has on the first line the size of the input to expect and the size of the
output to expect. Then on every other pair of lines in the file, the first
line specifies the double input values and the second line specifies the
double output values. These should both be of the length specified by the
first line in the file. Before writing the dataset into the file it outputs
the information about the dataset it is creating.

The program accepts the following parameters:

-f <file to write dataset into>
This parameter specifies the name of the file to write the generated dataset
into. If this is a file that already exists, it will be overwritten, so be
careful. The parameter must be specified for the program to run.

-n <number to create>
This parameter specifies the positive integer number of random networks
(input/output pairs) for the program to create in the specified file. It must
be at least 1. The default value is 100.

-i <input size for network>
This parameter specifies the number of inputs that the simulated networks are
to have. It must be at least 1. The default is 2.

-o <output size for network>
This parameter specifies the number of outputs that the simulated networks are
to have. It must be at least 1. The default is 2.

-h <next hidden layer size>
This parameter adds a hidden layer of the given size to the network. It can
be used multiple times to add multiple hidden layers, where each layer will
appear in the order specified in the network, with the first one the layer
right after the input layer. Each layer must have at least one unit in it. The
default is to have no hidden layers.

-s <random number seed>
This parameter specifies the seed number (a long) that is to be used as the
seed for the random number generator. If the same seed value is given with
the same other parameters, then the networks created will be exactly the same.
The default seed is 1234567.

-H
If this parameter is specified, then a help message about the usage of the
program will be output.

Example:
    java DatasetCreator -f test.txt -n 47 -i 3 -h 2 -h 5 -o 4
    This will create 47 random networks that have 3 inputs, 3 hidden layers,
    one with 2 units and the other with 5, and an output layer with 4 units.
    It will save this dataset into the file "test.txt".

This program is used in the project to create the datasets to train the
sigma-pi simulators on. For more information, see DatasetCreator.java.


NETWORK TESTER:

This program is just for testing a network against a dataset. More
specifically, it reads in a FeedForwardNetwork object from a specified file
(such as one produced by the NetworkEvolver program) and then reads in a
dataset in the double dataset format that datasets are created with by the
DatasetCreator program. It then tests the network against all of the input in
the dataset and compares it to the expected output, outputting the mean
squared error for each input (along with the actual output and the target
output, unless specified not to do so). Once it is done, it outputs the
average mean squared error over all of the inputs in the dataset and then
outputs the entire network (unless it is specified not to do so).

The program accepts the following parameters:

-n <network file>
This parameter specifies the name of the file that contains the
FeedForwardNetwork object that is the network that will be tested against the
specified dataset. This parameter is required to run the program.

-d <dataset file>
This parameter specifies the name of the file to read the dataset of double
input and output values from, which is the dataset that the specified network
will be tested against. This dataset should have been created by the
DatasetCreator program or it at least must be in the format used by that
program. This parameter is also required to run the program.

-S
If this parameter is given, the actual output and target output values of the
network on each input will not be shown. The default is to show all of these
values, but it can be slightly hard to read for networks with large output
vectors.

-N
If this parameter is given, the network itself will not be printed out after
all of the testing is done. The default is to show the network.

-h
If this parameter is given, a help message about the usage of this program
will be output.

Example:
    java NetworkTester -n super.net -d data.txt
    This will test the network in the file super.net against the inputs in the
    file data.txt.

For the project, this program is used to test the SigmaPiNetworks created by
the NetworkEvolver to see if they have generalized to another dataset. For
more information about the network testing program see NetworkTester.java.


HOW TO RUN THE EXPERIMENTS:

EXPERIMENT 1:

To run the first experiment, I did the following commands:

First, create the two datasets used in the experiment:

java DatasetCreator -f experiment_1.txt      -i 2 -o 1 -n 100 -s 1234567
java DatasetCreator -f experiment_1_test.txt -i 2 -o 1 -n 100 -s 47474747

Run the genetic algorithm using the first dataset for fitness evaluation:

java NetworkEvolver -e 1 -d experiment_1.txt -g 50 -p 200 -n network_1.net

Finally, test the best network created by the algorithm on the other dataset:

java NetworkTester  -n network_1.net -d experiment_1_test.txt


EXPERIMENT 2:

To run the second experiment, I did the following commands:

First, create the two datasets used in the experiment:

java DatasetCreator -f experiment_2.txt      -i 2  -o 2 -n 100 -s 1234567
java DatasetCreator -f experiment_2_test.txt -i 2  -o 2 -n 100 -s 47474747

Run the genetic algorithm using the first dataset for fitness evaluation:

java NetworkEvolver -e 2 -d experiment_2.txt -g 1000 -p 200 -n network_2.net

Finally, test the best network created by the algorithm on the other dataset:

java NetworkTester  -n network_2.net -d experiment_2_test.txt


EXPERIMENT 3:

To run the third experiment, I did the following:

First, create the two datasets used in the experiment:

java DatasetCreator -f experiment_3.txt      -i 2 -h 2 -o 1 -n 100 -s 1234567
java DatasetCreator -f experiment_3_test.txt -i 2 -h 2 -o 1 -n 100 -s 47474747

Run the genetic algorithm using the first dataset for fitness evaluation:

java NetworkEvolver -e 3 -d experiment_3.txt -g 5000 -p 200 -n network_3.net

(If you try this, you might want to use a smaller number than 5000, since it
takes a very long time to run)

Finally, test the best network created by the algorithm on the other dataset:

java NetworkTester  -n network_3.net -d experiment_3_test.txt


BUGS:

There are no known bugs in this program.