Other programmatic interfaces

This chapter discusses interfaces to C++, C#, Java, Fortran and Python offered by the Knitro callable library.

Knitro in a C++ application

Note

C++ driver-based interface has been superseded by C++ object-oriented interface, see Object-oriented interface reference. The C++ driver and examples are not available anymore since Knitro 10.0.

Calling Knitro from a C++ application follows the same outline as a C application. The distribution provides a C++ general test harness in the directory examples/C++. In the example, optimization problems are coded as subclasses of an abstract interface and compiled as separate shared objects. A main driver program dynamically loads a problem and sets up callback mode so Knitro can invoke the particular problem’s evaluation methods. The main driver can also use Knitro to conveniently check partial derivatives against finite-difference approximations. It is easy to add more test problems to the test environment.

Knitro in a C# application

Calling Knitro from a C# application is similar to using the object-oriented interface in C++. The primary difference between the C++ and C# version of the object-oriented interface is in the syntax and function name capitalization. The C# function names are capitalized, and the functions use IList<> (implemented as List<>) for function arguments and return values.

The C# object-oriented interface requires .NET Version 4.0 and up. The interface uses P/Invoke to call the C Knitro callable library and convert data and function signatures between C# and C, and uses knitro.h and the knitro.dll dynamic library.

Examples of problem definitions and Knitro callbacks in C# can be found in the example folders distributed with Knitro, and the source code for the interface is provided for informational purposes.

Knitro in a Java application

Calling Knitro from a Java application is similar to using the object-oriented interface in C++. The primary difference between the C++ and Java version of the object-oriented interface is in the syntax. The Java function names are capitalized, and the functions use List<> (implemented as ArrayList<>) for function arguments and return values.

The Java object-oriented interface requires Java 1.6 and up. The interface uses JNA (Java Native Access) to call the C Knitro callable library and convert data and function signatures between Java and C, and uses knitro.h and the knitro.dll dynamic library (libknitro.so on Linux; libknitro.dylib on Mac OS X).

Examples of problem definitions and Knitro callbacks in Java can be found in the example folders distributed with Knitro, and the source code for the interface is provided for informational purposes.

Knitro in a Fortran application

Calling Knitro from a Fortran application follows the same outline as a C application. The optimization problem must be defined in terms of arrays and constants that follow the old pre-Knitro 11.0 API, and then the Fortran version of KTR_init_problem() is called. Fortran integer and double precision types map directly to C int and double types.

Fortran applications require wrapper functions written in C to (1) isolate the KTR_context structure, which has no analog in unstructured Fortran, (2) convert C function names into names recognized by the Fortran linker, and (3) renumber array indices to start from zero (the C convention used by Knitro) for applications that follow the Fortran convention of starting from one. The wrapper functions can be called from Fortran with exactly the same arguments as their C language counterparts, except for the omission of the KTR_context argument.

An example Fortran program and set of C wrappers is provided in examples/Fortran. The example loads the matrix sparsity of the optimization problem with indices that start numbering from zero, and therefore requires no conversion from the Fortran convention of numbering from one. The C wrappers provided are sufficient for the simple example, but do not implement all the functionality of the Knitro callable library. Users are free to write their own C wrapper routines, or extend the example wrappers as needed.

Knitro in a Python application

Knitro provides a Python interface for the Knitro callable library functions defined in knitro.h. The Python API loads directly the Knitro library (knitro.dll on Windows; libknitro.so on Unix; libknitro.dylib on Mac OS X). With this interface, Python applications can create a Knitro solver instance and call Python methods that execute the corresponding Knitro functions. The Python form of Knitro is thread-safe, which means that a Python application can create multiple instances of a Knitro solver in different threads, each instance solving a different problem. This feature might be important in an application that is deployed on a web server. However, please note that Python interpreters are usually not thread safe so callbacks cannot be evaluated in parallel. Thus par_concurrent_evals is always initialized to 0/no in the Python interface, but may still be set to 1/yes by the user.

Calling Knitro from a Python application follows the same outline as a C application, with the same methods. C int and double types are automatically mapped into their Python counterparts (int and float). C arrays are automatically mapped into Python list types. C pointers to native C types are automatically mapped into the corresponding Python native type. Methods that accept NULL values in C also accept None values in Python.

The definition of the optimization problem is similar to the Knitro C API, building a model in pieces while providing specific structures to Knitro (e.g. linear or quadratic structures), while providing callbacks to handle general nonlinear structures. The call sequence for using Knitro is almost exactly the same as C applications that call knitro.h functions with a KN_context_ptr object. A typical sequence of function calls is as follows:

  • KN_new(): create a new Knitro solver context pointer, allocating resources.
  • KN_add_vars()/KN_add_cons()/KN_set_*bnds(): add basic problem information to Knitro.
  • KN_add_*_linear_struct()/KN_add_*_quadratic_struct(): add specific problem structures.
  • KN_add_eval_callback(): add callback for nonlinear evaluations if needed.
  • KN_set_cb_*(): set properties for nonlinear evaluation callbacks.
  • KN_set_*_param(): set user options/parameters.
  • KN_solve(): solve the problem.
  • KN_free(): delete the Knitro context pointer, releasing allocated resources.

A major difference between the C and Python APIs is the handling of function return codes. In C, Knitro functions always return an integer code, which is 0 in case of success and non-zero in case of error. C users have to check the return code to make sure that each function was executed properly. In Python, Knitro functions raise Python errors in case of failure to execute the function. Some functions do not return anything (such as KN_set_*_param()) and some return the expected output (such as KN_get_*_param()).

Python functions can be provided as callbacks for Knitro as long as they follow the corresponding callback function prototypes (defined in knitro.h). Although the Python language makes it unnecessary, Python objects may be passed to the callback function through the userParams argument.

The Numpy module is also supported by the additional module knitroNumPy.py file and allows the use of Numpy arrays instead of Python lists. Take a look at sample program exampleNLP1NumPy.py that illustrates the use of Numpy.

The Knitro Python API supports Python versions 2.7 and 3.6.