                   ADDITIONAL GLPK API ROUTINES
            Supplement to GLPK User's Guide, July 2001

         Andrew Makhorin <mao@mai2.rcnet.ru, mao@gnu.org>



CONTENTS
--------

Introduction
glp_set_row_fctr() -- set row scale factor
glp_set_col_fctr() -- set column scale factor
glp_get_row_fctr() -- determine row scale factor
glp_get_col_fctr() -- determine column scale factor
glp_scale_prob() -- scale problem
glp_write_mps() -- write problem data in MPS format
glp_simplex1() -- comprehensive driver to the simplex method
glp_pivot_in() -- push auxiliary variables into the basis
glp_pivot_out() -- pull structural variables from the basis



Introduction
------------

This document is a supplement to GLPK User's Guide. It describes some
new API routines recently added to the package.

The first group is scaling routines.

Scaling a problem is replacing the constraint matrix A of original LP
problem by a new, scaled constraint matrix A' = R*A*S, where R ans S are
diagonal scaling matrices. Diagonal elements of the matrix R are called
row scale factors, diagonal elements of the matrix S are called column
scale factors. As a rule correct scaling involves improving numerical
propeties of LP problem.

Note that changing scale factors by the scaling routines doesn't affect
on numerical values of problem components (i.e. bounds of variables as
well as objective and constraints coefficients are not chaged) -- scale
factors are applied to a problem only for a time of its processing by
a solver. See also the Section 1.8 Scaling LP problem in the document
"GLPK: Implementation of the revised simplex method".

The second group is additional drivers to the simplex method.

The comprehensive driver glp_simplex1() has the following additional
features:

- starting from an advanced basis;

- choosing between primal and dual simplex on both phases I and II;

- prematurely terminating the search if either iteration limit, or time
  limit, or objective function limit is reached.

The routines glp_pivot_in() and glp_pivot_out() are basis maintaining
routines. For example, on deleting or changing rows it is desirable to
keep dual feasibility of the current basis, therefore the routine
glp_pivot_in() may be used in order to make rows, which will be deleted
or changed, entering into the basis. The routine glp_pivot_out() may be
used in the same way in order to make columns, which will be deleted or
changed, leaving the basis that allows keeping primal feasibility of the
current basis solution.

In GLPK distribution there is an non-trivial example of using these
driver routines (see the file 'sample/lpglpk30.c'). In this example
GLPK is used as a base LP solver for Concorde, a well known program for
solving Traveling Salesman Problem (TSP). For details see comments in
the file 'lpglpk30.c'.



glp_set_row_fctr() -- set row scale factor
------------------------------------------

*Synopsis*

#include "glpk.h"
void glp_set_row_fctr(LPI *lp, int i, double fctr);

*Description*

The routine glp_set_row_fctr() sets (changes) scale factor of the i-th
row specified by the parameter fctr (should be positive).

Row scale factor is an optinal quantity, which may be used by the solver
in order to scale the problem.



glp_set_col_fctr() -- set column scale factor
---------------------------------------------

*Synopsis*

#include "glpk.h"
void glp_set_col_fctr(LPI *lp, int j, double fctr);

*Description*

The routine glp_set_col_fctr() sets (changes) scale factor of the j-th
column specified by the parameter fctr (should be positive).

Column scale factor is an optional quantity, which may be used by the
solver in order to scale the problem.



glp_get_row_fctr() -- determine row scale factor
------------------------------------------------

*Synopsis*

#include "glpk.h"
double glp_get_row_fctr(LPI *lp, int i);

*Returns*

The routine glp_get_row_fctr() returns a scale factor assigned to the
i-th row.



glp_get_col_fctr() -- determine column scale factor
---------------------------------------------------

*Synopsis*

#include "glpk.h"
double glp_get_col_fctr(LPI *lp, int j);

*Returns*

The routine glp_get_col_fctr() returns a scale factor assigned to the
j-th column.



glp_scale_prob() -- scale problem
---------------------------------

*Synopsis*

