FILEFORMATS
===========

Version: 0.1
Date: 07/22 1995
Author: Marko Meyer (mme@pub.th-zwickau.de)

		Marko Meyer 
		Teichstrasse 27
		D-08289 Schneeberg
		F.R.G.

This file is Copyright (C) 1995 Marko Meyer.
I disclaim every warranty in the information stated below. 
Please read the files README, doc/LICENSE and doc/DISCLAIMER.
If you miss one of these files, please contact me via the adresses above.


Contents:
=========

0. General Information
1. Files presented to BACKNET by the user
1.1 The weight-file.
1.2 The pattern-file.
1.3 The learn-pattern-file.
2. Files created by BACKNET
2.1. The output-file.
2.2. The error-file.

-----------------------------------------------------------------------------
0. General Information
-----------------------------------------------------------------------------

All files used by BACKNET are regular ASCII-files. They can be made with an
editor of your choice.
BACKNET's methods read the files line oriented. That means: every line should
be separated from the next by a '\n'-sign (as it is expressed in C and as it is
done by most editors just by pressing RETURN (or similar) at the end of the
line). The lines should not exceed LINELENGTH characters. LINELENGTH is 
defined in include/backnet.h and by default set to 80. If your line exceeds 
that length it will be truncated and every information behind position 
LINELENGTH is lost.
Every information provided by this document is coded in a way called
'Data Dictionary', but if you are used to read documentation for compilers
and programming languages you should have no problems reading this.

Usually the files have the following extensions:

		Content-specific name           Extension
		-----------------------------------------
		weight - file                   .gwi | .gwb
		pattern - file                  .mst
		learn - pattern - file          .lrn
		error - file                    .err
		output - file                   .out 

You may find that the extensions are sometimes a little bit strange and 
unrelated to the content-specific names. This is true; they come from 
very early times of the library when it was only planned as a tool for 
a singular programming project done by Germans. If you know German language
you will see the meaning of these extensions.
You can change this extensions in include/backnet.h; that's why I refer to
these files with their content-specific name in this document.

The lines of each file can be reproduced from three forms:

    comment_line = '#' + something_not_near_defined + '\n'

    int_line = int_value + '\n'

    double_line = double_value + '\n'

where an int_value is an int, stored as string and a double_value is a double
stored as a string.
The something_not_near_defined - value in the comment_line is explained by
it's name. It can be any character or combination of characters because a 
comment_line is completely ignored by the file reader.
Notice that the lines have to start at zero-position! There _mustn't_ be 
any spaces or other characters before the '#', the int_value or the 
double_value!

=============================================================================

-----------------------------------------------------------------------------
1. Files presented to BACKNET by the user
-----------------------------------------------------------------------------
1.1 The weight - file
.....................

The weight - file stores the weights of the neurons when the Neural Network
is destroyed. There's a method 'Save' in NNet, Layer and Neuron that's used
to doing this. It must contain mainly two kinds of information: 

        *   the amount of Neurons the weights for can be found within
        *   the weights themselves.

There's one important thing regarding weight - files. When the file is
opened by NNet, the amount of Neurons written in the file is compared with
the amount of Neurons in the actual Network. If they match there's no check
regarding to the amounts of weights being saved in the file for every Neuron.
If this amount does not match the amount of weights that the Neuron wants
to read later or earlier there will be an error. But at the beginning of the
initialisation (within NNet) there's no chance to detect such things.
Maybe in further releases there will be some better possibilities to detect
such things.

Anyway - the file has the following format:

weight_file = {comment_line} 
            + int_line 			        *amount of Neurons*
            + 1{weight_section}

weight_section  = 1{comment_line}
                + 1{double_line}        *weights of one Neuron*

Each weight_section must start with at least one comment_line. That's really
important; because the Neuron 'knows' that the first thing it 'sees' in the
file must be a comment_line. 

