jas.ai.ann
Class NeuralNetwork

java.lang.Object
  jas.ai.ann.NeuralNetwork

public class NeuralNetwork
extends java.lang.Object

An implemntation of a three-layer artificial neural network. The learning mechanism is based on the error backpropagation.

Title: JAS

Description: Java Agent-based Simulation library

Copyright: 2003 Michele Sonnessa

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

Author:

Michele Sonnessa

Constructor Summary

NeuralNetwork(boolean withBias, int inputNodes, int hiddenNodes, int outputNodes)
Create a new artificial neural network.

NeuralNetwork(java.io.File annFile)
Create a new artificial neural network loading parameters from the given file.

Method Summary

void	assignNextDataSetSample() Assign input and target values of the current data sample in the NeuralDataSet.
NeuralDataSet	createNeuralDataSet() Create an empty dataset
void	evolve() Not yet implemented.
NodeLayer	getHiddenLayer() Return the current hidden layer.
Jama.Matrix	getHOWeights() Return the current hidden/output weight matrix.
Jama.Matrix	getIHWeights() Return the current input/hidden weight matrix.
InputNodeLayer	getInputLayer() Return the current input layer.
double	getLearningRate() Return the current learning rate.
double	getMomentum() Return the current momentum rate.
NeuralDataSet	getNeuralDataSet() Return the current data set.
OutputNodeLayer	getOutputLayer() Return the current output layer.
double	getOutputValue(int nodeIndex) Return the output value for the given node index.
double[]	getOutputVector() Return the whole output vector
boolean	getRandomLearningSequence() Return the current learning sequence order.
OutputNodeLayer	getTargetLayer() Return the current target layer.
boolean	hasBias() Tell if the ANN has got bias nodes or not.
boolean	isOutOfScale() If one of the input passed values or one of the output values comes out of the min/max ranges this method alerts.
void	learn() Make an epoch of training, analyzing each data sample.
void	pushDataInDataSet() Append to the NeuralDataSet the current input/target value set.
void	pushDataInDataSet(boolean inTraining) Append to the NeuralDataSet the current input/target value set.
void	randomizeWeights() Randomize the Wih and Who weight matrixes, using the standard randomWeightsRange range (-0.3, 0.3).
void	randomizeWeights(double weightRange) Randomize the Wih and Who weight matrixes, using the given range.
boolean	saveToFile(java.io.File annFile) Save the ANN to an XML file, without saving the current data set.
boolean	saveToFile(java.io.File annFile, boolean withDataSet) Save the ANN to an XML file.
void	setInputValue(int nodeIndex, double value) Assign an input to a specific node, using an orginal scale.
void	setInputVector(double[] values) Assign an array of values to the whole input layer, using an orginal scale.
void	setLearningParameters(double learningRate, double momentum, boolean randomLearningSequence) Set the paramters used in the learning of the ANN.
void	setNeuralDataSet(NeuralDataSet nds) Set a new neural data set to this ANN.
void	setTargetVector(double[] values) Assign an array of values to the whole target layer, using an orginal scale.
void	think() Compute the output values according to the current input ones.
java.lang.String	toStringWHO() Create a string representation of the current WHO matrix.
java.lang.String	toStringWIH() Create a string representation of the current WIH matrix.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NeuralNetwork

public NeuralNetwork(boolean withBias,
                     int inputNodes,
                     int hiddenNodes,
                     int outputNodes)

Create a new artificial neural network.

Parameters:

withBias - If true the input and hidden layers are created with a dummy node with constant value 1.0.

inputNodes - The number of nodes in the input layer (except the bias node).

hiddenNodes - The number of nodes in the hidden layer (except the bias node).

outputNodes - The number of nodes in the output layer.

NeuralNetwork

public NeuralNetwork(java.io.File annFile)

Create a new artificial neural network loading parameters from the given file.

Parameters:

annFile - An XML file containing ANN parameters.

Method Detail

assignNextDataSetSample

public void assignNextDataSetSample()

Assign input and target values of the current data sample in the NeuralDataSet. It may be used with the iteration methods.

createNeuralDataSet

public NeuralDataSet createNeuralDataSet()

Create an empty dataset

Returns:

The new NeuralDataSet.

evolve

public void evolve()

Not yet implemented.

getHiddenLayer

public NodeLayer getHiddenLayer()

Return the current hidden layer. It is a direct reference to the internal variable: any change to the variable will affect the behaviuor of the ANN.

Returns:

The hidden node layer.

getHOWeights

public Jama.Matrix getHOWeights()

Return the current hidden/output weight matrix. Hidden nodes are referenced by rows, while output ones by columns of the matrix. WARNING: It is a direct reference to the internal variable: any change to the matrix will affect the behaviuor of the ANN.

Returns:

The target node layer.

getIHWeights

public Jama.Matrix getIHWeights()

Return the current input/hidden weight matrix. Input nodes are referenced by rows, while hidden ones by columns of the matrix. WARNING: It is a direct reference to the internal variable: any change to the matrix will affect the behaviuor of the ANN.

Returns:

The target node layer.

getInputLayer

public InputNodeLayer getInputLayer()

Return the current input layer. It is a direct reference to the internal variable: any change to the variable will affect the behaviuor of the ANN.

Returns:

The input node layer.

getLearningRate

public double getLearningRate()

Return the current learning rate.

