naginterfaces.library.opt.handle_​read_​file

naginterfaces.library.opt.handle_read_file(file, ftype)

handle_read_file initializes a data structure for the NAG optimization modelling suite from a data file for problems such as, Linear Programming (LP), Quadratic Programming (QP), Second-order Cone Programming (SOCP), or linear Semidefinite Programming (SDP).

For full information please refer to the NAG Library document for e04sa

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e04/e04saf.html

Parameters

filestr

The name of the file to be opened.

ftypestr

The expected file format of the input file. $ftype$ is case insensitive.

$ftype=\text{'MPS'}$ or $\text{'M'}$

The input file is in MPS format.

$ftype=\text{'SDPA'}$ or $\text{'S'}$

The input file is in SDPA format.

Returns

handleHandle

Holds a handle to the internal data structure. It must not be changed between calls to the NAG optimization modelling suite.

pinfoint, ndarray, shape $\left(100\right)$

Problem sizes and statistics as given in the table below:

$0$	Number of variables ($\text{nvar}$).
$1$	Number of integer variables.
$2$	Number of binary variables.
$10$	Number of Lagrange multipliers (dual variables) for the bound constraints and linear constraints ($\text{nnzu}$).
$11$	Number of Lagrange multipliers (dual variables) for the cone constraints ($\text{nnzuc}$).
$12$	Number of nonzeros in all Lagrange multipliers for the matrix constraints ($\text{nnzua}$).
$20$	Flag indicating the objective function type, $0$: no objective, $1$: linear objective, $2$: quadratic without linear term, $3$: quadratic with linear term, $4$: general nonlinear, $5$: nonlinear least square with dense Jacobian, $6$: nonlinear least square with sparse Jacobian.
$21$	Number of residuals defined in a nonlinear least square problem.
$30$	Definition of box constraints, $0$: not defined, $1$: defined.
$31$	Number of linear constraints.
$32$	Number of nonlinear constraints.
$33$	Definition of Hessian for nonlinear objective and constraints, $0$: not defined, $-1$: defined as Lagrangian, $1$: defined as individual Hessians of the objective and the constraints.
$40$	Number of cone constraints.
$41$	Number of matrix inequality constraints.
$42$	Number of quadratic constraints.
otherwise	Reserved for future use.
$42$–$99$	Reserved for future use.

$\text{nvar}$, $\text{nnzu}$, $\text{nnzuc}$ and $\text{nnzua}$ define the problem size and are required by other functions such as handle_solve_lp_ipm(), handle_solve_socp_ipm() and handle_solve_pennon() in the optimization suite.

Raises

NagValueError

(errno $1$)

On entry, $ftype=⟨value⟩$.

Constraint: $ftype=\text{'MPS'}$, $\text{'M'}$, $\text{'SDPA'}$ or $\text{'S'}$.

(errno $2$)

Cannot open file $⟨value⟩$ for reading.

(errno $3$)

Cannot close file.

(errno $4$)

The input file seems to be empty. No data was read.

(errno $5$)

Reading from the file caused an unknown error on line $⟨value⟩$.

(errno $50$)

The token on line $⟨value⟩$ at position $⟨value⟩$ to $⟨value⟩$ was not recognized as a valid integer.

(errno $51$)

The token on line $⟨value⟩$ at position $⟨value⟩$ to $⟨value⟩$ was not recognized as a valid real number.

(errno $52$)

The token on line $⟨value⟩$ starting at position $⟨value⟩$ was too long and was not recognized.

(errno $53$)

An invalid number of variables was given on line $⟨value⟩$.

The number stated there is $⟨value⟩$ and needs to be at least $1$.

(errno $54$)

An invalid number of blocks was given on line $⟨value⟩$.

The number stated there is $⟨value⟩$ and needs to be at least $1$.

(errno $55$)

An invalid size of the block number $⟨value⟩$ was given on line $⟨value⟩$.

The number stated there is $⟨value⟩$ and needs to be nonzero.

(errno $56$)

