# The Knitro-Tuner

The Knitro-Tuner can help you identify some non-default options settings that may improve performance on a particular model or set of models. This section desribes how to use the Knitro-Tuner.

## Default Tuning

If you are unsure about what Knitro options should
be tuned to try to improve performance, then you can simply run the
default Knitro-Tuner by setting the option `tuner`

=1, when
running Knitro on your model. This will cause Knitro to automatically
run your model with a variety of automatically determined option settings,
and report some statistics at the end. Any Knitro options that have been
set in the usual way will remain fixed throughout the tuning procedure.

## Custom Tuning

If you have some ideas about which Knitro options you want to tune, then you can tell Knitro which options you want it to tune (as well as specify the values for particular options that you want Knitro to explore). This can be done by specifying a Tuner options file. A Tuner options file is a simple text file that is similar to a standard Knitro options file (see Setting options for details on how to define a standard Knitro options file).

A Tuner options file differs from a standard Knitro options file in a few ways:

- You can define multiple values (separated by spaces) for each option. This tells Knitro the values you want it to explore.
- You can specify an option name without any values. This will tell Knitro to explore all possible option values for that option. This only works for options that have a finite set of possible option value settings.
- A Tuner options file is loaded through the API function
`KN_load_tuner_file()`

if using the callable library API (procedures for loading a Tuner options file for other environments are demonstrated in the examples below).

All possible combinations of options/values specified in a Tuner options file will be explored by Knitro, while any Knitro options that have been set in the usual way will remain fixed throughout the tuning procedure.

An example of using the Knitro-Tuner and defining a Tuner options file
is provided in `examples/C`

in the Knitro distribution. Below is
the Tuner options file from that example.

```
# This file is used to specify the options and option values
# that will be systematically explored by the Knitro-Tuner
# in "tunerExample.c". One can specify the specific option
# values to be explored by a particular option (as with
# "bar_directinterval" and "linsolver_pivottol" below). If
# just the option name is listed (as with "algorithm" and
# "bar_murule"), then all values for that option will be
# explored (only for options that have a finite number of
# integer values).
algorithm
bar_directinterval 0 1 10
bar_murule
linsolver_pivottol 1e-8 1e-14
```

This options file tells the Knitro-Tuner to explore all possible
option values for the `algorithm`

and `bar_murule`

options, while exploring three values (0, 1 and 10) for the `bar_directinterval`

option and two values (1e-8 and 1e-14) for the `linsolver_pivottol`

option.

Knitro-Tuner works both with continuous and mixed-integer problems. The only difference being that the output and the options scanned by the tuner vary with the type of the problem.

## Tuner Output for Continuous Problems

The Tuner output for continuous models, by default, provides a summary line of output for each
solve during the tuning process indicating the results of that particular solve.
When the Tuner completes all solves, it reports the non-default option settings for
the fastest solve. Perhaps more insightful, however, is a summary table of statistics
provided by the Tuner at the end of the solve. For example, in the NLP example
provided in `examples/C`

, we may see something like this:

```
Summary Statistics
---------------------------------------------------------------------------
Percent Average Average
Option Name Value #Runs Optimal #FuncEvals Time
-------------------- ---------- -------- ------- ---------- ----------
bar_directinterval 0 24 100.00 12.2 0.001
bar_directinterval 1 24 100.00 7.9 0.001
bar_directinterval 10 24 100.00 7.9 0.001
-------------------- ---------- -------- ------- ---------- ----------
bar_murule 1 12 100.00 8.7 0.001
bar_murule 2 12 100.00 7.5 0.001
bar_murule 3 12 100.00 9.7 0.001
bar_murule 4 12 100.00 9.5 0.001
bar_murule 5 12 100.00 10.3 0.001
bar_murule 6 12 100.00 10.5 0.001
-------------------- ---------- -------- ------- ---------- ----------
linsolver_pivottol 1.00e-08 38 100.00 9.1 0.001
linsolver_pivottol 1.00e-14 38 100.00 9.1 0.001
-------------------- ---------- -------- ------- ---------- ----------
algorithm 1 36 100.00 12.7 0.002
algorithm 2 36 100.00 6.0 0.001
algorithm 3 2 100.00 5.0 0.002
algorithm 4 2 100.00 3.0 0.011
---------------------------------------------------------------------------
```

This table indicates the option values explored, the number of Tuner runs for each option value, the percentage of those runs where it found an optimal solution, the average number of function evaluations (in the cases where it found an optimal solution), and the average time (in the cases where it found an optimal solution). In this particular example, the model tested is very small, so the solution times are generally near 0.

This summary table provides some global view of which option settings may be preferable.
For example, the table above suggests that `algorithm`

