External Language Interfaces

To facilitate the development of other model language interfaces, a quite simple "eXternal Language Interface" (XLI) has been defined, which allows lp_solve to be dynamically configured (at run-time) to use alternative means to read and write the MIP model or write a solution file in a specific format. lp_solve has several build-in interfaces to models: mps, lp. XLI allows implementing a custom reader and writer for other model layouts and a solution layout.
This feature again gives a unique flexibility and openness to the user and developer community that we have quite some expectations for.
If you write your own XLI, we would be glad if you would share your code with the lp_solve community. We are very interested in providing as many different XLIs as possible to the community.

Under Windows, an XLI is provided as DLL (xli_*.dll), under UNIX/LINUX as a dynamic linked library (libxli_*.so). These libraries are loaded/linked at runtime with lp_solve.

Under Unix/Linux it is standard that a library has the lib prefix and a .so postfix.
For example libxli_MathProg.so
Under Windows there is no prefix and the postfix is .dll
For example xli_MathProg.dll

To make the calling structure for XLIs uniform across different types of OS, lp_solve automatically adds the prefix and postfix if not provided. So for example under all platforms, the MathProg XLI may be referenced as xli_MathProg. It is advised to call the XLIs as such.

To locate the XLI on the file system, the following search order is used if no path is provided:

Windows

1. Current directory.
2. A semi-colon-separated (;) list of directories in the user's PATH environment variable.

Unix/Linux

1. A colon-separated (:) list of directories in the user's LD_LIBRARY_PATH environment variable.
2. The list of libraries specified in /etc/ld.so.cache (which is generated from /etc/ld.so.conf).
3. /lib, followed by /usr/lib. Note the order here; this is the reverse of the order used by the old a.out loader. The old a.out loader, when loading a program, first searched /usr/lib, then /lib (see the man page ld.so(8)). This shouldn't normally matter, since a library should only be in one or the other directory (never both), and different libraries with the same name are a disaster waiting to happen.

Note again that this search path is only used if no path is specified for the XLI.

Using an XLI with the lp_solve stand-alone program

The lp_solve program provides a way to specify an XLI for reading a model, an XLI for writing the model and an XLI for writing the solution file. These can be different so that a model in one format can be converted to another format. It is still possible to both read and write the models with the build-in formats (mps, lp) and you can combine with the XLI.

Read a model

With the lp_solve program, to set the XLI to read the model, use the option
-rxli xliname filename

filename is the name (with optional path) of the model name to read. If no path is specified, the file is read from the current directory.

Depending on the XLI, an optional data file name can be provided. Use the option
-rxlidata datafilename

For example for the MathProg XLI, there is a possible optional datafilename containing the data. Note that this name may not start with a minus sign (-)

Depending on the XLI, options can be provided to change the behaviour of the routine. Use the option
-rxliopt "options"

So the following commands are valid for both Windows and Unix/Linux:

lp_solve -rxli xli_MathProg input.mod -rxlidata input.dat
lp_solve -rxli ./xli_MathProg input.mod -rxlidata input.dat

The latter makes sure that the XLI is searched in the current directory, especially for Unix/Linux.

Write a model

With the lp_solve program, to set the XLI to write the model, use the option
-wxli xliname filename

filename is the name (with optional path) of the model name to write. If no path is specified, the file is written in the current directory.

Depending on the XLI, options can be provided to change the behaviour of the routine. Use the option
-wxliopt "options"

So the following commands are valid for both Windows and Unix/Linux:

lp_solve input.lp -wxli xli_MathProg output.mod
lp_solve input.lp -wxli ./xli_MathProg output.mod

The latter makes sure that the XLI is searched in the current directory, especially for Unix/Linux.

Write a solution

With the lp_solve program, to set the XLI to write the solution, use the option
-wxlisol xliname filename

filename is the name (with optional path) of the solution name to write. If no path is specified, the file is written in the current directory.

Depending on the XLI, options can be provided to change the behaviour of the routine. Use the option
-wxlisolopt "options"

So the following commands are valid for both Windows and Unix/Linux:

lp_solve -rxli xli_DIMACS maxflow.net -wxlisol xli_DIMACS maxflow.sol
lp_solve -rxli ./xli_MathProg maxflow.net -wxlisol xli_DIMACS maxflow.sol

The latter makes sure that the XLI is searched in the current directory, especially for Unix/Linux.

Using an XLI from the lpsolve API

Read a model

The read_XLI reads a model via an XLI.
See the API call for its usage.

Write a model

To write a model, two API calls are needed:

First use set_XLI to set the XLI library
See the API call for its usage.

Then use write_XLI to write the model.
See the API call for its usage. Note that the last argument, results must FALSE.

Write a solution

To write a model, two API calls are needed:

First use set_XLI to set the XLI library
See the API call for its usage.

Then use write_XLI to write the model.
See the API call for its usage. Note that the last argument, results must TRUE.

Creating an XLI

This section is only for people who will create their own XLI because you have a model file type that is not supported by lp_solve. The developers would appreciate it if you would make this XLI public.

