%===========================================================================%
%                                                                           %
% This file is part of the documentation for the SYMPHONY MILP Solver.      %
%                                                                           %
% SYMPHONY was jointly developed by Ted Ralphs (ted@lehigh.edu) and         %
% Laci Ladanyi (ladanyi@us.ibm.com).                                        %
%                                                                           %
% (c) Copyright 2000-2011 Ted Ralphs. All Rights Reserved.                  %
%                                                                           %
% SYMPHONY is licensed under the Eclipse Public License. Please see         %
% accompanying file for terms.                                              %
%                                                                           %
%===========================================================================%

\label{C_Interface}

This chapter specifies the interface for using SYMPHONY's callable
library. These function calls can be used to build custom applications that
call SYMPHONY as a subroutine, as described in Section
\ref{callable_library}. All callable library function begin with the
prefix \code{sym\_}. To call these function from an application, include the
header file \code{symphony.h} and then link with the SYMPHONY library as
described \hyperref{here}{in Section }{}{getting_started}. In general, if an
array is requested, such as the array of lower bounds on the variables, for
instance, the user is responsible for allocating an array of appropriate size
and passing it to SYMPHONY. SYMPHONY will then fill up the array.

\newpage

\subsection{Primary Interface Functions}
%begin{description}
\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_open_environment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_open\_environment}
\sindex[f]{sym\_open\_environmet}
\begin{verbatim}
sym_environment *sym_open_environment()
\end{verbatim}

\bd
\describe

This routine is used to get a new SYMPHONY environment to be passed as an 
argument to all other API subroutines. This routine also invokes the callback
function \hyperref{{\tt user\_initialize()}} {{\tt user\_initialize()} (see
Section }{)}{user_initialize}.

\returns

\bt{lp{317pt}}
{\tt NULL} & Error. Environment could not be initialized. None of the 
other API subroutines can be called after this point.\\
{\tt sym\_environment *} & Pointer to a successfully opened environment \\
\et

\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_create_copy_environment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\functiondef{sym\_create\_copy\_environment}
\sindex[f]{sym\_create\_copy\_environmet}
\begin{verbatim}
sym_environment *sym_create_copy_environment(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine is used to copy the given environment.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt NULL} & An empty environment is passed in. \\
{\tt SYM\_ENVIRONMENT *} & Pointer to the copy of the environment. \\
\et  
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_parse_command_line
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_parse\_command\_line}
\label{sym_parse_command_line}
\sindex[f]{sym\_parse\_command\_line}
\begin{verbatim}
int sym_parse_command_line(sym_environment *env, int argc, char **argv)
\end{verbatim}

\bd
\describe

This routine parses the command line arguments. It must be called whenever the
user specifies any of SYMPHONY's built-in command-line switches. For instance,
this is the case when the user specifies the location of an MPS, LP, or GMPL
file using the \texttt{-F} or \texttt{-L} switch or when the user specifies
the location of a parameter file with the \texttt{-f} switch. This command
also invokes the user callback function \hyperref{{\tt user\_readparams()}}
{{\tt user\_readparams()} (see Section }{)}{user_readparams}.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.\\
{\tt int argc} & IN & The number of command line arguments. \\
{\tt char **argv} & IN & Array of pointers to these arguments. 
\et

\returns

\bt{lp{317pt}}
{\tt ERROR\_\_USER} & Error. User error detected in {\tt user\_readparams()} \\ 
& function.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_find_initial_bounds
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_find\_initial\_bounds}
\sindex[f]{sym\_find\_initial\_bounds}
\begin{verbatim}
int sym_find_initial_bounds(sym_environment *env)
\end{verbatim}
\bd
\describe

This routine invokes the user callback \hyperref{{\tt user\_start\_heurs()}}
{{\tt user\_start\_heurs()} (see Section }{)}{user_start_heurs} to set the
priori bound for the problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt ERROR\_\_USER} & Error. User error detected in {\tt user\_start\_heurs()} \\
&function.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_load_problem
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_load\_problem}
\sindex[f]{sym\_load\_problem}
\begin{verbatim}
int sym_load_problem(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine loads the description of the problem given in MPS or GMPL/AMPL
format or in a file read by a custom file parser implemented in the 
\hyperref{{\tt user\_io()}} {{\tt user\_io()} (see
Section }{)}{user_io} callback. If the problem is to be loaded from an MPS or
a GMPL/AMPL file whose location is specified on the command line, then the
{\tt sym\_parse\_command\_line()} function has to be invoked
beforehand. This function also invokes the user callback 
\hyperref{{\tt user\_initialize\_root\_node()}} {{\tt
user\_initialize\_root\_node()} (see Section
}{)}{user_initialize_root_node}. Note that if the user wishes to load the
problem manually without implementing a callback or using one of SYMPHONY's
built-in parsers (as is typically done in other callable libraries), then the
{\tt sym\_explicit\_load\_problem()} routine should be used.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt ERROR\_\_USER} & Error. User error detected in one of \\
&{\tt user\_io()} and {\tt user\_init\_draw()} \\ & functions.\\
{\tt ERROR\_\_READING\_GMPL\_FILE} & Error detected in the given 
GMPL/AMPL \\ &file. \\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%sym_explicit_load_problem
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_explicit\_load\_problem}
\sindex[f]{sym\_explicit\_load\_problem}
\begin{verbatim}
int sym_explicit_load_problem_user(sym_environment * env, int numcols, 
                          int numrows, int *start, int *index, double *value, 
                          double *collb, double *colub, char *is_int, 
                          double *obj, double *obj2, char *rowsen, 
                          double *rowrhs, double *rowrng, char make_copy)
\end{verbatim}

\bd
\describe

This routine is used to load a problem description into SYMPHONY manually. The
constraint matrix is passed in a standard column-ordered format. The arguments
here are the same as the fields in the \texttt{MIPdesc} data structure
discussed in Section \ref{data_structures}. Please see the discussion there for
a more detailed description of the arguments here.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.\\
{\tt int numcols} & IN & Number of the columns. \\
{\tt int numrows} & IN & Number of the rows.\\
{\tt int *start} & IN & Array of the starting positions of each of 
column. \\
{\tt int *index} & IN & Array of the row indices corresponding to 
each entry of {\tt value}. \\ 
{\tt int *value} & IN & Array of the values of nonzero entries of 
the constraint matrix in \emph{column order}. \\
{\tt double *collb} & IN & Array of the lower bounds of the columns. \\
{\tt double *colub} & IN & Array of the upper bounds of the columns. \\
{\tt double *obj} & IN & Array of the objective function coefficients. \\
{\tt double *obj2} & IN & Array of the second objective function 
coefficients when multi criteria solver is to be used. \\
{\tt char *rowsen} & IN & Array of the senses of the constraints. \\
&&'L': $\leq$ constraint \\
&&  	'E': =  constraint \\
&&  	'G': $\geq$ constraint \\
&&  	'R': ranged constraint \\
&&  	'N': free constraint \\
{\tt double *rowrhs} & IN & Array of the right hand side values. \\
{\tt double *rowrng} & IN & Array of the row ranges.\\
&& ({\tt sym\_get\_row\_upper}) - ({\tt sym\_get\_row\_lower}) if the row 
sense is {\tt 'R'}, 0 otherwise. \\
{\tt char make\_copy} & IN & SYMPHONY will create the copies of these
arrays for internal usage if this flag is set to true, otherwise, will own 
them.\\ 
\et

\returns

\bt{lp{280pt}}
{\tt ERROR\_\_USER} & Error. User error detected in \\
& {\tt user\_initialize\_root\_node} function. \\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_read_mps
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\functiondef{sym\_read\_mps}
\sindex[f]{sym\_read\_mps}
\begin{verbatim}
int sym_read_mps(sym_environment *env, char *infile)
\end{verbatim}

