CPXmpsread

Description

The routine CPXmpsread() is used to allocate memory for a CPLEX LP problem object and then to read a problem stored in a file into that memory. Problems stored in MPS format are read using the routine CPXmpsread(). The MPS format is described in detail in.Appendix E, File Formats.

Memory allocated by a successful invocation of these routines must be explicitly freed by the user when finished working with the problem.

The specific arrays for which allocated space must be freed include:

Depending on the MPS data and the argument numrims_p, some of these arrays will not be allocated. See the detailed description of the CPXmpsread arguments.

Most of the arguments to CPXmpsread() are variables that will contain the addresses of arrays describing the problem will be stored. Upon invoking CPXmpsread(), a default amount of memory is initially allocated for problem data. The size of the default memory allocations can be accessed using the CPXgetintparam() routine and the parameters CPX_PARAM_COLREADLIM, CPX_PARAM_ROWREADLIM, CPX_PARAM_NZREADLIM, CPX_PARAM_RIMREADLIM, and CPX_PARAM_RIMNZREADLIM described in Appendix A, Parameter Table. The amount of space actually needed for these arrays is calculated when the file containing the problem is read. The length of each array upon return from one of the file reading functions is contained in the location pointed to by one of the arguments colspace_p, rowspace_p, nzspace_p, colnamespace_p, rownamespace_p, rimspace_p, rimnzspace_p, and rimnamespace_p.

Specifically, the arrays and their associated lengths are shown below.

Length
Arrays

*colspace_p
*obj_p, *matbeg_p, *matcnt_p, *lb_p,
*ub_p, *colname_p

*rowspace_p
*rhs_p, *sen_p, *rowname_p, *rngval_p

*nzspace_p
*matind_p, *matval_p

*rimspace_p
*rimtype_p, *rimname_p, *rimbeg_p,
*rimcnt,_p, *freerowind_p

*rimnzspace_p
*rimind_p, *rimval_p

*colnamespace_p
*colnamestore_p

*rownamespace_p
*rownamestore_p

*rimnamespace_p
*rimnamestore_p

Length	Arrays
`*colspace_p`	`obj_p,` `matbeg_p, matcnt_p, lb_p,` `ub_p, colname_p`
`*rowspace_p`	`rhs_p, sen_p, rowname_p, rngval_p`
`*nzspace_p`	`matind_p, matval_p`
`*rimspace_p`	`rimtype_p, rimname_p, rimbeg_p,` `rimcnt,_p, *freerowind_p`
`*rimnzspace_p`	`rimind_p, rimval_p`
`*colnamespace_p`	`*colnamestore_p`
`*rownamespace_p`	`*rownamestore_p`
`*rimnamespace_p`	`*rimnamestore_p`

The file reading functions will allocate additional space for the returned arrays based upon the values in the length variables when the function is called. For example, if *rowspace_p = 500 when CPXmpsread() is called, then the arrays *rhs_p, *sense_p, *rngval_p and *rowname_p will be allocated so that they are 500 entries longer than is necessary to hold the relevant data from the problem being read. The same is true for *colspace_p, *nzspace_p, *colnamespace_p, *rownamespace_p, *rimnzspace_p, and *rimnamespace_p.

Return Value

If the file is successfully read, CPXmpsread() returns the value 0 and the data pointed to by the following arguments are pointers to allocated memory: obj_p, rhs_p, sense_p, matbeg_p, matcnt_p, matind_p, matval_p, lb_p, ub_p, objname_p, rhsname_p, colname_p, rowname_p, colnamestore_p, rownamestore_p, dataname_p, bndname_p, rngname_p, rimname_p, rimnamestore_p, rimtype_p, rimind_p, rimval_p, rimbeg_p, rimcnt_p, rngval_p, and freerowind_p. If the file is not read successfully, a nonzero value is returned indicating the nature of the error, that the problem was not read, and that no memory was allocated.

Synopsis

