added a simple manual for ann_mlp

svn path=/trunk/externals/ann/; revision=3024

1 files changed, 137 insertions, 0 deletions

diff --git a/helps/ann_mlp-manual.txt b/helps/ann_mlp-manual.txt
new file mode 100755
index 0000000..446ed22
--- /dev/null
+++ b/helps/ann_mlp-manual.txt
@@ -0,0 +1,137 @@
+-----------------ann_mlp manual 

+

+by davide morelli - info@davidemorelli.it

+

+

+-----------What is a neural network?

+

+To be shure you fully understand what is and why to use a ANN, read

+http://www.doc.ic.ac.uk/~nd/surprise_96/journal/vol4/cs11/report.html

+

+-----------Why use a ANN?

+Because they are useful in Pattern recognition, gesure recognition (patterns

+over time), associative recall of data (images, sounds, etc), predictions

+(e.g. time-series forecasting), complex data handling, etc..

+

+--ANNs can handle noisy inputs: 

+if you trained your ANN that [1,1] -> 1

+Then if you pass [1.1, 0.9] -> 1 probably..

+

+--ANNs can be trained without writing code: 

+see ann/examples/ann_mlp_example2 (in CVS), you can teach the ANN to tell

+you when all these balls are close together or still.. How could you do this

+coding? You'd have to compute the distance of every ball from every other

+ball, then sum all the distances and ... Very complex and difficult! With

+ANN you simply teach when the balls are close and when they are not, you

+don't have to write code at all, you just have to use pd.

+

+-----------How to build a ANN?

+INPUTS:

+You must code your input data as a list of float. 

+E.g. If you want timbre recognition you must fft a signal then build a list

+with fft's partial and feed ann_mlp with it

+E.g. if you want midi chord recognition and you played A4 C5 E6 then use the

+midi values of the notes of the chord to build a list with 3 integers (57 60

+64) 

+

+Tip: inputs should be 0 centered

+the example of chord recognition should not work well (hard to train)

+because possible input values go from 30 to 90, you should remap them so

+they go from -30 to 30

+Notice how the inputs in ann/examples/ann_mlp_example2 go from -1 to 1

+If you can't make inputs 0 centered they should at least start from 0

+

+Tip: inputs should be normalized

+If you have one input that goes from -10 to 10 and another input that goes

+from -1 to 1 the first input will be more important than the second input

+

+OUTPUTS:

+Each "meaning" you want your ANN to detect should have its own output.

+Notice ann/examples/ann_mlp_example2:

+"Calm" and "chaos" have their outputs even if they are related.

+I could have set only 1 output = for calm and 1 for chaos.

+But having separated outputs I can see if my ANN has been trained well or

+not, but also could be that a situation is neither calm nor chaotic, or

+somehow calm AND chaotic..

+

+-----------TRAINING ON THE FLY:

+It is much easier to train the ANN on the fly rather than using a train

+file.

+To train on the fly you simply must pass a list with [inputs + expected

+outputs(

+If you have 3 inputs and 2 outputs then you must pass a list with 5 floats

+E.g. You want to train a ANN for a simple logical function: OR

+You build a ann_mlp with 2 inputs and 1 output

+You set |train(

+You pass lists like 

+|0 0 0(  inputs are 0 0 output is 0

+|1 0 1(  inputs are 1 0 output is 1

+|0 1 1(  inputs are 0 1 output is 1

+And so on.. Repeating until MSE is low enough

+

+MSE tells you the general error the ANN currently have with the inputs and

+outputs you are giving

+

+When you are ready set |run(

+And start passing lists with only inputs values

+|0 0(

+|1 0(

+Etc..

+The left outlet of ann_mlp will start sending lists of float, in this case a

+list with only 1 float

+

+-----------PUTTING ALL TOGETHER:

+

+1) Create a ANN passing ann_mlp a message with num_inputs and num_outputs

+E.g. (the simple ann for logical function OR)

+|create 2 1(

+|

+[ann_mlp]

+

+2) set train mode

+|train(

+|

+[ann_mlp]

+

+3) train the ANN passing lists num_inputs+num_outputs long

+|0 0 0(

+|

+[ann_mlp]

+(repeat at will using different inputs until mse is low - right outlet)

+

+4) set run mode

+|run(

+|

+[ann_mlp]

+

+5) run the net passing lists num_inputs long, the left outlet will send a

+list with the results

+|0 0(

+|

+[ann_mlp]

+

+When everything is fine you can save it to a file

+|save filename(

+|

+[ann_mlp]

+

+Can be loaded in 2 ways

+|load filename(

+|

+[ann_mlp]

+

+Or as argument

+

+[ann_mlp filename]

+

+-----------

+

+For a more in-depth sight over technical issues:

+http://fann.sourceforge.net/report/report.html

+See fann manual for details on advanced params (activation functions,

+training params, etc..)

+http://fann.sourceforge.net/

+

+-----------

+

+questions and suggestions to info@davidemorelli.it