NAG C Library Function Document

nag_opt_sparse_mps_read (e04mzc)

1

Purpose

2

Specification

3

Description

NAME   user-supplied name
ROWS
       data line(s)
COLUMNS
       data line(s)
RHS
       data line(s)
RANGES (optional)
       data line(s)
BOUNDS (optional)
       data line(s)
ENDATA

%N%%DUMMYROW

4

References

5

Arguments

1:    $\mathbf{mps\_file}$ – const char *Input

On entry: the name of the MPSX data file. If mps_file is a null pointer or null string, then the data is assumed to come from stdin.

2:    $\mathbf{n}$ – Integer *Output

On exit: the number of columns (variables) specified by the data file.

3:    $\mathbf{m}$ – Integer *Output

On exit: the number of rows specified by the data file. This is the number of general linear constraints in the problem, including the objective row.

4:    $\mathbf{nnz}$ – Integer *Output

On exit: the number of nonzeros in the problem (including the objective row).

5:    $\mathbf{iobj}$ – Integer *Output

On exit: if $\mathbf{iobj}>0$, row iobj of $A$ is a free row containing the nonzero coefficients of the vector $c$ (the rows of $A$ are indexed $1,2,\dots ,\mathbf{m}$). If $\mathbf{iobj}=0$, the coefficients of $c$ are assumed to be zero.

6:    $\mathbf{a}$ – double **Output

On exit: the nnz nonzero elements of $A$, ordered by increasing column index.

Sufficient memory is allocated internally by nag_opt_sparse_mps_read (e04mzc) and may be freed by the utility function nag_opt_sparse_mps_free (e04myc).

7:    $\mathbf{ha}$ – Integer **Output

On exit: the nnz row indices of the nonzero elements of $A$.

Sufficient memory is allocated internally by nag_opt_sparse_mps_read (e04mzc) and may be freed by the utility function nag_opt_sparse_mps_free (e04myc).

8:    $\mathbf{ka}$ – Integer **Output

On exit: the $\mathbf{n}+1$ indices indicating the beginning of each column of $A$ in a. More precisely, $\mathbf{ka}\left[\mathit{j}-1\right]$ contains the index in a of the start of the $\mathit{j}$th column, for $\mathit{j}=1,2,\dots ,\mathbf{n}-1$. Note that $\mathbf{ka}\left[0\right]=0$ and $\mathbf{ka}\left[\mathbf{n}\right]=\mathbf{nnz}$.

Sufficient memory is allocated internally by nag_opt_sparse_mps_read (e04mzc) and may be freed by the utility function nag_opt_sparse_mps_free (e04myc).

9:    $\mathbf{bl}$ – double **Output

10:  $\mathbf{bu}$ – double **Output

On exit: bl and bu hold the lower bounds and upper bounds, respectively, for all the variables and constraints, in the following order. The first n elements contain the bounds on the variables $x$ and the next m elements contain the bounds for the linear objective term $c^{\mathrm{T}}x$ and the general linear constraints $Ax$ (if any). Note that an ‘infinite’ lower bound is indicated by $\mathbf{bl}\left[j-1\right]=-{10}^{20}$, an ‘infinite’ upper bound by $\mathbf{bl}\left[j-1\right]={10}^{20}$, and an equality constraint by $\mathbf{bl}\left[j-1\right]=\mathbf{bu}\left[j-1\right]$. (The lower bound for $c^{\mathrm{T}}x$, stored in $\mathbf{bl}\left[\mathbf{n}+\mathbf{iobj}-1\right]$, is set to $-\mathbf{options}\mathbf{.}\mathbf{col\_up\_default}$, and the upper bound, stored in $\mathbf{bl}\left[\mathbf{n}+\mathbf{iobj}-1\right]$ is set to $\mathbf{options}\mathbf{.}\mathbf{col\_up\_default}$; the optional parameter $\mathbf{options}\mathbf{.}\mathbf{col\_lo\_default}$ has a default value of ${10}^{20}$; see Section 11.)