=2 may be preferable
for models of this type since it (on average) requires a little less time to find
an optimal solution. Although if function evaluations were the dominant cost, then
`algorithm`

=4 might be preferable. The table also suggests that perhaps
the non-default setting `bar_murule`

=2 should be used, since it requires, on
average, the fewest number of function evaluations to converge, although other values
are only slightly worse.

More detailed output can be obtained through non-default settings of `tuner_outsub`

.
In particular, if `tuner_outsub`

=1, then a summary file called
`knitro_tuner_summary.log`

is created in the current folder/directory.
Each line of this file shows the option settings used and the summary results
with these settings. A corresponding file called `knitro_tuner_summary.csv`

is also created, which allows easily reading these results into a spreadsheet.
Additionally, if `tuner_outsub`

=2, the individual
output file for each tuner solve is created in a file called
`knitro_tuner_*.log`

, where * is the corresponding solve number.

## Tuner Output for Mixed-Integer Problems

The Tuner output for mixed-integer models is similar to the output for continuous models, but highlights some statistics unique to mixed-integer optimization. Comparing to the continuous Tuner output, the mixed-integer Tuner output also prints the percent of runs where Knitro finds a feasible solution, the average objective gap, and the average number of nodes explored in the branch-and-bound process.

```
Summary Statistics
--------------------------------------------------------------------------------------------------
Percent Percent Average Average Average
Option Name Value #Runs Optimal Feasible ObjGap #Nodes Time
-------------------- ---------- -------- ------- --------- ---------- ---------- ----------
mip_zerohalf 0 4 100.00 100.00 0.000 5.0 0.026
mip_zerohalf 1 4 100.00 100.00 0.000 5.0 0.008
mip_zerohalf 2 4 100.00 100.00 0.000 5.0 0.009
mip_zerohalf 3 4 100.00 100.00 0.000 5.0 0.009
-------------------- ---------- -------- ------- --------- ---------- ---------- ----------
mip_knapsack 0 4 100.00 100.00 0.000 5.0 0.026
mip_knapsack 1 4 100.00 100.00 0.000 5.0 0.008
mip_knapsack 2 4 100.00 100.00 0.000 5.0 0.009
mip_knapsack 3 4 100.00 100.00 0.000 5.0 0.009
--------------------------------------------------------------------------------------------------
```

## Tuner Options

The following options may be used to customize the performance of the Knitro-Tuner, both on continuous and mixed-integer models.

Option | Meaning |
---|---|

`tuner` |
Enable Tuner |

`tuner_maxtime_cpu` |
Maximum CPU time for Tuner, in seconds |

`tuner_maxtime_real` |
Maximum real time for Tuner, in seconds |

`tuner_optionsfile` |
Specify location/name of Tuner options file |

`tuner_outsub` |
Output additional Tuner subproblem solve information |

`tuner_terminate` |
Termination condition for Tuner |

Note that setting `par_numthreads`

to use multiple threads allows the tuner
to be run in parallel.

The following examples show how to load a Tuner options file in various environments.

## AMPL example

When using Knitro/AMPL, you can specify the location/name of a Tuner options file
through the `tuner_optionsfile`

option as shown below.

```
ampl: option knitro_options "tuner=1 tuner_optionsfile='tuner-explore.opt'";
```

## MATLAB example

In Knitro/MATLAB, the only way to enable the Knitro-Tuner and specify the location
of a Tuner options file is through a standard Knitro options file. For example,
the following Knitro options file, passed as the last argument to *knitromatlab*
would enable the
Tuner and load the Tuner options file `tuner-explore.opt`

assumed to
exist in the current folder/directory.

```
# Example Knitro options file used to enable the Tuner
# and load a Tuner options file in Knitro/MATLAB.
tuner 1
tuner_optionsfile tuner-explore.opt
```

## C example

In the callable library interface, a Tuner options file can be loaded
through the `KN_load_tuner_file()`

API function.

```
/*---- TURN ON THE KNITRO-TUNER */
if (KN_set_int_param (kc, KN_PARAM_TUNER, KN_TUNER_ON) != 0)
exit( -1 );
/*---- LOAD TUNER OPTIONS FILE "tuner-explore.opt". */
if (KN_load_tuner_file (kc, "tuner-explore.opt") != 0)
exit( -1 );
```

## Object-oriented C++ example

In the object-oriented interface, a Tuner options file can be loaded
through the `KTRSolver::loadTunerFile()`

method.

```
// Turn on the KNITRO options file.
solver.setParam(KTR_PARAM_TUNER, KTR_TUNER_ON);
// Load tuner options file "tuner-explore.opt".
solver.loadTunerFile("tuner-explore.opt");
```