\bd
\describe
This routine is used to load an instance from an MPS file. 
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt char *infile} & IN & Pointer to a character array indicating the name 
of the file. \\
\et

\returns
\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_read_gmpl
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\functiondef{sym\_read\_gmpl}
\sindex[f]{sym\_read\_gmpl}
\begin{verbatim}
int sym_read_gmpl(sym_environment *env, char *modelfile, char *datafile)
\end{verbatim}

\bd
\describe
This routine is used to load an instance from a GMPL file. 
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt char *modelfile} & IN & Pointer to a character array indicating the name 
of the model file. \\
{\tt char *datafile} & IN & Pointer to a character array indicating the name 
of the data file. \\
\et

\returns
\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_solve
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_solve}
\sindex[f]{sym\_solve}
\label{sym_solve}
\begin{verbatim}
int sym_solve(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine solves the currently loaded MILP problem from scratch even in the
presence of a loaded warm start. Any warm start information loaded or kept
before will be deleted from the environment!

\args

\bt{llp{250pt}}
{\tt }
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{250pt}}
{\tt ERROR\_\_USER} & Error. User error detected in one of \\
&{\tt user\_send\_lp\_data()}, \\
&{\tt user\_send\_cg\_data()}, \\
&{\tt user\_send\_cp\_data()}, \\ 
&{\tt user\_receive\_feasible\_solution()}, \\
&{\tt user\_display\_solution()} and  \\
&{\tt user\_process\_own\_messages()} functions. \\ 
{\tt TM\_OPTIMAL\_SOLUTION\_FOUND} & Tree Manager (TM) found the optimal solution and stopped.\\ 
{\tt TM\_TIME\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
time limit.\\
{\tt TM\_NODE\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
node limit. \\
{\tt TM\_TARGET\_GAP\_ACHIEVED} & TM stopped after achieving the predefined 
target gap. \\
{\tt TM\_FOUND\_FIRST\_FEASIBLE} & TM stopped after finding the first feasible 
solution. \\
{\tt TM\_ERROR\_\_NO\_BRANCHING\_CANDIDATE} & Error. TM stopped. User didn't 
select branching candidate in {\tt user\_select\_candidates()} callback. \\ 
{\tt TM\_ERROR\_\_ILLEGAL\_RETURN\_CODE} & Error. TM stopped after getting a 
non-valid return code. \\
{\tt TM\_ERROR\_\_NUMERICAL\_INSTABILITY} & Error. TM stopped due to some 
numerical difficulties. \\
{\tt TM\_ERROR\_\_COMM\_ERROR} & Error. TM stopped due to communication 
error. \\
{\tt TM\_ERROR\_\_USER} & Error. TM stopped. User error detected in one of 
user callbacks called during TM processes. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_warm_solve
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_warm\_solve}
\sindex[f]{sym\_warm\_solve}
\begin{verbatim}
int sym_warm_solve(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine re-solves the corresponding problem after some of the parameters
have been changed or problem data has been modified from a warm start.  If the
user plans to invoke this routine, the \texttt{keep\_warm\_start} parameter
must be set to \texttt{TRUE} before the initial call to the {\tt sym\_solve()}
routine, so that SYMPHONY will collect the necessary warm starting information
during the solve procedure.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{250pt}}
{\tt ERROR\_\_USER} & Error. User error detected in one of \\
&{\tt user\_send\_lp\_data}, \\
&{\tt user\_send\_cg\_data}, \\
&{\tt user\_send\_cp\_data}, \\
&{\tt user\_receive\_feasible\_solution}, \\
&{\tt user\_display\_solution} and  \\
&{\tt user\_process\_own\_messages} functions. \\ 
{\tt TM\_OPTIMAL\_SOLUTION\_FOUND} & Tree Manager (TM) found the optimal 
solution and stopped.\\ 
{\tt TM\_TIME\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
time limit.\\
{\tt TM\_NODE\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
node limit. \\
{\tt TM\_TARGET\_GAP\_ACHIEVED} & TM stopped after achieving the predefined 
target gap. \\
{\tt TM\_FOUND\_FIRST\_FEASIBLE} & TM stopped after finding the first feasible 
solution. \\
{\tt TM\_ERROR\_\_NO\_BRANCHING\_CANDIDATE} & Error. TM stopped. User didn't 
select branching candidate in {\tt user\_select\_candidates} callback\\ 
{\tt TM\_ERROR\_\_ILLEGAL\_RETURN\_CODE} & Error. TM stopped after getting a 
non-valid return code. \\
{\tt TM\_ERROR\_\_NUMERICAL\_INSTABILITY} & Error. TM stopped due to some 
numerical difficulties. \\
{\tt TM\_ERROR\_\_COMM\_ERROR} & Error. TM stopped due to communication 
error. \\
{\tt TM\_ERROR\_\_USER} & Error. TM stopped. User error detected in one of 
user callbacks called during TM processes. \\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_mc_solve
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_mc\_solve}
\sindex[f]{sym\_mc\_solve}
\begin{verbatim}
int sym_mc_solve(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine is used to solve the loaded problem as a multicriteria problem.
For this function, a second objective function must be set either by calling
the {\tt sym\_set\_obj2\_coeff()} function or by passing it directly using the
{\tt sym\_explict\_load\_problem()} function.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{250pt}}
{\tt } 
{\tt ERROR\_\_USER} & Error. User error detected in one of \\
&{\tt user\_send\_lp\_data()}, \\
&{\tt user\_send\_cg\_data()}, \\
&{\tt user\_send\_cp\_data()}, \\
&{\tt user\_receive\_feasible\_solution()}, \\
&{\tt user\_display\_solution()}, \\
&{\tt user\_process\_own\_messages()} functions. \\ 
{\tt TM\_OPTIMAL\_SOLUTION\_FOUND} & The set of supported or nondominated 
solutions have been found. \\
{\tt TM\_ERROR\_\_NO\_BRANCHING\_CANDIDATE} & Error. TM stopped. User didn't 
select branching candidate in {\tt user\_select\_candidates} callback\\ 
{\tt TM\_ERROR\_\_ILLEGAL\_RETURN\_CODE} & Error. TM stopped after getting a 
non-valid return code. \\
{\tt TM\_ERROR\_\_NUMERICAL\_INSTABILITY} & Error. TM stopped due to some 
numerical difficulties. \\
{\tt TM\_ERROR\_\_COMM\_ERROR} & Error. TM stopped due to communication 
error. \\
{\tt TM\_ERROR\_\_USER} & Error. TM stopped. User error detected in one of 
user callbacks activated by user and invoked during TM processes. \\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_create_permanent_cut_pools
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_create\_permanent\_cut\_pools}
\sindex[f]{sym\_create\_permanent\_cut\_pools}
\begin{verbatim}
int sym_create_permanent_cut_pools(sym_environment *env, int *cp_num)
\end{verbatim}

\bd
\describe

This routine is used to create a global cut pool that will be saved even after
the solve call exits and can be used to initialize the cut pool for later
solve calls. This can be useful when solving a series of related MILPs that
share classes of globally valid inequalities. For instance, if only the
objective function is varied, as is the case with multicriteria integer
programming, then cuts can be saved for use in later solve calls.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int *cp\_num} & OUT & Pointer to an integer indicating the
number of cut pools stored in the environment.
\et

\returns

\bt{lp{317pt}}
{\tt INT} & The number of the cut pools created. 
\et
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_user_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_user\_data}
\sindex[f]{sym\_set\_user\_data}
\begin{verbatim}
int sym_set_user_data(sym_environment *env, void *user)
\end{verbatim}

\bd
\describe

