E04RDF (PDF version)
E04 Chapter Contents
E04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

E04RDF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

E04RDF reads in a linear semidefinite programming problem (SDP) from a file in sparse SDPA format and returns it in the form which is usable by routines E04RAF (initialization), E04REF (linear objective function), E04RNF (linear matrix constraints), E04SVF (solver) and E04RZF (deallocation) from the NAG optimization modelling suite.

2  Specification

SUBROUTINE E04RDF ( INFILE, MAXNVAR, MAXNBLK, MAXNNZ, FILELST, NVAR, NBLK, NNZ, CVEC, NNZA, IROWA, ICOLA, A, BLKSIZEA, IFAIL)
INTEGER  INFILE, MAXNVAR, MAXNBLK, MAXNNZ, FILELST, NVAR, NBLK, NNZ, NNZA(MAXNVAR+1), IROWA(MAXNNZ), ICOLA(MAXNNZ), BLKSIZEA(MAXNBLK), IFAIL
REAL (KIND=nag_wp)  CVEC(MAXNVAR), A(MAXNNZ)

3  Description

E04RDF is capable of reading linear semidefinite programming problems (SDP) from a text file in sparse SDPA format. The problem is captured and returned in the following form:
minimize xn cTx   (a) subject to   i=1 n xi Ai - A0 0 ,   (b) (1)
where Ai denotes symmetric matrices and c is a vector. The expression S0 stands for a constraint on the eigenvalues of a symmetric matrix S, namely, all the eigenvalues should be non-negative, i.e., the matrix S should be positive semidefinite.
Please note that this form covers even general linear SDP formulations with multiple linear matrix inequalities and a set of standard linear constraints. A set of mA linear matrix inequalities
i=1 n xi Aik - A0k 0 ,  k=1,,mA (2)
can be equivalently expressed as one matrix inequality (1)(b) in the following block diagonal form where the matrices Ai1 , Ai2 , , AimA  create the diagonal blocks of Ai:
i=1 n xi Ai1 Ai2 AimA - A01 A02 A0mA 0 .  
In addition, notice that if all matrices A i k  belonging to the same block, say block k, are themselves diagonal matrices (or have dimension 1×1), the associated matrix inequality
i=1 n xi Aik - A0k 0 (3)
defines actually a standard linear constraint
Bxl  
where l and columns of the matrix B are formed by the diagonals of matrices A0k and A1k,,Ank, respectively. Precisely, li = A0k ii  and bij = Ajk ii . See Section 10.

3.1  Sparse SDPA file format

The problem data is written in an ASCII input file in a SDPA sparse format which was first introduced in Fujisawa et al. (1998). In the description below we follow closely the specification from Borchers (1999).
The format is line oriented. If more elements are required on the line they need to be separated by a space, a tab or any of the special characters ‘,’, ‘(’, ‘)’, ‘{’ or ‘}’. The file consists of six sections:
1. Comments. The file can begin with arbitrarily many lines of comments. Each line of comments must begin with ‘"’ or ‘*’.
2. The first line after the comments contains integer n, the number of variables. The rest of this line is ignored.
3. The second line after the comments contains integer mA, the number of blocks in the block diagonal structure of the matrices. Additional text on this line after mA is ignored.
4. The third line after the comments contains a vector of mA integers that give the sizes of the individual blocks. Negative numbers may be used to indicate that a block is actually a diagonal submatrix. Thus a block size of ‘-5’ indicates a 5 by 5 block in which only the diagonal elements are nonzero.
5. The fourth line after the comments contains an n-dimensional real vector defining the objective function vector c.
6. The remaining lines of the file contain nonzero entries in the constraint matrices, with one entry per line. The format for each line is
matno blkno i j entry  
where matno is the number 0,,n of the matrix to which this entry belongs and blkno specifies the block number k=1,2,,mA within this matrix. Together, they uniquely identify the block A matno blkno . Integers i and j are one-based indices which specify a location of the entry within the block. Note that since all matrices are assumed to be symmetric, only entries in the upper triangle of a matrix should be supplied. Finally, entry should give the real value of the entry in the matrix. Precisely, A matno blkno i j = A matno blkno j i = entry .
In the text below and in the file listing (FILELST) we use the word ‘token’ as a reference to a group of contiguous characters without a space or any other delimeters.

3.2  Recommendation on how best to use E04RDF

