fileform.tex

basic.c */ /**//* Project:NeuroBasic, basic package*//**/ /* Survey:This is a simple Basic b-code

% *******************************************************************
%
% File:         fileform.tex
%
% Project:      NeuroBasic, appendix of manual
%
% Survey:       Describes the SN matrix file format
%
% Author:       Urs Mueller
%               Electronics Laboratory, ETH Zuerich,
%               Switzerland
%
% Created:      July 24, 1994
% Modified:     August 2, 1994 (um)
%
% *******************************************************************




\chapter{File Formats}
\index{file formats|(}
\label{sec_matformat}
%*********************

Training data and weight sets are stored as matrix files on disk.  The
file format is taken form the \SN\ simulator of Neuristique Inc. 
\index{sn simulator@\SN\ simulator} Matrix files can have up to three
dimensions and they can be stored in three different formats: {\small
ASCII}, floating-point and fixed-point.

An {\em\small ASCII\/} file contains all the elements of a matrix as
numbers in a plain text file. This format is compatible between almost
all computer systems. It can therefore be used to exchange data
between almost any type of computer, e.\thinspace{}g. between a Sun
workstation and a {\small PC}. Furthermore, a matrix in this format
can by created, displayed and modified by an ordinary text editor. On
the other hand, ASCII files are longer and loading data takes longer
compared to the other two formats!

In the {\em floating-point\/} format the matrix elements are stored as
binary floating-point numbers (32 bit wide each). The loading and
saving is fast and the files are typically shorter than in the {\small
ASCII} format. But it is not always compatible between different
computer systems. For example, floating-point matrices cannot be
exchanged between Sun workstations and {\small PC}s.

In the {\em fixed-point\/} format, finally, the elements of a matrix
are stored as binary fixed-point numbers (8 bit with a fractional part
of 4 bit). The files therefore are four times smaller compared to the
floating-point format, but the numbers have less precision. This
format is more compatible between different computer systems than the
floating-point format but less compatible than the {\small ASCII}
format. The loading and saving is fast.

The following sections contain the exact definition of each of the
tree formats.


\section{The ASCII Matrix Format}
\index{ascii file format@\ASCII\ file format}
%============================================

The first line of the file is the matrix header. It consists of the
letters ``.MAT'', the number of dimensions and the size of each
dimension. Then the array elements are written, separated by spaces,
newline characters or tabs. Different rows of a matrix don't
necessarily have to be individual lines of text. The array elements
are ordered with the elements in higher dimensions changing faster.

The following is a legal {\small ASCII} matrix file:

\begin{verbatim}
        .MAT 2 3 4
        2.3  -1.2  3.4  1
        0.1   7.7  2.3  4.3
        44    2.345
        0.12  2.434e5
\end{verbatim}


\section{The Floating-Point Matrix Format}
\index{floating-point file format}
%=========================================

A file of this format contains a 20-byte header, followed by a memory
image of the single precision (32 bit) floating-point matrix. The
header consists of five 4-byte integers. The first integer is a
``magic number'' that should be equal to 1e3d4c51 (hexadecimal) or
507333713 (decimal), the second integer contains the number of
dimensions of the array (1\ldots3), the remaining three numbers are
the size of the array in each dimension (the size of a nonexisting
dimensions, e.g. the z-dimension in a 2-dimensional matrix must be 1).

The array elements are ordered with the elements in higher dimensions
changing faster.


\section{The Compact Fixed-Point Matrix Format}
\index{fixed-point file format} \index{compact fixed-point file format}
%======================================================================

The headers of this format and the floating-point format are identical
except that the magic number of the fixed-point format is 1e3d4c52
(hexadecimal) or 507333714 (decimal). Each following byte represents
a fixed-point number between $-8$ and $+8$ ($+8$ not included), the
first 4 bits (most significant nibble) contain the integral part, the
remaining 4 bits contain the fractional part. The fixed-point numbers
are represented in the two's complement format.

The following two C functions illustrate the conversion between
compacted fixed-point numbers and floating-point numbers:

\begin{verbatim}
    /* Compact fixed-point to floating-point */
    float unpack(signed char b)
    {
      return (float)b / 16.0;
    }

    /* Floating-point to compact fixed-point */
    signed char pack(float x)
    {
      if (x > 8.0 - 1/16.0) return 0x7f;
      else if (x < -8.0)    return 0x80;
      else                  return (signed char)(x*16.0);
    }
\end{verbatim}

The array elements are ordered with the elements in higher dimensions
changing faster.


\section{Pattern Files}
\index{pattern files}
%======================

A pattern file is stored as a two-dimensional matrix where each
pattern represents a vector of the matrix. This means that one pattern
immediately follows an other. Note that in the \SN\ matrix format
higher dimensions change faster in memory. This means that the x
dimension of the matrix indicates the number of patterns and the y
dimension the size of each pattern. The z dimension (not used in the
\ASCII\ format) must be 1.

The following two \ASCII\ matrices represent input and target patterns
for the {\small EXOR} problem:

\begin{verbatim}
    .MAT 2 4 2          .MAT 2 4 1
    0  0                0
    0  1                1
    1  0                1
    1  1                0
\end{verbatim}

After loading the patterns are numbered starting from 0 with
the first pattern being number 0.


\section{Weight Files}
\index{weight files}
%=====================

\subsection{Fully Connected Weight Sets}
%---------------------------------------
Fully connected weights are stored as two-dimensional matrices. Each
line of the matrix represents the weights for one neuron in the upper
layer. The first line corresponds to the first neuron in the layer
and so on. The last value in each line indicates the weight of the
bias (an additional input which is constant 1.0).

The following is an example of a weight set for a 3-neuron layer
with 5 inputs where all bias weights are set to 0.

\begin{verbatim}
    .MAT 2 3 6
    1  2  3  4  5  0
    4  3  2  6  5  0
    1  6  4  3  9  0
\end{verbatim}

\index{file formats|)}