Not enough data was given on line $⟨value⟩$ specifying block sizes.

Expected $⟨value⟩$ tokens but found only $⟨value⟩$.

(errno $57$)

Not enough data was given on line $⟨value⟩$ specifying the objective function.

Expected $⟨value⟩$ tokens but found only $⟨value⟩$.

(errno $58$)

Not enough data was given on line $⟨value⟩$ specifying nonzero matrix elements.

Expected $⟨value⟩$ tokens but found only $⟨value⟩$.

(errno $59$)

Invalid structural data found on line $⟨value⟩$.

The given matrix number is out of bounds. Its value $⟨value⟩$ must be between $⟨value⟩$ and $⟨value⟩$ (inclusive).

(errno $60$)

Invalid structural data found on line $⟨value⟩$.

The given block number is out of bounds. Its value $⟨value⟩$ must be between $⟨value⟩$ and $⟨value⟩$ (inclusive).

(errno $61$)

Invalid structural data found on line $⟨value⟩$.

The given row index is out of bounds, it must respect the size of the block. Its value $⟨value⟩$ must be between $⟨value⟩$ and $⟨value⟩$ (inclusive).

(errno $62$)

Invalid structural data found on line $⟨value⟩$.

The given column index is out of bounds, it must respect the size of the block. Its value $⟨value⟩$ must be between $⟨value⟩$ and $⟨value⟩$ (inclusive).

(errno $63$)

Invalid structural data found on line $⟨value⟩$.

The specified nonzero element is not in the upper triangle.

The row index is $⟨value⟩$ and column index is $⟨value⟩$.

(errno $64$)

Invalid structural data found on line $⟨value⟩$.

The specified element belongs to a diagonal block but is not diagonal.

The row index is $⟨value⟩$ and column index is $⟨value⟩$.

(errno $65$)

An entry in the constraints with $matno=⟨value⟩$, $blkno=⟨value⟩$, row index $⟨value⟩$ and column index $⟨value⟩$ was defined more than once. All entries need to be unique.

(errno $66$)

A premature end of the input stream. The part defining the number of variables was not found.

(errno $66$)

A premature end of the input stream. The part defining the number of blocks was not found.

(errno $66$)

A premature end of the input stream. The part defining the dimensions of the blocks was not found.

(errno $66$)

A premature end of the input stream. The part defining the objective function was not found.

(errno $66$)

A premature end of the input stream. The part defining the nonzero entries was not found.