This routine is used to give SYMPHONY a pointer to the user's problem data
structure. This pointer will then be handed back to the user during subsequent
calls to user callbacks. This allows the user to store static problem
data. Note that this pointer can also be stored by filling out the callback
function \hyperref{{\tt user\_initialize()}} {{\tt user\_initialize()}(see
Section }{)}{user_initialize}.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.\\
{\tt void *user} & IN & Pointer to the user defined problem structure. 
%SYMPHONY, instead of making a copy or overriding, will directly use the 
%object itself, thus, any later modification on the object will be known unless
%its location is changed. 

\et

\returns

\bt{lp{317pt}}
{\tt ERROR\_\_USER} & Error in the passed in {\tt user} structure.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% NEW sym_get_user_data
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_user\_data}
\sindex[f]{sym\_get\_user\_data}
\begin{verbatim}
int sym_get_user_data(sym_environment *env, void **user)
\end{verbatim}

\bd
\describe
This routine is used to get the user's problem data structure from 
SYMPHONY environment. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.\\
{\tt void **user} & OUT & Pointer to the user defined problem structure. 
%SYMPHONY, instead of making a copy or overriding, will directly use the 
%object itself, thus, any later modification on the object will be known unless
%its location is changed. 

\et

\returns

\bt{lp{317pt}}
{\tt ERROR\_\_USER} & Error in the passed in {\tt user} structure.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_close_environment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_close\_environment}
\sindex[f]{sym\_close\_environment}
\begin{verbatim}
int sym_close_environment(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine closes the environment and returns the allocated memory.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{270pt}}
{\tt ERROR\_\_USER} & Error. User error detected in {\tt user\_free\_master()} 
function.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

\ed

\newpage

\subsection{Parameter Query and Modification}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_defaults
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_set\_defaults}
\sindex[f]{sym\_set\_defaults}
\begin{verbatim}
int sym_set_defaults(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine sets all the environment variables and parameters
to their default values. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment to 
be modified. 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully. \\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_int param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_int\_param}
\sindex[f]{sym\_set\_int\_param}
\begin{verbatim}
void sym_set_int_param(sym_environment *env, char *key, int value)
\end{verbatim}

\bd
\describe

This routine is used to set an integer type parameter.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter to be set. \\
{\tt int value} & OUT & New value of the corresponding parameter.
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_dbl param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_dbl\_param}
\sindex[f]{sym\_set\_dbl\_param}
\begin{verbatim}
void sym_set_int_param(sym_environment *env, char *key, double value)
\end{verbatim}

\bd
\describe

This routine is used to set a double type parameter.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter to be set. \\
{\tt double value} & OUT & New value of the corresponding parameter.
\et
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_str param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_str\_param}
\sindex[f]{sym\_set\_str\_param}
\begin{verbatim}
void sym_set_str_param(sym_environment *env, char *key, char *value)
\end{verbatim}

\bd
\describe

This routine is used to set a string type parameter.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter to be set. \\
{\tt char *value} & OUT & New value of the corresponding parameter.
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_int_param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_int\_param}
\sindex[f]{sym\_get\_int\_param}
\begin{verbatim}
int sym_get_int_param(sym_environment *env, char *key)
\end{verbatim}

\bd
\describe

This routine is used to get the value of an integer type parameter. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter.
\et

\returns

\bt{lp{317pt}}
{\tt INT} & An integer indicating the value of the parameter. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_dbl_param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_dbl\_param}
\sindex[f]{sym\_get\_dbl\_param}
\begin{verbatim}
double sym_get_int_param(sym_environment *env, char *key)
\end{verbatim}

\bd
\describe

This routine is used to get the value of a double type parameter.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter.
\et

\returns

\bt{lp{317pt}}
{\tt DOUBLE} & A double indicating the value of the parameter. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_str_param
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_str\_param}
\sindex[f]{sym\_get\_str\_param}
\begin{verbatim}
char *sym_get_int_param(sym_environment *env, char *key)
\end{verbatim}

\bd
\describe

This routine is used to get the value of a string type parameter.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char *key} & IN & The name of the parameter.
\et

\returns

\bt{lp{317pt}}
{\tt CHAR*} & A character array indicating the value of the parameter. \\
\et  
\ed
\vspace{1ex}

\ed

\newpage

\subsection{Solver Status Query Functions}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_status
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_get\_status}
\sindex[f]{sym\_get\_status}
\begin{verbatim}
int sym_get_status(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn the termination
status of the solution procedure.

\args
\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{250pt}}
{\tt ERROR\_\_USER} & Error. User error detected in one of \\
&{\tt user\_send\_lp\_data()}, \\
&{\tt user\_send\_cg\_data()}, \\
&{\tt user\_send\_cp\_data()}, \\
&{\tt user\_receive\_feasible\_solution()}, \\
&{\tt user\_display\_solution()}, \\
&{\tt user\_process\_own\_messages()} functions. \\ 
{\tt TM\_OPTIMAL\_SOLUTION\_FOUND} & Tree Manager (TM) found the optimal solution and stopped.\\ 
{\tt TM\_TIME\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
time limit.\\
{\tt TM\_NODE\_LIMIT\_EXCEEDED} & TM stopped after reaching the predefined 
node limit. \\
{\tt TM\_TARGET\_GAP\_ACHIEVED} & TM stopped after achieving the predefined 
target gap. \\
{\tt TM\_FOUND\_FIRST\_FEASIBLE} & TM stopped after finding the first feasible 
solution. \\
{\tt TM\_ERROR\_\_NO\_BRANCHING\_CANDIDATE} & Error. TM stopped. User didn't 
select branching candidate in {\tt user\_select\_candidates()} callback\\ 
{\tt TM\_ERROR\_\_ILLEGAL\_RETURN\_CODE} & Error. TM stopped after getting an
invalid return code. \\
{\tt TM\_ERROR\_\_NUMERICAL\_INSTABILITY} & Error. TM stopped due to some 
numerical difficulties. \\
{\tt TM\_ERROR\_\_COMM\_ERROR} & Error. TM stopped due to communication 
error. \\
{\tt TM\_ERROR\_\_USER} & Error. TM stopped. User error detected in one of 
user callbacks called during TM processes. \\
\et
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_proven_optimal
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_proven\_optimal}
\sindex[f]{sym\_is\_proven\_optimal}
\begin{verbatim}
int sym_is_proven_optimal(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the problem 
was solved to optimality.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & The problem was solved to optimality. \\
{\tt FALSE} & The problem was not solved to optimality.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_proven_primal_infeasible
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_proven\_primal\_infeasible}
\sindex[f]{sym\_is\_proven\_primal\_infeasible}
\begin{verbatim}
int sym_is_proven_primal_infeasible(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the problem 
was proven to be infeasible.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & The problem was proven to be infeasible. \\
{\tt FALSE} & The problem was not proven to be infeasible.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_iteration_limit_reached
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_iteration\_limit\_reached}
\sindex[f]{sym\_is\_iteration\_limit\_reached}
\begin{verbatim}
int sym_is_iteration_limit_reached(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the iteration 
(node limit) was reached. It can also be used if ``find\_first\_feasible'' 
parameter was set to true before solving the problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & The iteration limit is reached. \\
{\tt FALSE} & The iteration limit is not reached.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_time_limit_reached
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_time\_limit\_reached}
\sindex[f]{sym\_is\_time\_limit\_reached}
\begin{verbatim}
int sym_is_time_limit_reached(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the time limit 
was reached. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & Time limit was reached. \\
{\tt FALSE} & Time limit was not reached.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_target_gap_achieved
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_target\_gap\_achieved}
\sindex[f]{sym\_is\_target\_gap\_achieved}
\begin{verbatim}
int sym_is_target_gap_achieved(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the target gap was
reached. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & Target gap was reached. \\
{\tt FALSE} & Target gap was not reached.\\
\et

\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_abandoned
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_is\_abandoned}
\sindex[f]{sym\_is\_abandoned}
\begin{verbatim}
int sym_is_abandoned(sym_environment *env)
\end{verbatim}