int CPXmpsread (CPXENVptr env,
                char *filename,
                int *numcols_p,
                int *numrows_p,
                int *numrims_p,
                int *objsen_p,
                double **obj_p,
                double **rhs_p,
                char **sense_p,
                int **matbeg_p,
                int **matcnt_p,
                int **matind_p,
                double **matval_p,
                double **lb_p,
                double **ub_p,
                double **rngval_p,
                int **freerowind_p,
                int **rimtype_p,
                int **rimbeg_p,
                int **rimcnt_p,
                int **rimind_p,
                double **rimval_p,
                char **dataname_p,
                char **objname_p,
                char **rhsname_p,
                char **rngname_p,
                char **bndname_p,
                char ***colname_p,
                char **colnamestore_p,
                char ***rowname_p,
                char **rownamestore_p,
                char ***rimname_p,
                char **rimnamestore_p,
                int *colspace_p,
                int *rowspace_p,
                int *nzspace_p,
                int *rimspace_p,
                int *rimnzspace_p,
                unsigned *colnamespace_p,
                unsigned *rownamespace_p,
                unsigned *rimnamespace_p);

Arguments


CPXENVptr env

The pointer to the CPLEX environment as returned by one of the CPXopenCPLEX routines.

char *filename

A character string that is the name of the file to be read.

int *numcols_p

A pointer to an integer that will contain the number of columns in the constraint matrix or, equivalently, the number of variables in the CPLEX LP problem object.

int *numrows_p

A pointer to an integer that will contain the number of rows in the constraint matrix not including the objective function or bound constraints on the variables.

int *numrims_p

A pointer to an integer that will contain the number of extra free row, bound, range and right-hand side vectors. If numrims_p is NULL, the arrays corresponding to freerowind_p, rimtype_p, rimbeg_p, rimcnt_p, rimind_p, rimval_p, rimname_p and rimnamestore_p will not be allocated and any information in the MPS data set that would have been stored in these arrays will be lost.

int *objsen_p

A pointer to an integer that will contain a value indicating whether the problem is a minimization or maximization problem. Possible values are:

CPX_MIN
(1)
minimize

CPX_MAX
(-1)
maximize

`CPX_MIN`	(1)	minimize
`CPX_MAX`	(-1)	maximize

double **obj_p

A pointer to a variable that will contain the address of an array containing the objective function coefficients.

double **rhs_p

A pointer to a variable that will contain the address of an array containing the right-hand side coefficient for each constraint in the problem object.

char **sense_p

A pointer to a variable that will contain the address of an array containing the sense of each constraint in the problem object. Possible values are:

'L'
constraint

'E'
= constraint

'G'
constraint

'R'
ranged constraint

'L'	constraint
'E'	= constraint
'G'	constraint
'R'	ranged constraint

int **matbeg_p
int **matcnt_p
int **matind_p
double **matval_p

These four arguments are pointers to variables that will contain the address of arrays that describe the constraint matrix, including free rows but no rim rows. CPLEX reads only the nonzero coefficients grouped by column in the array *matval_p. Every column is stored in sequential locations in this array with (*matbeg_p)[i] containing the index of the beginning of column i and (*matcnt_p)[i] containing the number of entries in column i. Each entry, (*matind_p)[i], indicates the row number of the corresponding coefficient, (*matval_p)[i].

double **lb_p

A pointer to a variable that will contain the address of an array containing the lower bound on each of the variables.

double **ub_p

A pointer to a variable that will contain the address of an array containing the upper bound on each of the variables.

double **rngval_p

A pointer to a variable that will contain the address of an array containing the range values of RHS ranged constraints.

int **freerowind_p

A pointer to a variable that will contain the address of an array containing the original row index for each free row, excluding the objective row, in the original problem matrix before being extracted by CPXmpsread(). *freerowind_p is not allocated if numrims_p is NULL or if *rimspace_p is 0 after the call to CPXmpsread().

int **rimtype_p

A pointer to a variable that will contain the address of an array containing the original row index for each free row, excluding the objective row, in the original problem matrix before being extracted by CPXmpsread(). *rimtype_p is not allocated if numrims_p is NULL or if *rimspace_p is 0 after the call to CPXmpsread(). Possible values are:

1
Extra free row

2
Extra RHS rim vector

3
Extra range rim vector

4
Extra lower bound rim vector

5
Extra upper bound rim vector

1	Extra free row
2	Extra RHS rim vector
3	Extra range rim vector
4	Extra lower bound rim vector
5	Extra upper bound rim vector

int **rimbeg_p
int **rimcnt_p
int **rimind_p
double **rimval_p

