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

The C++ interface is built on top of the Knitro C API Calling Knitro from a C++ application follows a similar outline as a C application, but uses an object-oriented framework. The Knitro distribution provides many examples of formulating and solving problems using the object-oriented C++ interface in the directory examples/C++. For more details regarding calling Knitro from C++, see Object-oriented interface reference.

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.8 and up. The interface uses BridJ, a Java native interoperability library, 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 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 List<> for function arguments and return values.

In the problem evaluation callbacks (KNEvalFCCallback, KNEvalGACallback, KNEvalHCallback, KNEvalHVCallback, KNEvalRsdCallback, KNEvalRsdJacCallback), in KNMSInitPtCallback and in KNUserCallback, the functions use IList<> (ReadOnlyCollection<> for read-only data) for function arguments.

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 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 C callable library API, and then the Fortran version of the C API functions should be 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 KN_context and CB_context structures, which have no analog in unstructured Fortran, (2) convert C function names into names recognized by the Fortran linker, and (3) possibly renumber array indices to start from zero (the C convention used by Knitro) for applications that follow the Fortran convention of starting from one. Generally the wrapper functions can be called from Fortran with exactly the same arguments as their C language counterparts, except for the omission of any KN_context and CB_context arguments.

Several example Fortran programs and a set of C wrappers are provided in examples/Fortran. The C wrappers provided allow the user to specify either 0-based or 1-based array indexing. When using 1-based indexing, the C wrappers will automatically make the conversion to 0-based indexing as required by the Knitro API. The provided C wrappers cover most of the important API functions available in Knitro, but do not currently 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 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.