\bd
\describe

This post-solution query routine is used to learn whether the problem 
was abandoned for some reason.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.
\et

\returns

\bt{lp{317pt}}
{\tt TRUE} & The problem was abandoned. \\
{\tt FALSE} & The problem was not abandoned.\\
\et
\ed
\vspace{1ex}

\ed

\newpage

\subsection{Data Query Functions}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_create_copy_mip_desc
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_create\_copy\_mip\_desc}
\sindex[f]{sym\_create\_copy\_mip\_desc}
\begin{verbatim}
MIPdesc *sym_create_copy_mip_desc(sym_environment *env)
\end{verbatim}

\bd
\describe

This routine is used to copy the problem description loaded to the environment.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
\et

\returns

\bt{lp{317pt}}
{\tt NULL} & An empty environment is passed in or there is no problem
description loaded to the environment. \\
{\tt MIPdesc *} & Pointer to the copy of the problem description. \\
\et  
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_num_cols
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_num\_cols}
\sindex[f]{sym\_get\_num\_cols}
\begin{verbatim}
int sym_get_num_cols(sym_environment *env, int *numcols)
\end{verbatim}

\bd
\describe

This routine is used to get the number of the columns of the current problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int *numcols} & OUT & Pointer to an integer indicating the number of 
columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_num_rows
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_num\_rows}
\sindex[f]{sym\_get\_num\_rows}
\begin{verbatim}
int sym_get_num_cols(sym_environment *env, int *numrows)
\end{verbatim}

\bd
\describe

This routine is used to get the number of the rows of the current problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int *numrows} & OUT & Pointer to an integer indicating the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_num_elements
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_num\_elements}
\sindex[f]{sym\_get\_num\_elements}
\begin{verbatim}
int sym_get_num_elements(sym_environment *env, int *numelems)
\end{verbatim}

\bd
\describe

This routine is used to get the number of non-zero entries of the 
constraint matrix of the current problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int *numelems} & OUT & Pointer to an integer indicating the number of 
non-zero elements.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_col_lower
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_col\_lower}
\sindex[f]{sym\_get\_col\_lower}
\begin{verbatim}
int sym_get_col_lower(sym_environment *env, double *collb)
\end{verbatim}

\bd
\describe

This routine is used to get the lower bounds of the variables.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt double *collb} & OUT & Pointer to a double type array to be filled by 
the column lower bounds. Note that, the size of this array has to be at least 
the number of columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_col_upper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_col\_upper}
\sindex[f]{sym\_get\_col\_upper}
\begin{verbatim}
int sym_get_col_upper(sym_environment *env, double *colub)
\end{verbatim}

\bd
\describe

This routine is used to get the upper bounds of the variables.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt double *colub} & OUT & Pointer to a double type array to be filled by 
the column upper bounds. Note that, the size of this array has to be at least 
the number of columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_row_sense
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_row\_sense}
\sindex[f]{sym\_get\_row\_sense}
\begin{verbatim}
int sym_get_row_sense(sym_environment *env, char *rowsen)
\end{verbatim}

\bd
\describe

This routine is used to get the row senses.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt char *rowsen} & OUT & Pointer to a char type array to be filled by 
the row senses. Note that, the size of this array has to be at least 
the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_rhs
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_rhs}
\sindex[f]{sym\_get\_rhs}
\begin{verbatim}
int sym_get_rhs(sym_environment *env, double *rowrhs)
\end{verbatim}

\bd
\describe

This routine is used to get the right hand side vector.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *rowrhs} & OUT & Pointer to a double type array to be filled by 
the right hand side vector. Note that, the size of this array has to be at 
least the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_row_range
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_row\_range}
\sindex[f]{sym\_get\_row\_range}
\begin{verbatim}
int sym_get_row_range(sym_environment *env, double *rowrng)
\end{verbatim}

\bd
\describe

This routine is used to get the row ranges. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *rowrng} & OUT & Pointer to a double type array to be filled by 
the row range values. Note that, the size of this array has to be at 
least the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_row_lower
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_row\_lower}
\sindex[f]{sym\_get\_row\_lower}
\begin{verbatim}
int sym_get_row_lower(sym_environment *env, double *rowlb)
\end{verbatim}

\bd
\describe

This routine is used to get the lower bounds of the rows.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *rowlb} & OUT & Pointer to a double type array to be filled by 
the row lower bounds. Note that, the size of this array has to be at 
least the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_row_upper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_row\_upper}
\sindex[f]{sym\_get\_row\_upper}
\begin{verbatim}
int sym_get_row_upper(sym_environment *env, double *rowub)
\end{verbatim}

\bd
\describe

This routine is used to get the upper bounds of the rows.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *rowub} & OUT & Pointer to a double type array to be filled by 
the row upper bounds. Note that, the size of this array has to be at 
least the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed

\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_matrix
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\functiondef{sym\_get\_matrix}
\sindex[f]{sym\_get\_matrix}
\begin{verbatim}
int sym_get_matrix(sym_environment *env, int *nz, int *matbeg, int *matind, 
		   double *matval)
\end{verbatim}

\bd
\describe
This routine is used to get the constraint matrix in a standard column-ordered format.
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int *nz} & OUT &  Pointer to integer indicating the non zero elements of
the constraint matrix. \\
{\tt int *matbeg} & OUT & Pointer to a double type array to be filled 
by the starting positions of each of 
column. Note that, the size of this array has to be at least the number 
of columns+1\\
{\tt int *matind} & OUT  &Pointer to a double type array to be filled by the
 row indices corresponding to each entry of {\tt matval}. Note that, the size of this array has to be at least the number of nonzero elements of the constraint matrix.\\ 
{\tt int *matval} & OUT & Pointer to a double type array of the values of 
nonzero entries of the constraint matrix in \emph{column order}.  Note that, the size of this array has to be at least the number of nonzero elements of the constraint matrix.\\
\et
\returns
\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_obj_coeff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_obj\_coeff}
\sindex[f]{sym\_get\_obj\_coeff}
\begin{verbatim}
int sym_get_obj_coeff(sym_environment *env, double *obj)
\end{verbatim}

\bd
\describe

This routine is used to get the objective vector.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *obj} & OUT & Pointer to a double type array to be filled by 
the objective vector. Note that, the size of this array has to be at 
least the number of columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_obj2_coeff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_obj2\_coeff}
\sindex[f]{sym\_get\_obj2\_coeff}
\begin{verbatim}
int sym_get_obj2_coeff(sym_environment *env, double *obj2)
\end{verbatim}

\bd
\describe

This routine is used to get the second objective vector if it exists. By
default, it is set to the zero vector.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *obj2} & OUT & Pointer to a double type array to be filled by 
the second objective vector. Note that, the size of this array has to be at 
least the number of columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_obj_sense
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_obj\_sense}
\sindex[f]{sym\_get\_obj\_sense}
\begin{verbatim}
int sym_get_obj_sense(sym_environment *env, int *sense)
\end{verbatim}

\bd
\describe

This routine is used to get the objective sense.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int *sense} & OUT & Pointer to an integer indicating the objective 
sense. In return, it will be {\tt 1} in case of minimization and {\tt -1}
in case of maximization. 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_continuous
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_continuous}
\sindex[f]{sym\_is\_continuous}
\begin{verbatim}
int sym_is_continuous(sym_environment *env, int index, int *value)
\end{verbatim}

\bd
\describe

This routine is used to learn whether the queried variable is 
continuous.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int index} & IN & The index of the queried variable. Note that, it has 
to be at most the number of columns.\\
{\tt int *value} & OUT & Pointer to a boolean indicating the variable status.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_binary
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_binary}
\sindex[f]{sym\_is\_binary}
\begin{verbatim}
int sym_is_binary(sym_environment *env, int index, int *value)
\end{verbatim}

