Knitro / AMPL reference

A complete list of available Knitro options can be shown by typing:

knitroampl -=

in a terminal. For a detailed description of all options and their values, see Knitro options.

The following AMPL-specific options are not listed in the general options reference and are documented below.

AMPL-specific options

  • leastsquares: Set to 1 to solve the AMPL model as a least-squares model (default 0). See the Nonlinear Least Squares section below.

  • objno: Selects which objective to optimize when the model has multiple objectives. 0 = none, 1 = first (default), 2 = second (if _nobjs > 1), etc.

  • objrep: Whether to replace minimize obj: v; with minimize obj: f(x) when variable v appears linearly in exactly one constraint of the form s.t. c: v >= f(x); or s.t. c: v == f(x);.

Value

Description

0

no replacement

1

yes for v >= f(x) (default)

2

yes for v == f(x)

3

yes in both cases

  • optionsfile: Path that specifies the location of a Knitro options file if provided.

  • relax: Whether to ignore integrality (default 0).

Value

Description

0

do not relax

1

relax all integer variables

  • storequadcoefs: Store quadratic coefficients when solving QCQPs (default 1).

Value

Description

0

do not store quadratic coefficients

1

store quadratic coefficients

  • timing: Whether to report problem I/O and solve times (default 0).

Value

Description

0

no timing output

1

report on stdout

2

report on stderr

3

report on both stdout and stderr

  • use_asl: Controls whether to use AMPL ASL or the Knitro nonlinear modeler for nonlinear evaluations.

Value

Description

0

use Knitro nonlinear modeler

1

use AMPL ASL for nonlinear evaluations

  • version: Report the software version and exit.

  • wantsol: Controls solution reporting without the -AMPL flag.

Value

Description

1

write .sol file

2

print primal variable values

4

print dual variable values

8

do not print solution message

Values can be summed to combine behaviors.

Return codes

Upon completion, Knitro displays a message and returns an exit code to AMPL. If Knitro found a solution, it displays the message:

Locally optimal or satisfactory solution

with exit code of zero; the exit code can be seen by typing:

ampl: display solve_result_num;

If a solution is not found, then Knitro returns a non-zero return code from the table below:

Value

Description

0

Locally optimal or satisfactory solution.

100

Current feasible solution estimate cannot be improved. Nearly optimal.

101

Relative change in feasible solution estimate < xtol.

102

Current feasible solution estimate cannot be improved.

103

Relative change in feasible objective < ftol for ftol_iters.

104

Returning best feasible iterate (when soltype = 1).

105

Multistart: Feasible point found.

200

Convergence to an infeasible point. Problem may be locally infeasible.

201

Relative change in infeasible solution estimate < xtol.

202

Current infeasible solution estimate cannot be improved.

203

Multistart: No primal feasible point found.

204

Problem determined to be infeasible with respect to constraint bounds.

205

Problem determined to be infeasible with respect to variable bounds.

300

Problem appears to be unbounded.

400

Iteration limit reached. Current point is feasible.

401

Time limit reached. Current point is feasible.

402

Function evaluation limit reached. Current point is feasible.

403

MIP: All nodes have been explored. Integer feasible point found.

404

MIP: Integer feasible point found.

405

MIP: Subproblem solve limit reached. Integer feasible point found.

406

MIP: Node limit reached. Integer feasible point found.

410

Iteration limit reached. Current point is infeasible.

411

Time limit reached. Current point is infeasible.

412

Function evaluation limit reached. Current point is infeasible.

413

MIP: All nodes have been explored. No integer feasible point found.

415

MIP: Subproblem solve limit reached. No integer feasible point found.

416

MIP: Node limit reached. No integer feasible point found.

501

LP solver error.

502

Evaluation error.

503

Not enough memory.

504

Terminated by user.

505

Terminated after derivative check.

506

Input or other API error.

507

Internal Knitro error.

508

Unknown termination.

509

Illegal objno value.

For more information on return codes, see Return codes.

AMPL suffixes defined for Knitro

To represent values associated with a model component, AMPL employs various qualifiers or suffixes appended to component names. A suffix consists of a period or “dot” (.) followed by a short identifier (ex: x1.lb returns the current lower bound of the variable x1).

A lot of built-in suffixes are available in AMPL, you may find the list at http://www.ampl.com/NEW/suffbuiltin.html.

