%* glpk02.tex *% \chapter{Basic API Routines} \section{General conventions} \subsection{Library header} All GLPK API data types and routines are defined in the header file \verb|glpk.h|. It should be included in all source files which use GLPK API, either directly or indirectly through some other header file as follows: \begin{verbatim} #include \end{verbatim} \subsection{Error handling} If some GLPK API routine detects erroneous or incorrect data passed by the application program, it writes appropriate diagnostic messages to the terminal and then abnormally terminates the application program. In most practical cases this allows to simplify programming by avoiding numerous checks of return codes. Thus, in order to prevent crashing the application program should check all data, which are suspected to be incorrect, before calling GLPK API routines. Should note that this kind of error handling is used only in cases of incorrect data passed by the application program. If, for example, the application program calls some GLPK API routine to read data from an input file and these data are incorrect, the GLPK API routine reports about error in the usual way by means of the return code. \subsection{Thread safety} The standard version of GLPK API is {\it not} thread safe and therefore should not be used in multi-threaded programs. \subsection{Array indexing} Normally all GLPK API routines start array indexing from 1, not from 0 (except the specially stipulated cases). This means, for example, that if some vector $x$ of the length $n$ is passed as an array to some GLPK API routine, the latter expects vector components to be placed in locations \verb|x[1]|, \verb|x[2]|, \dots, \verb|x[n]|, and the location \verb|x[0]| normally is not used. To avoid indexing errors it is most convenient and most reliable to declare the array \verb|x| as follows: \begin{verbatim} double x[1+n]; \end{verbatim} \noindent or to allocate it as follows: \begin{verbatim} double *x; . . . x = calloc(1+n, sizeof(double)); . . . \end{verbatim} \noindent In both cases one extra location \verb|x[0]| is reserved that allows passing the array to GLPK routines in a usual way. \section{Problem object} All GLPK API routines deal with so called {\it problem object}, which is a program object of type \verb|glp_prob| and intended to represent a particular LP or MIP instance. The type \verb|glp_prob| is a data structure declared in the header file \verb|glpk.h| as follows: \begin{verbatim} typedef struct glp_prob glp_prob; \end{verbatim} Problem objects (i.e. program objects of the \verb|glp_prob| type) are allocated and managed internally by the GLPK API routines. The application program should never use any members of the \verb|glp_prob| structure directly and should deal only with pointers to these objects (that is, \verb|glp_prob *| values). The problem object consists of the following segments: \vspace*{-8pt} \begin{itemize}\setlength{\itemsep}{0pt} \item problem segment, \item basis segment, \item interior-point segment, and \item MIP segment. \end{itemize} \subsection{Problem segment} The {\it problem segment} contains original LP/MIP data, which corresponds to the problem formulation (1.1)---(1.3) (see Section \ref{seclp}, page \pageref{seclp}). This segment includes the following components: \vspace*{-8pt} \begin{itemize}\setlength{\itemsep}{0pt} \item rows (auxiliary variables), \item columns (structural variables), \item objective function, and \item constraint matrix. \end{itemize} \vspace*{-7pt} Rows and columns have the same set of the following attributes: \vspace*{-7pt} \begin{itemize}\setlength{\itemsep}{0pt} \item ordinal number, \item symbolic name (1 up to 255 arbitrary graphic characters), \item type (free, lower bound, upper bound, double bound, fixed), \item numerical values of lower and upper bounds, \item scale factor. \end{itemize} \vspace*{-7pt} {\it Ordinal numbers} are intended for referencing rows and columns. Row ordinal numbers are integers $1, 2, \dots, m$, and column ordinal numbers are integers $1, 2, \dots, n$, where $m$ and $n$ are, respectively, the current number of rows and columns in the problem object. {\it Symbolic names} are intended for informational purposes. They also can be used for referencing rows and columns. {\it Types and bounds} of rows (auxiliary variables) and columns (structural variables) are explained above (see Section \ref{seclp}, page \pageref{seclp}). {\it Scale factors} are used internally for scaling rows and columns of the constraint matrix. Information about the {\it objective function} includes numerical values of objective coefficients and a flag, which defines the optimization direction (i.e. minimization or maximization). The {\it constraint matrix} is a $m \times n$ rectangular matrix built of constraint coefficients $a_{ij}$, which defines the system of linear constraints (1.2) (see Section \ref{seclp}, page \pageref{seclp}). This matrix is stored in the problem object in both row-wise and column-wise sparse formats. Once the problem object has been created, the application program can access and modify any components of the problem segment in arbitrary order. \subsection{Basis segment} The {\it basis segment} of the problem object keeps information related to the current basic solution. It includes: \vspace*{-8pt} \begin{itemize}\setlength{\itemsep}{0pt} \item row and column statuses, \item basic solution statuses, \item factorization of the current basis matrix, and \item basic solution components. \end{itemize} \vspace*{-8pt} The {\it row and column statuses} define which rows and columns are basic and which are non-basic. These statuses may be assigned either by the application program of by some API routines. Note that these statuses are always defined independently on whether the corresponding basis is valid or not. The {\it basic solution statuses} include the {\it primal status} and the {\it dual status}, which are set by the simplex-based solver once the problem has been solved. The primal status shows whether a primal basic solution is feasible, infeasible, or undefined. The dual status shows the same for a dual basic solution. The {\it factorization of the basis matrix} is some factorized form (like {\it LU}-factorization) of the current basis matrix (defined by the current row and column statuses). The factorization is used by simplex-based solvers and kept when the solver terminates the search. This feature allows efficiently reoptimizing the problem after some modifications (for example, after changing some bounds or objective coefficients). It also allows performing the post-optimal analysis (for example, computing components of the simplex table, etc.). The {\it basic solution components} include primal and dual values of all auxiliary and structural variables for the most recently obtained basic solution. \subsection{Interior-point segment} The {\it interior-point segment} contains interior-point solution components, which include the solution status, and primal and dual values of all auxiliary and structural variables. \subsection{MIP segment} The {\it MIP segment} is used only for MIP problems. This segment includes: \vspace*{-8pt} \begin{itemize}\setlength{\itemsep}{0pt} \item column kinds, \item MIP solution status, and \item MIP solution components. \end{itemize} \vspace*{-8pt} The {\it column kinds} define which columns (i.e. structural variables) are integer and which are continuous. The {\it MIP solution status} is set by the MIP solver and shows whether a MIP solution is integer optimal, integer feasible (non-optimal), or undefined. The {\it MIP solution components} are computed by the MIP solver and include primal values of all auxiliary and structural variables for the most recently obtained MIP solution. Note that in case of MIP problem the basis segment corresponds to the optimal solution of LP relaxation, which is also available to the application program. Currently the search tree is not kept in the MIP segment, so if the search has been terminated, it cannot be continued. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Problem creating and modifying routines} \subsection{glp\_create\_prob --- create problem object} \synopsis \begin{verbatim} glp_prob *glp_create_prob(void); \end{verbatim} \description The routine \verb|glp_create_prob| creates a new problem object, which initially is ``empty'', i.e. has no rows and columns. \returns The routine returns a pointer to the created object, which should be used in any subsequent operations on this object. \subsection{glp\_set\_prob\_name --- assign (change) problem name} \synopsis \begin{verbatim} void glp_set_prob_name(glp_prob *P, const char *name); \end{verbatim} \description The routine \verb|glp_set_prob_name| assigns a given symbolic \verb|name| (1 up to 255 characters) to the specified problem object. If the parameter \verb|name| is \verb|NULL| or empty string, the routine erases an existing symbolic name of the problem object. \subsection{glp\_set\_obj\_name --- assign (change) objective function name} \synopsis \begin{verbatim} void glp_set_obj_name(glp_prob *P, const char *name); \end{verbatim} \description The routine \verb|glp_set_obj_name| assigns a given symbolic \verb|name| (1 up to 255 characters) to the objective function of the specified problem object. If the parameter \verb|name| is \verb|NULL| or empty string, the routine erases an existing symbolic name of the objective function. \newpage \subsection{glp\_set\_obj\_dir --- set (change) optimization direction flag} \synopsis \begin{verbatim} void glp_set_obj_dir(glp_prob *P, int dir); \end{verbatim} \description The routine \verb|glp_set_obj_dir| sets (changes) the optimization direction flag (i.e. ``sense'' of the objective function) as specified by the parameter \verb|dir|: \verb|GLP_MIN| means minimization; \verb|GLP_MAX| means maximization. \noindent (Note that by default the problem is minimization.) \subsection{glp\_add\_rows --- add new rows to problem object} \synopsis \begin{verbatim} int glp_add_rows(glp_prob *P, int nrs); \end{verbatim} \description The routine \verb|glp_add_rows| adds \verb|nrs| rows (constraints) to the specified problem object. New rows are always added to the end of the row list, so the ordinal numbers of existing rows are not changed. Being added each new row is initially free (unbounded) and has empty list of the constraint coefficients. Each new row becomes a non-active (non-binding) constraint, i.e. the corresponding auxiliary variable is marked as basic. If the basis factorization exists, adding row(s) invalidates it. \returns The routine \verb|glp_add_rows| returns the ordinal number of the first new row added to the problem object. \subsection{glp\_add\_cols --- add new columns to problem object} \synopsis \begin{verbatim} int glp_add_cols(glp_prob *P, int ncs); \end{verbatim} \description The routine \verb|glp_add_cols| adds \verb|ncs| columns (structural variables) to the specified problem object. New columns are always added to the end of the column list, so the ordinal numbers of existing columns are not changed. Being added each new column is initially fixed at zero and has empty list of the constraint coefficients. Each new column is marked as non-basic, i.e. zero value of the corresponding structural variable becomes an active (binding) bound. If the basis factorization exists, it remains valid. \returns The routine \verb|glp_add_cols| returns the ordinal number of the first new column added to the problem object. \subsection{glp\_set\_row\_name --- assign (change) row name} \synopsis \begin{verbatim} void glp_set_row_name(glp_prob *P, int i, const char *name); \end{verbatim} \description The routine \verb|glp_set_row_name| assigns a given symbolic \verb|name| (1 up to 255 characters) to \verb|i|-th row (auxiliary variable) of the specified problem object. If the parameter \verb|name| is \verb|NULL| or empty string, the routine erases an existing name of $i$-th row. \subsection{glp\_set\_col\_name --- assign (change) column name} \synopsis \begin{verbatim} void glp_set_col_name(glp_prob *P, int j, const char *name); \end{verbatim} \description The routine \verb|glp_set_col_name| assigns a given symbolic \verb|name| (1 up to 255 characters) to \verb|j|-th column (structural variable) of the specified problem object. If the parameter \verb|name| is \verb|NULL| or empty string, the routine erases an existing name of $j$-th column. \subsection{glp\_set\_row\_bnds --- set (change) row bounds} \synopsis {\tt void glp\_set\_row\_bnds(glp\_prob *P, int i, int type, double lb, double ub);} \description The routine \verb|glp_set_row_bnds| sets (changes) the type and bounds of \verb|i|-th row (auxiliary variable) of the specified problem object. The parameters \verb|type|, \verb|lb|, and \verb|ub| specify the type, lower bound, and upper bound, respectively, as follows: \begin{center} \begin{tabular}{cr@{}c@{}ll} Type & \multicolumn{3}{c}{Bounds} & Comment \\ \hline \verb|GLP_FR| & $-\infty <$ &$\ x\ $& $< +\infty$ & Free (unbounded) variable \\ \verb|GLP_LO| & $lb \leq$ &$\ x\ $& $< +\infty$ & Variable with lower bound \\ \verb|GLP_UP| & $-\infty <$ &$\ x\ $& $\leq ub$ & Variable with upper bound \\ \verb|GLP_DB| & $lb \leq$ &$\ x\ $& $\leq ub$ & Double-bounded variable \\ \verb|GLP_FX| & $lb =$ &$\ x\ $& $= ub$ & Fixed variable \\ \end{tabular} \end{center} \noindent where $x$ is the auxiliary variable associated with $i$-th row. If the row has no lower bound, the parameter \verb|lb| is ignored. If the row has no upper bound, the parameter \verb|ub| is ignored. If the row is an equality constraint (i.e. the corresponding auxiliary variable is of fixed type), only the parameter \verb|lb| is used while the parameter \verb|ub| is ignored. Being added to the problem object each row is initially free, i.e. its type is \verb|GLP_FR|. \subsection{glp\_set\_col\_bnds --- set (change) column bounds} \synopsis {\tt void glp\_set\_col\_bnds(glp\_prob *P, int j, int type, double lb, double ub);} \description The routine \verb|glp_set_col_bnds| sets (changes) the type and bounds of \verb|j|-th column (structural variable) of the specified problem object. The parameters \verb|type|, \verb|lb|, and \verb|ub| specify the type, lower bound, and upper bound, respectively, as follows: \begin{center} \begin{tabular}{cr@{}c@{}ll} Type & \multicolumn{3}{c}{Bounds} & Comment \\ \hline \verb|GLP_FR| & $-\infty <$ &$\ x\ $& $< +\infty$ & Free (unbounded) variable \\ \verb|GLP_LO| & $lb \leq$ &$\ x\ $& $< +\infty$ & Variable with lower bound \\ \verb|GLP_UP| & $-\infty <$ &$\ x\ $& $\leq ub$ & Variable with upper bound \\ \verb|GLP_DB| & $lb \leq$ &$\ x\ $& $\leq ub$ & Double-bounded variable \\ \verb|GLP_FX| & $lb =$ &$\ x\ $& $= ub$ & Fixed variable \\ \end{tabular} \end{center} \noindent where $x$ is the structural variable associated with $j$-th column. If the column has no lower bound, the parameter \verb|lb| is ignored. If the column has no upper bound, the parameter \verb|ub| is ignored. If the column is of fixed type, only the parameter \verb|lb| is used while the parameter \verb|ub| is ignored. Being added to the problem object each column is initially fixed at zero, i.e. its type is \verb|GLP_FX| and both bounds are 0. \newpage \subsection{glp\_set\_obj\_coef --- set (change) objective coefficient or constant term} \synopsis \begin{verbatim} void glp_set_obj_coef(glp_prob *P, int j, double coef); \end{verbatim} \description The routine \verb|glp_set_obj_coef| sets (changes) the objective coefficient at \verb|j|-th column (structural variable). A new value of the objective coefficient is specified by the parameter \verb|coef|. If the parameter \verb|j| is 0, the routine sets (changes) the constant term (``shift'') of the objective function. \subsection{glp\_set\_mat\_row --- set (replace) row of the constraint matrix} \synopsis \begin{verbatim} void glp_set_mat_row(glp_prob *P, int i, int len, const int ind[], const double val[]); \end{verbatim} \description The routine \verb|glp_set_mat_row| stores (replaces) the contents of \verb|i|-th row of the constraint matrix of the specified problem object. Column indices and numerical values of new row elements should be placed in locations\linebreak \verb|ind[1]|, \dots, \verb|ind[len]| and \verb|val[1]|, \dots, \verb|val[len]|, respectively, where $0 \leq$ \verb|len| $\leq n$ is the new length of $i$-th row, $n$ is the current number of columns in the problem object. Elements with identical column indices are not allowed. Zero elements are allowed, but they are not stored in the constraint matrix. If the parameter \verb|len| is 0, the parameters \verb|ind| and/or \verb|val| can be specified as \verb|NULL|. \note If the basis factorization exists and changing the row changes coefficients at basic column(s), the factorization is invalidated. \subsection{glp\_set\_mat\_col --- set (replace) column of the constr\-aint matrix} \synopsis \begin{verbatim} void glp_set_mat_col(glp_prob *P, int j, int len, const int ind[], const double val[]); \end{verbatim} \description The routine \verb|glp_set_mat_col| stores (replaces) the contents of \verb|j|-th column of the constraint matrix of the specified problem object. Row indices and numerical values of new column elements should be placed in locations\linebreak \verb|ind[1]|, \dots, \verb|ind[len]| and \verb|val[1]|, \dots, \verb|val[len]|, respectively, where $0 \leq$ \verb|len| $\leq m$ is the new length of $j$-th column, $m$ is the current number of rows in the problem object. Elements with identical row indices are not allowed. Zero elements are allowed, but they are not stored in the constraint matrix. If the parameter \verb|len| is 0, the parameters \verb|ind| and/or \verb|val| can be specified as \verb|NULL|. \note If the basis factorization exists, changing the column corresponding to a basic structural variable invalidates it. \subsection{glp\_load\_matrix --- load (replace) the whole constraint matrix} \synopsis \begin{verbatim} void glp_load_matrix(glp_prob *P, int ne, const int ia[], const int ja[], const double ar[]); \end{verbatim} \description The routine \verb|glp_load_matrix| loads the constraint matrix passed in the arrays \verb|ia|, \verb|ja|, and \verb|ar| into the specified problem object. Before loading the current contents of the constraint matrix is destroyed. Constraint coefficients (elements of the constraint matrix) should be specified as triplets (\verb|ia[k]|, \verb|ja[k]|, \verb|ar[k]|) for $k=1,\dots,ne$, where \verb|ia[k]| is the row index, \verb|ja[k]| is the column index, and \verb|ar[k]| is a numeric value of corresponding constraint coefficient. The parameter \verb|ne| specifies the total number of (non-zero) elements in the matrix to be loaded. Coefficients with identical indices are not allowed. Zero coefficients are allowed, however, they are not stored in the constraint matrix. If the parameter \verb|ne| is 0, the parameters \verb|ia|, \verb|ja|, and/or \verb|ar| can be specified as \verb|NULL|. \note If the basis factorization exists, this operation invalidates it. \subsection{glp\_check\_dup --- check for duplicate elements in sparse matrix} \synopsis {\tt int glp\_check\_dup(int m, int n, int ne, const int ia[], const int ja[]);} \description The routine \verb|glp_check_dup checks| for duplicate elements (that is, elements with identical indices) in a sparse matrix specified in the coordinate format. The parameters $m$ and $n$ specifies, respectively, the number of rows and columns in the matrix, $m\geq 0$, $n\geq 0$. The parameter {\it ne} specifies the number of (structurally) non-zero elements in the matrix,\linebreak {\it ne} $\geq 0$. Elements of the matrix are specified as doublets $(ia[k],ja[k])$ for $k=1,\dots,ne$, where $ia[k]$ is a row index, $ja[k]$ is a column index. The routine \verb|glp_check_dup| can be used prior to a call to the routine \verb|glp_load_matrix| to check that the constraint matrix to be loaded has no duplicate elements. \returns \begin{retlist} 0& the matrix representation is correct;\\ $-k$& indices $ia[k]$ or/and $ja[k]$ are out of range;\\ $+k$& element $(ia[k],ja[k])$ is duplicate.\\ \end{retlist} \subsection{glp\_sort\_matrix --- sort elements of the constraint matrix} \synopsis \begin{verbatim} void glp_sort_matrix(glp_prob *P); \end{verbatim} \description The routine \verb|glp_sort_matrix| sorts elements of the constraint matrix by rebuilding its row and column linked lists. On exit from the routine the constraint matrix is not changed, however, elements in the row linked lists become ordered by ascending column indices, and the elements in the column linked lists become ordered by ascending row indices. \subsection{glp\_del\_rows --- delete rows from problem object} \synopsis \begin{verbatim} void glp_del_rows(glp_prob *P, int nrs, const int num[]); \end{verbatim} \description The routine \verb|glp_del_rows| deletes rows from the specified problem object. Ordinal numbers of rows to be deleted should be placed in locations \verb|num[1]|, \dots, \verb|num[nrs]|, where ${\tt nrs}>0$. Note that deleting rows involves changing ordinal numbers of other rows remaining in the problem object. New ordinal numbers of the remaining rows are assigned under the assumption that the original order of rows is not changed. Let, for example, before deletion there be five rows $a$, $b$, $c$, $d$, $e$ with ordinal numbers 1, 2, 3, 4, 5, and let rows $b$ and $d$ have been deleted. Then after deletion the remaining rows $a$, $c$, $e$ are assigned new oridinal numbers 1, 2, 3. If the basis factorization exists, deleting active (binding) rows, i.e. whose auxiliary variables are marked as non-basic, invalidates it. \newpage \subsection{glp\_del\_cols --- delete columns from problem object} \synopsis \begin{verbatim} void glp_del_cols(glp_prob *P, int ncs, const int num[]); \end{verbatim} \description The routine \verb|glp_del_cols| deletes columns from the specified problem object. Ordinal numbers of columns to be deleted should be placed in locations \verb|num[1]|, \dots, \verb|num[ncs]|, where ${\tt ncs}>0$. Note that deleting columns involves changing ordinal numbers of other columns remaining in\linebreak the problem object. New ordinal numbers of the remaining columns are assigned under the assumption that the original order of columns is not changed. Let, for example, before deletion there be six columns $p$, $q$, $r$, $s$, $t$, $u$ with ordinal numbers 1, 2, 3, 4, 5, 6, and let columns $p$, $q$, $s$ have been deleted. Then after deletion the remaining columns $r$, $t$, $u$ are assigned new ordinal numbers 1, 2, 3. If the basis factorization exists, deleting basic columns invalidates it. \subsection{glp\_copy\_prob --- copy problem object content} \synopsis \begin{verbatim} void glp_copy_prob(glp_prob *dest, glp_prob *prob, int names); \end{verbatim} \description The routine \verb|glp_copy_prob| copies the content of the problem object \verb|prob| to the problem object \verb|dest|. The parameter \verb|names| is a flag. If it is \verb|GLP_ON|, the routine also copies all symbolic names; otherwise, if it is \verb|GLP_OFF|, no symbolic names are copied. \subsection{glp\_erase\_prob --- erase problem object content} \synopsis \begin{verbatim} void glp_erase_prob(glp_prob *P); \end{verbatim} \description The routine \verb|glp_erase_prob| erases the content of the specified problem object. The effect of this operation is the same as if the problem object would be deleted with the routine \verb|glp_delete_prob| and then created anew with the routine \verb|glp_create_prob|, with the only exception that the pointer to the problem object remains valid. \newpage \subsection{glp\_delete\_prob --- delete problem object} \synopsis \begin{verbatim} void glp_delete_prob(glp_prob *P); \end{verbatim} \description The routine \verb|glp_delete_prob| deletes a problem object, which the parameter \verb|lp| points to, freeing all the memory allocated to this object. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Problem retrieving routines} \subsection{glp\_get\_prob\_name --- retrieve problem name} \synopsis \begin{verbatim} const char *glp_get_prob_name(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_prob_name| returns a pointer to an internal buffer, which contains symbolic name of the problem. However, if the problem has no assigned name, the routine returns \verb|NULL|. \subsection{glp\_get\_obj\_name --- retrieve objective function name} \synopsis \begin{verbatim} const char *glp_get_obj_name(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_obj_name| returns a pointer to an internal buffer, which contains symbolic name assigned to the objective function. However, if the objective function has no assigned name, the routine returns \verb|NULL|. \subsection{glp\_get\_obj\_dir --- retrieve optimization direction flag} \synopsis \begin{verbatim} int glp_get_obj_dir(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_obj_dir| returns the optimization direction flag (i.e. ``sense'' of the objective function): \verb|GLP_MIN| means minimization; \verb|GLP_MAX| means maximization. \subsection{glp\_get\_num\_rows --- retrieve number of rows} \synopsis \begin{verbatim} int glp_get_num_rows(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_num_rows| returns the current number of rows in the specified problem object. \subsection{glp\_get\_num\_cols --- retrieve number of columns} \synopsis \begin{verbatim} int glp_get_num_cols(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_num_cols| returns the current number of columns in the specified problem object. \subsection{glp\_get\_row\_name --- retrieve row name} \synopsis \begin{verbatim} const char *glp_get_row_name(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_name| returns a pointer to an internal buffer, which contains a symbolic name assigned to \verb|i|-th row. However, if the row has no assigned name, the routine returns \verb|NULL|. \subsection{glp\_get\_col\_name --- retrieve column name} \synopsis \begin{verbatim} const char *glp_get_col_name(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_name| returns a pointer to an internal buffer, which contains a symbolic name assigned to \verb|j|-th column. However, if the column has no assigned name, the routine returns \verb|NULL|. \subsection{glp\_get\_row\_type --- retrieve row type} \synopsis \begin{verbatim} int glp_get_row_type(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_type| returns the type of \verb|i|-th row, i.e. the type of corresponding auxiliary variable, as follows: \verb|GLP_FR| --- free (unbounded) variable; \verb|GLP_LO| --- variable with lower bound; \verb|GLP_UP| --- variable with upper bound; \verb|GLP_DB| --- double-bounded variable; \verb|GLP_FX| --- fixed variable. \subsection{glp\_get\_row\_lb --- retrieve row lower bound} \synopsis \begin{verbatim} double glp_get_row_lb(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_lb| returns the lower bound of \verb|i|-th row, i.e. the lower bound of corresponding auxiliary variable. However, if the row has no lower bound, the routine returns \verb|-DBL_MAX|. \vspace*{-4pt} \subsection{glp\_get\_row\_ub --- retrieve row upper bound} \synopsis \begin{verbatim} double glp_get_row_ub(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_ub| returns the upper bound of \verb|i|-th row, i.e. the upper bound of corresponding auxiliary variable. However, if the row has no upper bound, the routine returns \verb|+DBL_MAX|. \vspace*{-4pt} \subsection{glp\_get\_col\_type --- retrieve column type} \synopsis \begin{verbatim} int glp_get_col_type(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_type| returns the type of \verb|j|-th column, i.e. the type of corresponding structural variable, as follows: \verb|GLP_FR| --- free (unbounded) variable; \verb|GLP_LO| --- variable with lower bound; \verb|GLP_UP| --- variable with upper bound; \verb|GLP_DB| --- double-bounded variable; \verb|GLP_FX| --- fixed variable. \vspace*{-4pt} \subsection{glp\_get\_col\_lb --- retrieve column lower bound} \synopsis \begin{verbatim} double glp_get_col_lb(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_lb| returns the lower bound of \verb|j|-th column, i.e. the lower bound of corresponding structural variable. However, if the column has no lower bound, the routine returns \verb|-DBL_MAX|. \subsection{glp\_get\_col\_ub --- retrieve column upper bound} \synopsis \begin{verbatim} double glp_get_col_ub(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_ub| returns the upper bound of \verb|j|-th column, i.e. the upper bound of corresponding structural variable. However, if the column has no upper bound, the routine returns \verb|+DBL_MAX|. \subsection{glp\_get\_obj\_coef --- retrieve objective coefficient or constant term} \synopsis \begin{verbatim} double glp_get_obj_coef(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_obj_coef| returns the objective coefficient at \verb|j|-th structural variable (column). If the parameter \verb|j| is 0, the routine returns the constant term (``shift'') of the objective function. \subsection{glp\_get\_num\_nz --- retrieve number of constraint coefficients} \synopsis \begin{verbatim} int glp_get_num_nz(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_num_nz| returns the number of non-zero elements in the constraint matrix of the specified problem object. \subsection{glp\_get\_mat\_row --- retrieve row of the constraint matrix} \synopsis \begin{verbatim} int glp_get_mat_row(glp_prob *P, int i, int ind[], double val[]); \end{verbatim} \description The routine \verb|glp_get_mat_row| scans (non-zero) elements of \verb|i|-th row of the constraint matrix of the specified problem object and stores their column indices and numeric values to locations \verb|ind[1]|, \dots, \verb|ind[len]| and \verb|val[1]|, \dots, \verb|val[len]|, respectively, where $0\leq{\tt len}\leq n$ is the number of elements in $i$-th row, $n$ is the number of columns. The parameter \verb|ind| and/or \verb|val| can be specified as \verb|NULL|, in which case corresponding information is not stored. \newpage \returns The routine \verb|glp_get_mat_row| returns the length \verb|len|, i.e. the number of (non-zero) elements in \verb|i|-th row. \subsection{glp\_get\_mat\_col --- retrieve column of the constraint matrix} \synopsis \begin{verbatim} int glp_get_mat_col(glp_prob *P, int j, int ind[], double val[]); \end{verbatim} \description The routine \verb|glp_get_mat_col| scans (non-zero) elements of \verb|j|-th column of the constraint matrix of the specified problem object and stores their row indices and numeric values to locations \linebreak \verb|ind[1]|, \dots, \verb|ind[len]| and \verb|val[1]|, \dots, \verb|val[len]|, respectively, where $0\leq{\tt len}\leq m$ is the number of elements in $j$-th column, $m$ is the number of rows. The parameter \verb|ind| and/or \verb|val| can be specified as \verb|NULL|, in which case corresponding information is not stored. \returns The routine \verb|glp_get_mat_col| returns the length \verb|len|, i.e. the number of (non-zero) elements in \verb|j|-th column. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Row and column searching routines} Sometimes it may be necessary to find rows and/or columns by their names (assigned with the routines \verb|glp_set_row_name| and \verb|glp_set_col_name|). Though a particular row/column can be found by its name using simple enumeration of all rows/columns, in case of large instances such a {\it linear} search may take too long time. To significantly reduce the search time the application program may create the row/column name index, which is an auxiliary data structure implementing a {\it binary} search. Even in worst cases the search takes logarithmic time, i.e. the time needed to find a particular row (or column) by its name is $O(\log_2m)$ (or $O(\log_2n)$), where $m$ and $n$ are, resp., the number of rows and columns in the problem object. It is important to note that: 1. On creating the problem object with the routine \verb|glp_create_prob| the name index is {\it not} created. 2. The name index can be created (destroyed) at any time with the routine \verb|glp_create_index| (\verb|glp_delete_index|). Having been created the name index becomes part of the corresponding problem object. 3. The time taken to create the name index is $O[(m+n)\log_2(m+n)]$, so it is recommended to create the index only once, for example, just after the problem object was created. 4. If the name index exists, it is automatically updated every time the name of a row/column is assigned/changed. The update operation takes logarithmic time. 5. If the name index does not exist, the application should not call the routines \verb|glp_find_row| and \verb|glp_find_col|. Otherwise, an error message will be issued and abnormal program termination will occur. 6. On destroying the problem object with the routine \verb|glp_delete_prob|, the name index, if exists, is automatically destroyed. \subsection{glp\_create\_index --- create the name index} \synopsis \begin{verbatim} void glp_create_index(glp_prob *P); \end{verbatim} \description The routine \verb|glp_create_index| creates the name index for the specified problem object. The name index is an auxiliary data structure, which is intended to quickly (i.e. for logarithmic time) find rows and columns by their names. This routine can be called at any time. If the name index already exists, the routine does nothing. \newpage \subsection{glp\_find\_row --- find row by its name} \synopsis \begin{verbatim} int glp_find_row(glp_prob *P, const char *name); \end{verbatim} \returns The routine \verb|glp_find_row| returns the ordinal number of a row, which is assigned the specified symbolic \verb|name|. If no such row exists, the routine returns 0. \subsection{glp\_find\_col --- find column by its name} \synopsis \begin{verbatim} int glp_find_col(glp_prob *P, const char *name); \end{verbatim} \returns The routine \verb|glp_find_col| returns the ordinal number of a column, which is assigned the specified symbolic \verb|name|. If no such column exists, the routine returns 0. \subsection{glp\_delete\_index --- delete the name index} \synopsis \begin{verbatim} void glp_delete_index(glp_prob *P); \end{verbatim} \description The routine \verb|glp_delete_index| deletes the name index previously created by the routine\linebreak \verb|glp_create_index| and frees the memory allocated to this auxiliary data structure. This routine can be called at any time. If the name index does not exist, the routine does nothing. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Problem scaling routines} \subsection{Background} In GLPK the {\it scaling} means a linear transformation applied to the constraint matrix to improve its numerical properties.\footnote{In many cases a proper scaling allows making the constraint matrix to be better conditioned, i.e. decreasing its condition number, that makes computations numerically more stable.} The main equality is the following: $$\widetilde{A}=RAS,\eqno(2.1)$$ where $A=(a_{ij})$ is the original constraint matrix, $R=(r_{ii})>0$ is a diagonal matrix used to scale rows (constraints), $S=(s_{jj})>0$ is a diagonal matrix used to scale columns (variables), $\widetilde{A}$ is the scaled constraint matrix. From (2.1) it follows that in the {\it scaled} problem instance each original constraint coefficient $a_{ij}$ is replaced by corresponding scaled constraint coefficient: $$\widetilde{a}_{ij}=r_{ii}a_{ij}s_{jj}.\eqno(2.2)$$ Note that the scaling is performed internally and therefore transparently to the user. This means that on API level the user always deal with unscaled data. Scale factors $r_{ii}$ and $s_{jj}$ can be set or changed at any time either directly by the application program in a problem specific way (with the routines \verb|glp_set_rii| and \verb|glp_set_sjj|), or by some API routines intended for automatic scaling. \subsection{glp\_set\_rii --- set (change) row scale factor} \synopsis \begin{verbatim} void glp_set_rii(glp_prob *P, int i, double rii); \end{verbatim} \description The routine \verb|glp_set_rii| sets (changes) the scale factor $r_{ii}$ for $i$-th row of the specified problem object. \subsection{glp\_set\_sjj --- set (change) column scale factor} \synopsis \begin{verbatim} void glp_set_sjj(glp_prob *P, int j, double sjj); \end{verbatim} \description The routine \verb|glp_set_sjj| sets (changes) the scale factor $s_{jj}$ for $j$-th column of the specified problem object. \subsection{glp\_get\_rii --- retrieve row scale factor} \synopsis \begin{verbatim} double glp_get_rii(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_rii| returns current scale factor $r_{ii}$ for $i$-th row of the specified problem object. \vspace*{-6pt} \subsection{glp\_get\_sjj --- retrieve column scale factor} \vspace*{-4pt} \synopsis \begin{verbatim} double glp_get_sjj(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_sjj| returns current scale factor $s_{jj}$ for $j$-th column of the specified problem object. \vspace*{-6pt} \subsection{glp\_scale\_prob --- scale problem data} \vspace*{-4pt} \synopsis \begin{verbatim} void glp_scale_prob(glp_prob *P, int flags); \end{verbatim} \description The routine \verb|glp_scale_prob| performs automatic scaling of problem data for the specified problem object. The parameter \verb|flags| specifies scaling options used by the routine. The options can be combined with the bitwise OR operator and may be the following: \verb|GLP_SF_GM | --- perform geometric mean scaling; \verb|GLP_SF_EQ | --- perform equilibration scaling; \verb|GLP_SF_2N | --- round scale factors to nearest power of two; \verb|GLP_SF_SKIP| --- skip scaling, if the problem is well scaled. The parameter \verb|flags| may be also specified as \verb|GLP_SF_AUTO|, in which case the routine chooses the scaling options automatically. \vspace*{-6pt} \subsection{glp\_unscale\_prob --- unscale problem data} \vspace*{-4pt} \synopsis \begin{verbatim} void glp_unscale_prob(glp_prob *P); \end{verbatim} The routine \verb|glp_unscale_prob| performs unscaling of problem data for the specified problem object. ``Unscaling'' means replacing the current scaling matrices $R$ and $S$ by unity matrices that cancels the scaling effect. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{LP basis constructing routines} \subsection{Background} To start the search the simplex method needs a valid initial basis. In GLPK the basis is completely defined by a set of {\it statuses} assigned to {\it all} (auxiliary and structural) variables, where the status may be one of the following: \verb|GLP_BS| --- basic variable; \verb|GLP_NL| --- non-basic variable having active lower bound; \verb|GLP_NU| --- non-basic variable having active upper bound; \verb|GLP_NF| --- non-basic free variable; \verb|GLP_NS| --- non-basic fixed variable. The basis is {\it valid}, if the basis matrix, which is a matrix built of columns of the augmented constraint matrix $(I\:|-A)$ corresponding to basic variables, is non-singular. This, in particular, means that the number of basic variables must be the same as the number of rows in the problem object. (For more details see Section \ref{lpbasis}, page \pageref{lpbasis}.) Any initial basis may be constructed (or restored) with the API routines \verb|glp_set_row_stat| and \verb|glp_set_col_stat| by assigning appropriate statuses to auxiliary and structural variables. Another way to construct an initial basis is to use API routines like \verb|glp_adv_basis|, which implement so called {\it crashing}.\footnote{This term is from early linear programming systems and means a heuristic to construct a valid initial basis.} Note that on normal exit the simplex solver remains the basis valid, so in case of reoptimization there is no need to construct an initial basis from scratch. \subsection{glp\_set\_row\_stat --- set (change) row status} \synopsis \begin{verbatim} void glp_set_row_stat(glp_prob *P, int i, int stat); \end{verbatim} \description The routine \verb|glp_set_row_stat| sets (changes) the current status of \verb|i|-th row (auxiliary variable) as specified by the parameter \verb|stat|: \verb|GLP_BS| --- make the row basic (make the constraint inactive); \verb|GLP_NL| --- make the row non-basic (make the constraint active); \verb|GLP_NU| --- make the row non-basic and set it to the upper bound; if the row is not double-bounded, this status is equivalent to \verb|GLP_NL| (only in case of this routine); \verb|GLP_NF| --- the same as \verb|GLP_NL| (only in case of this routine); \verb|GLP_NS| --- the same as \verb|GLP_NL| (only in case of this routine). \newpage \subsection{glp\_set\_col\_stat --- set (change) column status} \synopsis \begin{verbatim} void glp_set_col_stat(glp_prob *P, int j, int stat); \end{verbatim} \description The routine \verb|glp_set_col_stat sets| (changes) the current status of \verb|j|-th column (structural variable) as specified by the parameter \verb|stat|: \verb|GLP_BS| --- make the column basic; \verb|GLP_NL| --- make the column non-basic; \verb|GLP_NU| --- make the column non-basic and set it to the upper bound; if the column is not double-bounded, this status is equivalent to \verb|GLP_NL| (only in case of this routine); \verb|GLP_NF| --- the same as \verb|GLP_NL| (only in case of this routine); \verb|GLP_NS| --- the same as \verb|GLP_NL| (only in case of this routine). \subsection{glp\_std\_basis --- construct standard initial LP basis} \synopsis \begin{verbatim} void glp_std_basis(glp_prob *P); \end{verbatim} \description The routine \verb|glp_std_basis| constructs the ``standard'' (trivial) initial LP basis for the specified problem object. In the ``standard'' LP basis all auxiliary variables (rows) are basic, and all structural variables (columns) are non-basic (so the corresponding basis matrix is unity). \subsection{glp\_adv\_basis --- construct advanced initial LP basis} \synopsis \begin{verbatim} void glp_adv_basis(glp_prob *P, int flags); \end{verbatim} \description The routine \verb|glp_adv_basis| constructs an advanced initial LP basis for the specified problem object. The parameter \verb|flags| is reserved for use in the future and must be specified as zero. In order to construct the advanced initial LP basis the routine does the following: 1) includes in the basis all non-fixed auxiliary variables; 2) includes in the basis as many non-fixed structural variables as possible keeping the triangular form of the basis matrix; 3) includes in the basis appropriate (fixed) auxiliary variables to complete the basis. As a result the initial LP basis has as few fixed variables as possible and the corresponding basis matrix is triangular. \subsection{glp\_cpx\_basis --- construct Bixby's initial LP basis} \synopsis \begin{verbatim} void glp_cpx_basis(glp_prob *P); \end{verbatim} \description The routine \verb|glp_cpx_basis| constructs an initial basis for the specified problem object with the algorithm proposed by R.~Bixby.\footnote{Robert E. Bixby, ``Implementing the Simplex Method: The Initial Basis.'' ORSA Journal on Computing, Vol. 4, No. 3, 1992, pp. 267-84.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Simplex method routines} The {\it simplex method} is a well known efficient numerical procedure to solve LP problems. On each iteration the simplex method transforms the original system of equaility constraints (1.2) resolving them through different sets of variables to an equivalent system called {\it the simplex table} (or sometimes {\it the simplex tableau}), which has the following form: $$ \begin{array}{r@{\:}c@{\:}r@{\:}c@{\:}r@{\:}c@{\:}r} z&=&d_1(x_N)_1&+&d_2(x_N)_2&+ \dots +&d_n(x_N)_n \\ (x_B)_1&=&\xi_{11}(x_N)_1& +& \xi_{12}(x_N)_2& + \dots +& \xi_{1n}(x_N)_n \\ (x_B)_2&=& \xi_{21}(x_N)_1& +& \xi_{22}(x_N)_2& + \dots +& \xi_{2n}(x_N)_n \\ \multicolumn{7}{c} {.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .} \\ (x_B)_m&=&\xi_{m1}(x_N)_1& +& \xi_{m2}(x_N)_2& + \dots +& \xi_{mn}(x_N)_n \\ \end{array} \eqno (2.3) $$ where: $(x_B)_1, (x_B)_2, \dots, (x_B)_m$ are basic variables; $(x_N)_1, (x_N)_2, \dots, (x_N)_n$ are non-basic variables; $d_1, d_2, \dots, d_n$ are reduced costs; $\xi_{11}, \xi_{12}, \dots, \xi_{mn}$ are coefficients of the simplex table. (May note that the original LP problem (1.1)---(1.3) also has the form of a simplex table, where all equalities are resolved through auxiliary variables.) From the linear programming theory it is known that if an optimal solution of the LP problem (1.1)---(1.3) exists, it can always be written in the form (2.3), where non-basic variables are set on their bounds while values of the objective function and basic variables are determined by the corresponding equalities of the simplex table. A set of values of all basic and non-basic variables determined by the simplex table is called {\it basic solution}. If all basic variables are within their bounds, the basic solution is called {\it (primal) feasible}, otherwise it is called {\it (primal) infeasible}. A feasible basic solution, which provides a smallest (in case of minimization) or a largest (in case of maximization) value of the objective function is called {\it optimal}. Therefore, for solving LP problem the simplex method tries to find its optimal basic solution. Primal feasibility of some basic solution may be stated by simple checking if all basic variables are within their bounds. Basic solution is optimal if additionally the following optimality conditions are satisfied for all non-basic variables: \begin{center} \begin{tabular}{lcc} Status of $(x_N)_j$ & Minimization & Maximization \\ \hline $(x_N)_j$ is free & $d_j = 0$ & $d_j = 0$ \\ $(x_N)_j$ is on its lower bound & $d_j \geq 0$ & $d_j \leq 0$ \\ $(x_N)_j$ is on its upper bound & $d_j \leq 0$ & $d_j \geq 0$ \\ \end{tabular} \end{center} In other words, basic solution is optimal if there is no non-basic variable, which changing in the feasible direction (i.e. increasing if it is free or on its lower bound, or decreasing if it is free or on its upper bound) can improve (i.e. decrease in case of minimization or increase in case of maximization) the objective function. If all non-basic variables satisfy to the optimality conditions shown above (independently on whether basic variables are within their bounds or not), the basic solution is called {\it dual feasible}, otherwise it is called {\it dual infeasible}. It may happen that some LP problem has no primal feasible solution due to incorrect\linebreak formulation --- this means that its constraints conflict with each other. It also may happen that some LP problem has unbounded solution again due to incorrect formulation --- this means that some non-basic variable can improve the objective function, i.e. the optimality conditions are violated, and at the same time this variable can infinitely change in the feasible direction meeting no resistance from basic variables. (May note that in the latter case the LP problem has no dual feasible solution.) \subsection{glp\_simplex --- solve LP problem with the primal or dual simplex method} \synopsis \begin{verbatim} int glp_simplex(glp_prob *P, const glp_smcp *parm); \end{verbatim} \description The routine \verb|glp_simplex| is a driver to the LP solver based on the simplex method. This routine retrieves problem data from the specified problem object, calls the solver to solve the problem instance, and stores results of computations back into the problem object. The simplex solver has a set of control parameters. Values of the control parameters can be passed in the structure \verb|glp_smcp|, which the parameter \verb|parm| points to. For detailed description of this structure see paragraph ``Control parameters'' below. Before specifying some control parameters the application program should initialize the structure \verb|glp_smcp| by default values of all control parameters using the routine \verb|glp_init_smcp| (see the next subsection). This is needed for backward compatibility, because in the future there may appear new members in the structure \verb|glp_smcp|. The parameter \verb|parm| can be specified as \verb|NULL|, in which case the solver uses default settings. \returns \begin{retlist} 0 & The LP problem instance has been successfully solved. (This code does {\it not} necessarily mean that the solver has found optimal solution. It only means that the solution process was successful.) \\ \verb|GLP_EBADB| & Unable to start the search, because the initial basis specified in the problem object is invalid---the number of basic (auxiliary and structural) variables is not the same as the number of rows in the problem object.\\ \verb|GLP_ESING| & Unable to start the search, because the basis matrix corresponding to the initial basis is singular within the working precision.\\ \verb|GLP_ECOND| & Unable to start the search, because the basis matrix corresponding to the initial basis is ill-conditioned, i.e. its condition number is too large.\\ \verb|GLP_EBOUND| & Unable to start the search, because some double-bounded (auxiliary or structural) variables have incorrect bounds.\\ \verb|GLP_EFAIL| & The search was prematurely terminated due to the solver failure.\\ \verb|GLP_EOBJLL| & The search was prematurely terminated, because the objective function being maximized has reached its lower limit and continues decreasing (the dual simplex only).\\ \end{retlist} \begin{retlist} \verb|GLP_EOBJUL| & The search was prematurely terminated, because the objective function being minimized has reached its upper limit and continues increasing (the dual simplex only).\\ \verb|GLP_EITLIM| & The search was prematurely terminated, because the simplex iteration limit has been exceeded.\\ \verb|GLP_ETMLIM| & The search was prematurely terminated, because the time limit has been exceeded.\\ \verb|GLP_ENOPFS| & The LP problem instance has no primal feasible solution (only if the LP presolver is used).\\ \verb|GLP_ENODFS| & The LP problem instance has no dual feasible solution (only if the LP presolver is used).\\ \end{retlist} \para{Built-in LP presolver} The simplex solver has {\it built-in LP presolver}. It is a subprogram that transforms the original LP problem specified in the problem object to an equivalent LP problem, which may be easier for solving with the simplex method than the original one. This is attained mainly due to reducing the problem size and improving its numeric properties (for example, by removing some inactive constraints or by fixing some non-basic variables). Once the transformed LP problem has been solved, the presolver transforms its basic solution back to the corresponding basic solution of the original problem. Presolving is an optional feature of the routine \verb|glp_simplex|, and by default it is disabled. In order to enable the LP presolver the control parameter \verb|presolve| should be set to \verb|GLP_ON| (see paragraph ``Control parameters'' below). Presolving may be used when the problem instance is solved for the first time. However, on performing re-optimization the presolver should be disabled. The presolving procedure is transparent to the API user in the sense that all necessary processing is performed internally, and a basic solution of the original problem recovered by the presolver is the same as if it were computed directly, i.e. without presolving. Note that the presolver is able to recover only optimal solutions. If a computed solution is infeasible or non-optimal, the corresponding solution of the original problem cannot be recovered and therefore remains undefined. If you need to know a basic solution even if it is infeasible or non-optimal, the presolver should be disabled. \para{Terminal output} Solving large problem instances may take a long time, so the solver reports some information about the current basic solution, which is sent to the terminal. This information has the following format: \begin{verbatim} nnn: obj = xxx infeas = yyy (ddd) \end{verbatim} \noindent where: `\verb|nnn|' is the iteration number, `\verb|xxx|' is the current value of the objective function (it is unscaled and has correct sign); `\verb|yyy|' is the current sum of primal or dual infeasibilities (it is scaled and therefore may be used only for visual estimating), `\verb|ddd|' is the current number of fixed basic variables. The symbol preceding the iteration number indicates which phase of the simplex method is in effect: {\it Blank} means that the solver is searching for primal feasible solution using the primal simplex or for dual feasible solution using the dual simplex; {\it Asterisk} (\verb|*|) means that the solver is searching for optimal solution using the primal simplex; {\it Vertical dash} (\verb/|/) means that the solver is searching for optimal solution using the dual simplex. \para{Control parameters} This paragraph describes all control parameters currently used in the simplex solver. Symbolic names of control parameters are names of corresponding members in the structure \verb|glp_smcp|. \bigskip {\tt int msg\_lev} (default: {\tt GLP\_MSG\_ALL}) Message level for terminal output: \verb|GLP_MSG_OFF| --- no output; \verb|GLP_MSG_ERR| --- error and warning messages only; \verb|GLP_MSG_ON | --- normal output; \verb|GLP_MSG_ALL| --- full output (including informational messages). \bigskip {\tt int meth} (default: {\tt GLP\_PRIMAL}) Simplex method option: \verb|GLP_PRIMAL| --- use two-phase primal simplex; \verb|GLP_DUAL | --- use two-phase dual simplex; \verb|GLP_DUALP | --- use two-phase dual simplex, and if it fails, switch to the primal simplex. \bigskip {\tt int pricing} (default: {\tt GLP\_PT\_PSE}) Pricing technique: \verb|GLP_PT_STD| --- standard (``textbook''); \verb|GLP_PT_PSE| --- projected steepest edge. \bigskip {\tt int r\_test} (default: {\tt GLP\_RT\_HAR}) Ratio test technique: \verb|GLP_RT_STD| --- standard (``textbook''); \verb|GLP_RT_HAR| --- Harris' two-pass ratio test. \bigskip {\tt double tol\_bnd} (default: {\tt 1e-7}) Tolerance used to check if the basic solution is primal feasible. (Do not change this parameter without detailed understanding its purpose.) \newpage {\tt double tol\_dj} (default: {\tt 1e-7}) Tolerance used to check if the basic solution is dual feasible. (Do not change this parameter without detailed understanding its purpose.) \bigskip {\tt double tol\_piv} (default: {\tt 1e-9}) Tolerance used to choose eligble pivotal elements of the simplex table. (Do not change this parameter without detailed understanding its purpose.) \bigskip {\tt double obj\_ll} (default: {\tt -DBL\_MAX}) Lower limit of the objective function. If the objective function reaches this limit and continues decreasing, the solver terminates the search. (Used in the dual simplex only.) \bigskip {\tt double obj\_ul} (default: {\tt +DBL\_MAX}) Upper limit of the objective function. If the objective function reaches this limit and continues increasing, the solver terminates the search. (Used in the dual simplex only.) \bigskip {\tt int it\_lim} (default: {\tt INT\_MAX}) Simplex iteration limit. \bigskip {\tt int tm\_lim} (default: {\tt INT\_MAX}) Searching time limit, in milliseconds. \bigskip {\tt int out\_frq} (default: {\tt 500}) Output frequency, in iterations. This parameter specifies how frequently the solver sends information about the solution process to the terminal. \bigskip {\tt int out\_dly} (default: {\tt 0}) Output delay, in milliseconds. This parameter specifies how long the solver should delay sending information about the solution process to the terminal. \bigskip {\tt int presolve} (default: {\tt GLP\_OFF}) LP presolver option: \verb|GLP_ON | --- enable using the LP presolver; \verb|GLP_OFF| --- disable using the LP presolver. \newpage \para{Example 1} The following example main program reads LP problem instance in fixed MPS format from file \verb|25fv47.mps|,\footnote{This instance in fixed MPS format can be found in the Netlib LP collection; see {\tt ftp://ftp.netlib.org/lp/data/}.} constructs an advanced initial basis, solves the instance with the primal simplex method (by default), and writes the solution to file \verb|25fv47.txt|. \begin{footnotesize} \begin{verbatim} /* spxsamp1.c */ #include #include #include int main(void) { glp_prob *P; P = glp_create_prob(); glp_read_mps(P, GLP_MPS_DECK, NULL, "25fv47.mps"); glp_adv_basis(P, 0); glp_simplex(P, NULL); glp_print_sol(P, "25fv47.txt"); glp_delete_prob(P); return 0; } /* eof */ \end{verbatim} \end{footnotesize} Below here is shown the terminal output from this example program. \begin{footnotesize} \begin{verbatim} Reading problem data from `25fv47.mps'... Problem: 25FV47 Objective: R0000 822 rows, 1571 columns, 11127 non-zeros 6919 records were read Crashing... Size of triangular part = 799 0: obj = 1.627307307e+04 infeas = 5.194e+04 (23) 200: obj = 1.474901610e+04 infeas = 1.233e+04 (19) 400: obj = 1.343909995e+04 infeas = 3.648e+03 (13) 600: obj = 1.756052217e+04 infeas = 4.179e+02 (7) * 775: obj = 1.789251591e+04 infeas = 4.982e-14 (1) * 800: obj = 1.663354510e+04 infeas = 2.857e-14 (1) * 1000: obj = 1.024935068e+04 infeas = 1.958e-12 (1) * 1200: obj = 7.860174791e+03 infeas = 2.810e-29 (1) * 1400: obj = 6.642378184e+03 infeas = 2.036e-16 (1) * 1600: obj = 6.037014568e+03 infeas = 0.000e+00 (1) * 1800: obj = 5.662171307e+03 infeas = 6.447e-15 (1) * 2000: obj = 5.528146165e+03 infeas = 9.764e-13 (1) * 2125: obj = 5.501845888e+03 infeas = 0.000e+00 (1) OPTIMAL SOLUTION FOUND Writing basic solution to `25fv47.txt'... \end{verbatim} \end{footnotesize} \newpage \para{Example 2} The following example main program solves the same LP problem instance as in Example 1 above, however, it uses the dual simplex method, which starts from the standard initial basis. \begin{footnotesize} \begin{verbatim} /* spxsamp2.c */ #include #include #include int main(void) { glp_prob *P; glp_smcp parm; P = glp_create_prob(); glp_read_mps(P, GLP_MPS_DECK, NULL, "25fv47.mps"); glp_init_smcp(&parm); parm.meth = GLP_DUAL; glp_simplex(P, &parm); glp_print_sol(P, "25fv47.txt"); glp_delete_prob(P); return 0; } /* eof */ \end{verbatim} \end{footnotesize} Below here is shown the terminal output from this example program. \begin{footnotesize} \begin{verbatim} Reading problem data from `25fv47.mps'... Problem: 25FV47 Objective: R0000 822 rows, 1571 columns, 11127 non-zeros 6919 records were read 0: infeas = 1.223e+03 (516) 200: infeas = 7.000e+00 (471) 240: infeas = 1.106e-14 (461) | 400: obj = -5.394267152e+03 infeas = 5.571e-16 (391) | 600: obj = -4.586395752e+03 infeas = 1.389e-15 (340) | 800: obj = -4.158268146e+03 infeas = 1.640e-15 (264) | 1000: obj = -3.725320045e+03 infeas = 5.181e-15 (245) | 1200: obj = -3.104802163e+03 infeas = 1.019e-14 (210) | 1400: obj = -2.584190499e+03 infeas = 8.865e-15 (178) | 1600: obj = -2.073852927e+03 infeas = 7.867e-15 (142) | 1800: obj = -1.164037407e+03 infeas = 8.792e-15 (109) | 2000: obj = -4.370590250e+02 infeas = 2.591e-14 (85) | 2200: obj = 1.068240144e+03 infeas = 1.025e-13 (70) | 2400: obj = 1.607481126e+03 infeas = 3.272e-14 (67) | 2600: obj = 3.038230551e+03 infeas = 4.850e-14 (52) | 2800: obj = 4.316238187e+03 infeas = 2.622e-14 (36) | 3000: obj = 5.443842629e+03 infeas = 3.976e-15 (11) | 3060: obj = 5.501845888e+03 infeas = 8.806e-15 (2) OPTIMAL SOLUTION FOUND Writing basic solution to `25fv47.txt'... \end{verbatim} \end{footnotesize} \newpage \subsection{glp\_exact --- solve LP problem in exact arithmetic} \synopsis \begin{verbatim} int glp_exact(glp_prob *P, const glp_smcp *parm); \end{verbatim} \description The routine \verb|glp_exact| is a tentative implementation of the primal two-phase simplex method based on exact (rational) arithmetic. It is similar to the routine \verb|glp_simplex|, however, for all internal computations it uses arithmetic of rational numbers, which is exact in mathematical sense, i.e. free of round-off errors unlike floating-point arithmetic. Note that the routine \verb|glp_exact| uses only two control parameters passed in the structure \verb|glp_smcp|, namely, \verb|it_lim| and \verb|tm_lim|. \returns \begin{retlist} 0 & The LP problem instance has been successfully solved. (This code does {\it not} necessarily mean that the solver has found optimal solution. It only means that the solution process was successful.) \\ \verb|GLP_EBADB| & Unable to start the search, because the initial basis specified in the problem object is invalid---the number of basic (auxiliary and structural) variables is not the same as the number of rows in the problem object.\\ \verb|GLP_ESING| & Unable to start the search, because the basis matrix corresponding to the initial basis is exactly singular.\\ \verb|GLP_EBOUND| & Unable to start the search, because some double-bounded (auxiliary or structural) variables have incorrect bounds.\\ \verb|GLP_EFAIL| & The problem instance has no rows/columns.\\ \verb|GLP_EITLIM| & The search was prematurely terminated, because the simplex iteration limit has been exceeded.\\ \verb|GLP_ETMLIM| & The search was prematurely terminated, because the time limit has been exceeded.\\ \end{retlist} \para{Note} Computations in exact arithmetic are very time-consuming, so solving LP problem with the routine \verb|glp_exact| from the very beginning is not a good idea. It is much better at first to find an optimal basis with the routine \verb|glp_simplex| and only then to call \verb|glp_exact|, in which case only a few simplex iterations need to be performed in exact arithmetic. \newpage \subsection{glp\_init\_smcp --- initialize simplex solver control parameters} \synopsis \begin{verbatim} int glp_init_smcp(glp_smcp *parm); \end{verbatim} \description The routine \verb|glp_init_smcp| initializes control parameters, which are used by the simplex solver, with default values. Default values of the control parameters are stored in a \verb|glp_smcp| structure, which the parameter \verb|parm| points to. \subsection{glp\_get\_status --- determine generic status of basic solution} \synopsis \begin{verbatim} int glp_get_status(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_status| reports the generic status of the current basic solution for the specified problem object as follows: \verb|GLP_OPT | --- solution is optimal; \verb|GLP_FEAS | --- solution is feasible; \verb|GLP_INFEAS| --- solution is infeasible; \verb|GLP_NOFEAS| --- problem has no feasible solution; \verb|GLP_UNBND | --- problem has unbounded solution; \verb|GLP_UNDEF | --- solution is undefined. More detailed information about the status of basic solution can be retrieved with the routines \verb|glp_get_prim_stat| and \verb|glp_get_dual_stat|. \subsection{glp\_get\_prim\_stat --- retrieve status of primal basic solution} \synopsis \begin{verbatim} int glp_get_prim_stat(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_prim_stat| reports the status of the primal basic solution for the specified problem object as follows: \verb|GLP_UNDEF | --- primal solution is undefined; \verb|GLP_FEAS | --- primal solution is feasible; \verb|GLP_INFEAS| --- primal solution is infeasible; \verb|GLP_NOFEAS| --- no primal feasible solution exists. \subsection{glp\_get\_dual\_stat --- retrieve status of dual basic solution} \synopsis \begin{verbatim} int glp_get_dual_stat(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_dual_stat| reports the status of the dual basic solution for the specified problem object as follows: \verb|GLP_UNDEF | --- dual solution is undefined; \verb|GLP_FEAS | --- dual solution is feasible; \verb|GLP_INFEAS| --- dual solution is infeasible; \verb|GLP_NOFEAS| --- no dual feasible solution exists. \subsection{glp\_get\_obj\_val --- retrieve objective value} \synopsis \begin{verbatim} double glp_get_obj_val(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_obj_val| returns current value of the objective function. \subsection{glp\_get\_row\_stat --- retrieve row status} \synopsis \begin{verbatim} int glp_get_row_stat(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_stat| returns current status assigned to the auxiliary variable associated with \verb|i|-th row as follows: \verb|GLP_BS| --- basic variable; \verb|GLP_NL| --- non-basic variable on its lower bound; \verb|GLP_NU| --- non-basic variable on its upper bound; \verb|GLP_NF| --- non-basic free (unbounded) variable; \verb|GLP_NS| --- non-basic fixed variable. \newpage \subsection{glp\_get\_row\_prim --- retrieve row primal value} \synopsis \begin{verbatim} double glp_get_row_prim(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_prim| returns primal value of the auxiliary variable associated with \verb|i|-th row. \subsection{glp\_get\_row\_dual --- retrieve row dual value} \synopsis \begin{verbatim} double glp_get_row_dual(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_get_row_dual| returns dual value (i.e. reduced cost) of the auxiliary variable associated with \verb|i|-th row. \subsection{glp\_get\_col\_stat --- retrieve column status} \synopsis \begin{verbatim} int glp_get_col_stat(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_stat| returns current status assigned to the structural variable associated with \verb|j|-th column as follows: \verb|GLP_BS| --- basic variable; \verb|GLP_NL| --- non-basic variable on its lower bound; \verb|GLP_NU| --- non-basic variable on its upper bound; \verb|GLP_NF| --- non-basic free (unbounded) variable; \verb|GLP_NS| --- non-basic fixed variable. \subsection{glp\_get\_col\_prim --- retrieve column primal value} \synopsis \begin{verbatim} double glp_get_col_prim(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_prim| returns primal value of the structural variable associated with \verb|j|-th column. \newpage \subsection{glp\_get\_col\_dual --- retrieve column dual value} \synopsis \begin{verbatim} double glp_get_col_dual(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_dual| returns dual value (i.e. reduced cost) of the structural variable associated with \verb|j|-th column. \subsection{glp\_get\_unbnd\_ray --- determine variable causing unboundedness} \synopsis \begin{verbatim} int glp_get_unbnd_ray(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_unbnd_ray| returns the number $k$ of a variable, which causes primal or dual unboundedness. If $1\leq k\leq m$, it is $k$-th auxiliary variable, and if $m+1\leq k\leq m+n$, it is $(k-m)$-th structural variable, where $m$ is the number of rows, $n$ is the number of columns in the problem object. If such variable is not defined, the routine returns 0. \para{Note} If it is not exactly known which version of the simplex solver detected unboundedness, i.e. whether the unboundedness is primal or dual, it is sufficient to check the status of the variable with the routine \verb|glp_get_row_stat| or \verb|glp_get_col_stat|. If the variable is non-basic, the unboundedness is primal, otherwise, if the variable is basic, the unboundedness is dual (the latter case means that the problem has no primal feasible dolution). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Interior-point method routines} {\it Interior-point methods} (also known as {\it barrier methods}) are more modern and powerful numerical methods for large-scale linear programming. Such methods are especially efficient for very sparse LP problems and allow solving such problems much faster than the simplex method. In brief, the GLPK interior-point solver works as follows. At first, the solver transforms the original LP to a {\it working} LP in the standard format: \medskip \noindent \hspace{.5in} minimize $$z = c_1x_{m+1} + c_2x_{m+2} + \dots + c_nx_{m+n} + c_0 \eqno (2.4)$$ \hspace{.5in} subject to linear constraints $$ \begin{array}{r@{\:}c@{\:}r@{\:}c@{\:}r@{\:}c@{\:}l} a_{11}x_{m+1}&+&a_{12}x_{m+2}&+ \dots +&a_{1n}x_{m+n}&=&b_1 \\ a_{21}x_{m+1}&+&a_{22}x_{m+2}&+ \dots +&a_{2n}x_{m+n}&=&b_2 \\ \multicolumn{7}{c} {.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .} \\ a_{m1}x_{m+1}&+&a_{m2}x_{m+2}&+ \dots +&a_{mn}x_{m+n}&=&b_m \\ \end{array} \eqno (2.5) $$ \hspace{.5in} and non-negative variables $$x_1\geq 0,\ \ x_2\geq 0,\ \ \dots,\ \ x_n\geq 0 \eqno(2.6)$$ where: $z$ is the objective function; $x_1$, \dots, $x_n$ are variables; $c_1$, \dots, $c_n$ are objective coefficients; $c_0$ is a constant term of the objective function; $a_{11}$, \dots, $a_{mn}$ are constraint coefficients; $b_1$, \dots, $b_m$ are right-hand sides. Using vector and matrix notations the working LP (2.4)---(2.6) can be written as follows: $$z=c^Tx+c_0\ \rightarrow\ \min,\eqno(2.7)$$ $$Ax=b,\eqno(2.8)$$ $$x\geq 0,\eqno(2.9)$$ where: $x=(x_j)$ is $n$-vector of variables, $c=(c_j)$ is $n$-vector of objective coefficients, $A=(a_{ij})$ is $m\times n$-matrix of constraint coefficients, and $b=(b_i)$ is $m$-vector of right-hand sides. Karush--Kuhn--Tucker optimality conditions for LP (2.7)---(2.9) are the following: $$Ax=b,\eqno(2.10)$$ $$A^T\pi+\lambda=c,\eqno(2.11)$$ $$\lambda^Tx=0,\eqno(2.12)$$ $$x\geq 0,\ \ \lambda\geq 0,\eqno(2.13)$$ where: $\pi$ is $m$-vector of Lagrange multipliers (dual variables) for equality constraints (2.8),\linebreak $\lambda$ is $n$-vector of Lagrange multipliers (dual variables) for non-negativity constraints (2.9),\linebreak (2.10) is the primal feasibility condition, (2.11) is the dual feasibility condition, (2.12) is the primal-dual complementarity condition, and (2.13) is the non-negativity conditions. The main idea of the primal-dual interior-point method is based on finding a point in the primal-dual space (i.e. in the space of all primal and dual variables $x$, $\pi$, and $\lambda$), which satisfies to all optimality conditions (2.10)---(2.13). Obviously, $x$-component of such point then provides an optimal solution to the working LP (2.7)---(2.9). To find the optimal point $(x^*,\pi^*,\lambda^*)$ the interior-point method attempts to solve the system of equations (2.10)---(2.12), which is closed in the sense that the number of variables $x_j$, $\pi_i$, and $\lambda_j$ and the number equations are the same and equal to $m+2n$. Due to condition (2.12) this system of equations is non-linear, so it can be solved with a version of {\it Newton's method} provided with additional rules to keep the current point within the positive orthant as required by the non-negativity conditions (2.13). Finally, once the optimal point $(x^*,\pi^*,\lambda^*)$ has been found, the solver performs inverse transformations to recover corresponding solution to the original LP passed to the solver from the application program. \subsection{glp\_interior --- solve LP problem with the interior-point method} \synopsis \begin{verbatim} int glp_interior(glp_prob *P, const glp_iptcp *parm); \end{verbatim} \description The routine \verb|glp_interior| is a driver to the LP solver based on the primal-dual interior-point method. This routine retrieves problem data from the specified problem object, calls the solver to solve the problem instance, and stores results of computations back into the problem object. The interior-point solver has a set of control parameters. Values of the control parameters can be passed in the structure \verb|glp_iptcp|, which the parameter \verb|parm| points to. For detailed description of this structure see paragraph ``Control parameters'' below. Before specifying some control parameters the application program should initialize the structure \verb|glp_iptcp| by default values of all control parameters using the routine \verb|glp_init_iptcp| (see the next subsection). This is needed for backward compatibility, because in the future there may appear new members in the structure \verb|glp_iptcp|. The parameter \verb|parm| can be specified as \verb|NULL|, in which case the solver uses default settings. \returns \begin{retlist} 0 & The LP problem instance has been successfully solved. (This code does {\it not} necessarily mean that the solver has found optimal solution. It only means that the solution process was successful.) \\ \verb|GLP_EFAIL| & The problem has no rows/columns.\\ \verb|GLP_ENOCVG| & Very slow convergence or divergence.\\ \verb|GLP_EITLIM| & Iteration limit exceeded.\\ \verb|GLP_EINSTAB| & Numerical instability on solving Newtonian system.\\ \end{retlist} \newpage \para{Comments} The routine \verb|glp_interior| implements an easy version of the primal-dual interior-point method based on Mehrotra's technique.\footnote{S. Mehrotra. On the implementation of a primal-dual interior point method. SIAM J. on Optim., 2(4), pp. 575-601, 1992.} Note that currently the GLPK interior-point solver does not include many important features, in particular: \vspace*{-8pt} \begin{itemize} \item it is not able to process dense columns. Thus, if the constraint matrix of the LP problem has dense columns, the solving process may be inefficient; \item it has no features against numerical instability. For some LP problems premature termination may happen if the matrix $ADA^T$ becomes singular or ill-conditioned; \item it is not able to identify the optimal basis, which corresponds to the interior-point solution found. \end{itemize} \vspace*{-8pt} \para{Terminal output} Solving large LP problems may take a long time, so the solver reports some information about every interior-point iteration,\footnote{Unlike the simplex method the interior point method usually needs 30---50 iterations (independently on the problem size) in order to find an optimal solution.} which is sent to the terminal. This information has the following format: \begin{verbatim} nnn: obj = fff; rpi = ppp; rdi = ddd; gap = ggg \end{verbatim} \noindent where: \verb|nnn| is iteration number, \verb|fff| is the current value of the objective function (in the case of maximization it has wrong sign), \verb|ppp| is the current relative primal infeasibility (cf. (2.10)): $$\frac{\|Ax^{(k)}-b\|}{1+\|b\|},\eqno(2.14)$$ \verb|ddd| is the current relative dual infeasibility (cf. (2.11)): $$\frac{\|A^T\pi^{(k)}+\lambda^{(k)}-c\|}{1+\|c\|},\eqno(2.15)$$ \verb|ggg| is the current primal-dual gap (cf. (2.12)): $$\frac{|c^Tx^{(k)}-b^T\pi^{(k)}|}{1+|c^Tx^{(k)}|},\eqno(2.16)$$ and $[x^{(k)},\pi^{(k)},\lambda^{(k)}]$ is the current point on $k$-th iteration, $k=0,1,2,\dots$\ . Note that all solution components are internally scaled, so information sent to the terminal is suitable only for visual inspection. \newpage \para{Control parameters} This paragraph describes all control parameters currently used in the interior-point solver. Symbolic names of control parameters are names of corresponding members in the structure \verb|glp_iptcp|. \bigskip {\tt int msg\_lev} (default: {\tt GLP\_MSG\_ALL}) Message level for terminal output: \verb|GLP_MSG_OFF|---no output; \verb|GLP_MSG_ERR|---error and warning messages only; \verb|GLP_MSG_ON |---normal output; \verb|GLP_MSG_ALL|---full output (including informational messages). \bigskip {\tt int ord\_alg} (default: {\tt GLP\_ORD\_AMD}) Ordering algorithm used prior to Cholesky factorization: \verb|GLP_ORD_NONE |---use natural (original) ordering; \verb|GLP_ORD_QMD |---quotient minimum degree (QMD); \verb|GLP_ORD_AMD |---approximate minimum degree (AMD); \verb|GLP_ORD_SYMAMD|---approximate minimum degree (SYMAMD). \bigskip \para{Example} The following main program reads LP problem instance in fixed MPS format from file\linebreak \verb|25fv47.mps|,\footnote{This instance in fixed MPS format can be found in the Netlib LP collection; see {\tt ftp://ftp.netlib.org/lp/data/}.} solves it with the interior-point solver, and writes the solution to file \verb|25fv47.txt|. \begin{footnotesize} \begin{verbatim} /* iptsamp.c */ #include #include #include int main(void) { glp_prob *P; P = glp_create_prob(); glp_read_mps(P, GLP_MPS_DECK, NULL, "25fv47.mps"); glp_interior(P, NULL); glp_print_ipt(P, "25fv47.txt"); glp_delete_prob(P); return 0; } /* eof */ \end{verbatim} \end{footnotesize} \newpage Below here is shown the terminal output from this example program. \begin{footnotesize} \begin{verbatim} Reading problem data from `25fv47.mps'... Problem: 25FV47 Objective: R0000 822 rows, 1571 columns, 11127 non-zeros 6919 records were read Original LP has 822 row(s), 1571 column(s), and 11127 non-zero(s) Working LP has 821 row(s), 1876 column(s), and 10705 non-zero(s) Matrix A has 10705 non-zeros Matrix S = A*A' has 11895 non-zeros (upper triangle) Minimal degree ordering... Computing Cholesky factorization S = L'*L... Matrix L has 35411 non-zeros Guessing initial point... Optimization begins... 0: obj = 1.823377629e+05; rpi = 1.3e+01; rdi = 1.4e+01; gap = 9.3e-01 1: obj = 9.260045192e+04; rpi = 5.3e+00; rdi = 5.6e+00; gap = 6.8e+00 2: obj = 3.596999742e+04; rpi = 1.5e+00; rdi = 1.2e+00; gap = 1.8e+01 3: obj = 1.989627568e+04; rpi = 4.7e-01; rdi = 3.0e-01; gap = 1.9e+01 4: obj = 1.430215557e+04; rpi = 1.1e-01; rdi = 8.6e-02; gap = 1.4e+01 5: obj = 1.155716505e+04; rpi = 2.3e-02; rdi = 2.4e-02; gap = 6.8e+00 6: obj = 9.660273208e+03; rpi = 6.7e-03; rdi = 4.6e-03; gap = 3.9e+00 7: obj = 8.694348283e+03; rpi = 3.7e-03; rdi = 1.7e-03; gap = 2.0e+00 8: obj = 8.019543639e+03; rpi = 2.4e-03; rdi = 3.9e-04; gap = 1.0e+00 9: obj = 7.122676293e+03; rpi = 1.2e-03; rdi = 1.5e-04; gap = 6.6e-01 10: obj = 6.514534518e+03; rpi = 6.1e-04; rdi = 4.3e-05; gap = 4.1e-01 11: obj = 6.361572203e+03; rpi = 4.8e-04; rdi = 2.2e-05; gap = 3.0e-01 12: obj = 6.203355508e+03; rpi = 3.2e-04; rdi = 1.7e-05; gap = 2.6e-01 13: obj = 6.032943411e+03; rpi = 2.0e-04; rdi = 9.3e-06; gap = 2.1e-01 14: obj = 5.796553021e+03; rpi = 9.8e-05; rdi = 3.2e-06; gap = 1.0e-01 15: obj = 5.667032431e+03; rpi = 4.4e-05; rdi = 1.1e-06; gap = 5.6e-02 16: obj = 5.613911867e+03; rpi = 2.5e-05; rdi = 4.1e-07; gap = 3.5e-02 17: obj = 5.560572626e+03; rpi = 9.9e-06; rdi = 2.3e-07; gap = 2.1e-02 18: obj = 5.537276001e+03; rpi = 5.5e-06; rdi = 8.4e-08; gap = 1.1e-02 19: obj = 5.522746942e+03; rpi = 2.2e-06; rdi = 4.0e-08; gap = 6.7e-03 20: obj = 5.509956679e+03; rpi = 7.5e-07; rdi = 1.8e-08; gap = 2.9e-03 21: obj = 5.504571733e+03; rpi = 1.6e-07; rdi = 5.8e-09; gap = 1.1e-03 22: obj = 5.502576367e+03; rpi = 3.4e-08; rdi = 1.0e-09; gap = 2.5e-04 23: obj = 5.502057119e+03; rpi = 8.1e-09; rdi = 3.0e-10; gap = 7.7e-05 24: obj = 5.501885996e+03; rpi = 9.4e-10; rdi = 1.2e-10; gap = 2.4e-05 25: obj = 5.501852464e+03; rpi = 1.4e-10; rdi = 1.2e-11; gap = 3.0e-06 26: obj = 5.501846549e+03; rpi = 1.4e-11; rdi = 1.2e-12; gap = 3.0e-07 27: obj = 5.501845954e+03; rpi = 1.4e-12; rdi = 1.2e-13; gap = 3.0e-08 28: obj = 5.501845895e+03; rpi = 1.5e-13; rdi = 1.2e-14; gap = 3.0e-09 OPTIMAL SOLUTION FOUND Writing interior-point solution to `25fv47.txt'... \end{verbatim} \end{footnotesize} \newpage \subsection{glp\_init\_iptcp --- initialize interior-point solver control parameters} \synopsis \begin{verbatim} int glp_init_iptcp(glp_iptcp *parm); \end{verbatim} \description The routine \verb|glp_init_iptcp| initializes control parameters, which are used by the interior-point solver, with default values. Default values of the control parameters are stored in the structure \verb|glp_iptcp|, which the parameter \verb|parm| points to. \subsection{glp\_ipt\_status --- determine solution status} \synopsis \begin{verbatim} int glp_ipt_status(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_ipt_status| reports the status of a solution found by the interior-point solver as follows: \verb|GLP_UNDEF | --- interior-point solution is undefined; \verb|GLP_OPT | --- interior-point solution is optimal; \verb|GLP_INFEAS| --- interior-point solution is infeasible; \verb|GLP_NOFEAS| --- no feasible primal-dual solution exists. \subsection{glp\_ipt\_obj\_val --- retrieve objective value} \synopsis \begin{verbatim} double glp_ipt_obj_val(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_ipt_obj_val| returns value of the objective function for interior-point solution. \subsection{glp\_ipt\_row\_prim --- retrieve row primal value} \synopsis \begin{verbatim} double glp_ipt_row_prim(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_ipt_row_prim| returns primal value of the auxiliary variable associated with \verb|i|-th row. \newpage \subsection{glp\_ipt\_row\_dual --- retrieve row dual value} \synopsis \begin{verbatim} double glp_ipt_row_dual(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_ipt_row_dual| returns dual value (i.e. reduced cost) of the auxiliary variable associated with \verb|i|-th row. \subsection{glp\_ipt\_col\_prim --- retrieve column primal value} \synopsis \begin{verbatim} double glp_ipt_col_prim(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_ipt_col_prim| returns primal value of the structural variable associated with \verb|j|-th column. \subsection{glp\_ipt\_col\_dual --- retrieve column dual value} \synopsis \begin{verbatim} double glp_ipt_col_dual(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_ipt_col_dual| returns dual value (i.e. reduced cost) of the structural variable associated with \verb|j|-th column. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Mixed integer programming routines} \subsection{glp\_set\_col\_kind --- set (change) column kind} \synopsis \begin{verbatim} void glp_set_col_kind(glp_prob *P, int j, int kind); \end{verbatim} \description The routine \verb|glp_set_col_kind| sets (changes) the kind of \verb|j|-th column (structural variable) as specified by the parameter \verb|kind|: \verb|GLP_CV| --- continuous variable; \verb|GLP_IV| --- integer variable; \verb|GLP_BV| --- binary variable. Setting a column to \verb|GLP_BV| has the same effect as if it were set to \verb|GLP_IV|, its lower bound were set 0, and its upper bound were set to 1. \subsection{glp\_get\_col\_kind --- retrieve column kind} \synopsis \begin{verbatim} int glp_get_col_kind(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_get_col_kind| returns the kind of \verb|j|-th column (structural variable) as follows: \verb|GLP_CV| --- continuous variable; \verb|GLP_IV| --- integer variable; \verb|GLP_BV| --- binary variable. \subsection{glp\_get\_num\_int --- retrieve number of integer columns} \synopsis \begin{verbatim} int glp_get_num_int(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_num_int| returns the number of columns (structural variables), which are marked as integer. Note that this number {\it does} include binary columns. \newpage \subsection{glp\_get\_num\_bin --- retrieve number of binary columns} \synopsis \begin{verbatim} int glp_get_num_bin(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_get_num_bin| returns the number of columns (structural variables), which are marked as integer and whose lower bound is zero and upper bound is one. \subsection{glp\_intopt --- solve MIP problem with the branch-and-cut method} \synopsis \begin{verbatim} int glp_intopt(glp_prob *P, const glp_iocp *parm); \end{verbatim} \description The routine \verb|glp_intopt| is a driver to the MIP solver based on the branch-and-cut method, which is a hybrid of branch-and-bound and cutting plane methods. If the presolver is disabled (see paragraph ``Control parameters'' below), on entry to the routine \verb|glp_intopt| the problem object, which the parameter \verb|mip| points to, should contain optimal solution to LP relaxation (it can be obtained, for example, with the routine \verb|glp_simplex|). Otherwise, if the presolver is enabled, it is not necessary. The MIP solver has a set of control parameters. Values of the control parameters can be passed in the structure \verb|glp_iocp|, which the parameter \verb|parm| points to. For detailed description of this structure see paragraph ``Control parameters'' below. Before specifying some control parameters the application program should initialize the structure \verb|glp_iocp| by default values of all control parameters using the routine \verb|glp_init_iocp| (see the next subsection). This is needed for backward compatibility, because in the future there may appear new members in the structure \verb|glp_iocp|. The parameter \verb|parm| can be specified as \verb|NULL|, in which case the solver uses default settings. Note that the GLPK branch-and-cut solver is not perfect, so it is unable to solve hard or very large scale MIP instances for a reasonable time. \returns \begin{retlist} 0 & The MIP problem instance has been successfully solved. (This code does {\it not} necessarily mean that the solver has found optimal solution. It only means that the solution process was successful.) \\ \verb|GLP_EBOUND| & Unable to start the search, because some double-bounded variables have incorrect bounds or some integer variables have non-integer (fractional) bounds.\\ \verb|GLP_EROOT| & Unable to start the search, because optimal basis for initial LP relaxation is not provided. (This code may appear only if the presolver is disabled.)\\ \verb|GLP_ENOPFS| & Unable to start the search, because LP relaxation of the MIP problem instance has no primal feasible solution. (This code may appear only if the presolver is enabled.)\\ \end{retlist} \newpage \begin{retlist} \verb|GLP_ENODFS| & Unable to start the search, because LP relaxation of the MIP problem instance has no dual feasible solution. In other word, this code means that if the LP relaxation has at least one primal feasible solution, its optimal solution is unbounded, so if the MIP problem has at least one integer feasible solution, its (integer) optimal solution is also unbounded. (This code may appear only if the presolver is enabled.)\\ \verb|GLP_EFAIL| & The search was prematurely terminated due to the solver failure.\\ \verb|GLP_EMIPGAP| & The search was prematurely terminated, because the relative mip gap tolerance has been reached.\\ \verb|GLP_ETMLIM| & The search was prematurely terminated, because the time limit has been exceeded.\\ \verb|GLP_ESTOP| & The search was prematurely terminated by application. (This code may appear only if the advanced solver interface is used.)\\ \end{retlist} \para{Built-in MIP presolver} The branch-and-cut solver has {\it built-in MIP presolver}. It is a subprogram that transforms the original MIP problem specified in the problem object to an equivalent MIP problem, which may be easier for solving with the branch-and-cut method than the original one. For example, the presolver can remove redundant constraints and variables, whose optimal values are known, perform bound and coefficient reduction, etc. Once the transformed MIP problem has been solved, the presolver transforms its solution back to corresponding solution of the original problem. Presolving is an optional feature of the routine \verb|glp_intopt|, and by default it is disabled. In order to enable the MIP presolver, the control parameter \verb|presolve| should be set to \verb|GLP_ON| (see paragraph ``Control parameters'' below). \para{Advanced solver interface} The routine \verb|glp_intopt| allows the user to control the branch-and-cut search by passing to the solver a user-defined callback routine. For more details see Chapter ``Branch-and-Cut API Routines''. \para{Terminal output} Solving a MIP problem may take a long time, so the solver reports some information about best known solutions, which is sent to the terminal. This information has the following format: \begin{verbatim} +nnn: mip = xxx yyy gap (ppp; qqq) \end{verbatim} \noindent where: `\verb|nnn|' is the simplex iteration number; `\verb|xxx|' is a value of the objective function for the best known integer feasible solution (if no integer feasible solution has been found yet, `\verb|xxx|' is the text `\verb|not found yet|'); `\verb|rho|' is the string `\verb|>=|' (in case of minimization) or `\verb|<=|' (in case of maximization); `\verb|yyy|' is a global bound for exact integer optimum (i.e. the exact integer optimum is always in the range from `\verb|xxx|' to `\verb|yyy|'); `\verb|gap|' is the relative mip gap, in percents, computed as $gap=|xxx-yyy|/(|xxx|+{\tt DBL\_EPSILON})\cdot 100\%$ (if $gap$ is greater than $999.9\%$, it is not printed); `\verb|ppp|' is the number of subproblems in the active list, `\verb|qqq|' is the number of subproblems which have been already fathomed and therefore removed from the branch-and-bound search tree. \newpage \subsubsection{Control parameters} This paragraph describes all control parameters currently used in the MIP solver. Symbolic names of control parameters are names of corresponding members in the structure \verb|glp_iocp|. \bigskip\vspace*{-2pt} {\tt int msg\_lev} (default: {\tt GLP\_MSG\_ALL}) Message level for terminal output: \verb|GLP_MSG_OFF| --- no output; \verb|GLP_MSG_ERR| --- error and warning messages only; \verb|GLP_MSG_ON | --- normal output; \verb|GLP_MSG_ALL| --- full output (including informational messages). \bigskip\vspace*{-2pt} {\tt int br\_tech} (default: {\tt GLP\_BR\_DTH}) Branching technique option: \verb|GLP_BR_FFV| --- first fractional variable; \verb|GLP_BR_LFV| --- last fractional variable; \verb|GLP_BR_MFV| --- most fractional variable; \verb|GLP_BR_DTH| --- heuristic by Driebeck and Tomlin; \verb|GLP_BR_PCH| --- hybrid pseudo-cost heuristic. \bigskip\vspace*{-2pt} {\tt int bt\_tech} (default: {\tt GLP\_BT\_BLB}) Backtracking technique option: \verb|GLP_BT_DFS| --- depth first search; \verb|GLP_BT_BFS| --- breadth first search; \verb|GLP_BT_BLB| --- best local bound; \verb|GLP_BT_BPH| --- best projection heuristic. \bigskip\vspace*{-2pt} {\tt int pp\_tech} (default: {\tt GLP\_PP\_ALL}) Preprocessing technique option: \verb|GLP_PP_NONE| --- disable preprocessing; \verb|GLP_PP_ROOT| --- perform preprocessing only on the root level; \verb|GLP_PP_ALL | --- perform preprocessing on all levels. \bigskip\vspace*{-2pt} {\tt int sr\_heur} (default: {\tt GLP\_ON}) Simple rounding heuristic option: \verb|GLP_ON | --- enable applying the simple rounding heuristic; \verb|GLP_OFF| --- disable applying the simple rounding heuristic. \newpage {\tt int fp\_heur} (default: {\tt GLP\_OFF}) Feasibility pump heuristic option: \verb|GLP_ON | --- enable applying the feasibility pump heuristic; \verb|GLP_OFF| --- disable applying the feasibility pump heuristic. \bigskip {\tt int ps\_heur} (default: {\tt GLP\_OFF}) Proximity search heuristic\footnote{The Fischetti--Monaci Proximity Search (a.k.a. Proxy) heuristic. This algorithm is often capable of rapidly improving a feasible solution of a MIP problem with binary variables. It allows to quickly obtain suboptimal solutions in some problems which take too long time to be solved to optimality.} option: \verb|GLP_ON | --- enable applying the proximity search heuristic; \verb|GLP_OFF| --- disable applying the proximity search pump heuristic. \bigskip {\tt int ps\_tm\_lim} (default: {\tt 60000}) Time limit, in milliseconds, for the proximity search heuristic (see above). \bigskip {\tt int gmi\_cuts} (default: {\tt GLP\_OFF}) Gomory's mixed integer cut option: \verb|GLP_ON | --- enable generating Gomory's cuts; \verb|GLP_OFF| --- disable generating Gomory's cuts. \bigskip {\tt int mir\_cuts} (default: {\tt GLP\_OFF}) Mixed integer rounding (MIR) cut option: \verb|GLP_ON | --- enable generating MIR cuts; \verb|GLP_OFF| --- disable generating MIR cuts. \bigskip {\tt int cov\_cuts} (default: {\tt GLP\_OFF}) Mixed cover cut option: \verb|GLP_ON | --- enable generating mixed cover cuts; \verb|GLP_OFF| --- disable generating mixed cover cuts. \bigskip {\tt int clq\_cuts} (default: {\tt GLP\_OFF}) Clique cut option: \verb|GLP_ON | --- enable generating clique cuts; \verb|GLP_OFF| --- disable generating clique cuts. \newpage {\tt double tol\_int} (default: {\tt 1e-5}) Absolute tolerance used to check if optimal solution to the current LP relaxation is integer feasible. (Do not change this parameter without detailed understanding its purpose.) \bigskip {\tt double tol\_obj} (default: {\tt 1e-7}) Relative tolerance used to check if the objective value in optimal solution to the current LP relaxation is not better than in the best known integer feasible solution. (Do not change this parameter without detailed understanding its purpose.) \bigskip {\tt double mip\_gap} (default: {\tt 0.0}) The relative mip gap tolerance. If the relative mip gap for currently known best integer feasible solution falls below this tolerance, the solver terminates the search. This allows obtainig suboptimal integer feasible solutions if solving the problem to optimality takes too long time. \bigskip {\tt int tm\_lim} (default: {\tt INT\_MAX}) Searching time limit, in milliseconds. \bigskip {\tt int out\_frq} (default: {\tt 5000}) Output frequency, in milliseconds. This parameter specifies how frequently the solver sends information about the solution process to the terminal. \bigskip {\tt int out\_dly} (default: {\tt 10000}) Output delay, in milliseconds. This parameter specifies how long the solver should delay sending information about solution of the current LP relaxation with the simplex method to the terminal. \bigskip {\tt void (*cb\_func)(glp\_tree *tree, void *info)} (default: {\tt NULL}) Entry point to the user-defined callback routine. \verb|NULL| means the advanced solver interface is not used. For more details see Chapter ``Branch-and-Cut API Routines''. \bigskip {\tt void *cb\_info} (default: {\tt NULL}) Transit pointer passed to the routine \verb|cb_func| (see above). \bigskip {\tt int cb\_size} (default: {\tt 0}) The number of extra (up to 256) bytes allocated for each node of the branch-and-bound tree to store application-specific data. On creating a node these bytes are initialized by binary zeros. \bigskip {\tt int presolve} (default: {\tt GLP\_OFF}) MIP presolver option: \verb|GLP_ON | --- enable using the MIP presolver; \verb|GLP_OFF| --- disable using the MIP presolver. \newpage {\tt int binarize} (default: {\tt GLP\_OFF}) Binarization option (used only if the presolver is enabled): \verb|GLP_ON | --- replace general integer variables by binary ones; \verb|GLP_OFF| --- do not use binarization. \subsection{glp\_init\_iocp --- initialize integer optimizer control parameters} \synopsis \begin{verbatim} void glp_init_iocp(glp_iocp *parm); \end{verbatim} \description The routine \verb|glp_init_iocp| initializes control parameters, which are used by the branch-and-cut solver, with default values. Default values of the control parameters are stored in a \verb|glp_iocp| structure, which the parameter \verb|parm| points to. \subsection{glp\_mip\_status --- determine status of MIP solution} \synopsis \begin{verbatim} int glp_mip_status(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_mip_status| reports the status of a MIP solution found by the MIP solver as follows: \verb|GLP_UNDEF | --- MIP solution is undefined; \verb|GLP_OPT | --- MIP solution is integer optimal; \verb|GLP_FEAS | --- MIP solution is integer feasible, however, its optimality (or non-optimality) has not been proven, perhaps due to premature termination of the search; \verb|GLP_NOFEAS| --- problem has no integer feasible solution (proven by the solver). \subsection{glp\_mip\_obj\_val --- retrieve objective value} \synopsis \begin{verbatim} double glp_mip_obj_val(glp_prob *P); \end{verbatim} \returns The routine \verb|glp_mip_obj_val| returns value of the objective function for MIP solution. \subsection{glp\_mip\_row\_val --- retrieve row value} \synopsis \begin{verbatim} double glp_mip_row_val(glp_prob *P, int i); \end{verbatim} \returns The routine \verb|glp_mip_row_val| returns value of the auxiliary variable associated with \verb|i|-th row for MIP solution. \subsection{glp\_mip\_col\_val --- retrieve column value} \synopsis \begin{verbatim} double glp_mip_col_val(glp_prob *P, int j); \end{verbatim} \returns The routine \verb|glp_mip_col_val| returns value of the structural variable associated with \verb|j|-th column for MIP solution. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newpage \section{Additional routines} \subsection{glp\_check\_kkt --- check feasibility/optimality conditions} \synopsis {\parskip=0pt \tt void glp\_check\_kkt(glp\_prob *P, int sol, int cond, double *ae\_max, int *ae\_ind, \hspace{105pt}double *re\_max, int *re\_ind);} \description The routine \verb|glp_check_kkt| allows to check feasibility/optimality conditions for the current solution stored in the specified problem object. (For basic and interior-point solutions these conditions are known as {\it Karush--Kuhn--Tucker optimality conditions}.) The parameter \verb|sol| specifies which solution should be checked: \verb|GLP_SOL| --- basic solution; \verb|GLP_IPT| --- interior-point solution; \verb|GLP_MIP| --- mixed integer solution. The parameter \verb|cond| specifies which condition should be checked: \verb|GLP_KKT_PE| --- check primal equality constraints (KKT.PE); \verb|GLP_KKT_PB| --- check primal bound constraints (KKT.PB); \verb|GLP_KKT_DE| --- check dual equality constraints (KKT.DE). This conditions can be checked only for basic or interior-point solution; \verb|GLP_KKT_DB| --- check dual bound constraints (KKT.DB). This conditions can be checked only for basic or interior-point solution. Detailed explanations of these conditions are given below in paragraph ``Background''. On exit the routine stores the following information to locations specified by parameters \verb|ae_max|, \verb|ae_ind|, \verb|re_max|, and \verb|re_ind| (if some parameter is a null pointer, corresponding information is not stored): \verb|ae_max| --- largest absolute error; \verb|ae_ind| --- number of row (KKT.PE), column (KKT.DE), or variable (KKT.PB, KKT.DB) with the largest absolute error; \verb|re_max| --- largest relative error; \verb|re_ind| --- number of row (KKT.PE), column (KKT.DE), or variable (KKT.PB, KKT.DB) with the largest relative error. Row (auxiliary variable) numbers are in the range 1 to $m$, where $m$ is the number of rows in the problem object. Column (structural variable) numbers are in the range 1 to $n$, where $n$ is the number of columns in the problem object. Variable numbers are in the range 1 to $m+n$, where variables with numbers 1 to $m$ correspond to rows, and variables with numbers $m+1$ to $m+n$ correspond to columns. If the error reported is exact zero, corresponding row, column or variable number is set to zero. \para{Background} \def\arraystretch{1.5} The first condition checked by the routine is the following: $$x_R - A x_S = 0, \eqno{\rm (KKT.PE)}$$ where $x_R$ is the subvector of auxiliary variables (rows), $x_S$ is the subvector of structural variables (columns), $A$ is the constraint matrix. This condition expresses the requirement that all primal variables should satisfy to the system of equality constraints of the original LP problem. In case of exact arithmetic this condition would be satisfied for any basic solution; however, in case of inexact (floating-point) arithmetic, this condition shows how accurate the primal solution is, that depends on accuracy of a representation of the basis matrix used by the simplex method, or on accuracy provided by the interior-point method. To check the condition (KKT.PE) the routine computes the vector of residuals: $$g = x_R - A x_S,$$ and determines component of this vector that correspond to largest absolute and relative errors: $${\tt ae\_max}=\max_{1\leq i\leq m}|g_i|,$$ $${\tt re\_max}=\max_{1\leq i\leq m}\frac{|g_i|}{1+|(x_R)_i|}.$$ The second condition checked by the routine is the following: $$l_k \leq x_k \leq u_k {\rm \ \ \ for\ all}\ k=1,\dots,m+n, \eqno{\rm (KKT.PB)}$$ where $x_k$ is auxiliary ($1\leq k\leq m$) or structural ($m+1\leq k\leq m+n$) variable, $l_k$ and $u_k$ are, respectively, lower and upper bounds of the variable $x_k$ (including cases of infinite bounds). This condition expresses the requirement that all primal variables shoudl satisfy to bound constraints of the original LP problem. In case of basic solution all non-basic variables are placed on their active bounds, so actually the condition (KKT.PB) needs to be checked for basic variables only. If the primal solution has sufficient accuracy, this condition shows its primal feasibility. To check the condition (KKT.PB) the routine computes a vector of residuals: $$ h_k = \left\{ \begin{array}{ll} 0, & {\rm if}\ l_k \leq x_k \leq u_k \\ x_k - l_k, & {\rm if}\ x_k < l_k \\ x_k - u_k, & {\rm if}\ x_k > u_k \\ \end{array} \right. $$ for all $k=1,\dots,m+n$, and determines components of this vector that correspond to largest absolute and relative errors: $${\tt ae\_max}=\max_{1\leq k \leq m+n}|h_k|,$$ $${\tt re\_max}=\max_{1\leq k \leq m+n}\frac{|h_k|}{1+|x_k|}.$$ The third condition checked by the routine is: $${\rm grad}\;Z = c = (\tilde{A})^T \pi + d,$$ where $Z$ is the objective function, $c$ is the vector of objective coefficients, $(\tilde{A})^T$ is a matrix transposed to the expanded constraint matrix $\tilde{A} = (I|-A)$, $\pi$ is a vector of Lagrange multipliers that correspond to equality constraints of the original LP problem, $d$ is a vector of Lagrange multipliers that correspond to bound constraints for all (auxiliary and structural) variables of the original LP problem. Geometrically the third condition expresses the requirement that the gradient of the objective function should belong to the orthogonal complement of a linear subspace defined by the equality and active bound constraints, i.e. that the gradient is a linear combination of normals to the constraint hyperplanes, where Lagrange multipliers $\pi$ and $d$ are coefficients of that linear combination. To eliminate the vector $\pi$ rewrite the third condition as: $$ \left(\begin{array}{@{}c@{}}I \\ -A^T\end{array}\right) \pi = \left(\begin{array}{@{}c@{}}d_R \\ d_S\end{array}\right) + \left(\begin{array}{@{}c@{}}c_R \\ c_S\end{array}\right), $$ or, equivalently, $$ \left\{ \begin{array}{r@{}c@{}c} \pi + d_R&\ =\ &c_R, \\ -A^T\pi + d_S&\ =\ &c_S. \\ \end{array} \right. $$ Then substituting the vector $\pi$ from the first equation into the second we finally have: $$A^T (d_R - c_R) + (d_S - c_S) = 0, \eqno{\rm(KKT.DE)}$$ where $d_R$ is the subvector of reduced costs of auxiliary variables (rows), $d_S$ is the subvector of reduced costs of structural variables (columns), $c_R$ and $c_S$ are subvectors of objective coefficients at, respectively, auxiliary and structural variables, $A^T$ is a matrix transposed to the constraint matrix of the original LP problem. In case of exact arithmetic this condition would be satisfied for any basic solution; however, in case of inexact (floating-point) arithmetic, this condition shows how accurate the dual solution is, that depends on accuracy of a representation of the basis matrix used by the simplex method, or on accuracy provided by the interior-point method. To check the condition (KKT.DE) the routine computes a vector of residuals: $$u = A^T (d_R - c_R) + (d_S - c_S),$$ and determines components of this vector that correspond to largest absolute and relative errors: $${\tt ae\_max}=\max_{1\leq j\leq n}|u_j|,$$ $${\tt re\_max}=\max_{1\leq j\leq n}\frac{|u_j|}{1+|(d_S)_j-(c_S)_j|}.$$ \newpage The fourth condition checked by the routine is the following: $$ \left\{ \begin{array}{l@{\ }r@{\ }c@{\ }c@{\ }c@{\ }l@{\ }c@{\ }c@{\ }c@{\ }l} {\rm if} & -\infty & < & x_k & < & +\infty, & {\rm then} & d_k & = & 0 \\ {\rm if} & l_k & \leq & x_k & < & +\infty, & {\rm then} & d_k & \geq & 0\ {\rm(minimization)} \\ &&&&&& & d_k & \leq & 0\ {\rm(maximization)} \\ {\rm if} & -\infty & < & x_k & \leq & u_k, & {\rm then} & d_k & \leq & 0\ {\rm(minimization)} \\ &&&&&& & d_k & \geq & 0\ {\rm(maximization)} \\ {\rm if} & l_k & \leq & x_k & \leq & u_k, & {\rm then} & d_k & {\rm is} & {\rm of\ any\ sign} \\ \end{array}\right.\eqno{\rm(KKT.DB)} $$ for all $k=1,\dots,m+n$, where $d_k$ is a reduced cost (Lagrange multiplier) of auxiliary ($1\leq k\leq m$) or structural ($m+1\leq k\leq m+n$) variable $x_k$. Geometrically this condition expresses the requirement that constraints of the original problem must ``hold'' the point preventing its movement along the anti-gradient (in case of minimization) or the gradient (in case of maximization) of the objective function. In case of basic solution reduced costs of all basic variables are placed on their active (zero) bounds, so actually the condition (KKT.DB) needs to be checked for non-basic variables only. If the dual solution has sufficient accuracy, this condition shows the dual feasibility of the solution. To check the condition (KKT.DB) the routine computes a vector of residuals: $$ v_k = \left\{ \begin{array}{ll} 0, & {\rm if}\ d_k\ {\rm has\ correct\ sign} \\ |d_k|, & {\rm if}\ d_k\ {\rm has\ wrong\ sign} \\ \end{array} \right. $$ for all $k=1,\dots,m+n$, and determines components of this vector that correspond to largest absolute and relative errors: $${\tt ae\_max}=\max_{1\leq k\leq m+n}|v_k|,$$ $${\tt re\_max}=\max_{1\leq k\leq m+n}\frac{|v_k|}{1+|d_k - c_k|}.$$ Note that the complete set of Karush-Kuhn-Tucker optimality conditions also includes the fifth, so called {\it complementary slackness condition}, which expresses the requirement that at least either a primal variable $x_k$ or its dual counterpart $d_k$ should be on its bound for all $k=1,\dots,m+n$. Currently checking this condition is not implemented yet. \def\arraystretch{1} %* eof *%