(errno $100$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

OBJNAME indicator line found after ROWS indicator line.

(errno $101$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

COLUMNS indicator line found before ROWS indicator line.

(errno $102$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

RHS indicator line found before COLUMNS indicator line.

(errno $103$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

RANGES indicator line found before RHS indicator line.

(errno $104$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

BOUNDS indicator line found before COLUMNS indicator line.

(errno $105$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

QUADOBJ indicator line found before BOUNDS indicator line.

(errno $106$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

QUADOBJ indicator line found before COLUMNS indicator line.

(errno $107$)

Line $⟨value⟩$: Incorrect ordering of indicator lines.

CSECTION indicator line found before COLUMNS indicator line.

(errno $108$)

Line $⟨value⟩$: Unknown indicator line $⟨value⟩$.

(errno $109$)

Line $⟨value⟩$: Indicator line ‘$⟨value⟩$’ has been found more than once in the MPS file.

(errno $110$)

End of file found before ENDATA indicator line.

(errno $111$)

At least one mandatory section not found in MPS file.

(errno $112$)

Line $⟨value⟩$: An illegal line was detected in $⟨value⟩$ section.

This is neither a comment nor a valid data line.

(errno $113$)

Line $⟨value⟩$: Unknown inequality key $⟨value⟩$ in ROWS section.

Expected ‘N’, ‘G’, ‘L’ or ‘E’.

(errno $114$)

Line $⟨value⟩$: Empty ROWS section.

Neither the objective row nor the constraints were defined.

(errno $115$)

The supplied name in OBJNAME of the objective row was not found among the free rows in the ROWS section.

(errno $116$)

Line $⟨value⟩$: Illegal row name.

Row names must consist of printable characters only.

(errno $117$)

Line $⟨value⟩$: Illegal column name.

Column names must consist of printable characters only.

(errno $118$)

Line $⟨value⟩$: Row name $⟨value⟩$ has been defined more than once in the ROWS section.

(errno $119$)

Line $⟨value⟩$: Column ‘$⟨value⟩$’ has been defined more than once in the COLUMNS section. Column definitions must be continuous. (See COLUMNS Section).

(errno $120$)

Line $⟨value⟩$: Found 'INTORG' marker within 'INTORG' to 'INTEND' range.

(errno $121$)

Line $⟨value⟩$: Found 'INTEND' marker without previous marker being 'INTORG'.

(errno $122$)

Line $⟨value⟩$: Found 'INTORG' but not 'INTEND' before the end of the COLUMNS section.

(errno $123$)

Line $⟨value⟩$: Illegal marker type $⟨value⟩$.

Should be either 'INTORG' or 'INTEND'.

(errno $124$)

Line $⟨value⟩$: Unknown row name $⟨value⟩$ in $⟨value⟩$ section.

All row names must be specified in the ROWS section.

(errno $125$)

Line $⟨value⟩$: Unknown column name $⟨value⟩$ in $⟨value⟩$ section.

All column names must be specified in the COLUMNS section.

(errno $126$)

Inconsistent bounds for row ‘$⟨value⟩$’.

(errno $126$)

Inconsistent bounds for column ‘$⟨value⟩$’.

(errno $126$)

Line $⟨value⟩$: Unknown bound type $⟨value⟩$ in BOUNDS section.

(errno $127$)

More than one nonzero of $A$ has row name ‘$⟨value⟩$’ and column name ‘$⟨value⟩$’ in the COLUMNS section.

(errno $128$)

Field $⟨value⟩$ did not contain a number (see MPS input format).

(errno $129$)

Both quadratic objective and cone constraints found, not supported.

(errno $130$)

Line $⟨value⟩$: Second-order cone $⟨value⟩$ should have at least $2$ variables.

(errno $130$)

Line $⟨value⟩$: Rotated second-order cone $⟨value⟩$ should have at least $3$ variables.

(errno $131$)

Line $⟨value⟩$: Unknown cone type $⟨value⟩$.

(errno $132$)

Line $⟨value⟩$: Illegal cone name.

Cone names must consist of printable characters only.

(errno $133$)

Line $⟨value⟩$: Cone name $⟨value⟩$ has been defined more than once.

(errno $134$)

Line $⟨value⟩$: Column name $⟨value⟩$ has been defined more than once in cone constraint.

Notes

handle_read_file reads a file in one of the supported file formats and stores the data in a new handle. The supported formats are MPS and its derivatives (for LP, QP, SOCP) and sparse SDPA for linear semidefinite programming problems. See Further Comments for more details on the supported file formats. It might be useful to refer to the file format you use to fully understand the possible error messages. Once the file is successfuly processed, the problem can be solved by a compatible solver from the suite or queried via the printing function handle_print(). Once the problem is not needed any more, handle_free() should be called to destroy the handle and deallocate the memory held within. See the E04 Introduction for more details about the NAG optimization modelling suite. Also see the E04 Introduction for more details on the standard formulations of the optimization problems (e.g., LP, QP, SOCP and SDP) for better understanding on the notations used in this document.

References

Borchers, B, 1999, SDPLIB 1.2, A Library of semidefinite programming test problems, Optimization Methods and Software (11(1)), 683–690, http://euler.nmt.edu/~brian/sdplib/

Fujisawa, K, Kojima, M and Nakata, K, 1998, SDPA (Semidefinite Programming Algorithm) User’s Manual, Technical Report B-308, Department of Mathematical and Computing Sciences, Tokyo Institute of Technology.

IBM, 1971, MPSX – Mathematical programming system, Program Number 5734 XM4, IBM Trade Corporation, New York