General procedure for Fortran and C interfaces

The purpose of this section is to explain how one can build interface tools for another optimization package, similar to those interfaces sdunc and unc provided for UNCMIN. We provide generic scripts sdgen and gen to make this process easier. These scripts can be found in the $CUTER/build/prototypes directory.

For illustrative purposes, we assume the package for which one wishes to provide an interface is called pack. We suppose that both single and double precision instances of the package are available and that interfaces in both precisions are required. An interface for just one of the precisions can be obtained by ignoring any of the comments relating to the other. A number of additional comments regarding the interfacing of packages written in C are given in §1.10.2. We suggest the following steps.

1. Construct a driver program calling the new package and using the Fortran tools provided (for evaluating the objective function, its gradient, etc.) The existing driver programs (uncma, mnsma, ve09ma, stnma, etc.) might help you get started in writing this new driver.

   Now compile this program into an object file called packma.o. The double precision object should reside in the directory

   $MYCUTER/double/bin

   and the single precision object should reside in the directory

   $MYCUTER/single/bin,

2. Compile the double precision instance of the complete set of programs contained in the pack package into one object file^1.2 (for example, packd.o). Repeat this for the single precision instance of the package, producing a second object file (for example, packs.o),

3. Connect to $CUTER/build/prototypes and copy sdgen.pro and gen.pro to sdpack.pro and pack.pro respectively. This is done by typing

   prompt% cd $CUTER/build/prototypes
   prompt% cp sdgen.pro sdpack.pro
   prompt% cp gen.pro pack.pro

   at the command prompt,

4. Create the new directory $CUTER/common/src/pkg/pack,

5. Edit sdpack.pro and pack.pro and modify them as follows:
   1. change the name of the package to be interfaced from gen to pack. This is done in the assignment of the shell variables PAC and PACKAGE at the beginning of the script, so that it reads

      setenv PAC = pack
      setenv PACKAGE = pack

   2. if applicable, add or remove command-line options to the interfaces sdpack.pro and pack.pro, paying special attention to those options that are passed over to the SIF decoder and to runpackage.pro,

   3. properly set the PACKOBJ and SPECS environment variables to contain the object file(s)/libraries for the package and the specification file (if any) respectively. The object files^1.3 should lie in $MYCUTER/precision/bin, where precision is either single or double, and the specification file should lie in the directory $CUTER/common/src/pkg/$PACKAGE, i.e. in this case, $CUTER/common/src/pkg/pack.

6. Possibly, alter runpackage.pro to link BLAS libraries, or other relevant libraries.

7. The scripts now need to be cast against your machine-dependent specifications. This may be done by issuing the commands

   prompt% sed -f $MYCUTER/precision/config/script.sed file.pro > $MYCUTER/bin/file
   prompt% chmod a+x $MYCUTER/bin/file

   at the command prompt, where file is successively sdpack and pack. If you altered runpackage.pro, the same should be done for file=runpackage.

Note: In case your package is not going to be available on all the platforms for which you have a CUTEr installation, modify the scripts sdgen, gen and runpackage found in $MYCUTER/bin instead of the prototype scripts. Otherwise, it is recommended that you write prototypes and store them in $CUTER/build/prototypes.

We would be very pleased if you could send your interface and driver program to us, so that we can redistribute it with future versions of CUTEr, with proper ackowledgments. Thank you in advance and good luck!