14. API developer guidelines


The purpose of this chapter is to present some guidelines for developing an application which uses the MOSEK API.

14.1. Turn on logging

While developing a new application it is beneficial to turn on logging so that error and diagnostics messages are displayed.

Using the MSK_linkfiletotaskstream function a file can be linked to a task stream. This implies that all messages sent to a task stream are also written to a file. As an example consider the code fragment

MSK_linkfiletotaskstream(task,MSK_STREAM_LOG ,"moseklog.txt");

which shows how to link the file moseklog.txt to the log stream.

It is also possible to link a custom function to a stream using the MSK_linkfunctotaskstream function.

More log information can be obtained by modifying one or more of the parameters:

By default MOSEK will reduce the amount of log information after the first optimization on a given task. To get full log output on subsequent optimizations set:

MSK_IPAR_LOG_CUT_SECOND_OPT 0

14.2. Turn on data checking

In the development phase it is useful to use the parameter setting

MSK_IPAR_DATA_CHECK MSK_ON

which forces MOSEK to check the input data. For instance, MOSEK looks for NANs in double numbers and outputs a warning if any are found.

14.3. Debugging an optimization task

If something is wrong with a problem or a solution, one option is to output the problem to an OPF file and inspect it by hand. Use the MSK_writedata function to write a task to a file immediately before optimizing, for example as follows:

MSK_writedata(task,"taskdump.opf");
MSK_optimize(task);

This will write the problem in task to the file taskdump.opf. Inspecting the text file taskdump.opf may reveal what is wrong in the problem setup.

14.4. Error handling

Most functions in the C API return a response code which indicates whether an error occurred. It is recommended to check to the response code and in case it is indicating an error then an appropriate action should be taken.

14.5. Fatal error handling

If MOSEK encounter a fatal error caused by either an internal bug or a user error, an exit function is called. It is possible to tell MOSEK to use a custom exit function using the MSK_putexitfunc function. The user-defined exit function will then be called if a fatal error is detected.

The purpose of an exit function is to print out a suitable message that can help diagnose the cause of the error.

14.6. Checking for memory leaks and overwrites

If you suspect that MOSEK or your own application incorrectly overwrites memory or leaks memory, we suggest you use external tools such as Purify or valgrind to pinpoint the cause of the problem.

Alternatively, MOSEK has a memory check feature which can be enabled by letting the argument dbugfile be the name of a writable file when calling MSK_makeenv. If dgbfile is valid file name, then MOSEK will write memory debug information to this file. Assuming memory debugging is turned on, MOSEK will warn about MOSEK specific memory leaks when a MOSEK environment or task is deleted.

Moreover, the functions MSK_checkmemenv and MSK_checkmemtask can be used to check the memory allocated by a MOSEK environment or task at any time. If one these functions finds that the memory has been corrupted a fatal error is generated.

14.7. Check the problem status and solution status

If a problem is primal or dual infeasible and MOSEK detects this, it is not reported as an error. Therefore, it is important to check the problem status and solution status after the optimization optimization ended using the MSK_getsolutionstatus function or the MSK_getsolutioninf. function.

14.8. Important API limitations

14.8.1. Thread safety

The MOSEK API is thread-safe provided that a task is accessed from one thread only at any time.

14.8.2. Unicoded strings

The C API supports the usage of unicoded strings. Indeed all (char *) arguments are allowed to be UTF8 encoded strings.

14.8.2.1. Limitations

Please note that the MPS and LP file formats are ASCII formats. Therefore, it might be advantageous to limit all names of constraints, variables etc. to ASCII strings.

14.9. Bug reporting

If you think MOSEK is solving your problem incorrectly, please contact MOSEK support at support@mosek.com providing a detailed description of the problem. MOSEK support may ask for the task file which is produced as follows

MSK_writedata(task,"taskfile.mbt");
MSK_optimize(task);

The task data will then be written to the taskfile.mbt file in binary form which is very useful when reproducing a problem.

Mon Sep 14 15:49:52 2009