1.13 THE GQ-SHELL

General Introduction. Most of the programs provided in GQOPT require the user to write a MAIN program that reads in the data and calls the appropriate subroutine(s). This is time-consuming and error prone, because the user always has to check that he/she has the calling sequence of the subroutine right, that arrays are properly dimensioned, etc. The shell provided in this version of GQOPT eases many of these tasks.

In general, GQOPT permits users to name input data files anything they want, and (with very minor exceptions) also permits the user to name user-defined function and subroutines in arbitrary manner. By restricting the naming conventions and by requiring that data input conform to certain conventions, the SHELL permits many of these burdens to be avoided. Thus, for example, if the user wishes to solve the simultanous (nonlinear) equations

f(x)=0, g(x)=0, h(x)=0

by minimizing

f(x)**2+g(x)**2+h(x)**2,

the input file must be called MINRES.IN. If the user wishes to perform the Kolmogorov one-sample test (which requires the computation of the "theoretical" cumulative probabilities from a posited distribution function, the name of this function must be KOLSMIR.FOR. All the naming conventions and the order in which input has to be arranged is spelled out in the tables that follow.

Navigating between the part of the Handbook that describes the SHELL and the substantive parts of the Handbook is easy. Tables 1A, 2A, 3A, and 4A have clickable links to the other parts of the Handbook; each substantive section of the Handbook has clickable links back to the appropriate part of the SHELL description.

The SHELL subdirectory that is created when GQOPT is installed contains (1) both the source code (SHELL.FOR) and the object code (SHELL.OBJ), (2) sample input files for every SHELL function, (3) sample subroutines or function subprograms for every SHELL function that requires one. These subprograms are all contained in a single file and a subprogram must be present for every SHELL function that requires one, even if that function is not the one being executed. This is the reason that all these subroutines and functions are in a single file called SHELLFUN.FOR. The user would simply change that subprogram which pertains to his/her particular computation, compile the entire SHELLFUN.FOR (including all the subprograms that the user is not currently interested in, which therefore act as dummies), and then link SHELL.OBJ with SHELLFUN.OBJ and the appropriate library, i.e., .LIB file. SHELLFUN.FOR does not have to be recompiled unless the user wants to change it and improve on it. The presence in the SHELL subdirectory of all the functions and subroutines that might be needed, along with all the illustrative input files and output files (corresponding to the sample input files and functions provided) provides an excellent tutorial for the user. Once the user has provided the appropriate input file (and additional function/subroutine, if needed), the SHELL may be executed by invoking a generic command of the type

linkcommand SHELL.OBJ SHELLFUN.OBJ mylib

For the LF95 compiler, it would be 

lf95 shell.obj shellfun.obj -lib c:\gqopt710\lib\gqlf9571.lib

For the Digital Visual Fortran compiler,

df shell.obj shellfun.obj  c:\gqopt710\lib\gqdvf710.lib

For the WATCOM compiler, it would be 

wlink FILE shell,shellfun LIBRARY c:\gqopt710\lib\gqwat710.lib

assuming, of course, that the paths of the library are correct.

The SHELL is then invoked by typing

shell

(in the Unix environment, the program is called gqshell and must first be made executable by executing chmod u+x gqshell).

GQ-SHELL presents the user with a menu consisting of the following options:

                         1. Optimize
                         2. Equation solving
                         3. Statistical Routines
                         4. Utility Routines
                         5. Exit

You select an option by entering the number of the option and pressing ENTER. That will bring up another menu, depending on which option was selected, from which the user may further select the particular procedure desired.

The basic restrictions are the following:

  1. Input and output files must have fixed names (shown in the tables below)
  2. The input must be arranged in a certain format. Input in any event is unformatted: integers or decimal numbers (as the case may be) should be separated by one or more blanks. For the meaning of each input quantity, please consult the relevant section of the Handbook.
  3. If the procedure requires a user-supplied function, the name of the function must agree with the built-in name (shown in the tables below)

Selecting a procedure immediately starts execution; the SHELL expects to find the input as described below.

Selecting item 1.If the user selects 1 from the initial menu, the following secondary menu will appear:

1. General optimization using GRADX, DFP, POWELL, PATERN,
   RNSRCH,NMSIMP, MUKAI, or SSVM
2. Global optimization using simulated annealing
3. Global optimization using genetic algorithm
4. Linear programming when slacks provide a basic feasible solution
5. Linear programming when slacks do not provide a basic feasible
   solution')
6. Integer programming: Knapsack problem
7. Integer programming: Traveling salesman problem
8. Random genetic algorithm
9. Go to previous MENU')
10. Exit SHELL

The following table indicates the required input files and the function or subroutine names for which the user will have to prepare and compile programs:

Table 1-A. Input and Output Filenames, Function Names for Main Menu Choice=1
Sub-Choice Input file Output file Function name Handbook Reference

1

 optimize.in optimize.out optfunc GRADX, DFP, POWELL , NMSIMP, PATERN, RNSRCH , MUKAI, SSVM

2

 global1.in global1.out simafunc Simulated Annealing

3

 global2.in global2.out galgfunc Genetic Algorithm

4

 linprog1.in linprog1.out
 LP when BFS available

5

 linprog2.in linprog2.out
 LP when BFS not available

6

 knapsack.in knapsack.out
 Knapsack

7

 travsal.in travsal.out
 Traveling salesman

8

 global3.in global3.out granfunc Random genetic algorithm

We next present the arrangement of data values in the input files for the cases depicted in Table 1-B. In Tables 1-B, 2-B, 3-B, and 4-B input "lines" are described. These "lines" refer to the types of input, and not necessarily to actual lines. For example, in Table 1-B, sub-choice 6, three lines are described. Line 1 is an actual line that should contain two integers, n and b. "Line 2" describes the input of a vector c, which may take more than one actual line. "Line 3" describes the input of a vector a, which may also take more than one actual line.

Sub-choice 1 requires a further explanation. Optimization typically involves a function that requires data. Since the form in which the data are to be read in cannot be anticipated by the GQSHELL in a general way, the reader is reponsible for reading in the data in the OPTFUNC subroutine. An example of this is provided in the source code of SHELLFUN.FOR, which ensures that the data are read in only once, not every time the function subroutine is evaluated. The user must make sure that the appropriate compile flag is set so that local variables in subroutines are remembered.

Table 1-B. Arrangement of Data Input for Main Menu Choice=1
Sub-Choice Line No. Data Input and Explanation

1

1

 mx  np  iterl  iread                  !iread should=0 if default values of parameters are to be used, =1 if user wants to reset parameters

2

method                          !This should be either gradx or dfp or powell or patern or rnsrch or ssvm

3

acc                                !if iread=0 or method=mukai or method=nmsimp
iver  lt  ifp  isp  nloop  ist  iloop           !if iread=1 and method=gradx or =dfp or =ssvm
step1 stpacc nlnsr           !if iread=1 and method=powell
stpsiz shrink                    !if iread=1 and method=patern
deltaz sdelta rho              !if iread=1 and method=rnsrch

4

 fdfrac fdmin                    !if iread=1 and method=gradx or =dfp or =ssvm
x                                    !on this and subsequent lines, the values of the starting point, if iread=1 and method=patern or rnsrch or powell or if iread=0

5

 step1 stpacc nlnsr            !if iread=1 and method= gradx or= dfp
thetaa phii shrip1 shrip2 epss       !if iread=1 and method =ssvm

6

 rtm eig rtmult                  !if iread=1 and method= gradx
stpmin fopt                     ! if iread=1 and method=dfp
x                                    !on this and subsequent lines, the values of the starting point, if iread=1 and method=ssvm

7

 ispd                                !if iread=1 and method= gradx
inflg                                !if iread=1 and method= dfp

8

 acti actw zful betm          !if iread=1 and method= gradx
x                                     !on this and subsequent lines, the values of the starting point, if iread=1 and method= dfp

9

 thetaa phii shrip1 shrip2 epss !if iread=1 and method= gradx

10

 x                                      !on this and subsequent lines, the values of the starting point, if iread=1 and method=gradx
2
1
np  neps  ns  nt  max  maxevl
2
eps  rt  t
3
x        !read in as many lines as necessary
4
c        !read in as many lines as necessary
5
lb       !read in as many lines as necessary
6
ub      !read in as many lines as necessary
7
vm     !read in as many lines as necessary
3
1
np  nipop  npop  ngood  max
2
nc  initgen  ipair  imate  
3
kterl  imute  itest  ihowman  
4
xmute  bacc  shrink1  expand  alph1  bet1
5
xl        !read in as many lines as necessary
6
xh        !read in as many lines as necessary
4
1
m  n  ifr  kpiv
2
a        !read in by rows; each row must begin on a new line; read m+1 rows of n+1 elements each---see Sect. 17.1.1
5
1
m  n
2
a        !read in by rows; each row must begin on a new line; read m+1 rows of n+1 elements each---see Sect. 17.1.1
6
1
n  b
2
c        !read in as many lines as necessary
3
a        !read in as many lines as necessary
7
1
np  nipop  npop  ngood
2
jnitgen  jpair  jterl  jtest
3
ymute  bcc
4
c        !read by rows, as many lines as necessary, with each row beginning on a new line
8
1
np  n  isur  imod  max
2
xl        !read as many lines as necessary, with each row beginning on a new line
3
xh        !read as many lines as necessary, with each row beginning on a new line

Selecting item 2.If the user selects 2 from the initial menu, the following secondary menu will appear:

  1. For equations fi(x)=0, i=1,...,m, minimize sum of [fi(x)]-squared
  2. Newton-Raphson
  3. One equation, when unique root is in (a,b) interval: Regula falsi
  4. Solve polynomial
  5. Gauss-Seidel
  6. Go to previous MENU
  7. Exit GQ-SHELL

The following table indicates the required input files and the function or subroutine names for which the user will have to prepare and compile programs:

Table 2-A. Input and Output Filenames, Function Names for Main Menu Choice=2
Sub-Choice Input file Output file Function name Handbook Reference

1

minres.in minres.out
SLVMIN

2

 newraph.in newraph.out nwrpfuncNEWRAP

3

 regfal.in regfal.out regffuncREGFAL

4

polyroot.in polyroot.out
PROOTS

5

gausseid.in gausseid.out
Gauss-Seidel

We next present the arrangement of data values in the input files for the cases depicted in Table 2-A.

Table 2-B. Arrangement of Data Input for Main Menu Choice=2
Sub-Choice Line No. Data Input and Explanation

1

1

 np iterl iread                  !iread should=0 if default values of parameters are to be used, =1 if user wants to reset parameters

2

method                          !This should be either gradx or dfp or powell or patern or rnsrch or ssvm

3

acc                                !if iread=0
iver lt ifp isp nloop ist iloop           !if iread=1 and method=gradx or =dfp or =ssvm
step1 stpacc nlnsr           !if iread=1 and method=powell
stpsiz shrink                    !if iread=1 and method=patern
deltaz sdelta rho              !if iread=1 and method=rnsrch

4

 fdfrac fdmin                    !if iread=1 and method=gradx or =dfp or =ssvm
x                                    !on this and subsequent lines, the values of the starting point, if iread=1 and method=patern or rnsrch or powell

5

 step1 stpacc nlnsr            !if iread=1 and method= gradx or dfp
thetaa phii shrip1 shrip2 epss       !if iread=1 and method =ssvm

6

 rtm eig rtmult                  !if iread=1 and method= gradx
stpmin fopt                     ! if iread=1 and method=dfp
x                                    !on this and subsequent lines, the values of the starting point, if iread=1 and method=ssvm

7

 ispd                                !if iread=1 and method= gradx
inflg                                !if iread=1 and method= dfp

8

 acti actw zful betm          !if iread=1 and method= gradx
x                                     !on this and subsequent lines, the values of the starting point, if iread=1 and method= dfp

9

 thetaa phii shrip1 shrip2 epss !if iread=1 and method=gradx

10

 x                                      !on this and subsequent lines, the values of the starting point, if iread=1 and method=gradx

2

1

n iterl iread                       !iread should be set =0 if user does not want to read in new values for the variables in COMMON blocks BNWRP1 and BNWRP2

2

acc                                   !if iread=0
ivflim invlim                       !if iread=1

3

x                                       !if iread=0, this and subsequent lines should contain starting point
epcor epsvrt                      !if iread=1

4

acc                                    !if iread=1

5

x                                        !if iread=0, this and subsequent lines should contain starting point

3

1

a b acc

2

iterl

4

1

m iterl

2

xcof                                   !xcof(i) to contain the coefficient of x**(i-1)

5

1

np  iterl  max

2

x                                   !x to contain the starting point;read as many lines as necessary

Selecting item 3.If the user selects 3 from the initial menu, the following secondary menu will appear: 

    
                1. Kolmogorov Smirnov 1-sample test
                2. Kolmogorov Smirnov 2-sample test
                3. Wilcoxon-Mann-Whitney test
                4. Spearman Rho
                5. Kendall Tau
                6. Kendall Partial Tau
                7. Kendall Concordance W
                8. Cumulative Sample Distribibution
                9. Contingency Table
               10. Autocovariance Function
               11. Periodogram
               12. Spectrum
               13. Density Plots
               14. Countour Plot
               15. Density Estimation
               16. Kernel Regression
               17. Least Squares Regression
               18. Friedman Analysis of Variance
               19. Test Equality of Means
               20. Wald-Wolfowitz test
	      21. Continuous Convolution
	      22. Discrete Convolution
	      23. Cochran Q-test
	      24. Wilcoxon test
	      25. Go to previous MENU
	      26. Exit GQ-SHELL

The following tables indicate the (prescribed) names of input and output files (and of auxiliary function or subroutine names if needed) and gives directions for how the input is to be prepared.

The following table indicates the required input files and the function or subroutine names for which the user will have to prepare and compile programs:

Table 3-A. Input and Output Filenames, Function Names for Main Menu Choice=3
Sub-Choice Input file Output file Function name Handbook Reference

1

klsm1.in klsm1.outkolsmirKOL-SMIR 1-sample

2

klsm2.in klsm2.out
KOL-SMIR 2-sample

3

wmw.in wmw.out
Wilcoxon-Mann-Whitney

4

spear.in spear.out
Spearman Rho

5

kend-tau.in kend-tau.out
Kendall Tau

6

part-tau.in part-tau.out
Kendall Partial Tau

7

kw-conc.in kw-conc.out
Kendall W

8

cumdis.in cumdis.out
Cumul. Sample Dist.

9

conting.in conting.out
Contingency tables

10

autocov.in autocov.out
Autocovariance function

11

pergram.in pergram.out
Periodogram

12

spectrum.in spectrum.out
Spectrum

13

densplot.in densplot.out
Density plots

14

contour.in contour.outcntrfuncContour plots

15

density.in density
Nonparametric density estimation

16

kerreg.in kerreg.out
Kernel regression

17

regress.in regress.out
Regression estimation (OLS)

18

friedman.in friedman.out
Friedman analysis of variance

19

testmean.intestmean.out
Test equality of means

20

waldwolf.inwaldwolf.out
Wald-Wolfowitz test

21

convolve.inconvolve.out
convol.pr		convolutContinuous convolution

22

discconv.indiscconv.outfuncf, funcgDiscrete convolution

23

cochranq.incochranq.out
Cochran Q test

24

wilcoxon.inwilcoxon.out
Wilcoxon test

The arrangement of the input that is required is shown in the following table:

Table 3-B. Arrangement of Data Input for Main Menu Choice=3
Sub-Choice Line No. Data Input and Explanation

1

1

n

2

sig

3

x                                        !and subsequent lines, if necessary

2

1

n m

2

sig

3

x                                        !and subsequent lines, if necessary

4

y                                        !and subsequent lines, if necessary. The line(s) for the y-observations follow after all the x-observations

3

1

n1 n2

2

rt

3

a                                        !and subsequent lines, if necessary

4

b                                        !and subsequent lines, if necessary. The line(s) for the b-observations follow after all the a-observations

4

1

n

2

x                                       !and subsequent lines, if necessary.

3

y                                        !and subsequent lines, if necessary.The line(s) for the y-observations follow after all the a-observations

5

1

n

2

x                                       !and subsequent lines, if necessary.

3

y                                        !and subsequent lines, if necessary.The line(s) for the y-observations follow after all the x-observations

6

1

n

2

x                                       !and subsequent lines, if necessary.

3

y                                        !and subsequent lines, if necessary.The line(s) for the y-observations follow after all the x-observations

4

z                                        !and subsequent lines, if necessary.The line(s) for the z-observations follow after all the y-observations

7

1

m n

2

rk                                      !by rows; row 1 first, row 2 beginning on a new line next, etc.

8

1

n

2

a                                        !and subsequent lines, if necessary.

9

1

m n

2

a                                        !by rows; row 1 first, row 2 beginning on a new line next, etc..

10

1

n m

2

x                                        !and subsequent lines, if necessary.

11

1

m

2

x                                        !and subsequent lines, if necessary.

12

1

n

2

window                                !The letter "p" or "w" or "h" or the number "4" or "6" to replace "window".

3

x                                        !and subsequent lines, if necessary.

13

1

n

2

x                                       !and subsequent lines, if necessary.

3

y                                        !and subsequent lines, if necessary.The line(s) for the y-observations follow after all the x-observations

14

1

np i1 i2

2

iopt(1)    iopt(2)   iopt(3)                

3

xmin xmax ymin ymax zmin zmax zint                   !The last three only if iopt(1)=1

4

xlabel ylabel                        !enclosed in '     ' and separated by at least one blank

15

1

n nval kernel ih

2

eps  h                                 !if ih=0
eps                                     !if ih=1

3

x                                        !and subsequent lines, if necessary.

16

1

n m kernel igh ihw

2

h

3

conf

4

x                                        !and subsequent lines, if necessary.

5

y                                        !and subsequent lines, if necessary.

17

1

n k

2

x                                       !and subsequent lines, if necessary. Read in by observations, i.e., by rows of x. Each new observation (vector) to start on a new line.

3

y                                        !and subsequent lines, if necessary.The line(s) for the y-observations follow after all the x-observations

18

1

m n

2

rk                                      !by rows, i.e., by judges; row 1 first, row 2 beginning on a new line next, etc.

19

1

n1 n2

2

a1                                      !first sample; as many rows as necessary

3

a2                                      !second sample; as many rows as necessary

20

1

n1 n2

2

a1                                      !first sample; as many rows as necessary

3

a2                                      !second sample; as many rows as necessary

21

1

n npoint yl yh ax bx

22

1

n m

23

1

n k

2

jresp                                      !and subsequent lines, if necessary. Read in by individuals, i.e., by rows of jresp. Each new individual to start on a new line.

24

1

n

2

a1                                      !first set of measurements; as many rows as necessary

3

a2                                      !second setof measurements; as many rows as necessary

Selecting item 4. If the user selects 4 from the initial menu, the following secondary menu will appear: 

    
           1. Eigenvalues/eigenvectors for symmetric matrices
           2. Invert symmetric matrix (GJR)
           3. Invert arbitrary matrix using VERS
           4. Invert arbitrary matrix using MATVRT
           5. Solve system of linear equations using GAJORE
           6. Compute determinant
           7. Numeric integration
           8. Generate random variables from selected distributions
	  9. Plot a time series
	 10. Inverse of the cumulative normal 
          11. Go to previous MENU
          12. Exit SHELL

Selecting options 7 or 8 from this menu will result in sub-menus being presented. The following table indicates the required input files and the function or subroutine names for which the user will have to prepare and compile programs, both for this menu and the sub-menus:

Table 4-A. Input and Output Filenames, Function Names for Main Menu Choice=4
Sub-Choice Sub-Sub-Choice Input file Output file Function name Handbook Reference

1
matev2.in matev2.out
Eigenvalues of symmetric matrices

2


 invert1.in invert1.out
Invert symmetric matrix (GJR)

3


 invert2.in invert2.out
Invert arbitrary square matrix (VERS)

4
invert3.in invert3.out
Invert arbitrary square matrix (MATVRT)

5


 gajore.in gajore.out
Solve linear equations (GAJORE)

6


 determ.in determ.out
Compute determinant (DTRM)

7
1
 normal2.in normal2.out
Integrate normal density

7
2
 normal3.in normal3.out
Integrate normal density

7
3
 newtcot.in newtcot.outnwct1 or nwct2 or nwct3Newton Cotes integration

7
4
 weddle.in weddle.outwddWeddle integration

7
5
 romberg.in romberg.outrmbbRomberg integration

7
6
 gausleg.in gausleg.outgale1 or gale2 or gale3Gauss-Legendre integration

7
7
 igausleg.in igausleg.outgale1 or gale2 or gale3 or gale4Gauss-Legendre integration

7
8
 bivar2.in bivar2.outax(x), ay(x),bvr2(x,y)Variable limit bivariate integration

7
9
 gauslag.in gauslag.outglgGauss-Laguerre integration

7
10
 moncarl.in moncarl.out
Monte Carlo integration

8
1
 randvar.in randvar.out
Uniform random variables

8
2
 normalbm.in normalbm.out
Normal variates (Box-Muller)

8
3
 normalmb.in normalmb.out
Normal variates (Marsaglia-Bray)

8
4
 normalsu.in normalsu.out
Normal variates (summing uniforms)

8
5
 expon.in expon.out
Exponential variates

8
6
 cauchy.in cauchy.out
Cauchy variates

8
7
 raylei.in raylei.out
Rayleigh variates

8
8
 pareto.in pareto.out
Pareto variates

8
9
 logistic.in logistic.out
Logistic variates

9
plotcurv.in plotcurv.out
Plot a time series (PLOTCURV)

10
invgaus.in invgaus.out
Invert the cumulative normal (INVGAUS)

The arrangement of the input that is required is shown in the following table:

Table 4-B. Arrangement of Data Input for Main Menu Choice=4
Sub-Choice Sub-Sub-Choice Line No. Data Input and Explanation
1

1
n  isw
2
a          !on this and subsequent lines as necessary; since a is symmetric, you may list values by rows or columns; each new row (column) to start on a new line
2

1
n
2
a          !on this and subsequent lines as necessary; since a is symmetric, you may list values by rows or columns
3

1
n
2
a          !on this and subsequent lines as necessary; list matrix elements by rows; each row should start on a new line and use as many lines for each matrix row as necessary
4

1
n
2
a          !on this and subsequent lines as necessary; list matrix elements by rows; each row should start on a new line and use as many lines for each matrix row as necessary
5

1
n
2
b          !the vector of "right hand sides" on this and subsequent lines as needed
3
a          !on this and subsequent lines as necessary; list matrix elements by rows; each row should start on a new line and use as many lines for each matrix row as necessary
6

1
n
2
a          !on this and subsequent lines as necessary; list matrix elements by rows; each row should start on a new line and use as many lines for each matrix row as necessary
7
1
1
ax  ay  r12
2
method     !where method should be one of biv2 or dutt or clark
2
1
ax  ay  az  r12  r13  r23
2
method     !where method should be one of dutt or clark
3
1
idim
2
ax  bx  nx                                      !if idim=1
ax  bx  ay  by  nx  ny                     !if idim=2
ax  bx  ay  by  az  bz  nx  ny  nz     !if idim=3
4
1
ax  bx  n
5
1
ax  bx  
6
1
idim
2
ax  bx  nx                                      !if idim=1
ax  bx  ay  by  nx  ny                     !if idim=2
ax  bx  ay  by  az  bz  nx  ny  nz     !if idim=3
7
1
idim  n
2
ax  bx  nx                                      !if idim=1
ax  bx  ay  by  nx  ny                     !if idim=2
ax  bx  ay  by  az  bz  nx  ny  nz     !if idim=3
ax  bx  ay  by  az  bz  aw  bw  nx  ny  nz  nw   !if idim=4
8
1
ax  bx  
9
1
ax  n  
10
1
nrep  ndim  indep  iconst
2
a                   !read by rows starting with a(1,0); each row to start on a new line
3
xmu                !as many lines as necessary
4
sig                !if indep=.TRUE., as many lines as necessary
cov                !if indep=.FALSE.; by rows, with each row starting on a new line; as many lines as necessary
8
1
1
n
2
1
n
3
1
n
4
1
n  m
5
1
n  a
6
1
n  s
7
1
n  s
8
1
n  a  b
9
1
n
9

1
n
2
x          !the variable plotted on the horizontal axis; on this and subsequent lines as needed
3
y          !the variable plotted on the vertical axis; on this and subsequent lines as necessary;
10

1
xmu   var   y   acc   iterl

Return to

|Beginning|What's new|