NAG Library Function Document
nag_dtrsyl (f08qhc)
1
Purpose
nag_dtrsyl (f08qhc) solves the real quasi-triangular Sylvester matrix equation.
2
Specification
#include <nag.h> |
#include <nagf08.h> |
void |
nag_dtrsyl (Nag_OrderType order,
Nag_TransType trana,
Nag_TransType tranb,
Nag_SignType sign,
Integer m,
Integer n,
const double a[],
Integer pda,
const double b[],
Integer pdb,
double c[],
Integer pdc,
double *scale,
NagError *fail) |
|
3
Description
nag_dtrsyl (f08qhc) solves the real Sylvester matrix equation
where
or
, and the matrices
and
are upper quasi-triangular matrices in canonical Schur form (as returned by
nag_dhseqr (f08pec));
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_OrderTypeInput
-
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.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.
Constraint:
or .
- 2:
– Nag_TransTypeInput
-
On entry: specifies the option
.
- .
- or
- .
Constraint:
, or .
- 3:
– Nag_TransTypeInput
-
On entry: specifies the option
.
- .
- or
- .
Constraint:
, or .
- 4:
– Nag_SignTypeInput
-
On entry: indicates the form of the Sylvester equation.
- The equation is of the form .
- The equation is of the form .
Constraint:
or .
- 5:
– IntegerInput
-
On entry: , the order of the matrix , and the number of rows in the matrices and .
Constraint:
.
- 6:
– IntegerInput
-
On entry: , the order of the matrix , and the number of columns in the matrices and .
Constraint:
.
- 7:
– const doubleInput
-
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 quasi-triangular matrix
in canonical Schur form, as returned by
nag_dhseqr (f08pec).
- 8:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraint:
.
- 9:
– const doubleInput
-
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 quasi-triangular matrix
in canonical Schur form, as returned by
nag_dhseqr (f08pec).
- 10:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
b.
Constraint:
.
- 11:
– doubleInput/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:
– IntegerInput
-
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 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 2.3.1.2 in How to Use the NAG Library and its Documentation 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 2.7.6 in How to Use the NAG Library and its Documentation for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 2.7.5 in How to Use the NAG Library and its Documentation 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
nag_dtrsyl (f08qhc) 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 floating-point operations is approximately .
To solve the
general real Sylvester equation
where
and
are general nonsymmetric matrices,
and
must first be reduced to Schur form
:
where
and
are upper quasi-triangular and
and
are orthogonal. The original equation may then be transformed to:
where
and
.
may be computed by matrix multiplication;
nag_dtrsyl (f08qhc) may be used to solve the transformed equation; and the solution to the original equation can be obtained as
.
The complex analogue of this function is
nag_ztrsyl (f08qvc).
10
Example
This example solves the Sylvester equation
, where
and
10.1
Program Text
Program Text (f08qhce.c)
10.2
Program Data
Program Data (f08qhce.d)
10.3
Program Results
Program Results (f08qhce.r)