NAG CL Interface
f08qvc (ztrsyl)
1
Purpose
f08qvc solves the complex triangular Sylvester matrix equation.
2
Specification
void |
f08qvc (Nag_OrderType order,
Nag_TransType trana,
Nag_TransType tranb,
Nag_SignType sign,
Integer m,
Integer n,
const Complex a[],
Integer pda,
const Complex b[],
Integer pdb,
Complex c[],
Integer pdc,
double *scal,
NagError *fail) |
|
The function may be called by the names: f08qvc, nag_lapackeig_ztrsyl or nag_ztrsyl.
3
Description
f08qvc solves the complex Sylvester matrix equation
where
or
, and the matrices
and
are upper triangular;
is a scale factor (
) determined by the function to avoid overflow in
;
is
by
and
is
by
while the right-hand side matrix
and the solution matrix
are both
by
. The matrix
is obtained by a straightforward process of back-substitution (see
Golub and Van Loan (1996)).
Note that the equation has a unique solution if and only if , where and are the eigenvalues of and respectively and the sign ( or ) is the same as that used in the equation to be solved.
4
References
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (1992) Perturbation theory and backward error for Numerical Analysis Report University of Manchester
5
Arguments
-
1:
– Nag_OrderType
Input
-
On entry: the
order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by
. See
Section 3.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint:
or .
-
2:
– Nag_TransType
Input
-
On entry: specifies the option
.
- .
- .
Constraint:
or .
-
3:
– Nag_TransType
Input
-
On entry: specifies the option
.
- .
- .
Constraint:
or .
-
4:
– Nag_SignType
Input
-
On entry: indicates the form of the Sylvester equation.
- The equation is of the form .
- The equation is of the form .
Constraint:
or .
-
5:
– Integer
Input
-
On entry: , the order of the matrix , and the number of rows in the matrices and .
Constraint:
.
-
6:
– Integer
Input
-
On entry: , the order of the matrix , and the number of columns in the matrices and .
Constraint:
.
-
7:
– const Complex
Input
-
Note: the dimension,
dim, of the array
a
must be at least
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the by upper triangular matrix .
-
8:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraint:
.
-
9:
– const Complex
Input
-
Note: the dimension,
dim, of the array
b
must be at least
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the by upper triangular matrix .
-
10:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
b.
Constraint:
.
-
11:
– Complex
Input/Output
-
Note: the dimension,
dim, of the array
c
must be at least
- when
;
- when
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the by right-hand side matrix .
On exit:
c is overwritten by the solution matrix
.
-
12:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
c.
Constraints:
- if ,
;
- if , .
-
13:
– double *
Output
-
On exit: the value of the scale factor .
-
14:
– 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_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
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_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_PERTURBED
-
and have common or close eigenvalues, perturbed values of which were used to solve the equation.
7
Accuracy
Consider the equation . (To apply the remarks to the equation , simply replace by .)
Let
be the computed solution and
the residual matrix:
Then the residual is always small:
However,
is
not necessarily the exact solution of a slightly perturbed equation; in other words, the solution is not backwards stable.
For the forward error, the following bound holds:
but this may be a considerable over estimate. See
Golub and Van Loan (1996) for a definition of
, and
Higham (1992) for further details.
These remarks also apply to the solution of a general Sylvester equation, as described in
Section 9.
8
Parallelism and Performance
f08qvc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
The total number of real floating-point operations is approximately .
To solve the
general complex Sylvester equation
where
and
are general matrices,
and
must first be reduced to Schur form
:
where
and
are upper triangular and
and
are unitary. The original equation may then be transformed to:
where
and
.
may be computed by matrix multiplication;
f08qvc may be used to solve the transformed equation; and the solution to the original equation can be obtained as
.
The real analogue of this function is
f08qhc.
10
Example
This example solves the Sylvester equation
, where
and
10.1
Program Text
10.2
Program Data
10.3
Program Results