home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / APPS / ant.readme next >
Text File  |  2009-11-06  |  19KB  |  463 lines
  1. *******************************************************************************
  2. ***************                       A N T                     ***************
  3. ***************             (Artificial Neural Tool)            ***************
  4. ***************                                                 ***************
  5. ***************                 Ignacio Labrador,               ***************
  6. ***************               Ricardo Carrasco and              ***************
  7. ***************                Luis Martinez_Laso.              ***************
  8. ***************               CIEMAT (Spain)--1995              ***************
  9. *******************************************************************************
  10.  
  11. INTRODUCTION.
  12. -------------
  13.  
  14.    This is the directory containing the software called ANT for neural net 
  15. computations. These programs include a Multilayer Perceptron utility with the 
  16. training algorithm based on Back-propagation (nowadays, there is an abundant 
  17. bibliography about these kind of neural nets).
  18.  
  19.    One of the mayor advantages of this software is its simplicity and easy use.
  20. You can implement your own application using an Artificial Neural Net in a short
  21. span of time. Although no previous knowledge is needed to use this software we 
  22. strongly recommend some basic read on Artificial Neural Nets, in particular on 
  23. Multilayer Perceptron structures, in order to improve the permormance of your 
  24. applications.
  25.  
  26. These programs have successfully been used to develop real-world applications 
  27. as:
  28.     * Heating process control of a the vacuum vessel prototype for the Spanish
  29.       Stellerator Heliac TJ-II.
  30.     * Magnets current analysis in a fusion machine.
  31.     * Plasma position and control in a Fusion device.
  32.     * Differential ecuations solving
  33.     * Shape analysis of HgI2 crystals growing for radiation detectors.
  34.  
  35.    In any case, we will appreciate if you let us know about 
  36. your application and about any problem or comments to the address:
  37.  
  38.     Authors: Ignacio Labrador, Ricardo Carrasco, and Luis Martinez.
  39.     Address: CIEMAT, Av. Complutense 22,
  40.              28040 MADRID-SPAIN,
  41.              Fusion Nuclear Unit. Ed.6.
  42.     e-mail : ignacio@loki.ciemat.es
  43.  
  44.     Phone. : 34 +(9)1+3466644
  45.     fax    : 34 +(9)1+3466124
  46.  
  47. REQUIREMENTS.
  48. -------------
  49.  
  50. This software has been developed in a OS9 V2.4 system in their native C 
  51. language. A simple alphanumeric text terminal VT100 compatible is enough
  52. for running any application.
  53.  
  54. SOFTWARE STRUCTURE.
  55. -------------------
  56.  
  57.       ANT:
  58.                readme   is this file with the documentation.
  59.  
  60.                ant.c     is de utility for train, improve and execute
  61.                         the neural net with a menu interface.
  62.              
  63.                makefile    used to make all reallocatable files and executable.
  64.     
  65.                data_files  (orientative names of the xor and square recognition
  66.                             examples)
  67.  
  68.                  ant_init.xor, ant_init.square
  69.                              include the initial data of net configuration
  70.                             (read comments), and the weights calculated by
  71.                             the algorithm.
  72.  
  73.                  ant_examp.xor, ant_examp.square
  74.                              include the examples of inputs and output used
  75.                             to train or improve the net.
  76.       
  77.                  ant_in.xor, ant_in.square
  78.                              include inputs to be processed by the net, in
  79.                             order to obtain the net response.
  80.  
  81.                  ant_out.xor, ant_out.square
  82.                              stores output results if desired, including
  83.                             the inputs given by the user too.
  84.  
  85.      
  86.       ANT/DEFS:
  87.                         
  88.                ant.h      the header of defs and typedefs.
  89.                
  90.                antlib.h   the header of functions definitions.
  91.  
  92.       ANT/LIB:
  93.                  
  94.                antlib.c  the source library with routines including the example$
  95.    
  96.                antlib.l  the linkable module of the library.
  97.                  
  98.                makefile to make the library only.
  99.       
  100.       ANT/RELS:
  101.                   
  102.                all reallocatable modules are stored
  103.  
  104.  
  105. The configuration values of the net (number of layers, number of neurons, slope 
  106. of sigmoids per layer, error ...) are stored in the structure of type 'ant_net'
  107. defined in 'defs/ant.h'. Per each hidden and output layer an array of
  108. 'ant_neuron' structures (defs/ant.h) are allocated. Each neuron includes 
  109. weights (one per dendrite), the error and its output.
  110.                                                
  111.  
  112. INSTALLATION.
  113. ------------
  114.  
  115. To install ANT:
  116.  
  117.      1- OS9$ chd [to home directory]
  118.      2- OS9$ ftp loki.ciemat.es [or ftp 130.206.40.61]
  119.      3- ftp> login as anonymous
  120.      4- ftp> binary [to set transmision mode to binary]
  121.      5- ftp> cd pub/os9/ant
  122.      6- ftp> mget ant.ytar.Z compress ytar
  123.      7- in your machine uncompress  (command)
  124.         OS9$ load -d compress ytar [be sure the Microware version of compress
  125.                                     is not used]
  126.         OS9$ compress -dc ant.ytar.Z ! ytar x -
  127.      8- OS9$ chd ANT [to neural directory]
  128.      9- Edit makefile and change paths to libraries (if necessary)
  129.     10- OS9$ make
  130.         Installation is now completed, ready to run the application.
  131.     11- Two examples are provided with a xor simple neural net, and a 
  132.         simple square recognizer, otherwise
  133.     12- Write a ant_init.dat file (any name is valid) for your application
  134.     13- Write a ant_examp.dat file (any name is valid) with the training
  135.         examples. 
  136.     14- OS9> load -d user_root/cmds/ant
  137.     15- OS9> ant  <options> (train or improve the net with examples),
  138.         the weights are stored in the init file.
  139.         Without options you get the menu interface for interactive processing,
  140.         if you type ant -? you will get the help list of options.
  141.     16- Write a ant_in.dat file ( any name is valid) with the inputs
  142.         to be processed by the net.
  143.     17- type> ant  <options> ( and process inputs, asking whether you
  144.         want the outputs stored in a ant_out.dat type file or not
  145.         for the menu mode)
  146.  
  147. CONFIGURATING THE NET.
  148. ---------------------
  149. Configuration of the net is provided by the init file, in 'ant_init.dat'. The
  150. fields that you can change in this file are:
  151.  
  152.  
  153.                      ************** NET STRUCTURE ************
  154.                      Comments:
  155.                      Sigmoid type(DIG(1) or SYM(2))  : 1
  156.                      Number of Layers (hidden+out)   : 3
  157.                      Number of inputs                : 3
  158.                      Neurons in next layer           : 5
  159.                      Neurons in next layer           : 4
  160.                      Neurons in next layer           : 1
  161.                      Polarisation potential          : 1.0000
  162.                      Weight pertur. coef.            : 0.8000
  163.                      Weight noise (zero to one)      : 1.0000
  164.                      Convergence limit               : 0.0010
  165.                      ************** Sigmoid Slopes ***********
  166.                      S(1) : 0.5000
  167.                      S(2) : 0.5000
  168.                      S(3) : 1.0000
  169.                      *****************************************
  170.  
  171.  
  172. With 'sigmoid type' you can select the kind of sigmoidal function used in all
  173. nodes. We consider two types: DIGital (DIG), with horizontal asymptote in
  174. y=0 and y=1; and SYMetrical (SYM), with asymptote in y=1 and y=-1. The first
  175. one is defined by the function:
  176.  
  177.                             y(x) = 1/(1+exp(-Sx))
  178.  
  179. and is indicated specially in the cases in which you want use the perceptron to
  180. classify input patterns. The second one is the hyperbolic tangent function:
  181.  
  182.                               y(x) = tanh (Sx)
  183.  
  184. and it is used when you want to obtain positive and negative analog values
  185. in the output units of the net. This second function has an added advantage:
  186. you can find it implemented in silicon integrated electronic circuits, even 
  187. more, for nets of small size you can implement it electronically with comertial 
  188. discrete components.
  189.  
  190. In both functions, the 'S' factor allows you to select the slope of the
  191. functions. This factor is defined per each layer, and you can change it
  192. modifying the S(l) fields in the 'ant_init.dat' file, where 'l' is the layer 
  193. label in the net. Obviously, you have to include the same number of 'S(l)' 
  194. fields than the number of hidden layers plus the output layer.
  195.  
  196. The effect of 'S' factor is larger in the output layer than in the
  197. hidden layers. From our experience, values of 'S' around 1.0 are good for
  198. hidden layers, while for the output layer 'S' must be larger when you want 
  199. digital-like outputs to obtain an abrupt sigmoid, and smaller when you
  200. want analog outputs to get a soft slope.
  201.  
  202. The field 'layers' in the init file correspond to the total number of layers
  203. in the net (output and hidden layers). The maximum value that we have used is 
  204. 3. Usually most of the problems can be solved with two layers (one hidden 
  205. layer). However when convergence was impossible with two layers  
  206. we have used 3 layers. In the program the input layer is indexed as 
  207. layer 0 and only the inputs are considered (no neurons are allocated).
  208.  
  209. To set the number of neurons units in each layer, you must add (or delete) the
  210. corresponding number of fields like this:
  211.  
  212.                     'Neurons in next layer           : 2'
  213.  
  214. in function of the number of layers of your net; so, in the example above, we
  215. have a net with three layers, with 5 neurons in the first layer, 4 in the
  216. next one and 1 unit in the output layer.
  217.  
  218. As you know there is no an exact rule to find the number of units in each layer.
  219. From our experience, we think that the best is to start with only two layers,
  220. and with a little number of units in the hidden layer (the units in the output
  221. layer is defined by the number of components that you can obtain as output
  222. vector).  If in this conditions there is no convergence, you can increase the 
  223. number of hidden units and try again from the beginning. If the convergence is
  224. impossible with 2 layers you ougth to increase the number of layers to 3.
  225.  
  226. Each layer includes a fake neuron (labelled with the index 0) as polarization 
  227. (bias unit). You can change the output value of this node modifying the 
  228. 'polarization potential' field. We solve the most of our convergence problems 
  229. with a value of 1.0; only sometimes we select it as 0.0 in order to 
  230. eliminate the fake neuron.
  231.  
  232. The 'Weight pertur. coef.' field is the factor that determine the proportion of
  233. variation of the weights in each propagation of the examples across the net.
  234. In order to reduce the training time, is advisable to start the training with
  235. a high value (a value around 1.0 is a high value), and reducing it in a
  236. progressive form to values near to 0.0. If the convergence time is not an 
  237. important factor for you, is better to fix a small value (0.2 for example) from
  238. the beginning and wait patienly.
  239.  
  240. With the 'Weight noise (zero to one)      :' field you can fix the noise
  241. perturbation in the actualization of the weights in each interaction. With 'one'
  242. this perturbation is maximum and with 'zero' there is no perturbation at all.
  243. For the practical point of view we have not needed this noise perturbation
  244. (zero value) in most of the  problems soved till now.
  245.  
  246. With 'Convergence limit' field you can fix the maximun allowed quadratic 
  247. error in the training process. It is advisable to train the net in different 
  248. phases: first with a high error margin, and when the net has learnt perfectly
  249. all the examples given, reducing this parameter and train again (we call this 
  250. phase 'improve'), until the error of the net is smaller than the new value.
  251.  
  252. RUNNING THE UTILITY
  253. -------------------
  254.  
  255. The 'ant' utility can be invoked without options in the command line and 
  256. the init file name are requested explicitly. When you run the program in this 
  257. way the following menu will appear on the screen:
  258.  
  259. ==============================================================================
  260. Monday, April, 25, 1995.
  261. 1:09:52 pm
  262.  
  263.  
  264.           ___________________________________________________________
  265.  
  266.  
  267.          [T]  TRAIN NET
  268.  
  269.          [I]  IMPROVE NET
  270.  
  271.          [P]  PROCESS AN INPUT
  272.  
  273.          [E]  EXIT
  274.  
  275.           ___________________________________________________________
  276.  
  277.  
  278.  Select an option :
  279.  
  280. ==============================================================================
  281.  
  282. 1.-[T] TRAIN NET. This option allows to train the net from the very beginning.
  283.    Therefore, the weight matrix is initialize with small random values. Before
  284.    select this option is necessary:
  285.  
  286.      * Select the architecture of the net and all its parameters in the
  287.        inicialitation file (i.e. ant_init.dat).
  288.      * Edit a file with the examples that allow the training of the net
  289.        (i.e. ant_examp.dat), containing the input vector and the corresponding
  290.        desired output vector for each example. It is advisable to normalize all 
  291.        input and output vectors in this file; so, if you are using the tangent
  292.        hyperbolic function (option SYM) you must give all the examples with 
  293.        values in the interval [-1,1], and otherwise, if you use the digital 
  294.        (DIG) simoid, this interval must be [0,1].
  295.  
  296.    When you select this option and the net is training, something like:
  297.  
  298.     ]]]]]]]]]]]]]]]]]]e0
  299.     ]]]]]]]]]]]]e1
  300.     ]]]]]]]]]]]]]]]]]]]]]]]]]]e2
  301.     ]]]]]]]]]]]]]]e3
  302.     .
  303.     .
  304.     .
  305.     ]]]]]]]]]]]]]]]]]]]]]]en
  306.  
  307.      
  308.    will appear on the screen, where e0,e1,e2.... represent each example in the 
  309.    examples file 'ant_examp.dat', and the number of characters ']' in each line
  310.    is the number of times that has been necessary to do the backpropagation in
  311.    order to   minimize the error for each example. If, for example, you are 
  312.    training the net with 50 examples (n=50), the sequence from e0 to e49 will 
  313.    be repeated until all the characters ']' disappear in all lines. When this 
  314.    happens, your net is capable to recognize all the examples given in the 
  315.    'ant_examp.dat', and probably, it is capable to compute properly some 
  316.    generalize examples that where no in the training set.
  317.  
  318.    The weight values generated by the algorithm will be write in the
  319.    'ant_init.dat' file periodically during all the learning process, and when
  320.    convergence is achieved and the learning process is finished.
  321.  
  322.    To stop the learning process there are two procedures:
  323.  
  324.     a) <CTRL-C> to stop saving the actual weights.
  325.     b) <CTRL-E> to stop without saving.
  326.  
  327. 2.-[I] IMPROVE NET. This option must be selected only when the option [T] was
  328.    previously selected. This option is used when you want to start the learning
  329.    process from a set of weights known previously. The operation mode of the
  330.    program is the same that in the [T] option.
  331.  
  332. 3.-[P] PROCESS AN INPUT. This option is useful when is necessary to test the
  333.    response of your net once trained. To use it, is necessary to edit previously
  334.    a file with the examples 'ant_in.dat' (only the inputs to the net) to be
  335.    tested. The output is readable on the screen, or via an output file 
  336.    selectable by the user.
  337.  
  338. 4.-[E] EXIT. Finish the session with ANT.
  339.  
  340.   The ant utility can be run as a line command, to do that just type 
  341. ant <options> . The options list can be obtained typing ant -? and 
  342. the following printout is obtained.
  343.  
  344. $ ant -?  <CR>
  345.  
  346. Syntax: ant [<options>]
  347. Function:  Run the Artificial Neural Tool (see readme file)
  348. Options:
  349.     None          Run in menu mode\n");
  350.     -examp=<path> get net examples file from path (for -i and -t options)
  351.     -i            improve a trained net (examp file needed)
  352.     -in=<path>    get net input file from path (needed with -p option)
  353.     -init=<path>  get net init file from path (always needed)
  354.     -out=<path>   get net output file from path (needed with -p option)
  355.     -p            process an input (an input and output file needed)
  356.     -t            train the net (example file needed)\n\n");
  357.  
  358. Hint:     Try first to run the menu mode just typing  ant 
  359.  
  360.  
  361.  
  362. As examples of the command lines we have:
  363.  
  364.    #to train a net, type:
  365.  
  366.        $ ant -t -init=ant_init.dat -examp=ant_examp.dat
  367.  
  368.    #to improve a trained net, type:
  369.  
  370.        $ ant -i -init=ant_init.dat -examp=ant_examp.dat
  371.  
  372.    #to process an input by the trained net, type:
  373.  
  374.        $ ant -p -init=ant_init.dat -in=ant_in.dat -out=ant_out.dat
  375.  
  376.    The input values are in ant_in.dat file and the results are stored 
  377. in ant_out.dat file.
  378.  
  379.    Running the ant utility in command line mode is faster than menu mode,
  380. and is advisable when the convergence is slow.
  381.  
  382.  
  383.  
  384. APPLICATION.
  385. -----------
  386.  
  387.     Once a net is trained and you want to use their 'knowledge'
  388. in an application in your program you have just to use the init file with the 
  389. net information and the function ant_process() included in antlib.l .
  390.  
  391.     The program ant_xor.c shows how such application can include the 
  392. computation of a trained net. The code include the computation of an user 
  393. defined input vector and a simple call to the ant_process() function returns 
  394. the pointer to a vector with the net results.
  395.  
  396.     The template of a program in which the ant net is used is as follows:
  397.  
  398.  
  399.     
  400. /*************************************************************************
  401.  *
  402.  *       Application program:  PROGRAM_NAME         
  403.  *
  404.  *   To compile this program use the command:
  405.  *   
  406.  *  $cc -v=<ant_directory>/defs -l=<ant_directory>/lib/antlib.l program_name
  407.  * 
  408.  */
  409.        
  410. #include <strings.h>
  411. #include "ant.h"         /* neural net header    */
  412. #include "antlib.h"      /* functions prototypes */
  413. main (argc, argv)
  414. int argc;
  415. char **argv;
  416. {
  417.   ant_neuron  **ant_neuronD;        /* declare net structures */
  418.   ant_net     ant_netD;
  419.  
  420.   double  *input_vector,        /* user input and output vector */
  421.           *output_vector;
  422.  
  423.   strcpy( (ant_netD.init),file_name );   /* get init file name  */
  424.  
  425. /* fill paramter of the net data structure, layers neurons , weights ...*/  
  426.   ant_neuronD = ant_init(&ant_netD);   
  427.  
  428. /* allocate vector size = number of input of the net (layer 0)*/
  429.   input_vector = ( double *) calloc( ant_netD.n[0] , sizeof(double));   
  430.  
  431. /*     .      */
  432. /*     .      */
  433. /* user code  */    
  434. /*     .      */
  435. /*     .      */
  436.  
  437. /* fill input vector with the values to be processed  */
  438.  
  439. /*  ant_netD.n[0]-1    variable with the number of net inputs, 
  440.  *                      neurons in input layer l=0  */
  441.   
  442. /* propagate and compute the net output*/
  443.   output_vector=ant_process(input_vector,&ant_netD,ant_neuronD);  
  444. /* ant_process() return the pointer to the vector results*/    
  445.  
  446. /*  ant_netD.n[ant_netD.l - 1]-1 variable with the number of net outputs, 
  447.  *                                number of neuron in output layer */
  448.  
  449.  
  450. /*                                           */
  451. /* user code where the ant result is applied */    
  452. /*                                           */
  453.  
  454.     
  455. }  
  456.     
  457.     
  458. This application program has to be compiled with the command:
  459.     
  460.   $ cc -v=<ant_directory>/defs -l=<ant_directory>/lib/antlib.l  program_name
  461.  
  462.  
  463.