am-6.0 man page

     BPMAKE(1)                                                         BPMAKE(1)
                                      6/1/2000

     NAME
          bpmake - nntools compilation utility for backpropagation

     SYNOPSIS
          bpmake [ make arguments ]

     DESCRIPTION
          bpmake is a compilation tool for automatically creating backpropagtion
          neural network simulations with the aspirin neural network code
          generator. These simulations are automatically linked with the
          Migraines interface libraries and the data file reading libraries.
          bpmake is implemented as a shell script that is used with the Unix
          make utility. Your environment should have the following variables set
          before using bpmake: NNTOOLS set to the path where the
          Aspirin/Migraines software is installed.  MACHTYPE set to the type of
          machine you are on.  MANPATH should have $NNTOOLS/man appened to it
          (e.g. if NNTOOLS=/u1/nntools then setenv MANPATH
          ${MANPATH}:/u1/nntools/man).  Your path should include:
          $NNTOOLS/bin/$MACHTYPE, where $MACHTYPE expands to the type of machine
          you are running on. If you are unsure of the value to use for MACHTYPE
          then list the directories in $NNTOOLS/bin. All supported machines
          installed at your site will be listed.  A single aspirin file should
          exist in the current directory with a .aspirin suffix. By executing
          bpmake the aspirin simulation code generator will be invoked using the
          backpropagtion simulation code generator.  The resulting C code
          simulation is then compiled by bpmake. If there is a file user_init.c
          then this file is also compiled. The user_init.c file is the place the
          user can alter simulation parameters and preprocess data. This file
          MUST contain a function that returns void and takes no arguments
          called user_init().  The final executable simulation will call this
          function before it has initialized the simulation.  It is in this
          function that you can change parameters (e.g. learning rate) and
          define your own generators for suppling data to the simulation.  See
          Aspirin for Migraines User's Manual for details about using the
          user_init.c file.  Finally, a generic simulation (located in
          $NNTOOLS/migraines/bp ) called Backprop.c will be compiled and linked
          to the previously compiled files. The executable will be named by
          using the prefix of the aspirin file (e.g. speech.aspirin => speech).

          For examples of using bpmake with an aspirin file see the directory
          $NNTOOLS/examples.

     MAKE & ENVIRONMENT VARIABLES
          The Makefile used for the compilation with bpmake allows the user to
          override the internal variables by environment variables or variables
          supplied on the command line.  This is done by having the variable
          USE_ENV set to -e.  For example, the compiler optimization can be
          altered by setting the OPTIMIZE variable.  A very important variable
          is USER_LIBS. By setting this to a list of objects and/or libraries
          the user can link the user_init.c file to other functions. For

                                        - 1 -           Formatted:  June 1, 2000

     BPMAKE(1)                                                         BPMAKE(1)
                                      6/1/2000

          example, if you are reading images using Pixrects in the user_init.c
          file then you would set the USER_LIBS to -lpixrect so the Pixrect
          routines could be linked.

     DATA FILES
          The bpmake utility links a library of data file readers to the
          simulation. A number of formats are supplied. The simulation uses a
          data format (.df) file to control the loading of the data files. The
          .df file is an ascii file of "ReadFile" commands that tell the
          simulation what files to read and what format they are in. The .df
          file syntax supports C preprocessor #defines, macros and comments to
          make loading of large numbers of data files easy.  See
          $NNTOOLS/examples for examples of simulations that use data files.
          Refer to The Aspirin/MIGRAINES Software Tools User's Manual for
          details of the .df syntax and supported data file types.

     RUNNING A SIMULATION
          A simulation created with bpmake has a number of run time options. For
          this discussion assume that you have a file called speech.aspirin. You
          have typed bpmake and a simulation was generated called speech. The
          simulation can produce dump files of the weights in neural network.
          These dump files can be used to start the simulation from any point
          during the learning.  If you execute speech with a filename of a dump
          file then the weights from that file will be loaded into the network
          simulation.  In addition to a filename argument, the generated
          simulation takes a large number of flags. These can be found by
          executing speech -help The following will be printed out:

          usage: speech [flags] [dump file]

          flags:

               [-d][-datafile <datafile>] read datafile (a .df file)

               [-a][-alpha <learning rate>] set learning rate

               [-i][-inertia <inertia>] set inertia

               [-F][-Filename <dump file name>] ("Network" default)

               [-l][-learn] learn without graphics

               [-s][-save <iterations>] save to "Network.save" every
          <iterations> (5000 default)

               [-#] Append the current iteration number to the save file name

               [-t][-test <iterations> <passes> <bound>] test for convergence
                every <iterations> (5000 default) by going <passes>(default 100)
                through generators without an error exceeding +/-
          <bound>(default 0.1)

                                        - 2 -           Formatted:  June 1, 2000

     BPMAKE(1)                                                         BPMAKE(1)
                                      6/1/2000

               [-N][-Notest ] never test for convergence

               [-I][-Iterations <max_iterations>] exit after max_iterations
          (default is unlimited)

               [-n <mean> <variance>] add normally distributed noise to
          inputs(very slow)

               [-u <mean> <variance>] add uniformly distributed noise to
          inputs(slow)

               [-f][-forward <iterations>] go forward <iterations> (used for
          stats and benchmarking)

               [-E][-Epoch] go forward one epoch (1 pass thru all data)
               (does not apply to user-defined generators!)

               [-p][-print] print outputs and targets (used with -f)

               [-P][-Pdpfa <threshold>] Calculate Pd and Pfa for -f <iterations>
                using <threshold> for detection threshold (L2 norm)

               [-A][-AsciiDump] print out all the weights and thresholds to
          stdout

               [-AsciiDumpNoFmt] print out all the weights and thresholds to
          stdout (no formatting, use with -L)

               [-L][-LoadAscii] read from stdin the results of -AsciiDumpNoFmt

               [-h][-help] this message

          For examples of running a simulation read the README files of examples
          located in $NNTOOLS/examples. Each example contains a file called
          Learn which is a shell script that will run the entire example. Read
          this file to see how to run the example by hand or execute the file to
          have the example run automatically.

     FILES
          *.aspirin neural network description file user_init.c user's
          customization file $NNTOOLS/migraines/bp/Backprop.c the generic
          simulation $NNTOOLS/migraines/bp/bpmake the shell script
          $NNTOOLS/migraines/bp/Makefile.bp the Makefile

     SEE ALSO
          The Aspirin/MIGRAINES Software Tools User's Manual

     BUGS
          Mail bug reports to the author and be sure to include the version

                                        - 3 -           Formatted:  June 1, 2000

     BPMAKE(1)                                                         BPMAKE(1)
                                      6/1/2000

          information in the report.

     AUTHOR
          Russell Leighton
          email: taylor@world.std.com

                                        - 4 -           Formatted:  June 1, 2000