NearNeural

Class NeuralNet

java.lang.Object

NearNeural.NeuralNet

public class NeuralNet
extends java.lang.Object

A practical implementation of a feed-forward back propogating multi-layer perceptron network. In this implementatiion each net is comprised of layers of Neurons, connected by edges. Layers represent merely an ordered group of neurons which are guaranteed not to be connected either to themselves or to those in the layer downstream from themselves. Any number of input and output nodes are supported, with as little as two layers and a sum of two Neurons in the whole net.

The net can be trained by providing 'perfect' data in a given pattern using the train method. Its memory can be saved to a file and later loaded to allow for persistent learning. A custom backpropagation model defines what algorithm is used to train the net.

As of v0.2.0a Edges between nodes can be broken and moved manually. This is extremely powerful but also extremely dangerous as the net does not check for circular links. If you are to add entropy to link management it is probably wise to implement a checking algorithm.

Version:

0.3.0b

Author:

Stephen Wattam

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String[]	supportedVersions The versions from which this version can load files.
java.lang.String	version The version of the net code.

Constructor Summary

Constructors

Constructor and Description
NeuralNet(double[] p_inputs, int[] p_layers, ThresholdingAlgorithm p_thresholdModel, BackPropagationMethod p_backprop) Creates a new net with p_layers.length+1 layers, each with n nodes in them.
NeuralNet(java.io.FileReader p_file, ThresholdingAlgorithm p_thresholdModel, BackPropagationMethod p_backprop) Create a net from a saved net file.

Method Summary

Methods

Modifier and Type	Method and Description
BackPropagationMethod	getBackPropagationMethod() Returns the BackPropagationMethod used to train the net.
NeuronLayer	getLayer(int p_index) Returns a layer such that one may edit its nodes and structure manually.
int[]	getLayerStructure() Returns an array of integers representing the structure of the net.
Neuron	getNeuron(int p_layerIndex, int p_neuronIndex) Returns a neuron from anywhere in the current net.
int	getNumberOfLayers() Returns the number of layers in the net, without any extra information.
double[]	getOutput() Returns the output of the net as an array of doubles as long as the amount of output Neurons.
java.lang.String[]	getSupportedFileVersions() Returns an array of strings that represent (and correlate with) version ids from which this net can load files.
void	preCalculate() Precalculates all neuron values in order to speed up the net's calculation.
void	prune(double p_threshold) Removes edges with absolute values below the threshold given.
void	removeNeuron(Neuron p_neuron) Removes a neuron and all edges that point to and from it.
void	save(java.io.FileWriter p_file) Saves all net memory to a file.
void	setBackPropagationMethod(BackPropagationMethod p_backprop) Sets the BackPropagationMethod that willl be used to train the net.
void	setInputValue(double p_value, int p_index) Allows the user to set the value of one input Neuron.
void	setInputValues(double[] p_values) Sets input values from an array of doubles.
java.lang.String	toString() Returns a string representing the object.
double	train(double[] p_desirable) Runs the back propogation algorithms on the whole net.

Methods inherited from class java.lang.Object

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

Field Detail

version

public final java.lang.String version

The version of the net code.

See Also:

Constant Field Values

supportedVersions

public final java.lang.String[] supportedVersions

The versions from which this version can load files.

Constructor Detail

NeuralNet

public NeuralNet(double[] p_inputs,
         int[] p_layers,
         ThresholdingAlgorithm p_thresholdModel,
         BackPropagationMethod p_backprop)
          throws IndexOutOfBoundsException,
                 ValueOutOfBoundsException

Creates a new net with p_layers.length+1 layers, each with n nodes in them. p_layers must be of length one or above, each layer containing at least one Neuron else an IndexOutOfBoundsException exception will be thrown. The input data provided is taken as the input layer.

Parameters:

p_inputs - The array of inputs. Length of the input layer is taken from these.

p_layers - An array holding how many Neurons per NeuronLayer to maintain.

p_thresholdModel - The thresholding model to use for all neurons

p_backprop - The back propagation system to use for the net's training

Throws:

IndexOutOfBoundsException - if p_layers[] has fewer than 2 aspects

ValueOutOfBoundsException - if not enough Neurons exist in each layer to make the net functional (p_layers[i] < 1)

NeuralNet

public NeuralNet(java.io.FileReader p_file,
         ThresholdingAlgorithm p_thresholdModel,
         BackPropagationMethod p_backprop)
          throws java.io.IOException

Create a net from a saved net file. This resumes the net structure, Neurons and Edges. Nets must be loaded from files of their own version, else an IOException will be thrown. In the event that any other error occurs with the file an IOException will also be thrown.

Files are saved in a human-readable format which, as of version 0.1.0a has the following outline, with values being indexed in the [layer,neuron,edge weight] system

0.2.0a  //version
0.0040  //learning rate
3       //numver of layers

2       //nodes in layer 0, inputLayer
3       //nodes in hiden layers
4       //nodes in output layer

0.6     //input 0
0.8     //input 1

matrix data

When loading a net you must use the same threshold model as it was built with. Failure to do this results in very unpredictable behaviour. Changing its backpropagation model might cause the net to 'un-learn' its previous method of achieving results and learn a new method.

Parameters:

p_file - The file to load.

p_thresholdModel - The thresholding model to use for this reconstucted net

p_backprop - The backpropagation model to use.

Throws:

java.io.IOException - if the file is not valid and thus cannot be loaded

Method Detail

getBackPropagationMethod

public BackPropagationMethod getBackPropagationMethod()

Returns the BackPropagationMethod used to train the net.