Returns:

The learning rate.

getMomentum

public double getMomentum()

Return the current momentum rate.

Returns:

The momentum rate.

getNeuralDataSet

public NeuralDataSet getNeuralDataSet()

Return the current data set.

Returns:

The current NeuralDataSet.

getOutputLayer

public OutputNodeLayer getOutputLayer()

Return the current output layer. It is a direct reference to the internal variable: any change to the variable will affect the behaviuor of the ANN.

Returns:

The output node layer.

getOutputValue

public double getOutputValue(int nodeIndex)

Return the output value for the given node index. The value is unscaled, according to the min/max matrix.

Parameters:

nodeIndex - The 0-based index of the output layer.

Returns:

The unscaled value for the specified node.

getOutputVector

public double[] getOutputVector()

Return the whole output vector

Returns:

An array of values representing unscaled output of the ANN.

getRandomLearningSequence

public boolean getRandomLearningSequence()

Return the current learning sequence order.

Returns:

If true, iterator choose samples randomly, otherwise it follows the original order.

getTargetLayer

public OutputNodeLayer getTargetLayer()

Return the current target layer. It is a direct reference to the internal variable: any change to the variable will affect the behaviuor of the ANN.

Returns:

The target node layer.

hasBias

public boolean hasBias()

Tell if the ANN has got bias nodes or not.

Returns:

The bias flag state.

isOutOfScale

public boolean isOutOfScale()

If one of the input passed values or one of the output values comes out of the min/max ranges this method alerts.

Returns:

True if one of the original values in the input or in the output layer is out of scale range.

learn

public void learn()

Make an epoch of training, analyzing each data sample. It iterates the neural data set using the nextTrainingItem() method of the NeuralDataSet class.

pushDataInDataSet

public void pushDataInDataSet()

Append to the NeuralDataSet the current input/target value set. The inserted sample is assigned true to the flag inTraing.

pushDataInDataSet

public void pushDataInDataSet(boolean inTraining)

Append to the NeuralDataSet the current input/target value set.

Parameters:

inTraining - If true the sample is used during the learning, otherwise it will be used only for testing.

randomizeWeights

public void randomizeWeights()

Randomize the Wih and Who weight matrixes, using the standard randomWeightsRange range (-0.3, 0.3).

randomizeWeights

public void randomizeWeights(double weightRange)

Randomize the Wih and Who weight matrixes, using the given range.

Parameters:

weightRange - A double value representing the negative and positive bounds of the random range. For instance, a value of 0.4 will generate weights uniformly random within the range [-0.4, 0.4].

saveToFile

public boolean saveToFile(java.io.File annFile)

Save the ANN to an XML file, without saving the current data set.

Parameters:

annFile - A file (better if .xml) on the file system.

saveToFile

public boolean saveToFile(java.io.File annFile,
                          boolean withDataSet)

Save the ANN to an XML file. Current data set is saved according to the value of the given parameter.

Parameters:

annFile - A file (better if .xml) on the file system.

withDataSet - If true the XML file will contain the dataset, too. Otherwise only parameters and weights are saved.

setInputValue

public void setInputValue(int nodeIndex,
                          double value)

Assign an input to a specific node, using an orginal scale. The value will be scaled to the [0-1] range by the ANN, according the the min/max matrix.

Parameters:

nodeIndex - The number of the node (bias is not considered: nodeIndex 0 corresponds to the first non-bias node).

value - The unscaled values for the node.

setInputVector

public void setInputVector(double[] values)

Assign an array of values to the whole input layer, using an orginal scale. The values will be scaled to the [0-1] range by the ANN, according the the min/max matrix.

Parameters:

values - An array of double representing the input for each input node (bias is not considered).

Throws:

java.lang.ArrayIndexOutOfBoundsException - If values.length is not equal to the input vector length.

setLearningParameters

public void setLearningParameters(double learningRate,
                                  double momentum,
                                  boolean randomLearningSequence)

Set the paramters used in the learning of the ANN.

Parameters:

learningRage - (Epsilon) Is a double value between 0.0 and 1.0, representing the rate of changes in weights at each learning step. The more the learningRage is higher the more the ANN adapts to data samples.

momentum - Represents the momentum effect in the learning algorithm. High momentum values (0.0 - 1.0) keep the weight structure insensible to data changes.

randomLearningSequence - If true the learning algorithm selects randomly the sequence of data samples, otherwise the sequence correspondes to the original data input order.

setNeuralDataSet

public void setNeuralDataSet(NeuralDataSet nds)

Set a new neural data set to this ANN. WARNING: There is no check of input and output nodes correspondence. Please ensure that the given data set is compatible with this ANN structure.

Parameters:

nds - The new neural data set for this ANN.

setTargetVector

public void setTargetVector(double[] values)

Assign an array of values to the whole target layer, using an orginal scale. The values will be scaled to the [0-1] range by the ANN, according the the min/max matrix.

Parameters:

values - An array of double representing the target for each target node.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If values.length is not equal to the output vector length.

think

public void think()

Compute the output values according to the current input ones.

toStringWHO

public java.lang.String toStringWHO()

Create a string representation of the current WHO matrix.

Returns:

A string with a representation of the WHO matrix.

toStringWIH

public java.lang.String toStringWIH()

Create a string representation of the current WIH matrix.

Returns:

A string with a representation of the Wih matrix.