Purpose
To generate the benchmark examples for the numerical solution of
discrete-time algebraic Riccati equations (DAREs) of the form
T T T -1 T T
0 = A X A - X - (A X B + S) (R + B X B) (B X A + S ) + Q
as presented in [1]. Here, A,Q,X are real N-by-N matrices, B,S are
N-by-M, and R is M-by-M. The matrices Q and R are symmetric and Q
may be given in factored form
T
(I) Q = C Q0 C .
Here, C is P-by-N and Q0 is P-by-P. If R is nonsingular and S = 0,
the DARE can be rewritten equivalently as
T -1
0 = X - A X (I_n + G X) A - Q,
where I_n is the N-by-N identity matrix and
-1 T
(II) G = B R B .
Specification
SUBROUTINE BB02AD(DEF, NR, DPAR, IPAR, BPAR, CHPAR, VEC, N, M, P,
1 A, LDA, B, LDB, C, LDC, Q, LDQ, R, LDR, S, LDS,
2 X, LDX, DWORK, LDWORK, INFO)
C .. Scalar Arguments ..
INTEGER INFO, LDA, LDB, LDC, LDQ, LDR, LDS, LDWORK, LDX,
$ M, N, P
CHARACTER DEF
C .. Array Arguments ..
DOUBLE PRECISION A(LDA,*), B(LDB,*), C(LDC,*), DPAR(*), DWORK(*),
1 Q(*), R(*), S(LDS,*), X(LDX,*)
INTEGER IPAR(3), NR(2)
CHARACTER CHPAR*255
LOGICAL BPAR(7), VEC(10)
Arguments
Mode Parameters
DEF CHARACTER
This parameter specifies if the default parameters are
to be used or not.
= 'N' or 'n' : The parameters given in the input vectors
xPAR (x = 'D', 'I', 'B', 'CH') are used.
= 'D' or 'd' : The default parameters for the example
are used.
This parameter is not meaningful if NR(1) = 1.
Input/Output Parameters
NR (input) INTEGER array, dimension (2)
This array determines the example for which DAREX returns
data. NR(1) is the group of examples.
NR(1) = 1 : parameter-free problems of fixed size.
NR(1) = 2 : parameter-dependent problems of fixed size.
NR(1) = 3 : parameter-free problems of scalable size.
NR(1) = 4 : parameter-dependent problems of scalable size.
NR(2) is the number of the example in group NR(1).
Let NEXi be the number of examples in group i. Currently,
NEX1 = 13, NEX2 = 5, NEX3 = 0, NEX4 = 1.
1 <= NR(1) <= 4;
0 <= NR(2) <= NEXi, where i = NR(1).
DPAR (input/output) DOUBLE PRECISION array, dimension (4)
Double precision parameter vector. For explanation of the
parameters see [1].
DPAR(1) defines the parameter 'epsilon' for
examples NR = 2.2,2.3,2.4, the parameter 'tau'
for NR = 2.5, and the 1-by-1 matrix R for NR = 2.1,4.1.
For Example 2.5, DPAR(2) - DPAR(4) define in
consecutive order 'D', 'K', and 'r'.
NOTE that DPAR is overwritten with default values
if DEF = 'D' or 'd'.
IPAR (input/output) INTEGER array, dimension (3)
On input, IPAR(1) determines the actual state dimension,
i.e., the order of the matrix A as follows:
NR(1) = 1, NR(1) = 2 : IPAR(1) is ignored.
NR = NR(1).NR(2) = 4.1 : IPAR(1) determines the order of
the output matrix A.
NOTE that IPAR(1) is overwritten for Examples 1.1-2.3. For
the other examples, IPAR(1) is overwritten if the default
parameters are to be used.
On output, IPAR(1) contains the order of the matrix A.
On input, IPAR(2) is the number of colums in the matrix B
and the order of the matrix R (in control problems, the
number of inputs of the system). Currently, IPAR(2) is
fixed for all examples and thus is not referenced on
input.
On output, IPAR(2) is the number of columns of the
matrix B from (I).
On input, IPAR(3) is the number of rows in the matrix C
(in control problems, the number of outputs of the
system). Currently, IPAR(3) is fixed for all examples
and thus is not referenced on input.
On output, IPAR(3) is the number of rows of the matrix C
from (I).
NOTE that IPAR(2) and IPAR(3) are overwritten and
IPAR(2) <= IPAR(1) and IPAR(3) <= IPAR(1) for all
examples.
BPAR (input) LOGICAL array, dimension (7)
This array defines the form of the output of the examples
and the storage mode of the matrices Q, G or R.
BPAR(1) = .TRUE. : Q is returned.
BPAR(1) = .FALSE. : Q is returned in factored form, i.e.,
Q0 and C from (I) are returned.
BPAR(2) = .TRUE. : The matrix returned in array Q (i.e.,
Q if BPAR(1) = .TRUE. and Q0 if
BPAR(1) = .FALSE.) is stored as full
matrix.
BPAR(2) = .FALSE. : The matrix returned in array Q is
provided in packed storage mode.
BPAR(3) = .TRUE. : If BPAR(2) = .FALSE., the matrix
returned in array Q is stored in upper
packed mode, i.e., the upper triangle
of a symmetric n-by-n matrix is stored
by columns, e.g., the matrix entry
Q(i,j) is stored in the array entry
Q(i+j*(j-1)/2) for i <= j.
Otherwise, this entry is ignored.
BPAR(3) = .FALSE. : If BPAR(2) = .FALSE., the matrix
returned in array Q is stored in lower
packed mode, i.e., the lower triangle
of a symmetric n-by-n matrix is stored
by columns, e.g., the matrix entry
Q(i,j) is stored in the array entry
Q(i+(2*n-j)*(j-1)/2) for j <= i.
Otherwise, this entry is ignored.
BPAR(4) = .TRUE. : The product G in (II) is returned.
BPAR(4) = .FALSE. : G is returned in factored form, i.e.,
B and R from (II) are returned.
BPAR(5) = .TRUE. : The matrix returned in array R (i.e.,
G if BPAR(4) = .TRUE. and R if
BPAR(4) = .FALSE.) is stored as full
matrix.
BPAR(5) = .FALSE. : The matrix returned in array R is
provided in packed storage mode.
BPAR(6) = .TRUE. : If BPAR(5) = .FALSE., the matrix
returned in array R is stored in upper
packed mode (see above).
Otherwise, this entry is ignored.
BPAR(6) = .FALSE. : If BPAR(5) = .FALSE., the matrix
returned in array R is stored in lower
packed mode (see above).
Otherwise, this entry is ignored.
BPAR(7) = .TRUE. : The coefficient matrix S of the DARE
is returned in array S.
BPAR(7) = .FALSE. : The coefficient matrix S of the DARE
is not returned.
NOTE that there are no default values for BPAR. If all
entries are declared to be .TRUE., then matrices Q, G or R
are returned in conventional storage mode, i.e., as
N-by-N or M-by-M arrays where the array element Z(I,J)
contains the matrix entry Z_{i,j}.
CHPAR (output) CHARACTER*255
On output, this string contains short information about
the chosen example.
VEC (output) LOGICAL array, dimension (10)
Flag vector which displays the availability of the output
data:
VEC(j), j=1,2,3, refer to N, M, and P, respectively, and
are always .TRUE.
VEC(4) refers to A and is always .TRUE.
VEC(5) is .TRUE. if BPAR(4) = .FALSE., i.e., the factors B
and R from (II) are returned.
VEC(6) is .TRUE. if BPAR(1) = .FALSE., i.e., the factors C
and Q0 from (I) are returned.
VEC(7) refers to Q and is always .TRUE.
VEC(8) refers to R and is always .TRUE.
VEC(9) is .TRUE. if BPAR(7) = .TRUE., i.e., the matrix S
is returned.
VEC(10) refers to X and is .TRUE. if the exact solution
matrix is available.
NOTE that VEC(i) = .FALSE. for i = 1 to 10 if on exit
INFO .NE. 0.
N (output) INTEGER
The order of the matrices A, X, G if BPAR(4) = .TRUE., and
Q if BPAR(1) = .TRUE.
M (output) INTEGER
The number of columns in the matrix B (or the dimension of
the control input space of the underlying dynamical
system).
P (output) INTEGER
The number of rows in the matrix C (or the dimension of
the output space of the underlying dynamical system).
A (output) DOUBLE PRECISION array, dimension (LDA,N)
The leading N-by-N part of this array contains the
coefficient matrix A of the DARE.
LDA INTEGER
The leading dimension of array A. LDA >= N.
B (output) DOUBLE PRECISION array, dimension (LDB,M)
If (BPAR(4) = .FALSE.), then the leading N-by-M part
of this array contains the coefficient matrix B of
the DARE. Otherwise, B is used as workspace.
LDB INTEGER
The leading dimension of array B. LDB >= N.
C (output) DOUBLE PRECISION array, dimension (LDC,N)
If (BPAR(1) = .FALSE.), then the leading P-by-N part
of this array contains the matrix C of the factored
form (I) of Q. Otherwise, C is used as workspace.
LDC INTEGER
The leading dimension of array C. LDC >= P.
Q (output) DOUBLE PRECISION array, dimension (NQ)
If (BPAR(1) = .TRUE.) and (BPAR(2) = .TRUE.), then
NQ = LDQ*N.
IF (BPAR(1) = .TRUE.) and (BPAR(2) = .FALSE.), then
NQ = N*(N+1)/2.
If (BPAR(1) = .FALSE.) and (BPAR(2) = .TRUE.), then
NQ = LDQ*P.
IF (BPAR(1) = .FALSE.) and (BPAR(2) = .FALSE.), then
NQ = P*(P+1)/2.
The symmetric matrix contained in array Q is stored
according to BPAR(2) and BPAR(3).
LDQ INTEGER
If conventional storage mode is used for Q, i.e.,
BPAR(2) = .TRUE., then Q is stored like a 2-dimensional
array with leading dimension LDQ. If packed symmetric
storage mode is used, then LDQ is irrelevant.
LDQ >= N if BPAR(1) = .TRUE.;
LDQ >= P if BPAR(1) = .FALSE..
R (output) DOUBLE PRECISION array, dimension (MR)
If (BPAR(4) = .TRUE.) and (BPAR(5) = .TRUE.), then
MR = LDR*N.
IF (BPAR(4) = .TRUE.) and (BPAR(5) = .FALSE.), then
MR = N*(N+1)/2.
If (BPAR(4) = .FALSE.) and (BPAR(5) = .TRUE.), then
MR = LDR*M.
IF (BPAR(4) = .FALSE.) and (BPAR(5) = .FALSE.), then
MR = M*(M+1)/2.
The symmetric matrix contained in array R is stored
according to BPAR(5) and BPAR(6).
LDR INTEGER
If conventional storage mode is used for R, i.e.,
BPAR(5) = .TRUE., then R is stored like a 2-dimensional
array with leading dimension LDR. If packed symmetric
storage mode is used, then LDR is irrelevant.
LDR >= N if BPAR(4) = .TRUE.;
LDR >= M if BPAR(4) = .FALSE..
S (output) DOUBLE PRECISION array, dimension (LDS,M)
If (BPAR(7) = .TRUE.), then the leading N-by-M part of
this array contains the coefficient matrix S of the DARE.
LDS INTEGER
The leading dimension of array S. LDS >= 1, and
LDS >= N if BPAR(7) = .TRUE..
X (output) DOUBLE PRECISION array, dimension (LDX,NX)
If an exact solution is available (NR = 1.1,1.3,1.4,2.1,
2.3,2.4,2.5,4.1), then NX = N and the leading N-by-N part
of this array contains the solution matrix X.
Otherwise, X is not referenced.
LDX INTEGER
The leading dimension of array X. LDX >= 1, and
LDX >= N if an exact solution is available.
Workspace
DWORK DOUBLE PRECISION array, dimension (LDWORK)
LDWORK INTEGER
The length of the array DWORK. LDWORK >= N*N.
Error Indicator
INFO INTEGER
= 0 : successful exit;
< 0 : if INFO = -i, the i-th argument had an illegal
value;
= 1 : data file could not be opened or had wrong format;
= 2 : division by zero;
= 3 : G can not be computed as in (II) due to a singular R
matrix. This error can only occur if
BPAR(4) = .TRUE..
References
[1] Abels, J. and Benner, P.
DAREX - A Collection of Benchmark Examples for Discrete-Time
Algebraic Riccati Equations (Version 2.0).
SLICOT Working Note 1999-16, November 1999. Available from
http://www.win.tue.nl/niconet/NIC2/reports.html.
This is an updated and extended version of
[2] Benner, P., Laub, A.J., and Mehrmann, V.
A Collection of Benchmark Examples for the Numerical Solution
of Algebraic Riccati Equations II: Discrete-Time Case.
Technical Report SPC 95_23, Fak. f. Mathematik,
TU Chemnitz-Zwickau (Germany), December 1995.
Further Comments
Some benchmark examples read data from the data files provided with the collection.Example
Program Text
* BB02AD EXAMPLE PROGRAM TEXT
*
* Copyright (c) 2002-2017 NICONET e.V.
*
* .. Parameters ..
INTEGER NIN, NOUT
PARAMETER ( NIN = 5, NOUT = 6 )
INTEGER MMAX, NMAX, PMAX
PARAMETER ( MMAX = 100, NMAX = 100, PMAX = 100 )
INTEGER LDA, LDB, LDC, LDQ, LDR, LDS, LDX
PARAMETER ( LDA = NMAX, LDB = NMAX, LDC = PMAX,
$ LDQ = NMAX, LDR = NMAX, LDS = NMAX,
$ LDX = NMAX )
INTEGER LDWORK
PARAMETER ( LDWORK = NMAX*NMAX )
* .. Local Scalars ..
CHARACTER DEF
INTEGER I, INFO, ISYMM, J, LBPAR, LDPAR, LIPAR, M, N, P
* .. Local Arrays ..
DOUBLE PRECISION A(LDA, NMAX), B(LDB,MMAX), C(LDC, NMAX),
$ DPAR(4), DWORK(LDWORK), Q(LDQ, NMAX),
$ R(LDR, NMAX), S(LDS, NMAX), X(LDX, NMAX)
INTEGER IPAR(3), NR(2)
LOGICAL BPAR(7), VEC(10)
CHARACTER CHPAR(255)
* .. External Functions ..
LOGICAL LSAME
EXTERNAL LSAME
* .. External Subroutines ..
EXTERNAL BB02AD, MA02DD
* .. Executable Statements ..
WRITE( NOUT, FMT = 99999 )
* Skip the heading in the data file and read the data.
READ( NIN, FMT = '()' )
READ( NIN, FMT = * ) DEF
READ( NIN, FMT = * ) ( NR(I), I = 1, 2 )
IF( LSAME( DEF, 'N' ) ) THEN
READ( NIN, FMT = * ) LBPAR
IF( LBPAR.GT.0 ) READ( NIN, FMT = * ) ( BPAR(I), I = 1, LBPAR )
READ( NIN, FMT = * ) LDPAR
IF( LDPAR.GT.0 ) READ( NIN, FMT = * ) ( DPAR(I), I = 1, LDPAR )
READ( NIN, FMT = * ) LIPAR
IF( LIPAR.GT.0 ) READ( NIN, FMT = * ) ( IPAR(I), I = 1, LIPAR )
END IF
* Generate benchmark example
CALL BB02AD( DEF, NR, DPAR, IPAR, BPAR, CHPAR, VEC, N, M, P, A,
$ LDA, B, LDB, C, LDC, Q, LDQ, R, LDR, S, LDS, X, LDX,
$ DWORK, LDWORK, INFO )
*
IF( INFO.NE.0 ) THEN
WRITE( NOUT, FMT = 99998 ) INFO
ELSE
WRITE( NOUT, FMT = * ) CHPAR(1:70)
WRITE( NOUT, FMT = 99997 ) N
WRITE( NOUT, FMT = 99996 ) M
WRITE( NOUT, FMT = 99995 ) P
WRITE( NOUT, FMT = 99994 )
DO 10 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( A(I,J), J = 1, N )
10 CONTINUE
IF( VEC(5) ) THEN
WRITE( NOUT, FMT = 99993 )
DO 20 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( B(I,J), J = 1, M )
20 CONTINUE
ELSE
WRITE( NOUT, FMT = 99992 )
END IF
IF( VEC(6) ) THEN
WRITE( NOUT,FMT = 99991 )
DO 30 I = 1, P
WRITE( NOUT, FMT = 99977 ) ( C(I,J), J = 1, N )
30 CONTINUE
ELSE
WRITE( NOUT, FMT = 99990 )
END IF
IF( .NOT.VEC(5) ) THEN
WRITE( NOUT, FMT = 99989 )
IF( .NOT.BPAR(2) ) THEN
ISYMM = ( N * ( N + 1 ) ) / 2
CALL DCOPY( ISYMM, R, 1, DWORK, 1 )
IF( BPAR(3) ) THEN
CALL MA02DD( 'Unpack', 'Upper', N, R, LDR, DWORK )
ELSE
CALL MA02DD( 'Unpack', 'Lower', N, R, LDR, DWORK )
END IF
END IF
DO 40 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( R(I,J), J = 1, N )
40 CONTINUE
ELSE
WRITE( NOUT, FMT = 99988 )
END IF
IF( .NOT.VEC(6) ) THEN
IF( .NOT.BPAR(5) ) THEN
ISYMM = ( N * ( N + 1 ) ) / 2
CALL DCOPY( ISYMM, Q, 1, DWORK, 1 )
IF( BPAR(6) ) THEN
CALL MA02DD( 'Unpack', 'Upper', N, Q, LDQ, DWORK )
ELSE
CALL MA02DD( 'Unpack', 'Lower', N, Q, LDQ, DWORK )
END IF
END IF
WRITE( NOUT, FMT = 99987 )
DO 50 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( Q(I,J), J = 1, N )
50 CONTINUE
ELSE
WRITE( NOUT, FMT = 99986 )
END IF
IF( VEC(6) ) THEN
IF( .NOT.BPAR(5) ) THEN
ISYMM = ( P * ( P + 1 ) ) / 2
CALL DCOPY( ISYMM, Q, 1, DWORK, 1 )
IF( BPAR(6) ) THEN
CALL MA02DD( 'Unpack', 'Upper', P, Q, LDQ, DWORK )
ELSE
CALL MA02DD( 'Unpack', 'Lower', P, Q, LDQ, DWORK )
END IF
END IF
WRITE( NOUT, FMT = 99985 )
DO 60 I = 1, P
WRITE( NOUT, FMT = 99977 ) ( Q(I,J), J = 1, P )
60 CONTINUE
ELSE
WRITE( NOUT, FMT = 99984 )
END IF
IF( VEC(5) ) THEN
IF( .NOT.BPAR(2) ) THEN
ISYMM = ( M * ( M + 1 ) ) / 2
CALL DCOPY( ISYMM, R, 1, DWORK, 1 )
IF( BPAR(3) ) THEN
CALL MA02DD( 'Unpack', 'Upper', M, R, LDR, DWORK )
ELSE
CALL MA02DD( 'Unpack', 'Lower', M, R, LDR, DWORK )
END IF
END IF
WRITE( NOUT, FMT = 99983 )
DO 70 I = 1, M
WRITE( NOUT, FMT = 99977 ) ( R(I,J), J = 1, M )
70 CONTINUE
ELSE
WRITE( NOUT, FMT = 99982 )
END IF
IF( VEC(9) ) THEN
WRITE( NOUT, FMT = 99981 )
DO 80 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( S(I,J), J = 1, M )
80 CONTINUE
ELSE
WRITE( NOUT, FMT = 99980 )
END IF
IF( VEC(10) ) THEN
WRITE( NOUT, FMT = 99979 )
DO 90 I = 1, N
WRITE( NOUT, FMT = 99977 ) ( X(I,J), J = 1, N )
90 CONTINUE
ELSE
WRITE( NOUT, FMT = 99978 )
END IF
END IF
STOP
*
99999 FORMAT (' BB02AD EXAMPLE PROGRAM RESULTS', /1X)
99998 FORMAT (' INFO on exit from BB02AD = ', I3)
99997 FORMAT (/' Order of matrix A: N = ', I3)
99996 FORMAT (' Number of columns in matrix B: M = ', I3)
99995 FORMAT (' Number of rows in matrix C: P = ', I3)
99994 FORMAT (' A = ')
99993 FORMAT (' B = ')
99992 FORMAT (' B is not provided.')
99991 FORMAT (' C = ')
99990 FORMAT (' C is not provided.')
99989 FORMAT (' G = ')
99988 FORMAT (' G is not provided.')
99987 FORMAT (' Q = ')
99986 FORMAT (' Q is not provided.')
99985 FORMAT (' Q0 = ')
99984 FORMAT (' Q0 is not provided.')
99983 FORMAT (' R = ')
99982 FORMAT (' R is not provided.')
99981 FORMAT (' S = ')
99980 FORMAT (' S is not provided.')
99979 FORMAT (' X = ')
99978 FORMAT (' X is not provided.')
99977 FORMAT (20(1X,F8.4))
*
END
Program Data
BB02AD EXAMPLE PROGRAM DATA N 2 3 7 .T. .T. .T. .F. .F. .T. .T. 1 .1234 0Program Results
BB02AD EXAMPLE PROGRAM RESULTS increasingly bad scaled system as eps -> oo Order of matrix A: N = 2 Number of columns in matrix B: M = 1 Number of rows in matrix C: P = 2 A = 0.0000 0.1234 0.0000 0.0000 B = 0.0000 1.0000 C is not provided. G is not provided. Q = 1.0000 0.0000 0.0000 1.0000 Q0 is not provided. R = 1.0000 S = 0.0000 0.0000 X = 1.0000 0.0000 0.0000 1.0152