(a) The input file with the problem needs to be opened for reading by X04ACF (MODE=0). In this way we avoid possible limitations of maximal lengths of lines inherited by Fortran I/O (X04ACF uses the formatted stream access mode to bypass the restriction). If the file is opened by other means or standard input is used instead, lines within the file might be truncated which would produce a file format error message. This would most likely happen on the line defining the objective function. Setting FILELST=1 might help with possible file formatting errors.
(b) Unless the dimension of the problem (or its overestimate) is known in advance, call E04RDF initially with MAXNVAR=0, MAXNBLK=0 and MAXNNZ=0. In this case the exact size of the problem is computed and returned in NVAR, NBLK and NNZ. No other data will be stored and none of the arrays CVEC, NNZA, IROWA, ICOLA, A, BLKSIZEA will be referenced. Then the exact storage can be allocated and the file reopened. When E04RDF is called for the second time, the problem is read in and stored in appropriate arrays.
(c) The example in Section 10 shows a typical sequence of calls to solve the problem read in by E04RDF. First an empty handle needs to be initialized by E04RAF with NVAR variables. This should be followed by calls to E04REF and E04RNF to formulate the objective function and the constraints, respectively. The arguments of both routines use the same naming and storage as in E04RDF so the variables can be passed unchanged; only DIMA in E04RNF is new and should equal to SUM BLKSIZEA1:NBLK  and NNZASUM in E04RNF is the same as NNZ in E04RDF. You may at this point want to modify option settings using E04ZMF. If dual variables (Lagrangian multipliers) are required from the solver, sufficient space needs to be allocated. The size is equal to the sum of the number of elements of dense triangular matrices for each block. For further details, see the argument UA of the solver E04SVF. The solver should be called and then followed, finally, by a call to E04RZF to deallocate memory associated with the problem.

4  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.

5  Arguments

1:     INFILE – INTEGERInput
On entry: the unit number associated with the sparse SDPA data file. Note:  that the file needs to be opened in read mode by X04ACF with MODE=0.
Constraint: INFILE0.
2:     MAXNVAR – INTEGERInput
On entry: the upper limit for the number of variables in the problem. If it is set to zero, CVEC and NNZA will not be referenced.
Constraint: MAXNVAR0.
3:     MAXNBLK – INTEGERInput
On entry: the upper limit for the number of matrix constraints (i.e., the number of diagonal blocks within the matrix). If it is set to zero, BLKSIZEA will not be referenced.
Constraint: MAXNBLK0.
4:     MAXNNZ – INTEGERInput
On entry: the upper limit on the sum of nonzeros in all matrices Aik, for i=0,1,,NVAR and k=1,2,,NBLK. If it is set to zero, IROWA, ICOLA and A will not be referenced.
Constraint: MAXNNZ0.
5:     FILELST – INTEGERInput
On entry: if FILELST0, a listing of the input data is sent to the current advisory message unit (as defined by X04ABF). This can be useful for debugging the data file.
If FILELST=0, no listing is produced.
6:     NVAR – INTEGEROutput
7:     NBLK – INTEGEROutput
8:     NNZ – INTEGEROutput
On exit: the actual number of the variables n, matrix constraints mA and number of nonzeros of the problem in the file. This also indicates the exact memory needed in CVEC, NNZA, IROWA, ICOLA, A and BLKSIZEA.
9:     CVECMAXNVAR – REAL (KIND=nag_wp) arrayOutput
On exit: CVECi, for i=1,2,,NVAR, stores the dense vector c of the linear objective function.
10:   NNZAMAXNVAR+1 – INTEGER arrayOutput
On exit: NNZAi+1, for i=0,1,,NVAR, stores the number of nonzero elements in matrices Ai.
11:   IROWAMAXNNZ – INTEGER arrayOutput
12:   ICOLAMAXNNZ – INTEGER arrayOutput
13:   AMAXNNZ – REAL (KIND=nag_wp) arrayOutput
On exit: IROWA, ICOLA and A store the nonzeros in the upper triangle of matrices Ai, for i=0,1,,NVAR, in the coordinate storage, i.e., IROWAj are one-based row indices, ICOLAj are one-based column indices and Aj are the values of the nonzero elements, for j=1,2,,NNZ. See Section 9.
14:   BLKSIZEAMAXNBLK – INTEGER arrayOutput
On exit: BLKSIZEAk, for k=1,2,,NBLK, stores the sizes of the diagonal blocks in matrices Ai from the top to the bottom.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: E04RDF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
At least one of MAXNVAR, MAXNBLK or MAXNNZ is too small. Suggested values are returned in NVAR, NBLK and NNZ, respectively.
IFAIL=2
The token on line value at position value to value was not recognized as a valid integer.
IFAIL=3
The token on line value at position value to value was not recognized as a valid real number.
IFAIL=4
The token on line value starting at position value was too long and was not recognized.
IFAIL=5
An invalid number of variables was given on line value.
The number stated there is value and needs to be at least 1.
IFAIL=6
An invalid number of blocks was given on line value.
The number stated there is value and needs to be at least 1.
IFAIL=7
An invalid size of the block number value was given on line value.
The number stated there is value and needs to be nonzero.
IFAIL=8
Not enough data was given on line value specifying block sizes.
Expected mA tokens but found only value.
IFAIL=9
Not enough data was given on line value specifying the objective function.
Expected n tokens but found only value.
IFAIL=10
Not enough data was given on line value specifying nonzero matrix elements.
Expected value tokens but found only value.
IFAIL=11
Invalid structural data found on line value.
The given matrix number is out of bounds. Its value value must be between 0 and n (inclusive).
IFAIL=12
Invalid structural data found on line value.
The given block number is out of bounds. Its value value must be between 1 and mA (inclusive).
IFAIL=13
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).
IFAIL=14
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).
IFAIL=15
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.
IFAIL=16
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.
IFAIL=17
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.
IFAIL=18
A premature end of the input stream. The part defining the dimensions of the blocks was not found.
A premature end of the input stream. The part defining the nonzero entries was not found.
A premature end of the input stream. The part defining the number of blocks was not found.
A premature end of the input stream. The part defining the number of variables was not found.
A premature end of the input stream. The part defining the objective function was not found.
IFAIL=19
The input stream seems to be empty. No data was read. This might indicate a problem with opening the file, check that X04ACF was used correctly.
IFAIL=20
Reading from the stream caused an unknown error on line value.
IFAIL=21
On entry, INFILE=value.
Constraint: INFILE0.
On entry, MAXNBLK=value.
Constraint: MAXNBLK0.
On entry, MAXNNZ=value.
Constraint: MAXNNZ0.
On entry, MAXNVAR=value.
Constraint: MAXNVAR0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7  Accuracy