Returns:

The BackPropagationMethod used when the net trains

setBackPropagationMethod

public void setBackPropagationMethod(BackPropagationMethod p_backprop)

Sets the BackPropagationMethod that willl be used to train the net.

Parameters:

p_backprop - The BackPropagationMethod that will be used when train is called to adjust weights

getLayer

public NeuronLayer getLayer(int p_index)
                     throws IndexOutOfBoundsException

Returns a layer such that one may edit its nodes and structure manually. This is very dangerous and may cause the net to fail back propagation or not save/load.

When requesting layers be aware of any polymorphism that may be all cunning and sneaky.

Parameters:

p_index - The index of the layer to acquire, with 0 being the input layer.

Returns:

NeuronLayer The layer requested

Throws:

IndexOutOfBoundsException - if the index provided is out of bounds.

See Also:

getNumberOfLayers()

getNeuron

public Neuron getNeuron(int p_layerIndex,
               int p_neuronIndex)
                 throws IndexOutOfBoundsException

Returns a neuron from anywhere in the current net.

Parameters:

p_layerIndex - The index number of the layer in which the Neuron resides

p_neuronIndex - The index number of the neuron witin the specified layer

Returns:

The neuron selected

Throws:

IndexOutOfBoundsException - in the event that either of the indices is out of range

preCalculate

public void preCalculate()

Precalculates all neuron values in order to speed up the net's calculation. Values are precalculated in order away from the inputs (ripping down the layers). This is called every time one sets inputs or back propagates to ensure that the net stays current. It will not need to be called manually unless one edits neuron edges manually.

setInputValues

public void setInputValues(double[] p_values)
                    throws IndexOutOfBoundsException,
                           ValueOutOfBoundsException

Sets input values from an array of doubles. This array should have a length equal to the number of input nodes else an IndexOutOfBoundsException will be thrown. All values must be between -1 and 1 else a ValueOutOfBoundsException will be thrown.

Note that this value automatically calls preCalculate and hence inherits some slowness.

Parameters:

p_values - An array of doubles to set the input nodes as.

Throws:

IndexOutOfBoundsException - if the wrong amount of aspects are found in p_values, passed back from NeuronLayer.setInputValues

ValueOutOfBoundsException - if the wrong values are contained in p_values, passed back from NeuronLayer.setInputValues

See Also:

NeuronLayer, setInputValue(double, int), preCalculate()

setInputValue

public void setInputValue(double p_value,
                 int p_index)
                   throws IndexOutOfBoundsException,
                          ValueOutOfBoundsException

Allows the user to set the value of one input Neuron. This must be a permissable input value according to the threshold model used.

Parameters:

p_value - The value, between 0 and 1, to set the Neuron to.

p_index - The index of the input node to set.

Throws:

IndexOutOfBoundsException - in the event that the index given is invalid

ValueOutOfBoundsException - in the event that the given value is outside of the permissable input range of the function given

See Also:

setInputValues(double[])

getNumberOfLayers

public int getNumberOfLayers()

Returns the number of layers in the net, without any extra information.

Returns:

The number of layers, inclusive of inputs

getLayerStructure

public int[] getLayerStructure()

Returns an array of integers representing the structure of the net. Array aspect 0 contains the number input nodes, Array aspect (length-1) contains the number of output nodes.

Returns:

The structure of the net, represented as an array of integers

See Also:

NeuronLayer

getOutput

public double[] getOutput()

Returns the output of the net as an array of doubles as long as the amount of output Neurons. This output is precalculated when preCalculate is run, which is implicit when inputs are changed.

Returns:

All values from output Neurons represented as an array of doubles.

train

public double train(double[] p_desirable)
             throws IndexOutOfBoundsException

Runs the back propogation algorithms on the whole net. The backprop code works with the last set of input values, so the training cycle must consist of two calls: setInputValues and then train with correlating data.

Parameters:

p_desirable - An array of desirable output doubles, matched in length to the amount of output Neurons (those in the final layer).

Returns:

The mean squared error for this net, as returned by BackPropagationMethod.backPropagateOutputs

Throws:

IndexOutOfBoundsException - if the wrong amount of desirable outputs is passed

removeNeuron

public void removeNeuron(Neuron p_neuron)
                  throws ItemNotFoundException

Removes a neuron and all edges that point to and from it. Useful for pruning nets according to user-defined rules such as average edge weightings. Be aware of the prune method, however, which will probably suffice for most simple prune operations. This method runs the garbage collector, which is quite resource intensive.

Parameters:

p_neuron - The neuron to remove from this net. Various other methods allow for finding this.

Throws:

ItemNotFoundException - if the neuron passed is not in the net.

prune

public void prune(double p_threshold)

Removes edges with absolute values below the threshold given. This can be used to speed up the net without affecting output adversely. The garbage collector is run once during this method, which is quite resource intensive.

Parameters:

p_threshold - The value under which to remove an edge. (ie if (Math.abs(edge.getWeight()) < p_threshold))

save

public void save(java.io.FileWriter p_file)
          throws java.io.IOException

Saves all net memory to a file.

Parameters:

p_file - The file to save to

Throws:

java.io.IOException

See Also:

NeuralNet(FileReader, ThresholdingAlgorithm, BackPropagationMethod)

getSupportedFileVersions

public java.lang.String[] getSupportedFileVersions()

Returns an array of strings that represent (and correlate with) version ids from which this net can load files.

Returns:

A list of supported version numbers.

toString

public java.lang.String toString()

Returns a string representing the object.

Overrides:

toString in class java.lang.Object

Returns:

The string representing the current net.