To allow more solver-specific results of optimization, AMPL permits solver drivers to define new suffixes and to associate solution result information with them. Below is the list of the suffixes defined specifically for Knitro.

Suffix Name

Description

Model component

xhonorbnd

Specify variables that must always satisfy bounds; see honorbnds (input)

variable

chonorbnd

Specify constraints that must always satisfy bounds; see bar_feasible (input)

constraint

intvarstrategy

Treatment of integer variables; see mip_intvar_strategy (input)

variable

cfeastol

Specify individual constraint feasibility tolerances (input)

constraint

xfeastol

Specify individual variable bound feasibility tolerances (input)

variable

xscalefactor

Specify custom variable scaling factors (input)

variable

xscalecenter

Specify custom variable scaling centers (input)

variable

cscalefactor

Specify custom constraint scaling factors (input)

constraint

objscalefactor

Specify custom objective scaling factor (input)

objective

relaxbnd

Retrieve the best relaxation bound for MIP (output)

objective

incumbent

Retrieve the incumbent solution for MIP (output)

objective

priority

Specify branch priorities for MIP (input)

variable

numiters

Retrieve the number of iterations (output)

objective

numfcevals

Retrieve the number of function evaluations (output)

objective

opterror

Retrieve the final optimality error (output)

objective, variable, constraint

feaserror

Retrieve the final feasibility error (output)

objective, variable, constraint

Below is an example on how to use the specific Knitro suffixes in AMPL:

 1var x{j in 1..3} >= 0;
 2
 3minimize obj: 1000 - x[1]^2 - 2*x[2]^2 - x[3]^2 - x[1]*x[2] - x[1]*x[3];
 4
 5s.t. c1: 8*x[1] + 14*x[2] + 7*x[3] - 56 = 0;
 6
 7s.t. c2: x[1]^2 + x[2]^2 + x[3]^2 -25 >= 0;
 8
 9suffix xfeastol IN, >=0, <=1e6;
10suffix cfeastol IN, >=0, <=1e6;
11suffix objscalefactor IN, >=1e-6, <=1e6;
12
13let x[1].xfeastol := 1e-1;
14let c1.cfeastol := 1e-2;
15let obj.objscalefactor := 2;
16
17solve;
18
19display x[1].feaserror;
20display c1.opterror;
21display obj.numfcevals;
22display obj.feaserror;
23display obj.opterror;

Below is the corresponding output:

Final Statistics
----------------
Final objective value               =  9.51000000020162e+002
Final feasibility error (abs / rel) =   7.11e-015 / 4.55e-016
Final optimality error  (abs / rel) =   3.84e-009 / 1.37e-010
# of iterations                     =          9
# of CG iterations                  =          2
# of function evaluations           =          0
# of gradient evaluations           =          0
# of Hessian evaluations            =          0
Total program time (secs)           =       0.035 (     0.000 CPU time)
Time spent in evaluations (secs)    =       0.000

===============================================================================

Locally optimal or satisfactory solution.
objective 951; feasibility error 7.11e-15
9 iterations; 0 function evaluations

suffix feaserror OUT;
suffix opterror OUT;
suffix numfcevals OUT;
suffix numiters OUT;
x[1].feaserror = 0

c1.opterror = 0

obj.numfcevals = 12

obj.feaserror = 7.10543e-15

obj.opterror = 3.84018e-09

Nonlinear Least Squares

In some cases it may be more efficient to use the specialized Knitro API for nonlinear least-squares (see Least squares problems), which internally applies the Gauss-Newton Hessian, to solve a least-squares model formulated in AMPL. In particular this may be useful if the exact Hessian computed by AMPL is expensive. You can apply this specialized interface through AMPL by following these steps:

  • Set the objective function to 0

  • Specify each residual function as an equality constraint

  • Turn the AMPL presolver off by setting

option presolve 0;

  • Tell Knitro to apply the least-squares interface and disable presolve by setting

option knitro_options "leastsquares=1 presolve=0";

Below is an example of how to solve nonlinear least-squares problems in AMPL:

 1###########################################################
 2####              LSQ in AMPL with Knitro              ####
 3####                                                   ####
 4#### This example illustrates how to optimize least    ####
 5#### squares problems in AMPL by formulating it using  ####
 6#### AMPL syntax and also using Knitro least squares   ####
 7#### dedicated API.                                    ####
 8###########################################################
 9