These four arguments are pointers to variables that will contain the addresses of arrays that describe the extra rim vectors. Extra free-rows (rimtype = 1) have their coefficients stored in the arrays (*matind_p) and (*matval_p). (*rimbeg_p)[i] gives an index into (*matind_p) and (*matval_p). The coefficients for the other rim vector types are stored in the arrays (*rimind_p) and (*rimval_p). (*rimbeg_p)[i] gives the index into (*rimind_p) and (*rimval_p) for the first coefficient of the vector. For extra RHS and range vectors, the nonzero RHS and range coefficients are stored with their row indices. For a single extra bound vector, two extra vectors are stored, one of (*rimtype_p)[i] = 4 for the nonzero lower bound values, and one of (*rimtype_p)[i+1] = 5 for the non-infinity upper bound values. The column indices for these bound entries are stored in *rimind_p. The number of nonzeros in the ith extra rim vector is stored in (*rimcnt_p)[i].

These arrays are not allocated if numrims_p is NULL or if *rimspace_p is 0 after the call to CPXmpsread().

char **dataname_p

A pointer to a variable that will contain the address of a character string that indicates the name of the problem as defined on the NAME record of the input file.

char **objname_p

A pointer to a variable that will contain the address of a character string that indicates the name of the objective function.

char **rhsname_p

A pointer to a variable that will contain the address of a character string that indicates the name of the right-hand side vector.

char **rngname_p

A pointer to a variable that will contain the address of a a character string that indicates the name of the range vector.

char **bndname_p

A pointer to a variable that will contain the address of a character string that indicates the name of the selected bound vector.

char ***colname_p
char **colnamestore_p

colname_p is a pointer to a variable that will contain the address of an array containing pointers to character strings stored in the array *colnamestore_p. colnamestore_p is a pointer to a variable that will hold the address of an array of characters. These strings represent the names of the matrix columns, or equivalently, the variable names.

char ***rowname_p
char **rownamestore_p

rowname_p is a pointer to a variable that will contain the address of an array containing pointers to character strings stored in the array *rownamestore_p. rownamestore_p is a pointer to a variable that will hold the address of an array of characters. These strings represent the names of the matrix rows, or equivalently, the constraint names.

char ***rimname_p
char **rimnamestore_p

rimname_p is a pointer to a variable that will contain the address of an array containing pointers to character strings stored in *rimnamestore_p. rimnamestore_p is a pointer to a variable that will hold the address of an array of characters. These strings represent the names of the extra rim vectors. rimname_p and rimnamestore_p are NULL if *rimspace_p is 0 after the call to CPXmpsread().

int *colspace_p

A pointer to an integer that represents the length of the arrays pointed to by *obj_p, *matbeg_p, *matcnt_p, *lb_p, *ub_p, and *colname_p. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

int *rowspace_p

A pointer to an integer that represents the length of the arrays pointed to by *rhs_p, *sense_p, *rngval_p and *rowname_. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

int *nzspace_p

A pointer to an integer that represents the length of the arrays pointed to by *matind_p and *matval_p. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

int *rimspace_p

A pointer to an integer that represents the length of the arrays pointed to by *rimtype_p, *rimname_p, *rimbeg_p and *rimcnt_p. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

int *rimnzspace_p

A pointer to an integer that represents the length of the arrays pointed to by *rimind_p and *rimval_p. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

unsigned *colnamespace_p

A pointer to an unsigned integer that represents the length of the array pointed to by *colnamestore_p. It is also used, as described at the beginning of this section, to allocate additional space for this array.

unsigned *rownamespace_p

A pointer to an unsigned integer that indicates the length of the array pointed to by *rownamestore_p. It is also used, as described at the beginning of this section, to allocate additional space for this array.

unsigned *rimnamespace_p

A pointer to an unsigned integer that represents the length of the array pointed to by *rimnamestore_p. It is also used, as described at the beginning of this section, to allocate additional space for these arrays.

Example

status = CPXmpsread (env, filename, &numcols, &numrows, &numrims,
                     &objsen, &obj, &rhs, &sense, &matbeg,
                     &matcnt, &matind, &matval, &lb, &ub,
                     &rngval, &freerowind, &rimtype, &rimbeg,
                     &rimcnt, &rimind, &rimval, &dataname,
                     &objname, &rhsname, &rngname, &bndname,
                     &colname, &colnamestore, &rowname,
                     &rownamestore, &rimname, &rimnamestore,
                     &colspace, &rowspace, &nzspace, &rimspace,
                     &rimnzspace, &colnamespace, &rownamespace,
                     &rimnamespace);