NAG CL Interface
e04rpc (handle_set_quadmatineq)
1
Purpose
e04rpc is a part of the NAG optimization modelling suite and defines bilinear matrix terms either in a new matrix constraint or adds them to an existing linear matrix inequality.
2
Specification
void |
e04rpc (void *handle,
Integer nq,
const Integer qi[],
const Integer qj[],
Integer dimq,
const Integer nnzq[],
Integer nnzqsum,
const Integer irowq[],
const Integer icolq[],
const double q[],
Integer *idblk,
NagError *fail) |
|
The function may be called by the names: e04rpc or nag_opt_handle_set_quadmatineq.
3
Description
After the initialization function
e04rac has been called,
e04rpc may be used to define bilinear matrix terms. It may be used in two ways, either to add to the problem formulation a new bilinear matrix inequality (BMI) which does not have linear terms:
or to extend an existing linear matrix inequality constraint by bilinear terms:
Here
are
by
(sparse) symmetric matrices and
, if present, is the number of the existing constraint. This function will typically be used on semidefinite programming problems with bilinear matrix constraints (BMI-SDP)
The function can be called multiple times to define an additional matrix inequality or to extend an existing one, but it cannot be called twice to extend the same matrix inequality. The argument
idblk is used to distinguish whether a new matrix constraint should be added (
) or if an existing linear matrix inequality should be extended (
). In the latter case,
idblk should be set to
, the number of the existing inequality. See
e04rnc for details about formulation of linear matrix constraints and their numbering and a further description of
idblk. See
Section 4.1 in the
E04 Chapter Introduction for more details about the NAG optimization modelling suite. In the further text, the index
will be omitted.
It is expected that only some of the matrices
will be nonzero therefore only their index pairs
are listed in arrays
qi and
qj. Note that a pair
should not repeat, i.e., a matrix
should not be defined more than once. No particular ordering of pairs
is expected but other input arrays
irowq,
icolq,
q and
nnzq need to respect the chosen order.
Note: the dimension of must respect the size of the linear matrix inequality if they are supposed to expand it (case ).
Matrices
are symmetric and thus only their upper triangles are passed to the function. They are stored in sparse coordinate storage format (see
Section 2.1.1 in the
F11 Chapter Introduction), i.e., every nonzero from the upper triangles is coded as a triplet of row index, column index and the numeric value. All these triplets from all
matrices are passed to the function in three arrays:
irowq for row indices,
icolq for column indices and
q for the values. No particular order of nonzeros within one matrix is enforced but all nonzeros belonging to one
matrix need to be stored next to each other. The first
nonzeros belong to
where
,
, the following
nonzeros to the next one given by
qi,
qj and so on. The array
nnzq thus splits arrays
irowq,
icolq and
q into sections so that each section defines one
matrix. See
Table 1 below. Functions
e04rdc and
e04rnc use the same data organization so further examples can be found there.
irowq |
upper triangle |
upper triangle |
|
upper triangle
|
icolq |
nonzeros |
nonzeros |
|
nonzeros |
q |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 1
Coordinate storage format of matrices in input arrays
4
References
Syrmos V L, Abdallah C T, Dorato P and Grigoriadis K (1997) Static output feedback – a survey Journal Automatica (Journal of IFAC) (Volume 33) 2 125–137
5
Arguments
-
1:
– void *
Input
-
On entry: the handle to the problem. It needs to be initialized by
e04rac and
must not be changed between calls to the NAG optimization modelling suite.
-
2:
– Integer
Input
-
On entry: the number of index pairs of the nonzero matrices .
Constraint:
.
-
3:
– const Integer
Input
-
4:
– const Integer
Input
-
On entry: the index pairs of the nonzero matrices in any order.
Constraint:
where
is the number of decision variables in the problem set during the initialization of the handle by
e04rac. The pairs do not repeat.
-
5:
– Integer
Input
-
On entry: , the dimension of matrices .
Constraints:
- ;
- if , dimq needs to be identical to the dimension of matrices of the constraint .
-
6:
– const Integer
Input
-
On entry: the numbers of nonzero elements in the upper triangles of matrices.
Constraint:
.
-
7:
– Integer
Input
-
On entry: the dimension of the arrays
irowq,
icolq and
q, at least the total number of all nonzeros in all
matrices.
Constraints:
- ;
- .
-
8:
– const Integer
Input
-
9:
– const Integer
Input
-
10:
– const double
Input
-
On entry: the nonzero elements of the upper triangles of matrices stored in coordinate storage format. The first elements belong to the first , the following to , etc.
Constraint:
, .
-
11:
– Integer *
Input/Output
-
On entry: if , a new matrix constraint is created; otherwise , the number of the existing linear matrix constraint to be expanded with the bilinear terms.
Constraint:
.
On exit: if on entry, the number of the new matrix constraint is returned. By definition, it is the number of the matrix inequalities already defined plus one. Otherwise, stays unchanged.
-
12:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_ALREADY_DEFINED
-
On entry,
.
Bilinear terms of the matrix inequality block with the given
idblk have already been defined.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_DIM_MATCH
-
On entry,
,
.
The correct dimension of the given
idblk is
.
Constraint:
dimq must match the dimension of the block supplied earlier.
- NE_HANDLE
-
The supplied
handle does not define a valid handle to the data structure for the NAG optimization modelling suite. It has not been initialized by
e04rac or it has been corrupted.
- NE_INDICES
-
On entry, index pair with
and
repeats.
Constraint: each index pair
qi,
qj must be unique.
On entry, , and .
Constraint: .
On entry, , and .
Constraint: .
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint: .
- NE_INT_ARRAY_1
-
On entry, and .
Constraint: .
- 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.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_INVALID_CS
-
On entry, an error occurred in matrix of index , , .
For , and .
Constraint: .
On entry, an error occurred in matrix of index , , .
For , and .
Constraint: .
On entry, an error occurred in matrix of index , , .
For , and .
Constraint: (elements within the upper triangle).
On entry, an error occurred in matrix of index , , .
More than one element of has row index and column index .
Constraint: each element of must have a unique row and column index.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
- NE_PHASE
-
The problem cannot be modified in this phase any more, the solver has already been called.
- NE_REF_MATCH
-
On entry,
.
The given
idblk does not match with any existing matrix inequality block.
The maximum
idblk is currently
.
On entry,
.
The given
idblk refers to a nonexistent matrix inequality block.
No matrix inequalities have been added yet.
7
Accuracy
Not applicable.
8
Parallelism and Performance
e04rpc is not threaded in any implementation.
None.
10
Example
This example demonstrates how semidefinite programming can be used in control theory. See also
Section 10 in
e04rac for links to further examples in the suite.
The problem, from static output feedback (SOF) control
Syrmos et al. (1997), solved here is the linear time-invariant (LTI) ‘test’ system
subject to static output feedback
Here , and are given matrices, is the vector of state variables, is the vector of control inputs, is the vector of system outputs, and is the unknown feedback gain matrix.
The problem is to find
such that
(4) is time-stable when subject to
(5), i.e., all eigenvalues of the closed-loop system matrix
belong to the left half-plane. From the Lyapunov stability theory, this holds if and only if there exists a symmetric positive definite matrix
such that
Hence, by introducing the new variable, the Lyapunov matrix
, we can formulate the SOF problem as a feasibility BMI-SDP problem in variables
and
. As we cannot formulate the problem with sharp matrix inequalities, we can solve the following system instead (note that the objective function is added to bound matrix
):
For
,
,
and the unknown matrices expressed as
the problem
(6) can be rewritten in the form
(3) as follows:
This formulation has been stored in a generic BMI-SDP data file which is processed and solved by the example program.
10.1
Program Text
10.2
Program Data
10.3
Program Results