\bd
\describe

This routine is used to learn whether the queried variable is 
binary.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int index} & IN & The index of the queried variable. Note that, it has 
to be at most the number of columns.\\
{\tt int *value} & OUT & Pointer to a boolean indicating the variable status.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_is_integer
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_is\_integer}
\sindex[f]{sym\_is\_integer}
\begin{verbatim}
int sym_is_integer(sym_environment *env, int index, int *value)
\end{verbatim}

\bd
\describe

This routine is used to ask whether the queried variable is 
integer.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int index} & IN & Index of the queried variable. Note that, it has to 
be at most the number of columns.\\
{\tt int *value} & OUT & Pointer to a boolean indicating the variable status.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_infinity
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_infinity}
\sindex[f]{sym\_get\_infinity}
\begin{verbatim}
double sym_get_infinity()
\end{verbatim}

\bd
\describe

This routine returns the infinity value of SYMPHONY.

\args

\returns

\bt{lp{317pt}}
{\tt DOUBLE} & Infinity value of SYMPHONY
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_col_solution
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_col\_solution}
\sindex[f]{sym\_get\_col\_solution}
\begin{verbatim}
int sym_get_col_solution(sym_environment *env, double *colsol)
\end{verbatim}

\bd
\describe

This routine is used to get the post-solution column values.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *colsol} & OUT & Pointer to a double type array to be filled by 
the solution vector. Note that, the size of this array has to be at least 
the number of columns.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_row_activity
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_row\_activity}
\sindex[f]{sym\_get\_row\_activity}
\begin{verbatim}
double *sym_get_row_activity(sym_environment *env, double *rowact)
\end{verbatim}

\bd
\describe

This routine is used to get the row activities which are defined as the 
left hand side values, i.e., constraint matrix times the solution.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *rowact} & OUT & Pointer to a double type array to be filled by 
the row activity values. Note that, the size of this array has to be at least 
the number of rows.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_obj_val
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_obj\_val}
\sindex[f]{sym\_get\_obj\_val}
\begin{verbatim}
double *sym_get_obj_val(sym_environment *env, double *objval)
\end{verbatim}

\bd
\describe

This routine is used to get the objective value after solving the problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *objval} & OUT & Pointer to a double indicating the post-solution
objective value. 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_primal_bound
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_primal\_bound}
\sindex[f]{sym\_get\_primal\_bound}
\begin{verbatim}
double *sym_get_primal_bound(sym_environment *env, double *ub)
\end{verbatim}

\bd
\describe

This routine is used to get the a priori upper/lower bound for the problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt double *ub} & OUT & Pointer to a double indicating the upper 
(for minimization) or lower (for maximization) bound obtained through user 
defined primal heuristics.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_iteration_count
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_iteration\_count}
\sindex[f]{sym\_get\_iteration\_count}
\begin{verbatim}
double *sym_get_iteration\_count(sym_environment *env, int *numnodes)
\end{verbatim}

\bd
\describe

This routine is used to get the number of the analyzed nodes of the 
branching tree after solving the problem. It can also be used to query
the status of a loaded warm start.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment.\\
{\tt int *numnodes} & OUT & Pointer to an integer indicating the number of 
nodes analyzed so far. 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
\et  
\ed
\vspace{1ex}

\ed

\newpage

\subsection{Data Modification Functions}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_obj_coeff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_set\_obj\_coeff}
\sindex[f]{sym\_set\_obj\_coeff}
\begin{verbatim}
double *sym_set_obj_coeff(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set an objective coefficient. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the objective coefficient to be modified. 
Note that, it has to be at most the number of columns.\\
{\tt double value} & IN & New objective value of the corresponding column.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_obj2_coeff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_obj2\_coeff}
\sindex[f]{sym\_set\_obj2\_coeff}
\begin{verbatim}
double *sym_set_obj2_coeff(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set a coefficient of the second objective function
of the corresponding bicriteria problem. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the objective coefficient to be modified. 
Note that, it has to be at most the number of columns.\\
{\tt double value} & IN & New value of the objective coefficient to be 
modified.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_col_lower
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_col\_lower}
\sindex[f]{sym\_set\_col\_lower}
\begin{verbatim}
double *sym_set_col_lower(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set the lower bound of a variable.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the variable. Note that, it has to be at 
most the number of columns.\\
{\tt double value} & IN & New lower bound of the variable.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_col_upper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_col\_upper}
\sindex[f]{sym\_set\_col\_upper}
\begin{verbatim}
double *sym_set_col_upper(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set the upper bound of a variable.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the variable. Note that, it has to be at most 
the number of columns. \\
{\tt double value} & IN & New upper bound of the variable.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_row_lower
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_row\_lower}
\sindex[f]{sym\_set\_row\_lower}
\begin{verbatim}
double *sym_set_row_lower(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set the lower bound of a row.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the row. Note that, it has to be at most the 
number of rows.\\
{\tt double value} & IN & New lower bound of the row.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_row_upper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_row\_upper}
\sindex[f]{sym\_set\_row\_upper}
\begin{verbatim}
double *sym_set_row_upper(sym_environment *env, int index, double value)
\end{verbatim}

\bd
\describe

This routine is used to set the upper bound of a row.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the row. Note that, it has to be at most the 
number of rows.\\
{\tt double value} & IN & New upper bound of the row.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_row_type
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_row\_type}
\sindex[f]{sym\_set\_row\_type}
\begin{verbatim}
int sym_set_row_type(sym_environment *env, int index, char rowsense, 
                     double rowrhs, double rowrng)
\end{verbatim}

\bd
\describe

This routine is used to set the characteristics of a row.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN & Index of the row. Note that, it has to be at most the 
number of rows.\\
{\tt char rowsense} & IN & New sense of the row. \\
{\tt double rowrhs} & IN & New value of the right hand side of the row. \\
{\tt double rowrng} & IN & New value of the row range.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_obj_sense
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_obj\_sense}
\sindex[f]{sym\_set\_obj\_sense}
\begin{verbatim}
int sym_set_obj_sense(sym_environment *env, int sense)

\end{verbatim}

\bd
\describe

This routine is used to set the objective sense. By default, SYMPHONY 
will solve a minimization problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int sense} & IN & New sense of the objective function. It can be 1 and -1 
for minimization and maximization. Otherwise, SYMPHONY will assume the 
objective sense to be minimization.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully \\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_col_solution
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_col\_solution}
\sindex[f]{sym\_set\_col\_solution}
\begin{verbatim}
int sym_set_col_solution(sym_environment *env, double *colsol)

\end{verbatim}

\bd
\describe

This routine is used to set the current solution if a known one exists. Note
that setting the column solution will not affect or help the treemanager's 
processes other than setting the best feasible solution and the corresponding
upper bound. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt double *colsol} & IN &  Pointer to a double type array of the known 
column values. Note that, if the given solution is not feasible or if 
a better solution was found/loaded before, SYMPHONY will refuse to set the 
column solution and will leave this function without success.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_primal_bound
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_primal\_bound}
\sindex[f]{sym\_set\_primal\_bound}
\begin{verbatim}
int sym_set_primal_bound(sym_environment *env, double bound)

\end{verbatim}

\bd
\describe

This routine is used to set a priori upper/lower bound to the problem.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt double double} & IN &  The value of the priori upper (for minimization) 
or lower (for maximization) bound.
\et

\returns

\bt{lp{317pt}}

{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_continuous
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_continuous}
\sindex[f]{sym\_set\_continuous}
\begin{verbatim}
int sym_set_continuous(sym_environment *env, int index)

\end{verbatim}

\bd
\describe