#include "glpk.h"
void glp_scale_prob(LPI *lp, int how);

*Description*

The routine glp_scale_prob performs automatic scaling the problem data
depending on the parameter how:

0 - equilibration scaling;
1 - geometric mean scaling;
2 - geometric mean scaling, then equilibration scaling.

In order to scale the problem the routine uses current coefficients of
the constrint matrix.

A result of this operation are row and column scale factors that are
stored by the routine into the problem object.



glp_write_mps() -- write problem data in MPS format
---------------------------------------------------

*Synopsis*

#include "glpk.h"
int glp_write_mps(LPI *lp, char *fname, struct wmps *parm);

*Description*

The routine glp_write_mps() writes LP problem data using MPS format to
the output text file whose name is the character string parm.

The parameter parm is a pointer to the parameter block used by the
routine. It is allowed to specify NULL, in which case standard values
are used by default. If the parameter block is used, before a call to
the routine glp_write_mps() the block should be initialized by means of
the statement glp_init_wmps(parm), and the the application program can
change some of the control parameters. Description of the control
parameters used by the routine is given below.

Description of MPS format can be found in the document "GLPK User's
Guide".

*Returns*

0 - no errors;
1 - invalid control parameters;
2 - operation failed due to errors.

In case of non-zero return code the routine sends all diagnostics to
stderr.

*Control parameters*

The behavior of the routine glp_write_mps() depends on the following
control parameters, which are members of the structure wmps, pointer to
which is passed to the routine. (Initializers means standard values set
by default):

int prob_info = 1;

   If this flag is set, the routine writes several comment cards that
   contains some information about the problem. Otherwise the routine
   writes no comment cards.

int make_obj = 2;

   This parameter controls output objective function row:
   0 - never output objective function row;
   1 - always output objective function row;
   2 - output objective function row if and only if the problem has no
       free rows.

int use_names = 1;

   If this flag is set, the routine tries to generate standard 8-char
   MPS names using orifinal row and column names as templates. Otherwise
   the routine generates plain names using sequential numbers of rows
   and columns.

int one_entry = 0;

   If this flag is set, the routine keeps fields 5 and 6 empty.
   Otherwise the routine uses all fields.

int pedantic = 0;

   If this flag is set, the routine never omits column and vector names.
   Otherwise the routine omits these names every time when possible.

int skip_empty = 0;

   If this flag is set, the routine writes all columns, including empty
   ones (which have no constraint coefficients). Otherwise the routine
   writes only non-empty columns.



glp_simplex1() -- comprehensive driver to the simplex method
------------------------------------------------------------

*Synopsis*

#include "glpk.h"
int glp_simplex1(LPI *lp, struct spx1 *parm);

*Description*

The routine glp_simplex1() is a comprehensive driver to the routines
which implement components of the revised simplex method for linear
programming.

This routine obtains problem data from the problem object, which the
parameter lp points to, calls the simplex method routines to solve the
problem, and stores the computed solution back to the problem object.

The parameter parm is a pointer to the parameter block used by the
routine. It is allowed to specify NULL, in which case standard values
are used by default. If the problem is not very hard, standard default
values fit for most cases. If the parameter block is used, before a call
to the routine glp_simplex1() the block should be initialized by means
of the statement glp_init_spx1(parm), and then the application program
can change some of control parameters. Detailed description of control
parameters used by the solver is given below.

*Returns*

The routine glp_simplex1() returns one of the following codes:

 0 - no errors;
-1 - iteration limit exceeded;
-2 - time limit exceeded;
-3 - objective lower limit reached;
-4 - objective upper limit reached;
+1 - invalid control parameter;
+2 - invalid initial basis;
+3 - numerical problems with basis matrix.

Negative return codes mean that there is no error, but the solver was
not able to finish the search because of some limitation and therefore
the most recently obtained solution is reported.

*Control parameters*

The behavior of the driver glp_simplex1() depends on the following
control parameters, which are members of the structure spx1, pointer to
which is passed to the routine. (Initializers mean standard values set
by default):

