Setting options

Knitro offers a number of user options for modifying behavior of the solver. Each option takes a value that may be an integer, double precision number, or character string. Options are usually identified by a string name (for example, algorithm), but programmatic interfaces also identify options by an integer value associated with a C language macro defined in the file knitro.h. (for example, KTR_PARAM_ALG). Most user options can be specified with either a numeric value or a string value.

Note

The naming convention is that user options beginning with bar_ apply only to the barrier/interior-point algorithms; options beginning with act_ apply only to the active-set/SQP algorithms; options beginning with mip_ apply only to the mixed integer programming (MIP) solvers; options beginning with ms_ apply only to the multi-start procedure; and options specific to the multi-algorithm procedure begin with ma_. Options specific to parallel features begin with par_.

Setting Knitro options within AMPL

We have seen how to specify user options, for example:

ampl: option knitro_options "alg=2 bar_maxcrossit=2 outlev=1";

A complete list of Knitro options that are available in AMPL can be shown by typing:

knitroampl -=

The output produced by this command, along with a description of each option, is provided in Section Knitro / AMPL reference.

Note

When specifying multiple options, all options must be set with one knitro_options command as shown in the example above. If multiple knitro_options commands are specified in an AMPL session, only the last one will be read.

When running knitroampl directly with an AMPL file, user options can be set on the command line as follows:

knitroampl testproblem.nl maxit=100 opttol=1.0e-5

Setting Knitro options with MATLAB

There are two ways knitromatlab can read user options: either using the fmincon format (explained in the MATLAB documentation), or using the Knitro options file (explained below). If both types of options are used, Knitro options override fmincon format options.

The Knitro option file is a simple text file that contains, on each line, the name of a Knitro option and its value. For instance, the content of the file could be:

algorithm    auto
bar_directinterval  10
bar_feasible no

Assuming that the Knitro options file is named knitro.opt and is stored in the current directory, and that the fmincon-format options structure is named KnitroOptions, the call to knitromatlab would be:

[x fval] = ...
    knitromatlab(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,extendedFeatures,KnitroOptions, ...
                 'knitro.opt')

The Knitro options file is a general mechanism to pass options to Knitro. It can also be used with the callable library interface, but is most useful with the Knitro/MATLAB interface for which it is the only way to set many of the available options.

Setting Knitro options with the callable library

The functions for setting user options have the form:

int KTR_set_int_param (KTR_context *kc, int param_id, int value)

for setting integer valued parameters, or:

int KTR_set_double_param (KTR_context *kc, int param_id, double value)

for setting double precision valued parameters.

For example, to specify the Interior/CG algorithm and a tight optimality stop tolerance:

status = KTR_set_int_param (kc, KTR_PARAM_ALG, KTR_ALG_BAR_CG);
status = KTR_set_double_param (kc, KTR_PARAM_OPTTOL, 1.0e-8);

Refer to the Callable Library Reference Manual (Changing and reading solver parameters) for a comprehensive list.

Setting KNITRO options with the object-oriented interface

User options are set with a single overloaded KTRSolver function that has the form:

void solver.setParam(param_identifier, param_value);

The argument param_identifier is either a string with the parameter’s name or an integer with the parameter’s identifier number (enumerated object with all options have been defined to simplify this step). The argument param_value is an integer, double, or string, depending on the type of parameter that is set.

For example, to specify the Interior/CG algorithm and a tight optimality stop tolerance:

solver.setParam(KTR_PARAM_ALG, KTR_ALG_BAR_CG);
solver.setParam(KTR_PARAM_OPTTOL, 1.0e-8);

Refer to the Callable Library Reference Manual (Changing and reading solver parameters) for a comprehensive list of parameters. The object-oriented interface uses the same parameters as the callable library.

The Knitro options file

The Knitro options file allows the user to easily change user options by editing a text file, instead of modifying application code.

Options are set by specifying a keyword and a corresponding value on a line in the options file. Lines that begin with a “#” character are treated as comments and blank lines are ignored. For example, to set the maximum allowable number of iterations to 500, you could create the following options file:

# Knitro Options file
maxit            500

MATLAB users may simply pass the name of the Knitro options file to knitromatlab as demonstrated in Getting started with MATLAB. When using the callable library, the options file is read into Knitro by calling the following function before invoking KTR_init_problem() or KTR_mip_init_problem():

int KTR_load_param_file (KTR_context *kc, char const *filename)

For example, if the options file is named myoptions.opt:

status = KTR_load_param_file (kc, "myoptions.opt");

The full set of options used by Knitro in a given solve may be written to a text file through the function call:

int KTR_save_param_file (KTR_context *kc, char const *filename)

For example:

status = KTR_save_param_file (kc, "knitro.opt");

A sample options file knitro.opt is provided for convenience and can be found in the examples/C directory. Note that this file is only read by application drivers that call KTR_load_param_file(), such as examples/C/callbackExample2.c.

In the object oriented interface, the equivalent functions for loading and saving parameter files are the following:

void KTRSolver::loadParamFile(std::string filename);
void KTRSolver::saveParamFile(std::string filename);