View source for GLPK/Using the GLPK callable library

This page describes issues related to the use of GLPK as a callable library. As such this page should be primarily of interest to developers writing application programs in C or C++ and making use of the GLPK application programming interface (API).

== Official documentation ==

The [[GLPK/Literature#Official_GLPK_documentation|official GLPK documentation]] file <tt>doc/glpk.pdf</tt> contains a '''full reference''' for the GLPK API. That material is therefore not repeated here. See [[GLPK/Obtaining_GLPK|obtaining GLPK]].

== Short example ==

The following API example implements the linear constrained optimization model:

{|
| maximize || <math>0.6 x_1 + 0.5 x_2</math>
|-
| subject to || <math>x_1 + 2 x_2 \le 1</math>
|-
|            || <math>3 x_1 + x_2 \le 2</math>
|}

<syntaxhighlight lang="c">
/* short.c */

#include <stdio.h>            /* C input/output                       */
#include <stdlib.h>           /* C standard library                   */
#include <glpk.h>             /* GNU GLPK linear/mixed integer solver */

int main(void)
{
  /* declare variables */
  glp_prob *lp;
  int ia[1+1000], ja[1+1000];
  double ar[1+1000], z, x1, x2;
  /* create problem */
  lp = glp_create_prob();
  glp_set_prob_name(lp, "short");
  glp_set_obj_dir(lp, GLP_MAX);
  /* fill problem */
  glp_add_rows(lp, 2);
  glp_set_row_name(lp, 1, "p");
  glp_set_row_bnds(lp, 1, GLP_UP, 0.0, 1.0);
  glp_set_row_name(lp, 2, "q");
  glp_set_row_bnds(lp, 2, GLP_UP, 0.0, 2.0);
  glp_add_cols(lp, 2);
  glp_set_col_name(lp, 1, "x1");
  glp_set_col_bnds(lp, 1, GLP_LO, 0.0, 0.0);
  glp_set_obj_coef(lp, 1, 0.6);
  glp_set_col_name(lp, 2, "x2");
  glp_set_col_bnds(lp, 2, GLP_LO, 0.0, 0.0);
  glp_set_obj_coef(lp, 2, 0.5);
  ia[1] = 1, ja[1] = 1, ar[1] = 1.0; /* a[1,1] = 1 */
  ia[2] = 1, ja[2] = 2, ar[2] = 2.0; /* a[1,2] = 2 */
  ia[3] = 2, ja[3] = 1, ar[3] = 3.0; /* a[2,1] = 3 */
  ia[4] = 2, ja[4] = 2, ar[4] = 1.0; /* a[2,2] = 1 */
  glp_load_matrix(lp, 4, ia, ja, ar);
  /* solve problem */
  glp_simplex(lp, NULL);
  /* recover and display results */
  z = glp_get_obj_val(lp);
  x1 = glp_get_col_prim(lp, 1);
  x2 = glp_get_col_prim(lp, 2);
  printf("z = %g; x1 = %g; x2 = %g\n", z, x1, x2);
  /* housekeeping */
  glp_delete_prob(lp);
  glp_free_env();
  return 0;
}
</syntaxhighlight>

Production code would, of course, check the return value from function <tt>glp_simplex</tt> and react accordingly.

=== Linux ===

These instructions relate to Linux (the details for other operating systems should be similar).

Build <tt>short</tt> using your system compiler, in this case GNU GCC:

<syntaxhighlight lang="bash">
$ gcc -Wall short.c -lglpk -o short
</syntaxhighlight>

Run the resulting binary:

<pre>
$ ./short 
*     0: obj =   0.000000000e+00  infeas =  0.000e+00 (0)
*     2: obj =   4.600000000e-01  infeas =  0.000e+00 (0)
OPTIMAL SOLUTION FOUND
z = 0.46; x1 = 0.6; x2 = 0.2
</pre>

You should obtain <math>x_1 = 0.6</math> and <math>x_2 = 0.2</math> as part of the terminal output from your program.

The GLPK runtime reporting format (the lines starting *) are covered in the callable library part of the [[GLPK/Literature#Official_GLPK_documentation|official GLPK documentation]] and also [[GLPK/Terminal_output|here]].

The same problem is coded in [[GLPK/GMPL_(MathProg)#Short_example|MathProg]].

== Submitting patches ==

GLPK patches are best submitted by posting them to the most appropriate of the two [[GLPK/Introduction#The_GLPK_project|GLPK mailing lists]].
Note that the GLPK project does not maintain a web-based [[w:Source_code_repository|source code repository]]. 

If creating source file patches, please refrain from using tabs and restrict line lengths to 72&nbsp;chars.

== Thread safety ==

GLPK is ''not inherently'' [[w:Thread_safety|thread safe]]. Please consult the GLPK newsgroup archives for more information about the use of GLPK APIs under concurrent execution. In particular, see this [http://lists.gnu.org/archive/html/help-glpk/2010-04/msg00031.html discussion] and, more latterly, this [http://lists.gnu.org/archive/html/help-glpk/2012-12/msg00027.html discussion].

If your problem involves multiple LPs (or can be structured thus), then consider running each LP as a separate processes.  This makes sense only for multi-core hardware.

== Reenterability ==

Andrew [http://lists.gnu.org/archive/html/help-glpk/2012-12/msg00044.html said] that reenterability 
is a property of the code that allows running several instances of
the same program in parallel using the only copy of that program in the
memory. This property requires the program not to alter its own code
and statically allocated data.
See also Wikipedia definition of [[w:Reentrancy (computing)|reentrancy]].

The glpk code is reenterable except two internal routines tls_set_ptr
and tls_get_ptr (see src/env/tls.c). In a reenterable version of glpk
these two routines should be replaced with platform-specific ones.

The current version of tls.c is not reentrant:
<syntaxhighlight lang="c">
static void *tls = NULL;

void tls_set_ptr(void *ptr)
{     tls = ptr;
      return;
}

void *tls_get_ptr(void)
{     void *ptr;
      ptr = tls;
      return ptr;
}
</syntaxhighlight>

Andrew [http://lists.gnu.org/archive/html/help-glpk/2010-04/msg00043.html suggested] reentrant version: 
<syntaxhighlight lang="c">
#include <pthread.h>
pthread_key_t _glp_pth_key;
/* must be initialized in the main program */

void tls_set_ptr(void *ptr)
{     pthread_setspecific(_glp_pth_key, ptr);
      return;
}

void *tls_get_ptr(void)
{     void *ptr;
      ptr = pthread_getspecific(_glp_pth_key);
      return ptr;
}
</syntaxhighlight>

Latest GCC compilers have storage class keyword [http://gcc.gnu.org/onlinedocs/gcc-4.4.3/gcc/Thread_002dLocal.html __thread ]:
<syntaxhighlight lang="c">
static __thread void *tls = NULL;

void tls_set_ptr(void *ptr)
{     tls = ptr;
}

void *tls_get_ptr(void)
{     return tls;
}
</syntaxhighlight>

Visual Studio 2005 compiler has similar storage-class modifier [http://msdn.microsoft.com/en-us/library/9w1sdazb%28v=vs.80%29.aspx __declspec( thread )]:
<syntaxhighlight lang="c">
static __declspec( thread ) void *tls = NULL;

void tls_set_ptr(void *ptr)
{     tls = ptr;
}

void *tls_get_ptr(void)
{     return tls;
}
</syntaxhighlight>

[https://github.com/PetterS/glpk/commit/3f49e9060eeaf9a502a5c550b19eecc87632811b This commit] makes the library re-rentrant on Windows and Linux.

== Deprecated GLPK APIs ==

A number of GLPK APIs have been recently deprecated and replaced. Unless otherwise stated, the <tt>lpx_</tt> prefix has been replaced with a <tt>glp_</tt> prefix. In all cases, developers should double check with the official documentation.

As of version 4.49, developers ''must'' migrate to these new APIs.
The old API routines, whose names begin with <tt>lpx_</tt>, have now been removed from the GLPK API and are no longer available.

{| class=wikitable
! GLPK !! Deprecated                   !! Comment
|-
| 4.16 || <tt>lpx_add_cols</tt>        ||
|-
|      || <tt>lpx_add_rows</tt>        ||
|-
|      || <tt>lpx_create_index</tt>    ||
|-
|      || <tt>lpx_create_prob</tt>     ||
|-
|      || <tt>lpx_del_cols</tt>        ||
|-
|      || <tt>lpx_del_rows</tt>        ||
|-
|      || <tt>lpx_delete_index</tt>    ||
|-
|      || <tt>lpx_delete_prob</tt>     ||
|-
|      || <tt>lpx_find_col</tt>        ||
|-
|      || <tt>lpx_find_row</tt>        ||
|-
|      || <tt>lpx_get_col_dual</tt>    ||
|-
|      || <tt>lpx_get_col_kind</tt>    ||
|-
|      || <tt>lpx_get_col_lb</tt>      ||
|-
|      || <tt>lpx_get_col_name</tt>    ||
|-
|      || <tt>lpx_get_col_prim</tt>    ||
|-
|      || <tt>lpx_get_col_stat</tt>    ||
|-
|      || <tt>lpx_get_col_type</tt>    ||
|-
|      || <tt>lpx_get_col_ub</tt>      ||
|-
|      || <tt>lpx_get_mat_col</tt>     ||
|-
|      || <tt>lpx_get_mat_row</tt>     ||
|-
|      || <tt>lpx_get_num_bin</tt>     ||
|-
|      || <tt>lpx_get_num_cols</tt>    ||
|-
|      || <tt>lpx_get_num_int</tt>     ||
|-
|      || <tt>lpx_get_num_nz</tt>      ||
|-
|      || <tt>lpx_get_num_rows</tt>    ||
|-
|      || <tt>lpx_get_obj_coef</tt>    ||
|-
|      || <tt>lpx_get_obj_dir</tt>     ||
|-
|      || <tt>lpx_get_obj_name</tt>    ||
|-
|      || <tt>lpx_get_obj_val</tt>     ||
|-
|      || <tt>lpx_get_prob_name</tt>   ||
|-
|      || <tt>lpx_get_row_dual</tt>    ||
|-
|      || <tt>lpx_get_row_lb</tt>      ||
|-
|      || <tt>lpx_get_row_name</tt>    ||
|-
|      || <tt>lpx_get_row_prim</tt>    ||
|-
|      || <tt>lpx_get_row_stat</tt>    ||
|-
|      || <tt>lpx_get_row_type</tt>    ||
|-
|      || <tt>lpx_get_row_ub</tt>      ||
|-
|      || <tt>lpx_ipt_col_dual</tt>    ||
|-
|      || <tt>lpx_ipt_col_prim</tt>    ||
|-
|      || <tt>lpx_ipt_obj_val</tt>     ||
|-
|      || <tt>lpx_ipt_row_dual</tt>    ||
|-
|      || <tt>lpx_ipt_row_prim</tt>    ||
|-
|      || <tt>lpx_load_matrix</tt>     ||
|-
|      || <tt>lpx_mip_col_val</tt>     ||
|-
|      || <tt>lpx_mip_obj_val</tt>     ||
|-
|      || <tt>lpx_mip_row_val</tt>     ||
|-
|      || <tt>lpx_set_col_bnds</tt>    ||
|-
|      || <tt>lpx_set_col_kind</tt>    ||
|-
|      || <tt>lpx_set_col_name</tt>    ||
|-
|      || <tt>lpx_set_col_stat</tt>    ||
|-
|      || <tt>lpx_set_mat_col</tt>     ||
|-
|      || <tt>lpx_set_mat_row</tt>     ||
|-
|      || <tt>lpx_set_obj_coef</tt>    ||
|-
|      || <tt>lpx_set_obj_dir</tt>     ||
|-
|      || <tt>lpx_set_obj_name</tt>    ||
|-
|      || <tt>lpx_set_prob_name</tt>   ||
|-
|      || <tt>lpx_set_row_bnds</tt>    ||
|-
|      || <tt>lpx_set_row_name</tt>    ||
|-
|      || <tt>lpx_set_row_stat</tt>    ||
|-
| 4.18 || <tt>lpx_simplex</tt>         || 
|-
| 4.20 || <tt>lpx_integer</tt>         || see:&nbsp;<tt>glp_iotopt</tt>
|-
| 4.29 || <tt>lpx_read_mps</tt>        || 
|-
|      || <tt>lpx_read_freemps</tt>    || 
|-
|      || <tt>lpx_write_mps</tt>       || 
|-
|      || <tt>lpx_write_freemps</tt>   || 
|-
|      || <tt>lpx_read_cpxlp</tt>      || 
|-   
|      || <tt>lpx_write_cpxlp</tt>     || 
|-
| 4.31 || <tt>lpx_scale_prob</tt>      || 
|-
|      || <tt>lpx_std_basis</tt>       || 
|-
|      || <tt>lpx_adv_basis</tt>       || 
|-
|      || <tt>lpx_cpx_basis</tt>       || 
|-
| 4.32 || <tt>lpx_integer</tt>         || 
|-
|      || <tt>lpx_intopt</tt>          || 
|-
| 4.33 || <tt>lpx_exact</tt>           || 
|-
|      || <tt>lpx_get_ray_info</tt>    || see: <tt>glp_unbnd_ray</tt>
|-
|      || <tt>lpx_interior</tt>        || 
|-
|      || <tt>lpx_read_model</tt>      || 
|-
| 4.37 || <tt>lpx_print_sol</tt>       || 
|-
|      || <tt>lpx_print_ips</tt>       || see: <tt>lpx_print_ipt</tt>
|-
|      || <tt>lpx_print_mip</tt>       || 
|-
|      || <tt>lpx_print_prob</tt>      || see: <tt>glp_print_lp</tt>
|-
| 4.41 || <tt>lpx_transform_row</tt>   || 
|-
|      || <tt>lpx_transform_col</tt>   || 
|-
|      || <tt>lpx_prim_ratio_test</tt> || 
|-
|      || <tt>lpx_dual_ratio_test</tt> || 
|-
| 4.42 || <tt>lpx_print_sens_bnds</tt> || see: <tt>glp_print_ranges</tt>
|-
| 4.49 || <tt>lpx_check_kkt</tt>       || see: <tt>glp_check_kkt</tt>
|}

== Recently added GLPK APIs ==

New APIs get added to GLPK from time to time. 
These are listed below.
If appropriate, a new API may also be exposed by an associated GLPSOL command-line option in the same or a subsequent release.

''Note'': this information only dates back as far as release 4.31 in February 2007.

{| class=wikitable
|-
!GLPK !! Added                        !! Comment
|-
| 4.49 || <tt>glp_check_kkt</tt>       || replaces <tt>lpx_check_kkt</tt>
|-
|      || <tt>glp_mincost_relax4</tt>  || solve minimum cost flow problem using RELAX-IV code
|-
| 4.47 || <tt>glp_intfeas1</tt>        || solve CNF-SAT problem instance with GLPK code (tentative)
|-
| 4.46 || <tt>glp_read_cnfsat</tt>     || read CNF-SAT problem data in DIMACS format
|-
|      || <tt>glp_write_cnfsat</tt>    || write CNF-SAT problem data in DIMACS format
|-
|      || <tt>glp_check_cnfsat</tt>    || check CNF-SAT problem instance
|-
|      || <tt>glp_minisat1</tt>        || solve CNF-SAT problem instance with MiniSat
|-
| 4.44 || <tt>glp_cpp</tt>             || solve critical path problems
|-
| 4.42 || <tt>glp_check_dup</tt>       || check for duplicate elements in sparse matrix
|-
|      || <tt>glp_sort_matrix</tt>     || sort elements of the constraint matrix
|-
|      || <tt>glp_read_prob</tt>       || read problem data in GLPK format
|-
|      || <tt>glp_write_prob</tt>      || write problem data in GLPK format
|-
|      || <tt>glp_analyze_bound</tt>   || analyze active bound of non-basic variable
|-
|      || <tt>glp_analyze_coef</tt>    || analyze objective coefficient at basic variable
|-
|      || <tt>glp_print_ranges</tt>    || print sensitivity analysis report
|-
| 4.41 || <tt>glp_transform_row</tt>   || transform explicitly specified row
|-
|      || <tt>glp_transform_col</tt>   || transform explicitly specified column
|-
|      || <tt>glp_prim_rtest</tt>      || perform primal ratio test
|-
|      || <tt>glp_dual_rtest</tt>      || perform dual ratio test
|-
| 4.40 || <tt>glp_del_vertices</tt>    || remove vertices from graph
|-
|      || <tt>glp_del_arc</tt>         || remove arc from graph
|-
|      || <tt>glp_wclique_exact</tt>   || find maximum weight clique with the exact algorithm developed by Prof P Ostergard
|-
|      || <tt>glp_read_ccdata</tt>     || read graph in DIMACS clique/coloring format
|-
|      || <tt>glp_write_ccdata</tt>    || write graph in DIMACS clique/coloring format
|-
| 4.39 || <tt>glp_warm_up</tt>         || "warm up" LP basis
|-
|      || <tt>glp_set_vertex_name</tt> || assign (change) vertex name
|-
|      || <tt>glp_create_v_index</tt>  || create vertex name index
|-
|      || <tt>glp_find_vertex</tt>     || find vertex by its name
|-
|      || <tt>glp_delete_v_index</tt>  || delete vertex name index
|-
|      || <tt>glp_read_asnprob</tt>    || read assignment problem data in DIMACS format
|-
|      || <tt>glp_write_asnprob</tt>   || write assignment problem data in DIMACS format
|-
|      || <tt>glp_check_asnprob</tt>   || check correctness of assignment problem data
|-
|      || <tt>glp_asnprob_lp</tt>      || convert assignment problem to LP
|-
|      || <tt>glp_asnprob_okalg</tt>   || solve assignment problem with the out-of-kilter algorithm
|-
|      || <tt>glp_asnprob_hall</tt>    || find bipartite matching of maximum cardinality with Hall's algorithm
|-
| 4.37 || <tt>glp_print_sol</tt>       || write basic solution in printable format
|-
|      || <tt>glp_print_ipt</tt>       || write interior-point solution in printable format
|-
|      || <tt>glp_print_mip</tt>       || write MIP solution in printable format
|-
|      || <tt>glp_read_graph</tt>      || read (di)graph from plain text file
|-
|      || <tt>glp_write_graph</tt>     || write (di)graph to plain text file
|-
|      || <tt>glp_weak_comp</tt>       || find all weakly connected components
|-
|      || <tt>glp_strong_comp</tt>     || find all strongly connected components
|-
| 4.36 || <tt>glp_mincost_okalg</tt>   || find minimum-cost flow with out-of-kilter algorithm
|-
|      || <tt>glp_maxflow_ffalg</tt>   || find maximal flow with Ford-Fulkerson algorithm
|-
| 4.35 || <tt>glp_create_graph</tt>    || create graph
|-
|      || <tt>glp_set_graph_name</tt>  || assign (change) graph name
|-
|      || <tt>glp_add_vertices</tt>    || add new vertices to graph
|-
|      || <tt>glp_add_arc</tt>         || add new arc to graph
|-
|      || <tt>glp_erase_graph</tt>     || erase graph content
|-
|      || <tt>glp_delete_graph</tt>    || delete graph
|-
|      || <tt>glp_read_mincost</tt>    || read minimum cost flow problem data in DIMACS format
|-
|      || <tt>glp_write_mincost</tt>   || write minimum cost flow problem data in DIMACS format
|-
|      || <tt>glp_mincost_lp</tt>      || convert minimum cost flow problem to LP
|-
|      || <tt>glp_netgen</tt>          || Klingman's network problem generator
|-
|      || <tt>glp_gridgen</tt>         || grid-like network problem generator
|-
|      || <tt>glp_read_maxflow</tt>    || read maximum flow problem data in DIMACS format
|-
|      || <tt>glp_write_maxflow</tt>   || write maximum flow problem data in DIMACS format
|-
|      || <tt>glp_maxflow_lp</tt>      || convert maximum flow problem to LP
|-
|      || <tt>glp_rmfgen</tt>          || Goldfarb's maximum flow problem generator
|-
| 4.33 || <tt>glp_copy_prob</tt>       || copy problem object content
|-
|      || <tt>glp_exact</tt>           || solve LP in exact arithmetic (makes lpx_exact deprecated)
|-
|      || <tt>glp_get_unbnd_ray</tt>   || determine variable causing unboundedness (makes lpx_get_ray_info deprecated)
|-
|      || <tt>glp_interior</tt>        || solve LP with interior-point method (makes lpx_interior deprecated)
|-
| 4.32 || <tt>glp_ios_row_attr</tt>    || determine additional row attributes
|-
|      || <tt>glp_ios_pool_size</tt>   || determine current size of the cut pool
|-
|      || <tt>glp_ios_add_row</tt>     || add constraint to the cut pool
|-
|      || <tt>glp_ios_del_row</tt>     || delete constraint from the cut pool
|-
|      || <tt>glp_ios_clear_pool</tt>  || delete all constraints from the cut pool
|-
| 4.31 || <tt>glp_scale_prob</tt>      || automatic scaling of problem data
|-
|      || <tt>glp_std_basis</tt>       || construct standard initial LP basis
|-
|      || <tt>glp_adv_basis</tt>       || construct advanced initial LP basis
|-
|      || <tt>glp_cpx_basis</tt>       || construct Bixby's initial LP basis
|}

{{BookCat}}