int form = 1;

   This parameter specifies what form of the basis matrix should be used
   by the solver:
   0 - EFI;
   1 - RFI + Bartels & Golub updating technique;
   2 - RFI + Forrest & Tomlin updating technique.

int scale = 0;

   This parameter controls the scaling option:
   0 - do not scale the problem
   1 - scale the problem using scale factors specified in the problem
       object.

int initb = 0;

   This parameter controls the initial basis option:
   0 - use the standard basis, where all auxiliary variables are basic
       and all structural variables are non-basic;
   1 - use the basis specified in the problem object (this allows using
       an advanced basis provided by the application).

int feas = 0;

   This parameter specifies by what method the solver should search for
   primal feasible solution if the initial basis is not primal feasible:
   0 - use the primal simplex method and implicit artificial variables
       technique;
   1 - use the dual simplex method and artificial objective function
       technique.

int dual = 1;

   This parameter specifies what the solver should undertake if the
   initial basis is dual feasible:
   0 - ignore dual feasibility, i.e. search for primal feasible solution
       (phase I) and then search for optimal solution (phase II) using
       the primal simplex method;
   1 - search for optimal solution using the dual simplex method, i.e.
       skip the phase I.

int steep = 1;

   This parameter controls the pricing option (for both primal and dual
   simplex methods):
   0 - use the standard ("textbook") pricing;
   1 - use the steepest edge pricing proposed by Goldfarb and Reid.

int relax = 1;

   This parameter controls the ratio test option (for both primal and
   dual simplex methods):
   0 - use the standard ("textbook") ratio test;
   1 - use two-pass ratio test proposed by P.Harris.

int round = 1;

   This parameter controls the final solution rounding option:
   0 - keep all computed primal and dual values "as is";
   1 - replace computed primal and dual values, which are close to zero,
       by exact zeros (this rounding is performed once after the final
       solution has been obtained).

double tol_bnd = 1e-8;

   Relative tolerance which is used to see if the solution is primal
   feasible. It is not recommended to change this parameter without
   detailed understanding its purpose.

double tol_dj = 1e-7;

   Relative tolerance which is used to see if the solution is dual
   feasible. It is not recommended to change this parameter without
   detailed understanding its purpose.

double tol_piv = 1e-10;

   Relative tolerance which is used to choose the pivot element of the
   simplex table. It is not recommended to change this parameter without
   detailed understanding its purpose.

int max_iter = INT_MAX;

   Maximal allowed number of simplex iterations; if this parameter is
   zero, the solver performs no simplex iterations, but reports solution
   that corresponds to the initial basis.

int max_time = DBL_MAX;

   Maximal allowed time of computations, in seconds (fractional values
   may be used); if this parameter is zero, the solver performs
   no simplex iterations, but reports solution that corresponds to the
   initial basis.

double obj_min = -DBL_MAX, obj_max = +DBL_MAX;

   Allowed range of the objective function. The solver stops searching
   as soon as on the phase II the current value of the objective
   function becomes less than obj_min and continue decreasing or greater
   than obj_max and continue increasing. In order to avoid computing the
   objective function on each simplex iteration, the "infinte" range
   (-DBL_MAX, +DBL_MAX) should be specified.

int quiet = 0;

   This parameter controls displaying informative messages:
   0 - display all informative messages;
   1 - don't display any informative messages.

double delay = 0.0;

   Initial delay interval, in seconds. The solver doesn't display
   information about current solution the first delay seconds.

double freq = 1.0;

   Output frequency, in seconds. The solver displays information about
   current solution approx. once per freq seconds.

int iter_used;

   On entry this parameter is ignored. On exit this parameter is number
   of actually performed simplex iterations.

double time_used;

   On entry this parameter is ignored. on exit this parameter is elapsed
   time (in seconds) actually spent by the solver.



glp_pivot_in() -- push auxiliary variables into the basis
---------------------------------------------------------

*Synopsis*

#include "glpk.h"
int glp_pivot_in(LPI *lp, int flag[], struct piv1 *parm);

