C      ALGORITHM 738, COLLECTED ALGORITHMS FROM ACM.
C      THIS WORK PUBLISHED IN TRANSACTIONS ON MATHEMATICAL SOFTWARE,
C      VOL. 20, NO. 4, DECEMBER, 1994, P. 494-495.

GUIDE TO GENERAL-BASE PROGRAMS
------------------------------

These routines generate well-spaced sets of points
for use in multidimensional integration and in
global optimization.


The programs are written in Fortran 77.
There are three sets, with main routines

     GFARIT
     GFPLYS
     GENIN

respectively.  The subroutines associated with these main
routines are listed in the respective comments to those routines
and in the the program directory.

For the first time these routines are used --

   1.  Compile all main routines and subroutines.
   2.  Link each main routine with its respective subroutines.
   3.  Run the main routines GFARIT, GFPLYS, GENIN in that order.
   4.  Save the files gftabs.dat and irrtabs.dat produced
       by GFARIT and GFPLYS.

*****
*****   The procedure above works on the Vax.
*****   For your computer, it may have to be modified slightly.
*****

*****   The Unix version has common blocks FIELD.inc and
*****   COMM.inc which are incorporated by an extended FORTRAN
*****   compiler automatically.  For the Vax versions, these
*****   blocks have already been included in the respective
*****   routines; the user need do nothing about them.
*****

Subsequently --

       It is necessary only to run GENIN.

          &&&&&&  GENIN is a driver skeleton.  It offers the
          &&&&&&  user a menu, asking him to choose the
          &&&&&&  number of an integrand [assuming that TESTF
          &&&&&&  has an integrand with that number], the
          &&&&&&  dimension, the base, and the skip value.
          &&&&&&  It tells the user what the "optimal" base is,
          &&&&&&  without requiring him to choose it.  It also
          &&&&&&  suggests possible skip values.  Various
          &&&&&&  combinations of integrals, dimensions, bases,
          &&&&&&  and skip values can be tried before choosing
          &&&&&&  to quit GENIN.


With the exception of note 3 below,
the general-base programs do not use extended FORTRAN functions
(in contrast to the programs tailored for base 2).  However, if
you wish to use base 2, the base-2 programs will run much faster
than the general-base programs.

The general-base programs are portable with the following
possible exceptions:

   1.  OPEN statements are system dependent.
   2.  The parameter NBITS is these programs is 
       the number of bits per word, excluding sign.
       It is currently set to 31.  If not appropriate for
       your computer, modify the PARAMETER statements giving
       the value of NBITS throughout.
   3.  The Unix version contains system-dependent timing
       statements, which can be deleted or modified.  The
       Vax version has no timing statements, but these can be
       added, in a system-dependent way, if desired.


GUIDE TO BASE-2 PROGRAMS
------------------------
 
These programs generate well-spaced points for use
in multidimensional integration and in global optimization.

The programs are written in Fortran 77.

  *****  To run this set of programs on the VAX,
 
  *****  first -
  *****  compile GENIN2, INLO2, GOLO2, CALCC2, CALCV,
                 SETFLD, PLYMUL, CHARAC, TESTF

            &&&&&  Our VAX program does not measure elapsed
            &&&&&  time.  It can be modified in a system
            &&&&&  - dependent way to do so.  

            &&&&&  On the other hand, our Unix version does
            &&&&&  measure elapsed time, in a system-dependent
            &&&&&  way.  See the comments on the Unix version
            &&&&&  of GENIN2.

            &&&&&  In our VAX programs, the files FIELD.INC
            &&&&&  and COMM2.INC have already been incorporated
            &&&&&  where needed.  The user needs do to nothing
            &&&&&  about them.

            &&&&&  On the other hand, our Unix version processes
            &&&&&  these two files directly, using extended
            &&&&&  FORTRAN.
 
            &&&&&&  The user can replace our TESTF,
            &&&&&&  which contains four test integrals,
            &&&&&&  by his own TESTF with up to four
            &&&&&&  integrals of interest to him.
 
 
  *****  second -
  *****  link these compiled routines
 
  *****  third -
  *****  run GENIN2
 
           &&&&&&   GENIN2 is a driver skeleton.  It gives
           &&&&&&   the user a menu, asking him to choose
           &&&&&&   the number of the integral to be estimated
           &&&&&&   [assuming that TESTF has an integral with
           &&&&&&   the corresponding number], the dimension,
           &&&&&&   and the skip value -- offering
           &&&&&&   a suggested value.  Various combinations
           &&&&&&   of integrals, dimensions, and skip values
           &&&&&&   can be tried before choosing to quit GENIN2.


The procedure for other computers is similar.
 
  *****  For the VAX, we use the extended FORTRAN
  *****  IEOR [for bitwise exclusive-or].  Its name
  *****  and format may differ on other computers.
  *****  IEOR is used in INLO2 and GOLO2.
 
  *****  Under Unix, we use the extended Fortran function
  *****  XOR for IEOR.
 
  *****  OPEN statements may well have to be modified
  *****  to conform to local computer-center requirements.
  *****  For the base-2 programs, the only OPEN statement
  *****  is in GENIN2.  Interactive input-output is normally
  *****  from and to the user's terminal.  Batch output
  *****  goes to the file called OUTFIL.DAT.

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


 
 
 
 
 
 
There are several auxiliary subroutines.
Calling structure :
  GENIN2  calls  INLO2 and GOLO2.
  INLO2   calls  CALCC2.
  CALCC2  calls  CALCV and SETFLD.
  CALCV   calls  PLYMUL.
  SETFLD  calls  CHARAC.
  GOLO2,  PLYMUL, and CHARAC are self-contained.
 
The subroutines share a number of parameters and two common
blocks, which are described below.
 
The principal parameters :
  MAXDIM  - The maximum dimension that will be used.  An
    irreducible polynomial must be available for each
    dimension :  see subroutine CALCC2.
  NBITS   - The number of bits (not counting the sign) in
    a fixed-point integer.
*****
*****  Currently, NBITS is set to 31.  If your computer
*****  does not have 31 bits per word, excluding sign,
*****  modify the value of NBITS in each corrsponding
*****  PARAMETER statement.
*****
  DEG     - -1 :  see the comments on polynomials below.
 
Common block /COMM2/
  CJ    - The packed values of Niedderreiter's C(I,J,R).
  DIM   - The dimension of the sequence to be generated.
  COUNT - The index of the current item in the sequence.
  NEXTQ - The numerators of the next item in the sequence.
          These are like Niederreiter's XI(N) (page 54),
          except that N is implicit, afd the NEXTQ are
          integers.  To obtain the values of XI(N),
          multiply by RECIP (see GOLO2).
 
Array CJ of common block /COMM2/ is set up by subroutine
CALCC2.  The other members of this common block are set
up by subroutine INLO2.
 
Common block /FIELD/
  P   - The characteristic of the field in use.
  Q   - The order of the field in use.
  ADD, MUL, and SUB - Arithmetic tables for the field in use.
 
The values of the common block FIELD are set by SETFLD.
 
Polynomials :
  A polynomial POLY (say) is held in an array POLY(-1:MAXDEG).
  The coefficient of x**n is held in POLY(N), and the degree
  of the polynomial is held in POLY(-1).  The parameter
  DEG = -1 reminds us of this when necessary ;  that is,
  the degree of POLY is given by POLY(DEG).
 
Further comments accompany each subroutine.


