Getting started with the object-oriented interface

The Knitro object-oriented interface provides an object-oriented wrapper around the Knitro callable library. The interface is available in C++, C#, and Java. This document focuses on the C++ version of the interface. The interfaces are the same in functionality, differing only in language syntax and data types used in functions (e.g., std::vector<> in C++, IList<> in C#, and List<> in Java). Examples for each of the languages are available in the Knitro examples folders.

The C++ object-oriented interface is a header-only interface. Complete source code for the interface is included with Knitro for informational purposes. Usage requires including the knitro.h header within the include directory of Knitro and linking against the appropriate Knitro library file within the lib directory of Knitro.

The object-oriented API is used to solve an optimization problem through a sequence of function calls:

  • KTRIProblem* instance: create an instance of the problem to be solved by Knitro. The class is user-defined, inherits from the KTRIProblem class, and defines the problem characteristics.
  • KTRSolver solver(instance): load the problem definition into the Knitro solver and check out a Knitro license.
  • solver.solve(): solve the problem, with output stored in the solver object.

The example below shows how to define a problem and class and use these function calls.

First example

The follwing defines the same toy problem solved using AMPL, MATLAB, and the callable library.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
#include "KTRSolver.h"
#include "KTRProblem.h"
#include <iostream>

class ProblemExample : public knitro::KTRProblem {
private:
    // objective properties
    void setObjectiveProperties() {
        setObjType(knitro::KTREnums::ObjectiveType::ObjGeneral);
        setObjGoal(knitro::KTREnums::ObjectiveGoal::Minimize);
    }

    // variable bounds. All variables 0 <= x.
    void setVariableProperties() {
        setVarLoBnds(0.0);
    }

    // constraint properties
    void setConstraintProperties() {
        // set constraint types
        setConTypes(0, knitro::KTREnums::ConstraintType::ConGeneral);
        setConTypes(1, knitro::KTREnums::ConstraintType::ConGeneral);

        // set constraint lower bounds to zero for all variables
        setConLoBnds(0.0);

        // set constraint upper bounds
        setConUpBnds(0, 0.0);
        setConUpBnds(1, KTR_INFBOUND);
    }

  public:
      // constructor: pass number of variables and constraints to base class.
      // 3 variables, 2 constraints.
      ProblemExample() : KTRProblem(3, 2) {
          // set problem properties in constructor
          setObjectiveProperties();
          setVariableProperties();
          setConstraintProperties();
      }

      // Objective and constraint evaluation function
      // overrides KTRIProblem class
      double evaluateFC(
          const std::vector<double>& x,
          std::vector<double>& c,
          std::vector<double>& objGrad,
          std::vector<double>& jac) {

          // constraints
          c[0] = 8.0e0*x[0] + 14.0e0*x[1] + 7.0e0*x[2] - 56.0e0;
          c[1] = x[0] * x[0] + x[1] * x[1] + x[2] * x[2] - 25.0e0;

          // return objective function value
          return 1000 - x[0] * x[0] - 2.0e0*x[1] * x[1] - x[2] * x[2]
              - x[0] * x[1] - x[0] * x[2];
      }
  };

  int main(int argc, char *argv[]) {
      // Create a problem instance.
      ProblemExample* problem = new ProblemExample();

      // Create a solver - optional arguments: use numerical derivative evaluation.
      knitro::KTRSolver solver(problem, KTR_GRADOPT_FORWARD, KTR_HESSOPT_BFGS);

      int solveStatus = solver.solve();

      if (solveStatus != 0) {
          std::cout << std::endl;
    std::cout << "Knitro failed to solve the problem, final status = ";
          std::cout << solveStatus << std::endl;
      }
      else {
          std::cout << std::endl << "Knitro successful, objective is = ";
          std::cout << solver.getObjValue() << std::endl;
      }

      return 0;
  }

This is similar to the callable library example. The problem definition is contained in a class definition and is simpler. Variable and constraint properties can be defined more compactly; memory for the problem characteristics does not need to be allocated by the user; and the Jacobian sparsity pattern is automatically defined as a full matrix because no Jacobian non-zero size is provided.

The Knitro solver functions are called from the KTRSolver class. Like the callable library, the object-oriented interface does not provide automatic derivatives. Derivatives can be computed manually and defined in the KTRProblem class. This is covered in the chapter on Derivatives.

The above example can be compiled and linked against Knitro, and produces the same output as the callable library output. As in the callable library, this requires more problem definition than AMPL, such as defining the variable and constraint types. The object-oriented interface provide ease-of-use over the callable library with similar functionality and performance.

Further information

Another chapter of this documentation is dedicated to the object-oriented interface (Object-oriented interface reference). The reference manual chapter on the callable library (Callable library API reference) provides information on the callable library underlying the object-oriented interface. This section provides a comprehensive documentation of the Knitro callable library functions, which are accessible through methods of the KTRSolver class.

Finally, the source code for the object-oriented interface is provided as a reference. The .h header files for the C++ interface document the interface functionality.

Additional examples

More examples using the object-oriented interface are provided in the examples/C++, examples/CSharp and examples/Java directories of the Knitro distribution.