Sufficient memory is allocated internally by nag_opt_sparse_mps_read (e04mzc) and may be freed by the utility function nag_opt_sparse_mps_free (e04myc).

11:  $\mathbf{xs}$ – double **Output

On exit: a set of initial values for the n variables and m constraints in the problem. More precisely, $\mathbf{xs}\left[\mathit{j}\right]=\min \left(\max \left(0.0,\mathbf{bl}\left[\mathit{j}\right]\right),\mathbf{bu}\left[\mathit{j}\right]\right)$, for $\mathit{j}=0,1,\dots ,\mathbf{m}+\mathbf{n}-1$.

Sufficient memory is allocated internally by nag_opt_sparse_mps_read (e04mzc) and may be freed by the utility function nag_opt_sparse_mps_free (e04myc).

12:  $\mathbf{options}$ – Nag_E04_Opt *Input/Output

On entry/exit: a pointer to a structure of type Nag_E04_Opt whose members are optional parameters for nag_opt_sparse_mps_read (e04mzc). These structure members offer the means of adjusting the argument values used when reading in the MPSX file and on output will supply further details of the results. A description of the members of options is given below in Section 11.2.

If any of these optional parameters are required then the structure options should be declared and initialized by a call to nag_opt_init (e04xxc) and supplied as an argument to nag_opt_sparse_mps_read (e04mzc). However, if the optional parameters are not required the NAG defined null pointer, E04_DEFAULT, can be used in the function call.

13:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_2_REAL_EE_OPT_ARG_CONS

On entry, $\mathbf{options}\mathbf{.}\mathbf{col\_lo\_default}=〈\mathit{\text{value}}〉$ while $\mathbf{options}\mathbf{.}\mathbf{col\_up\_default}=〈\mathit{\text{value}}〉$. Constraint: $\mathbf{options}\mathbf{.}\mathbf{col\_lo\_default}\le \mathbf{options}\mathbf{.}\mathbf{col\_up\_default}$.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{bnd\_name}$ had an illegal value.

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{obj\_name}$ had an illegal value.

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{output\_level}$ had an illegal value.

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{prob\_name}$ had an illegal value.

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{range\_name}$ had an illegal value.

On entry, argument $\mathbf{options}\mathbf{.}\mathbf{rhs\_name}$ had an illegal value.

NE_INT_OPT_ARG_LT

On entry, $\mathbf{options}\mathbf{.}\mathbf{ncol\_approx}=〈\mathit{\text{value}}〉$. Constraint: $\mathbf{options}\mathbf{.}\mathbf{ncol\_approx}\ge 1$.

On entry, $\mathbf{options}\mathbf{.}\mathbf{nrow\_approx}=〈\mathit{\text{value}}〉$. Constraint: $\mathbf{options}\mathbf{.}\mathbf{nrow\_approx}\ge 1$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_INVALID_REAL_RANGE_F

Value $〈\mathit{\text{value}}〉$ given to $\mathbf{options}\mathbf{.}\mathbf{est\_density}$ is not valid. Correct range is $\mathbf{options}\mathbf{.}\mathbf{est\_density}>0.0$.

NE_MPS_ENDATA_NOT_FOUND

The file does not contain an ENDATA indicator.

NE_MPS_ILLEGAL_DATA_LINE

An illegal data line has been read from the MPSX file. This is neither a comment nor a legal data line.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_ILLEGAL_NAME

An illegal row or column name has been detected. Names must contain only alphanumeric characters with no leading blanks.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_ILLEGAL_NUMBER

Number expected but value could not be read. Check numerical fields.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_ILLEGAL_SETNAME

An illegal name has been detected in Field 2 of the RHS, RANGES or BOUNDS section.
Names must contain only alphanumeric characters with no leading blanks.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_INVALID_BND_TYPE

An invalid bound type appears in the BOUNDS section. Expect: LO, UP, FX, FR, MI, PL, BV or UI.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_INVALID_BND_VAL

Invalid numeric field in bound data. Value expected for types: LO, UP, FX, UI. Blank field expected for types: FR, MI, PL, BV.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_INVALID_INDICATOR