To create your own XLI, you have to create a DLL/shared library that implements the following routines:

lp_XLI1.c must be included at the beginning of the source file. This to include an extra routine xli_compatible needed by the lpsolve library to check the compatibility.

If you want to create XLIs yourself, make sure that under Windows, you use 8 byte alignments. This is needed for the XLIs to work correctly with the general distribution of lp_solve and also to make sharing XLIs as uncomplicated as possible. If not, it will likely crash. It doesn't matter which calling convention is used to compile the library. The XLI_CALLMODEL directive makes sure that the calling convention of the needed routines is always ok independent of the calling convention specified in the project.
Also under windows, a definition file must be added. If this is not done, it will not work. The definition file should have extension .def and contain the following:

EXPORTS
  xli_compatible           @1
  xli_name                 @2
  xli_readmodel            @3
  xli_writemodel           @4

The definition file must be added to the project. How to do this depends on the version.
For Visual Studio 6: Project, Add to Project, Files, Files of type: Definition files (.def) and choose the created .def file
For Visual Studio .NET: Project, Properties, Linker, Input, Module Definition file. There you enter the name (with optional path) of the .def file.

XLI prototype

/* Generic include libraries */
#include <malloc.h>
#include <string.h>
#include "lp_lib.h"
#ifdef FORTIFY
# include "lp_fortify.h"
#endif

/* Include routines common to language interface implementations */

#include "lp_XLI1.c"

char * XLI_CALLMODEL xli_name(void)
{
  return("XLI_xxx v1.0" );  /* return the name and version */
}

MYBOOL XLI_CALLMODEL xli_readmodel(lprec *lp, char *model, char *data, char *options, int verbose)
{
  MYBOOL status = FALSE;

  /* implement the code here to read the model */

  return(status); /* status says if the model could be read or not. TRUE is ok, FALSE is not ok */
}

MYBOOL XLI_CALLMODEL xli_writemodel(lprec *lp, char *filename, char *options, MYBOOL results)
{
  MYBOOL status = FALSE;

  /* implement the code here to write the model */

  return( status ); /* status says if the model could be written or not. TRUE is ok, FALSE is not ok */
}

Working example:

/*  Modularized external language interface module - w/interface for lp_solve v5.0+
   ----------------------------------------------------------------------------------
    Author:        Peter Notebaert
    Contact:       lpsolve@peno.be
    License terms: LGPL.

    Template used:
    Requires:

    Release notes:
    v1.0.0  28 June 2004        First implementation.

   ---------------------------------------------------------------------------------- */

/* Generic include libraries */
#include <malloc.h>
#include <string.h>
#include "lp_lib.h"

/* Include libraries for this language system */
#include <math.h>

#ifdef FORTIFY
# include "lp_fortify.h"
#endif

/* Include routines common to language interface implementations */
#include "lp_XLI1.c"

char * XLI_CALLMODEL xli_name(void)
{
  return( "xli_demo v1.0" );
}

MYBOOL XLI_CALLMODEL xli_readmodel(lprec *lp, char *model, char *data, char *options, int verbose)
{
  MYBOOL status = FALSE;
  REAL row[1+2]; /* must be 1 more then number of columns ! */

  lp->add_columnex(lp, 0, NULL, NULL); /* add empty column */
  lp->add_columnex(lp, 0, NULL, NULL); /* add empty column */
  lp->set_add_rowmode(lp, TRUE);
  row[1] = 1.0;
  row[2] = 2.0;
  lp->add_constraint(lp, row, GE, 3.0); /* constructs the row: +v_1 +2 v_2 >= 3 */
  lp->set_add_rowmode(lp, FALSE);
  status = TRUE;

  return(status);
}

MYBOOL XLI_CALLMODEL xli_writemodel(lprec *lp, char *filename, char *options, MYBOOL results)
{
  if (!results)
    return(lp->write_lp(lp, filename));
  else {
    lp->print_objective(lp);
    lp->print_solution(lp, 1);
    lp->print_constraints(lp, 1);
    return(TRUE);
  }
}

EXPORTS
  xli_compatible           @1
  xli_name                 @2
  xli_readmodel            @3
  xli_writemodel           @4

This example is not very practical. It is only useful for demonstration purposes. Let's assume that the name of this library is xli_demo.
xli_readmodel creates the model. It doesn't even read from a file in this example. xli_writemodel uses write_lp to write the model to filename and some print_* functions to print the solution.

This XLI can be called from lp_solve via the following syntax:

lp_solve -S0 -rxli xli_demo "" -wxli xli_demo output.txt -wxlisol xli_demo ""

An empty ("") filename is provided because it isn't used by this demo. This command will create a file output.txt with contents:

/* Objective function */
min: ;

/* Constraints */
+C1 +2 C2 >= 3;

Because we didn't provide the option -parse_only, the model is also solved. However the lp_solve option -S0 disables showing the results. Results are generated via the -wxlisol option:

Value of objective function: 0

Actual values of the variables:
C1                              3
C2                              0

Actual values of the constraints:
R1                              3