This routine is used to set the type of a variable to be continuous.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN &  The index of the variable to be modified. Note that, 
it has to be at most the number of columns.\\ 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_integer
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_integer}
\sindex[f]{sym\_set\_integer}
\begin{verbatim}
int sym_set_continuous(sym_environment *env, int index)

\end{verbatim}

\bd
\describe

This routine is used to set the type of a variable to be integer.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int index} & IN &  The index of the variable to be modified. Note that, 
it has to be at most the number of columns.\\
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_col_names
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_col\_names}
\sindex[f]{sym\_set\_col\_names}
\begin{verbatim}
int sym_set_col_names(sym_environment * env, char **colname)
\end{verbatim}

\bd
\describe

This routine is used to set the column names. 

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt char **colname} & IN &  Pointer to a string array including the column 
names. Note that, the size of this array has to be at least the number of 
columns.\\ 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_add_col
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_add\_col}
\sindex[f]{sym\_add\_col}
\begin{verbatim}
int sym_add_col(sym_environment *env, int numelems, int *indices, 
                double *elements, double collb, double colub,
                double obj, char *name)
\end{verbatim}

\bd
\describe

This routine is used to add a new column to the original problem description.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int numelems} & IN & An integer indicating the non zero elements of
the column. \\
{\tt int *indices} & IN & Pointer to an integer type array indicating the row 
indices of the non zero elements of the column and having a size of at least
{\tt numelems}. \\
{\tt double *elements} & IN & Pinter to a double type array indicating the 
values of the non zero elements of the column and having a size of at least 
{\tt numelems}. \\
{\tt double collb} & IN & A double indicating the lower bound of the column. \\
{\tt double colub} & IN & A double indicating the upper bound of the column.\\
{\tt double obj} & IN & A double indicating the objective coefficient value
of the column. \\
{\tt char *name} & IN & Pointer to a string of the name of the column.  
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_add_row
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_add\_row}
\sindex[f]{sym\_add\_row}
\begin{verbatim}
int sym_add_row(sym_environment *env, int numelems, int *indices, 
                double *elements, char rowsen, double rowrhs,
                double rowrng)

\end{verbatim}

\bd
\describe

This routine is used to add a new row to the original constraint matrix.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int numelems} & IN & An integer indicating the non zero elements of
the row. \\
{\tt int *indices} & IN & Pointer to an integer type array indicating the 
column indices of the non zero elements of the row and having a size of 
at least {\tt numelems}. \\
{\tt double *elements} & IN & Pointer to a double type array indicating the
values of the non zero elements of the row and having a size of 
at least {\tt numelems}. \\
{\tt char rowsen} & IN & A character indicating the sense of the row. \\
{\tt double rowrhs} & IN & A double indicating the right hand side of the 
row.\\
{\tt double rowrng} & IN & A double indicating the range value
of the row.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_delete_cols
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_delete\_cols}
\sindex[f]{sym\_delete\_cols}
\begin{verbatim}
int sym_delete_cols(sym_environment *env, int num, int * indices)
\end{verbatim}

\bd
\describe

This routine is used to delete columns from the original problem description.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int num} & IN & An integer indicating the number of columns to be 
deleted.\\
{\tt int *indices} & IN & Pointer to an integer type array indicating the 
indices of the columns to be deleted and having a size of 
at least {\tt num}.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully or 
one of the {\tt indices} \\
&is out of the range of [0, number of variables-1] \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_delete_rows
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_delete\_rows}
\sindex[f]{sym\_delete\_rows}
\begin{verbatim}
int sym_delete_rows(sym_environment *env, int num, int * indices)
\end{verbatim}

\bd
\describe

This routine is used to delete rows from the original constraint matrix.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt int num} & IN & An integer indicating the number of rows to be deleted.\\
{\tt int *indices} & IN & An array indicating the indices of the rows to 
be deleted and having a size of at least {\tt num}.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully or
one of the \\
&{\tt indices} is out of the range of [0, number of variables-1] \\
\et  
\ed
\vspace{1ex}

\ed

\newpage

\subsection{Warm Starting Functions}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_write_warm_start_desc
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_write\_warm\_start\_desc}
\sindex[f]{sym\_write\_warm\_start\_desc}
\begin{verbatim}
int sym_write_warm_start_desc(warm_start_desc *ws, char *file)
\end{verbatim}

\bd
\describe

This routine is used to write the given warm start structure to a file.

\args

\bt{llp{250pt}}
{\tt warm\_start\_desc *ws} & IN & Pointer to the warm start description to 
be written. \\
{\tt char *file} & IN & The name of the file the warm start is desired to be
written to. 
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_read_warm_start
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_read\_warm\_start}
\sindex[f]{sym\_read\_warm\_start}
\begin{verbatim}
int sym_read_warm_start(char *file, warm_start_desc *ws)
\end{verbatim}

\bd
\describe

This routine is used to read in a warm start structure from a file.

\args

\bt{llp{250pt}}
{\tt char *file} & IN & The name of the file the warm start is desired to be
read from. \\
{\tt warm\_start\_desc *ws} & OUT & Pointer to a warm start object 
to be read from the file.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_delete_warm_start
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_delete\_warm\_start}
\sindex[f]{sym\_delete\_warm\_start}
\begin{verbatim}
void sym_delete_warm_start(warm_start_desc *ws)
\end{verbatim}

\bd
\describe

This routine is used to free a warm start structure and return the allocated 
memory.

\args

\bt{llp{250pt}}
{\tt warm\_start\_desc *ws} & IN & Pointer to the warm start description to be 
deleted.
\et

\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_warm_start
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_warm\_start}
\sindex[f]{sym\_get\_warm\_start}
\begin{verbatim}
warm_start_desc *sym_get_warm_start(sym_environment *env, int copy_warm_start,
warm_start_desc **ws)
\end{verbatim}

\bd
\describe

This routine is used to get the warm start description loaded to the 
environment.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int copy\_warm\_start} & IN & A boolean indicating whether the warm start
of the environment is desired to be copied or overtaken. \\
{\tt warm\_start\_desc **ws} & OUT & Pointer to a pointer to be directed  
to a copy or the itself of the currently loaded warm start.  
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_set_warm_start
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_set\_warm\_start}
\sindex[f]{sym\_set\_warm\_start}
\begin{verbatim}
int sym_set_warm_start(sym_environment *env, warm_start_desc *ws)
\end{verbatim}

\bd
\describe

This routine is used to load a warm start structure to the environment.

\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & INOUT & Pointer to the SYMPHONY environment. \\
{\tt warm\_start\_desc *ws} & IN & Pointer to the warm start structure to be 
loaded to the environment.
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully. \\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_create_copy_warm_start
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_create\_copy\_warm\_start}
\sindex[f]{sym\_create\_copy\_warm\_start}
\begin{verbatim}
warm_start_desc *sym_create_copy_warm_start(warm_start_desc *ws)
\end{verbatim}

\bd
\describe

This routine is used to copy the given warm start structure.

\args

\bt{llp{250pt}}
{\tt warm\_start\_desc *ws} & INOUT & Pointer to the warm start structure to 
be copied.
\et

\returns

\bt{lp{317pt}}
{tt NULL} & An empty warm start description is passed in. \\
{\tt WARM\_START\_DESC *} & Pointer to the copy of the warm start structure. \\
\et  
\ed

\vspace{1ex}

\ed

\newpage

\subsection{Sensitivity Analysis Functions}

\bd

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_lb_for_new_rhs
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\firstfuncdef{sym\_get\_lb\_for\_new\_rhs}
\sindex[f]{sym\_get\_lb\_for\_new\_rhs}
\begin{verbatim}
int sym_get_lb_for_new_rhs(sym_environment *env, int cnt, int *new_rhs_ind, 
                           double *new_rhs_val, double *lb_for_new_rhs)
			      
\end{verbatim}

\bd
\describe