Unknown, unexpected or invalid indicator line read. Expect: NAME, ROWS, COLUMNS, RHS, RANGES, BOUNDS or ENDATA, starting in column 1 of file, and in that order. RANGES and/or BOUNDS may be omitted. Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_INVALID_INTORG_INTEND

An INTORG or INTEND marker is not correctly specified or is unexpected (e.g., INTEND has no matching INTORG).
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_INVALID_ROW_TYPE

An invalid row type appears in the ROWS section. Expect: N, G, L or E.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_NO_COLS

There were no columns specified in the COLUMNS section.
Last MPSX line read ($〈\mathit{\text{value}}〉$): $〈\mathit{string}〉$.

NE_MPS_NO_NEWLINE

New line expected but not found.
Last MPSX line read ($〈\mathit{\text{value}}〉$): $〈\mathit{string}〉$.

NE_MPS_NO_OBJ

The objective row was not found. There must be at least one row of type N in the ROWS section and, if an objective name was specified, there must be a type N row with this name. Last MPSX line read ($〈\mathit{\text{value}}〉$): $〈\mathit{string}〉$.

NE_MPS_NO_ROWS

There were no rows specified in the ROWS section.
Last MPSX line read ($〈\mathit{\text{value}}〉$): $〈\mathit{string}〉$.

NE_MPS_PROB_NOT_FOUND

The specified problem has not been found in the MPSX file.

NE_MPS_REPEAT_ROW

A row has been specified more than once.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_RHS_RANGE_BND_NOT_FOUND

The name of the RHS, RANGES or BOUNDS set to be used was not found in the file.

NE_MPS_SPLIT_COL

Column data is not contiguous. All entries for a given column must appear together in the COLUMNS section.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_UNKNOWN_COLNAME

An unknown column name appears in the BOUNDS section. All the column names must be specified in the COLUMNS section.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_MPS_UNKNOWN_ROWNAME

An unknown row name appears in the $〈\mathit{string}〉$ section. All the row names must be specified in the ROWS section.
Error at MPSX line $〈\mathit{\text{value}}〉$: $〈\mathit{string}〉$.

NE_NAMES_NOT_NAG_MEM

$\mathbf{options}\mathbf{.}\mathbf{crnames}$ is not null but does not point to memory allocated by an earlier call to this function. This function does not accept user-allocated memory assigned to $\mathbf{options}\mathbf{.}\mathbf{crnames}$.

NE_NOT_APPEND_FILE

Cannot open file $〈\mathit{string}〉$ for appending.

NE_NOT_CLOSE_FILE

Cannot close file $〈\mathit{string}〉$.

NE_NOT_READ_FILE

Cannot open file $〈\mathit{string}〉$ for reading.

NE_NULL_ARGUMENT

Argument a is a null pointer. It should contain the address of a variable of type double *.

Argument bl is a null pointer. It should contain the address of a variable of type double *.

Argument bu is a null pointer. It should contain the address of a variable of type double *.

Argument ha is a null pointer. It should contain the address of a variable of type Integer *.

Argument iobj is a null pointer. It should contain the address of a variable of type Integer.

Argument ka is a null pointer. It should contain the address of a variable of type Integer *.

Argument m is a null pointer. It should contain the address of a variable of type Integer.

Argument n is a null pointer. It should contain the address of a variable of type Integer.

Argument nnz is a null pointer. It should contain the address of a variable of type Integer.

Argument xs is a null pointer. It should contain the address of a variable of type double *.

NE_OPT_NOT_INIT

Options structure not initialized.

NE_WRITE_ERROR

Error occurred when writing to file $〈\mathit{string}〉$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04mzce.c)

10.2

Program Data

Program Data (e04mzce.d)

10.3

Program Results

Program Results (e04mzce.r)

11

Optional Parameters

11.1

Optional Parameter Checklist and Default Values

11.2

Description of the Optional Parameters

11.3

Description of Printed Output

12

Example 2 (ex2)