10# Reset AMPL
11reset;
12
13# Reset initial guesses between consecutive runs
14option reset_initial_guesses 1;
15
16# Reinitialize random seed for generating same values over runs
17option randseed 1;
18
19### The first part of the example will demonstrate how to formulate a
20### least squares problem in AMPL using usual AMPL syntax.
21### Also, we will illustrate an AMPL trick to improve performances.
22
23# We use a large number to demonstrate the AMPL expansion trick
24param M := 1000000;
25
26# Create random values for the "estimates"
27param alpha{1..M};
28let{i in 1..M} alpha[i] := Uniform01();
29
30# Variable: minimize the sum of squares of the distance between var_alpha
31# and the "estimates"
32var var_alpha;
33
34### 1. Straightforward least squares formulation with no expansion ###
35
36## Straightforward least square problem.
37## The objective is expressed directly, without expanding the square terms.
38minimize obj_no_expand:
39    0.5 * sum{i in 1..M} (alpha[i]-var_alpha)^2;
40
41# Optimize non-expanded problem
42solve obj_no_expand;
43
44
45### 2. Least squares with square terms expansion ###
46
47## Same problem but this time the objective is expanded.
48## Notice that, using this trick, the runtime decreases significantly.
49minimize obj_expanded:
50    0.5 * (
51        M * var_alpha^2 -
52        2 * var_alpha * ( sum{i in 1..M} alpha[i] ) +
53        sum{i in 1..M} alpha[i]^2
54    );
55
56# Optimize expanded problem
57solve obj_expanded;
58
59# Check objective value
60display obj_expanded - obj_no_expand;
61
62
63### 3. Least squares using Knitro LSQ API ###
64
65# Set Ampl and Knitro options
66option presolve 0; # disable AMPL presolve, this is mandatory!
67option knitro_options "leastsquares=1 presolve=0"; # Enable Knitro LSQ
68
69## Same problem but this time based on Knitro's least-squares API.
70# Objective must be constant
71minimize obj_lsq: 0;
72
73# Each residual is a constraint: residual = 0
74# s.t. res{i in 1..M}:(alpha[i]-var_alpha)^2 = 0;
75s.t. res{i in 1..M}:
76    alpha[i] - var_alpha = 0;
77
78# Optimize problem using on Knitro LSQ API
79solve obj_lsq;

Below is the corresponding (filtered) output:

[...]

  Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
       0   1.665516e+005  0.000e+000
       1   4.168899e+004  0.000e+000  2.754e-013  4.997e-001        0

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =  4.16889869527361e+004
Final feasibility error (abs / rel) =   0.00e+000 / 0.00e+000
Final optimality error  (abs / rel) =   2.75e-013 / 3.30e-014
# of iterations                     =          1
# of CG iterations                  =          0
# of function evaluations           =          4
# of gradient evaluations           =          3
# of Hessian evaluations            =          1
Total program time (secs)           =       0.452 (     0.453 CPU time)
Time spent in evaluations (secs)    =       0.274

===============================================================================

[...]

  Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
       0   1.665516e+005  0.000e+000
       1   4.168899e+004  0.000e+000  0.000e+000  4.997e-001        0

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =  4.16889869527314e+004
Final feasibility error (abs / rel) =   0.00e+000 / 0.00e+000
Final optimality error  (abs / rel) =   0.00e+000 / 0.00e+000
# of iterations                     =          1
# of CG iterations                  =          0
# of function evaluations           =          4
# of gradient evaluations           =          3
# of Hessian evaluations            =          1
Total program time (secs)           =       0.002 (     0.000 CPU time)
Time spent in evaluations (secs)    =       0.000

===============================================================================

[...]

  Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
       0   1.665516e+005  0.000e+000
       1   4.168899e+004  0.000e+000  1.376e-009  4.997e-001        0

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =  4.16889869527361e+004
Final feasibility error (abs / rel) =   0.00e+000 / 0.00e+000
Final optimality error  (abs / rel) =   1.38e-009 / 3.30e-014
# of iterations                     =          1
# of CG iterations                  =          0
# of residual evaluations           =          4
# of Jacobian evaluations           =          2
Total program time (secs)           =       0.301 (     0.500 CPU time)
Time spent in evaluations (secs)    =       0.163