*Description*

The routine glp_pivot_in() is a special version of the simplex method.
It performs necessary amount of simplex iterations in order to enter
specified auxiliary variables into the basis.

On entry the current basis should be specified in the problem object lp.
On exit the problem object will contain information about the new basis
constructed by the routine.

The array flag should have at least 1+m locations, where m is number
of rows (auxiliary variables). The location flag[0] is not used. If
flag[i] (1 <= i <= m) is non-zero, the routine tries to make the i-th
auxiliary variable be basic. Otherwise, the i-th auxiliary variable is
not considered.

The parameter parm is a pointer to the parameter block used by the
routine. It is allowed to specify NULL, in which case standard values
are used by default. If the parameter block is used, before a call to
the routine glp_pivot_in() the block should be initialized by means of
the statement glp_init_piv1(parm), and the the application program can
change some of the control parameters. Description of the control
parameters used by the routine glp_pivot_in() is given below.

*Returns*

 0 - no errors;
-1 - all required auxiliary variables are basic, therefore no basis
     transformations were performed;
+1 - invalid control parameter;
+2 - invalid current basis;
+3 - some required auxiliary variable can't be made basic;
+4 - numerical problems with the basis matrix.

If the return code is non-zero, the current basis specified in the
problem object is not changed.

*Control parameters*

The behavior of the routine glp_pivot_in() depends on the following
control parameters, which are members of the structure piv11, pointer to
which is passed to the routine. (Initializers means standard values set
by default):

int form = 1;

   This parameter specifies what form of the basis matrix should be used
   by the routine:
   0 - EFI;
   1 - RFI + Bartels & Golub updating technique;
   2 - RFI + Forrest & Tomlin updating technique.

int scale = 0;

   This parameter controls the scaling option:
   0 - do not scale the constraint matrix;
   1 - scale the constraint matrix using scale factors specified in the
       problem object.

double tol = 0.01;

   A relative tolerance used to choose a pivot element of the simplex
   table. Increasing this parameter involves better numerical stability
   for expense of worse sparsity of the basis matrix and vice versa.
   This parameter should be in the range 0 < tol < 1.



glp_pivot_out() -- pull structural variables from the basis
-----------------------------------------------------------

*Synopsis*

#include "glpk.h"
int glp_pivot_out(LPI *lp, int flag[], struct piv1 *parm);

*Description*

The routine glp_pivot_out() is a special version of the simplex method.
It performs necessary amount of simplex iterations in order to pull
specified structural variables from the basis.

On entry the current basis should be specified in the problem object lp.
On exit the problem object will contain information about the new basis
constructed by the routine.

The array flag should have at least 1+n locations, where n is number
of columns (structural variables). The location flag[0] is not used.
If flag[j] (1 <= j <= n) is non-zero, the routine tries to make j-th
structural variable be non-basic. Otherwise, the j-th structural
variable is not considered.

The parameter parm is a pointer to the parameter block used by the
routine. It is allowed to specify NULL, in which case standard values
are used by default. If the parameter block is used, before a call to
the routine glp_pivot_out() the block should be initialized by means of
the statement glp_init_piv1(parm), and the the application program can
change some of the control parameters. The control parameters used by
the routine glp_pivot_out() are the same as in case of the routine
glp_pivot_in() (see above).

*Returns*

 0 - no errors;
-1 - all required structural variables are non-basic, therefore no basis
      transformations were performed;
+1 - invalid control parameter;
+2 - invalid current basis;
+3 - some required structural variables can't be made non-basic;
+4 - numerical problems with the basis matrix.

If the return code is non-zero, the current basis specified in the
problem object is not changed.

------------------------------------------------------------------------

The GLPK package is a part of the GNU project, released under the aegis
of GNU.

Copyright (C) 2001 Andrew Makhorin, Department for Applied Informatics,
Moscow Aviation Institute, Moscow, Russia. All rights reserved.

Free Software Foundation, Inc., 59 Temple Place -- Suite 330, Boston,
MA 02111, USA.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