This routine is used for a basic sensitivity analysis of the right hand side
case. It returns a lower bound for the problem with a modified
right hand side using the information gathered from the branching tree of 
the original solved problem. Note that, in order to use this feature, the
\texttt{sensitivity\_analysis} parameter needs to be set before solving 
the original problem.
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int cnt} & IN & The number of the non zero elements in the new right 
hand side vector. \\
{\tt int *new\_rhs\_ind} & IN & Array of the column indices of these non 
zero elements. \\
{\tt double *new\_rhs\_val} & IN & Array of the values of these non zero 
elements. \\
{\tt double *lb\_for\_new\_rhs} & OUT & Pointer to a double indicating the 
lower bound obtained for the new problem. \\
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_ub_for_new_rhs
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_ub\_for\_new\_rhs}
\sindex[f]{sym\_get\_ub\_for\_new\_rhs}
\begin{verbatim}
int sym_get_ub_for_new_rhs(sym_environment *env, int cnt, int *new_rhs_ind, 
                           double *new_rhs_val, double *ub_for_new_rhs)
			      
\end{verbatim}

\bd
\describe

This routine is used for a basic sensitivity analysis of the right hand side
case. It returns a quick upper bound for the problem with a modified
right hand side using the information gathered from the branching tree of 
the original solved problem. Note that, in order to use this feature, the
\texttt{sensitivity\_analysis} parameter needs to be set before solving 
the original problem. 
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int cnt} & IN & The number of the non zero elements in the new right 
hand side vector. \\
{\tt int *new\_rhs\_ind} & IN & Array of the column indices of these non 
zero elements. \\
{\tt double *new\_rhs\_val} & IN & Array of the values of these non zero 
elements. \\
{\tt double *ub\_for\_new\_rhs} & OUT & Pointer to a double indicating the 
lower bound obtained for the new problem. This value will be set to 
{\tt SYM\_INFINITY} if an upper bound can not be found. \\
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_lb_for_new_obj
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_lb\_for\_new\_obj}
\sindex[f]{sym\_get\_lb\_for\_new\_obj}
\begin{verbatim}
int sym_get_lb_for_new_rhs(sym_environment *env, int cnt, int *new_obj_ind, 
                           double *new_obj_val, double *lb_for_new_obj)
			      
\end{verbatim}

\bd
\describe

This routine is used for a basic sensitivity analysis of the objective 
function case. It returns a quick lower bound for the problem with a modified
objective vector using the information gathered from the branching tree of 
the original solved problem. Note that, in order to use this feature, the
\texttt{sensitivity\_analysis} parameter needs to be set before solving 
the original problem.
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int cnt} & IN & The number of the non zero elements in the new objective
coefficients. \\
{\tt int *new\_obj\_ind} & IN & Array of the column indices of these non 
zero elements. \\
{\tt double *new\_obj\_val} & IN & Array of the values of these non zero 
elements. \\
{\tt double *lb\_for\_new\_obj} & OUT & Pointer to a double indicating the 
lower bound obtained for the new problem.\\
\et
\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sym_get_ub_for_new_obj
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\functiondef{sym\_get\_ub\_for\_new\_obj}
\sindex[f]{sym\_get\_ub\_for\_new\_obj}
\begin{verbatim}
int sym_get_ub_for_new_rhs(sym_environment *env, int cnt, int *new_obj_ind, 
                           double *new_obj_val, double *ub_for_new_obj)
			      
\end{verbatim}

\bd
\describe

This routine is used for a basic sensitivity analysis of the objective 
function case. It returns a quick lower bound for the problem with a modified
objective vector using the information gathered from the branching tree of 
the original solved problem. Note that, in order to use this feature, the
\texttt{sensitivity\_analysis} parameter needs to be set before solving 
the original problem.
\args

\bt{llp{250pt}}
{\tt sym\_environment *env} & IN & Pointer to the SYMPHONY environment. \\
{\tt int cnt} & IN & The number of the non zero elements in the new objective
coefficients. \\
{\tt int *new\_obj\_ind} & IN & Array of the column indices of these non 
zero elements. \\
{\tt double *new\_obj\_val} & IN & Array of the values of these non zero 
elements. \\
{\tt double *ub\_for\_new\_obj} & OUT & Pointer to a double indicating the 
upper bound obtained for the new problem. This value will be set to
{\tt SYM\_INFINITY} if an upper bound can not be found.\\
\et

\returns

\bt{lp{317pt}}
{\tt FUNCTION\_TERMINATED\_NORMALLY} & Function invoked successfully.\\
{\tt FUNCTION\_TERMINATED\_ABNORMALLY} & Function invoked unsuccessfully.\\
\et  
\ed
\vspace{1ex}

\ed
\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% END
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Callable Library C++ API}
\label{C++_Interface}

SYMPHONY's C++ interface is derived from COIN-OR's Open Solver Interface
(OSI). The OSI methods are implemented simply as wrapped calls to the SYMPHONY
C callable library just described. For instance, when an instance of the OSI
interface class is constructed, a call is made to
\texttt{sym\_open\_environment()} and a pointer to the environment is stored
in the class and when the OSI object is destroyed,
\texttt{sym\_close\_environment} is called to destroy the environment object. 
Most subsequent calls within the class can then be made without
any arguments. To fully support SYMPHONY's capabilities, we have 
extended the OSI interface to include some other methods not in the base 
class. For example, we added calls equivalent to our 
\texttt{sym\_parse\_command\_line()} and \texttt{sym\_find\_initial\_bounds()}.
Additionally, SYMPHONY has a warm start class derived from the CoinWarmStart 
base class to support the new functionalities of the MILP warm starting such 
as \texttt{sym\_get\_warm\_start} and \texttt{sym\_set\_warm\_start}. They are 
also implemented as wrapped calls to the C interface library. 

In order to have the whole list of the methods and information 
regarding their usage, see the OSI SYMPHONY interface and SYMPHONY warm start
header files (\texttt{OsiSymSolverInterface.hpp} and 
\texttt{SymWarmStart.hpp}). Here, we will give the table of the C library 
equivalent calls of the C++ interface routines with brief descriptions:

\newpage

