The sifdecode command

It may be useful in some cases to decode a SIF-encoded problem without running an optimization package afterwards, or to simply check the syntax of the SIF file. Either in this respect, or as part of a bigger project--for instance, SifDec--the sifdecode command is invoked whenever it comes to decoding a SIF file. The sifdecode command recognizes a number of command-line options, many of which only make sense when sifdecode is used in conjunction with an optimization package. For more information on how to use SifDec in conjunction with CUTEr, refer to the manual [4]. The options are described below.

sifdecode	[-s] [-h] [-k] [-o j] [-l secs] [-f] [-b] [-a j] [-show]
	[-param name=value[,name=value...]] [-force] [-debug] probname[.SIF]

where

-s

use the single-precision SIF decoder, if installed. This is useful to subsequently solve the problem in single precision, using some optimization package;

-h

(or [-help]) prints a help message;

-k

keep the load module after use; this is only useful in conjunction with some optimization package;

-r

discourage recompilation of the test problem; this is only useful in conjunction with some optimization package;

-o $j$

verbosity level: -o 0 is silent mode and -o 1 is verbose mode. The default is -o 0;

-l secs

limits the CPU running time to secs seconds; this is only useful in conjunction with some optimization package;

-f

generate the relevant subroutines for automatic differentiation in forward mode;

-b

generate the relevant subroutines for automatic differentiation in backward mode;

-a $j$

when used in conjunction with -f or -b, -a 1 uses the older HSL automatic differentiation package AD01, which -a 2 uses the newer, threadsafe, automatic differentiation package AD02;

-show

displays possible parameter settings for probname[.SIF]. Other options are ignored;

-param

casts probname[.SIF] against explicit parameter settings;

-debug

links the libraries and compile with -g option so as to allow debugging; this is only useful in conjunction with some optimization package;

-n

use the load module if it exists. The default is to recompile; this is only useful in conjunction with some optimization package.

If probname.SIF is correct, this results in the creation of the files

ELFUN.f, GROUP.f, RANGE.f, OUTSDIF.d, AUTOMAT.d

containing the decoded problem data. Possibly, a file called EXTER.f may also be created, if probname.SIF relies on external Fortran subroutines.

One of the less convenient features of SIF-encoded problems was that the decoding procedures in CUTE [1] were not designed to recognise, nor to alter, instance-dependent variable parameters such as problem dimensions or critical coefficients. Many real models, particularly those that arise from some form of discretization, depend upon parameters that a user might wish to refine. With CUTE, a user wishing to change such a parameter was forced to edit the SIF file--these files were usually provided with a number of suggested values, all but one of which were ``commented out''. Since a number of users found this to be very inconvenient, SifDec makes provisions both for the definition and for the altering of variable parameters from the problem-decoding scripts.

Any real or integer parameter definition containing the comment $-PARAMETER in field 5 (i.e., in columns 40-50) in a SIF file defines that parameter to be a variable parameter--this is consistent with old-style SIF-encoded problems since strings starting with $ in this field were previously treated as comments. Any characters after $-PARAMETER will be regarded as comments, and will be passed back to a user on request. All SIF files in the CUTE collection that previously contained variable parameters have been updated to take advantage of this new SifDec facility, but of course they are still consistent with CUTE.

Given this extra syntax, the SIF decoding scripts have been extended to support two new options, allowing users to select variable parameters in the SIF file. The first of these options, -show, prints all the variable parameters present in the SIF file, along with suggested values to which they may be set as well as any other provided comments. For instance, the command

prompt% sifdecode -show LUBRIFC

produces, on my system, the output

  NN=10   (IE)                    comment:  n = 151 original value
  NN=50   (IE)                    comment:  n = 751
  NN=500  (IE)    -default value- comment:  n = 7501

indicating that the only parameter accepted by the problem described in LUBRIFC.SIF is called NN, that is takes integer values (IE), that it accepts the values 10, 50 or 500, 500 being the value used by default, and that these values correspond, in the problem, to the variable $n$ being equal to 151, 751 or 7501 respectively. We now examine how to select one of the possible values for each such parameter.

The -param command-line option to sifdecode allows users to choose, from the command line, which values to assign to these parameters. For instance, assuming that N and THETA have been marked as variables parameters of SAMPLE.SIF and that N=400 and THETA=3.5 are valid values, the command

prompt% sifdecode -param N=400,THETA=3.5 SAMPLE.SIF

will decode SAMPLE.SIF into the appropriate subroutines and data files, setting N to 400 and THETA to 3.5. Note that the above command and

prompt% sifdecode -param N=400 -param THETA=3.5 SAMPLE.SIF

are perfectly equivalent.

These new features allow users to systematically solve a set of problems in all prescribed, or possible, sizes. Default values are given in each SIF file, and we have taken the opportunity to raise these defaults to reflect the size of problem that we feel ought to be of current interest, given that many of the previous defaults were assigned over ten years ago.

As a possible extension of the -param command-line option, users may force a problem to be decoded/solved using parameter values which have not necessarily been pre-assigned in the SIF file. This is done using the -force option, as in

prompt% sifdecode -param N=1000,THETA=3.5 -force SAMPLE.SIF

where SAMPLE.SIF does not contain the parameter setting N=1000. Omitting the -force option would result in an abort of the process while specifying it results in the SIF decoder and the optimizer attempting to complete the solve using the value 1000 for N. Note that nothing guarantees that this value is valid in that context, and that the -force command-line option should be used carefully.

The options -param and -force are of course available on every sdpak interface and has the effect described above. With consistency concerns in mind, the -show option is also available from every sdpak, but has the sole effect of printing out the possible parameter settings, cancelling the subsequent call to the package pak.