When the weight - file is written by the Network automatically (as is done
everytime the method 'Save' is called), the comment_line of each weight_
section contains information about the Neuron which wrote it's weights 
into this section. This is not used by the Network when using this file as
weight - file for a newly built Network (remember  - it's a comment!) but it
may be useful for the user who looks at this file sometimes.

A typical weightfile might look like this:

-----------------------------snip------------------------------------------
# Weightfile as example. Has 3 Neuron's weights within.
3
# Neuron: 1 ; Layer: 1 ; Weights: 2 ; BIAS: 0
9.12345
1.3245
# Neuron: 2 ; Layer: 1 ; Weights: 2 ; BIAS: 0
0.675543
-2.452256
# Neuron: 1 ; Layer: 2 ; Weights: 2 ; BIAS: 0
8.99563
0.004533
-----------------------------snip------------------------------------------

The Network this weightfile may origin from has 2 Layers, with 2 Neurons in
the first Layer and 1 Neuron in the last Layer. A BIAS-weight (otherwise
referred to as BIAS - Neuron) is not used. 


There's another file with the same format; it's the weight - file - backup,
(with the default extension '.gwb', but this is only a default!) that's
made when the Network sees that a file with the same name and extension like
the planned file for saving weights already exists. It is just moved to a
file with the extension '.gwb' (or how you like it).

............................................................................

1.2 The pattern - file
......................

The pattern - file is for providing the patterns being recalled by the 
Network. It is used both for learning and recalling purposes. 

The Network wants to read at first two int_values: the amount of 
input - Neurons (Neurons of the first Layer) and the amount of patterns
being presented within the file. You will find it logically that in the
pattern_sections there will be exactly that much double_lines like there
are Neurons in the first Layer. (Because that's a common fact.)
I only write this down, because YOU, the user, have to be aware that it's
the way I told you. The pattern - file is created by YOU (or by a tool
that YOU're providing), so you have to follow this rules strictly.

The format is the following:

pattern_file    = {comment_line}
                + int_line              * amount of input-Neurons *
                + int_line              * amount of patterns within *
                + 1{pattern_section}

pattern_section = 1{comment_line}
                + 1{double_line}


A typical pattern - file might look like this:

------------------------snip---------------------------------------------
# Pattern - file provided to BACKNET. Only as example.
2
4
# Pattern 1
0
0
# Pattern 2
0
1
# Pattern 3
1
0
# Pattern 4
1
1
------------------------snip----------------------------------------------

It can be used with the Network described above (2 Layers; 2 Input - Neurons,
1 Output - Neuron).

.............................................................................

1.3 The learn - pattern - file
..............................

The learn - pattern - file stores the target-output that the Net _should_ 
create when you teach it. The values stored there are compared with those
the Network writes to the OutputList. Then from that difference the error
that the Network made is calculated; transformed onto the weights and so on.

The format, function and rules are similar to the ones of the pattern - file; 
that's clear: both files are storing patterns. 
The amount of patterns being presented within the learn-pattern-file _must_
be the same like the amount of patterns presented by the appropriate
pattern-file!

Okay, that's the format:

learn_pattern_file  = {comment_line}
                    + int_line          * amount of output-Neurons *
                    + int_line          * amount of patterns within *
                    + 1{pattern_section}

the pattern_section is the same as the one used in the pattern - file.

A typical learn - pattern - file might look like this:

------------------------snip------------------------------------------------
# Learn-pattern-file. Just an example.
1
4
# Target 1
0
# Target 2
0
# Target 3
0
# Target 4
1
------------------------snip------------------------------------------------

It can be used with the above described Network, too. There are 4 Targets
inside used for 1 Output-Neuron.

============================================================================

----------------------------------------------------------------------------
2. Files created by BACKNET
----------------------------------------------------------------------------

If we would be nitpicking, we would say that the weight - file is created
by the Network, too. But since there's a possibility to create a weight - 
file yourself (although this is not very useful) we counted it as a file
being presented to BACKNET and created by the user.
The files described here are really _only_ created by BACKNET and it is not
possible that the user does so, because he would have to be a Neural Network
to find out the values being presented within the files ;-].

2.1 The output-file
...................

The output - file is the file, where the outputs after a recall are written 
to. It is created only in case of a recall. It contains the results of the
Networks work, the answers on the patterns read from the pattern - file.
These results are written into the output - file in the same order like the
patterns are assembled in the pattern - file. So by comparing the place where
the result in the output - file stands and the place of the pattern in the
pattern - file you can find the matching pair of pattern and result that 
you wanted to get from the net. 

The simplest and not very usual case is that you have only one pattern in the
patternfile and so only one result in the output-file, too.

Logically the values written in the output-file are the output-values of the
output-Neurons of the Network after the pattern has been recalled. You have
to interpret this yourself.

The format's like the following:

output_file = 1{comment_line}
            + int_line                  * amount of output-Neurons *
            + int_line                  * amount of result-patterns *
            + 1{pattern_section}

where the pattern_section is like the pattern_section in the pattern-file.

A typical output-file looks like the following one:

----------------------snip-------------------------------------------------
# Output-File written by BACKNET 0.1
1
4
# Result 1 -- for Pattern 1
0.0034221
# Result 2 -- for Pattern 2
0.00222134
# Result 3 -- for Pattern 3
0.00093321
# Result 4 -- for Pattern 4
0.9984533
----------------------snip-------------------------------------------------

This output_file could be one created by the Network, when it was teached
using the above pattern - and learn - pattern - files and now being recalled
using the above pattern - file.
You see that the result is similar to the values in the learn-pattern-file,
so that we can say, that the Network learnt the patterns well. You guess 
what the patterns are: the logical AND:

		pattern			learn - pattern			output
		----------------------------------------------
		0	0					0				0.0034221
		0	1					0				0.00222134
		1	0					0				0.00093321
		1	1					1				0.9984533

Along with the net you will find pattern- and learn-pattern-files for the
logical AND, OR and XOR, that you can learn different Networks on. You 
should do this when you want to test the correct function of a Network.
If it is a BACKPROPAGATION - Network, there should be no problems learning
AND and OR, only a little more learning steps are needed to learn the XOR.

...........................................................................

2.2 The error - file
....................

The error - file is just for your information during the learning process.
It is the only file, where you can find values about how good the Network
learns the patterns you present to it.

It is not too much structured:

error_file  = 1{comment_line}
            + 1{double_line}

where the double_line contains the errors made by the Network.

The following one is only an example and not from a real Network:

--------------------snip---------------------------------------------------
# Error-file created by BACKNET 0.1
0.8837773
0.7736623
0.7366366
0.7735553
0.6633883
0.8833326
0.449493
0.5663668
--------------------snip---------------------------------------------------

It could be theoretically from the learning - process of the above task:
the detection of AND. Four patterns have been presented in 2 learning steps.
(In reality this is much too less for learning the problem; 5000 steps should
do.)

The error - file is getting very large if you want the Network to have much
learning steps. In that case you should be aware, that with every learning
step a whole double value (10 ... 20 Bytes according to the precission)
is written to the file. When you have 10000 learning steps, what is a 
usual amount, this will result in an up to 200000 Byte big file.

That's all for this file, enjoy BACKNET!
===========================================================================