Not applicable.

8  Parallelism and Performance

E04RDF is not threaded in any implementation.

9  Further Comments

The following artificial example demonstrates how the elements of Ai matrices are organized within arrays NNZA, IROWA, ICOLA and A. For simplicity let us assume that NBLK=1, BLKSIZEA1=3 and NVAR=4. Please note that the values of the elements were chosen to ease readability rather than to define a valid problem.
Let the matrix constraint (1)(b) be defined by
A0 = 0 0.1 0 0.1 0 0.2 0 0.2 0.3 ,    
A1 = 1.1 0 0 0 1.2 1.3 0 1.3 1.4 ,    
A2 ​ empty,   
A3 = 0 0 0 0 3.1 0 0 0 3.2 ,    
A4 = 4.1 4.2 4.3 4.2 0 0 4.3 0 0 .  
All matrices Ai have to be symmetric and therefore only the elements in the upper triangles are stored. The table below shows how the arrays would be populated.
IROWA 01. 02. 03.   01. 02. 02. 03.     02. 03.   01. 02. 03.  
ICOLA 02. 03. 03.   01. 02. 03. 03.     02. 03.   01. 01. 01.  
A 0.1 0.2 0.3   1.1 1.2 1.3 1.4   000.0   3.1 3.2   4.1 4.2 4.3  
  A0  A1  A2  A3  A4 
NNZA 3 4 0 2 3
See also Section 3 in E04RNF which accepts the same format.

10  Example

The following example comes from Fujisawa et al. (1998).
Imagine that we want to store the following problem in a file in the SDPA format.
minimize x2 10x1 + 20x2 subject to 1 0 1 1 x1 x2 1 1.5 5 2 2 6 x2 - 3 0 0 4 0 .  
There are two variables (n=2) in the problem. One linear matrix constraint and one block of linear constraints can be formed as (1) with two diagonal blocks (mA=2). Both blocks have dimension 2 but the first one (defining linear constraints) is only diagonal, thus the sizes will be stated as -2 2 .
The problem can be rewritten as
minimize x2 cTx subject to A1x1 + A2x2 - A0 0  
where
The optimal solution is x*= 1.0 1.0 T with the objective function value 30.0. The optimal Lagrangian multipliers (dual variables) are 10.0, 0.0 and 20/7, -20/7 -20/7, 20/7 .
See also Section 10 in E04RAF for links to further examples in the suite.

10.1  Program Text

Program Text (e04rdfe.f90)

10.2  Program Data

Program Options (e04rdfe.opt)

10.3  Program Results

Program Results (e04rdfe.r)


E04RDF (PDF version)
E04 Chapter Contents
E04 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2016