%\begin{table}
%\centering
\resizebox{15cm}{12cm}{
\begin{tabular}{|l||l||l|} \hline
{\bf C++ Interface} & {\bf C Interface} & {\bf Description}\\ \hline \hline
OsiSymSolverInterface & sym\_open\_environment & 
create a new environment.\\ \hline \hline
loadProblem & sym\_load\_problem & 
load the problem read trough an MPS or GMPL file\\ \hline \hline
branchAndBound & sym\_solve/sym\_warm\_solve & 
solve the MILP problem from scratch or \\
& & from a warm start if loaded. \\ \hline \hline
resolve & sym\_warm\_solve & 
re-solve the MILP problem after some modifications.\\ \hline \hline
initialSolve & sym\_solve & 
solve the MILP problem from scratch.\\ \hline \hline
multiCriteriaBranchAndBound & sym\_mc\_solve & 
solve the multi criteria problem.\\ \hline \hline
setInitialData & sym\_set\_defaults & 
set the parameters to their defaults.\\ \hline \hline
parseCommandLine & sym\_parse\_command\_line & 
read the command line arguments.\\ \hline \hline
findInitialBounds & sym\_find\_initial\_bounds & 
find the initial bounds via the user defined heuristics.\\ \hline \hline
createPermanentCutPools & sym\_create\_permanent\_cut\_pools & 
save the global cuts. \\ \hline \hline
loadProblem & sym\_explicit\_load\_problem & 
load the problem through a set of arrays. \\ \hline \hline
getWarmStart & sym\_get\_warm\_start & 
get the warm start description.\\ \hline \hline
setWarmStart & sym\_set\_warm\_start & 
set the warm start description. \\ \hline
getLbForNewRhs & sym\_get\_lb\_for\_new\_rhs & 
find a lower bound to the new rhs problem\\ 
&&using the post solution info.\\ \hline \hline
getUbForNewRhs & sym\_get\_lb\_for\_new\_rhs & 
find an upper bound to the new rhs problem.\\
&&using the post solution info.\\ \hline \hline
getLbForNewObj & sym\_get\_lb\_for\_new\_rhs & 
find a lower bound to the new obj problem.\\
&&using the post solution info.\\ \hline \hline
getUbForNewObj & sym\_get\_lb\_for\_new\_rhs & 
find an upper bound to the new obj problem.\\
&&using the post solution info.\\ \hline \hline
reset & sym\_close\_environment & 
return the allocated memory.\\ \hline \hline
setIntParam & sym\_set\_int\_param & 
set the integer type OSI parameter.\\ \hline \hline
setSymParam(int) & sym\_set\_int\_param & 
set the integer type SYMPHONY parameter.\\ \hline \hline
setDblParam & sym\_set\_dbl\_param & 
set the double type OSI parameter.\\ \hline \hline
setSymParam(double) & sym\_set\_dbl\_param & 
set the double type SYMPHONY parameter.\\ \hline \hline
setStrParam & sym\_set\_str\_param & 
set the string type OSI parameter.\\ \hline \hline
setSymParam(string) & sym\_set\_str\_param & 
set the string type SYMPHONY parameter.\\ \hline \hline
getIntParam & sym\_get\_int\_param & 
get the value of the integer type OSI parameter. \\ \hline \hline
getSymParam(int \&) & sym\_get\_int\_param & 
get the value of the integer type SYMPHONY parameter. \\ \hline \hline
getDblParam & sym\_get\_dbl\_param & 
get the value of the double type OSI parameter. \\ \hline \hline
getSymParam(double \&) & sym\_get\_dbl\_param & 
get the value of the double type SYMPHONY parameter. \\ \hline \hline
getStrParam & sym\_get\_str\_param & 
get the value of the string type OSI parameter. \\ \hline \hline
getSymParam(string \&) & sym\_get\_str\_param & 
get the value of the string type SYMPHONY parameter. \\ \hline \hline
isProvenOptimal & sym\_is\_proven\_optimal & 
query the problem status. \\ \hline \hline
isProvenPrimalInfeasible & sym\_is\_proven\_primal\_infeasible & 
query the problem status. \\ \hline \hline
isPrimalObjectiveLimitReached & sym\_is\_target\_gap\_achieved & 
query the problem status. \\ \hline \hline
isIterationLimitReached & sym\_is\_iteration\_limit\_reached & 
query the problem status. \\ \hline \hline
isTimeLimitReached & sym\_is\_time\_limit\_reached & 
query the problem status. \\ \hline \hline
isTargetGapReached & sym\_is\_target\_gap\_achieved & 
query the problem status. \\ \hline \hline
getNumCols & sym\_get\_num\_cols & 
get the number of columns. \\ \hline \hline
getNumRows & sym\_get\_num\_rows & 
get the number of rows. \\ \hline \hline
getNumElements & sym\_get\_num\_elements & 
get the number of nonzero elements. \\ \hline \hline
getColLower & sym\_get\_col\_lower & 
get the column lower bounds. \\ \hline \hline
getColUpper & sym\_get\_col\_upper & 
get the column upper bounds. \\ \hline \hline
getRowSense & sym\_get\_row\_sense & 
get the row senses. \\ \hline \hline
getRightHandSide & sym\_get\_rhs & 
get the rhs values. \\ \hline \hline
getRowRange & sym\_get\_row\_range & 
get the row range values. \\ \hline \hline
getRowLower & sym\_get\_row\_lower & 
get the row lower bounds. \\ \hline \hline
getRowUpper & sym\_get\_row\_upper & 
get the row upper bounds. \\ \hline \hline
getObjCoefficients & sym\_get\_obj\_coeff & 
get the objective function vector. \\ \hline
\end{tabular}
}

\newpage

\resizebox{15cm}{10.5cm}{
\begin{tabular}{|l||l||l|} \hline
{\bf C++ Interface} & {\bf C Interface} & {\bf Description}\\ \hline \hline
getObjSense & sym\_get\_obj\_sense & 
get the objective sense. \\ \hline \hline
isContinuous & sym\_is\_continuous & 
query the variable type.\\ \hline \hline
isBinary & sym\_is\_binary &
query the variable type.\\ \hline \hline
isInteger & sym\_is\_integer &
query the variable type.\\ \hline \hline
isIntegerNonBinary & - & 
query the variable type.\\ \hline \hline
isFreeBinary & sym\_is\_binary &
query the variable type.\\ \hline \hline
getMatrixByRow & - & 
get the constraint matrix by row oriented. \\ \hline \hline
getMatrixByCol & - &
get the constraint matrix by column oriented. \\ \hline \hline
getInfinity & - & 
get the infinity definition of SYMPHONY. \\ \hline \hline
getColSolution & sym\_get\_col\_solution & 
get the current best column solution. \\ \hline \hline
getRowActivity & sym\_get\_row\_activity & 
get the current row activity. \\ \hline \hline
getObjValue & sym\_get\_obj\_val &
get the current best objective value. \\ \hline \hline
getPrimalBound & sym\_get\_primal\_bound & 
get the primal upper bound. \\ \hline \hline
getIterationCount & sym\_get\_iteration\_count &
get the number of the analyzed tree nodes. \\ \hline \hline
setObjCoeff & sym\_set\_obj\_coeff & 
set the objective function vector. \\ \hline \hline
setObj2Coeff & sym\_set\_obj2\_coeff & 
set the second objective function vector. \\ \hline \hline
setColLower & sym\_set\_col\_lower & 
set the column lower bounds. \\ \hline \hline
setColUpper & sym\_set\_col\_upper & 
set the column upper bounds. \\ \hline \hline
setRowLower & sym\_set\_row\_lower & 
set the row lower bounds. \\ \hline \hline
setRowUpper & sym\_set\_row\_upper & 
set the row upper bounds. \\ \hline \hline
setRowType & sym\_set\_row\_type & 
set the row characteristics. \\ \hline \hline
setObjSense & sym\_set\_obj\_sense & 
set the objective sense. \\ \hline \hline
setColSolution & sym\_set\_col\_solution & 
set the current solution. \\ \hline \hline
setContinuous & sym\_set\_continuous & 
set the variable type. \\ \hline \hline
setInteger & sym\_set\_integer & 
set the variable type. \\ \hline \hline
setColName & sym\_set\_col\_names & 
set the column names. \\ \hline \hline
addCol & sym\_add\_col & 
add columns to the constraint matrix. \\ \hline \hline
addRow & sym\_add\_row & 
add rows to the constraint matrix. \\ \hline \hline
deleteCols & sym\_delete\_cols & 
delete some columns from the constraint matrix. \\ \hline \hline
deleteRows & sym\_delete\_rows &
delete some rows from the constraint matrix. \\ \hline \hline
writeMps & - & 
write the current problem in MPS format. \\ \hline \hline
applyRowCut & - & 
add some row cuts. \\ \hline \hline
applyColCut & - & 
add some column cuts. \\ \hline \hline
SymWarmStart(warm\_start\_desc *) & sym\_create\_copy\_warm\_start & 
create a SYMPHONY warm start by copying the given one. \\ \hline \hline
SymWarmStart(char *) & sym\_read\_warm\_start & 
create a SYMPHONY warm start reading from file. \\ \hline \hline
getCopyOfWarmStartDesc & sym\_create\_copy\_warm\_start & 
get the copy of the warm start structure. \\ \hline \hline
writeToFile & sym\_write\_warm\_start\_desc & 
write the loaded warm start to a file. \\ \hline
\end{tabular}
%\end{table}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% END
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
