ctrlyap - Man Page

Name

ctrlyap — C-Interface

— C-Interface for standard Lyapunov and Stein equations with triangular coefficient matrices.

void mepack_double_trlyap_dag (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.
void mepack_single_trlyap_dag (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.
void mepack_double_trstein_dag (const char *TRANSA, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the Stein equation with OpenMP 4.
void mepack_single_trstein_dag (const char *TRANSA, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the Stein equation with OpenMP 4.
void mepack_double_trlyap_level2 (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.
void mepack_double_trlyap_level2_opt (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized for small problems)
void mepack_single_trlyap_level2 (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.
void mepack_single_trlyap_level2_opt (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized for small problems)
void mepack_double_trstein_level2 (const char *TRANSA, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Stein equation.
void mepack_single_trstein_level2 (const char *TRANSA, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-2 Bartels-Stewart Algorithm for the Stein equation.
void mepack_double_trlyap_level3 (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.
void mepack_double_trlyap_level3_2stage (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm with sub-blocking for the standard Lyapunov Equation.
void mepack_single_trlyap_level3 (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.
void mepack_single_trlyap_level3_2stage (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm with sub-blocking for the standard Lyapunov Equation.
void mepack_double_trstein_level3 (const char *TRANSA, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the Stein equation.
void mepack_double_trstein_level3_2stage (const char *TRANSA, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm with sub-blocking for the Stein equation.
void mepack_single_trstein_level3 (const char *TRANSA, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm for the Stein equation.
void mepack_single_trstein_level3_2stage (const char *TRANSA, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Bartels-Stewart Algorithm with sub-blocking for the Stein equation.
void mepack_double_trlyap_recursive (const char *TRANS, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.
void mepack_single_trlyap_recursive (const char *TRANS, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.
void mepack_double_trstein_recursive (const char *TRANSA, int M, double *A, int LDA, double *X, int LDX, double *SCALE, double *WORK, int *INFO)
Recursive blocking level-3 Bartels-Stewart Algorithm for the Stein equation.
void mepack_single_trstein_recursive (const char *TRANSA, int M, float *A, int LDA, float *X, int LDX, float *SCALE, float *WORK, int *INFO)
Recursive blocking level-3 Bartels-Stewart Algorithm for the Stein equation.

Detailed Description

C-Interface for standard Lyapunov and Stein equations with triangular coefficient matrices.

The Fortran routines to solve standard Lyapunov and Stein equations with triangular coefficients are wrapped in C to provide an easier access to them. All wrapper routines are direct wrappers to the corresponding Fortran subroutines without sanity checks. These are performed by the Fortran routines. Since the routines are using int values to pass sizes the work_space query will fail for large scale problems. For this reason the function mepack_memory should be used to query the required work_space from a C code. This function is aware of 64 bit integers if MEPACK is compiled with it.

Function Documentation

void mepack_double_trlyap_dag (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_double_trlyap_dag solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented using DAG Scheduling

This function is a wrapper around dla_trlyap_dag

See also

dla_trlyap_dag

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 132 of file trlyap.c.

void mepack_double_trlyap_level2 (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.

Purpose:

mepack_double_trlyap_level2 solves a Lyapunov equation of the following forms

   A * X  +  X * A**T = SCALE * Y                              (1)

or

   A **T * X  -  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 2 operations.

This is a wrapper around dla_trlyap_l2

See also

dla_trlyap_l2

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 132 of file trlyap.c.

void mepack_double_trlyap_level2_opt (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized for small problems)

Purpose:

mepack_double_trlyap_level2 solves a Lyapunov equation of the following forms

   A * X  +  X * A**T = SCALE * Y                              (1)

or

   A **T * X  -  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 2 operations.

This is a wrapper around dla_trlyap_l2_opt

See also

dla_trlyap_l2_opt

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 249 of file trlyap.c.

void mepack_double_trlyap_level3 (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_double_trlyap_level3 solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented a level-3 block approach.

This function is a wrapper around dla_trlyap_l3

See also

dla_trlyap_l3

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 132 of file trlyap.c.

void mepack_double_trlyap_level3_2stage (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm with sub-blocking for the standard Lyapunov Equation.

Purpose:

mepack_double_trlyap_level3_2stage solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented a level-3 block approach.

This function is a wrapper around dla_trlyap_l3_2s

See also

dla_trlyap_l3_2s

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 248 of file trlyap.c.

void mepack_double_trlyap_recursive (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_double_trlyap_recursive solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                              (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 3 operations and recursive blocking.

This function is a wrapper around dla_trlyap_recursive.

See also

dla_trlyap_recursive

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension 1
         Workspace for the algorithm

INFO

         INFO is INTEGER
         == 0:  successful exit
         < 0:  if INFO == -i, the i-the argument had an illegal value
         > 0:  The equation is not solved correctly. One of the arising inner
               system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 118 of file trlyap.c.

void mepack_double_trstein_dag (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the Stein equation with OpenMP 4.

Purpose:

mepack_double_trstein_dag solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by DGEES from LAPACK.

Remarks

The algorithm is implemented using DAG Scheduling

The routine is a wrapper around dla_trstein_dag.

See also

dla_trstein_dag

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 136 of file trstein.c.

void mepack_double_trstein_level2 (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_double_trstein_level2 solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by DGEES from LAPACK.

Remarks

The routine is a wrapper around dla_trstein_l2.

See also

dla_trstein_l2

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 135 of file trstein.c.

void mepack_double_trstein_level3 (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_double_trstein_level3 solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by DGEES from LAPACK.

Remarks

The routine is a wrapper around dla_trstein_l3.

See also

dla_trstein_l3

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 135 of file trstein.c.

void mepack_double_trstein_level3_2stage (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm with sub-blocking for the Stein equation.

Purpose:

mepack_double_trstein_level3_2stage solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by DGEES from LAPACK.

Remarks

The routine is a wrapper around dla_trstein_l3_2s.

See also

dla_trstein_l3_2s

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 255 of file trstein.c.

void mepack_double_trstein_recursive (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

Recursive blocking level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_double_trstein_recursive solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by DGEES from LAPACK.

Remarks

The routine is a wrapper around dla_trstein_recursive.

See also

dla_trstein_recursive

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is DOUBLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is DOUBLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is DOUBLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is DOUBLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 135 of file trstein.c.

void mepack_single_trlyap_dag (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_single_trlyap_dag solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented using DAG Scheduling

This function is a wrapper around sla_trlyap_dag

See also

sla_trlyap_dag

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 250 of file trlyap.c.

void mepack_single_trlyap_level2 (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.

Purpose:

mepack_single_trlyap_level2 solves a Lyapunov equation of the following forms

   A * X  +  X * A**T = SCALE * Y                              (1)

or

   A **T * X  -  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by SGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 2 operations.

This is a wrapper around sla_trlyap_l2

See also

sla_trlyap_l2

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 365 of file trlyap.c.

void mepack_single_trlyap_level2_opt (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized for small problems)

Purpose:

mepack_single_trlyap_level2_opt solves a Lyapunov equation of the following forms

   A * X  +  X * A**T = SCALE * Y                              (1)

or

   A **T * X  -  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by SGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 2 operations.

This is a wrapper around sla_trlyap_l2_opt

See also

sla_trlyap_l2_opt

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 482 of file trlyap.c.

void mepack_single_trlyap_level3 (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_single_trlyap_level3 solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented a level-3 block approach.

This function is a wrapper around sla_trlyap_l3

See also

sla_trlyap_l3

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 365 of file trlyap.c.

void mepack_single_trlyap_level3_2stage (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm with sub-blocking for the standard Lyapunov Equation.

Purpose:

mepack_single_trlyap_level3_2stage solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                               (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by DGEES from LAPACK.

Remarks

The algorithm is implemented a level-3 block approach.

This function is a wrapper around sla_trlyap_l3_2s

See also

sla_trlyap_l3_2s

Parameters

TRANS

         TRANS is a string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 481 of file trlyap.c.

void mepack_single_trlyap_recursive (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.

Purpose:

mepack_single_trlyap_recursive solves a Lyapunov equation of the following forms

   A  * X  +  X * A**T = SCALE * Y                              (1)

or

   A ** T * X  +  X * A = SCALE * Y                              (2)

where A is a M-by-M quasi upper triangular matrix.
The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
is generated by SGEES from LAPACK.

Remarks

The algorithm is implemented using BLAS level 3 operations and recursive blocking.

This function is a wrapper around sla_trlyap_recursive.

See also

sla_trlyap_recursive

Parameters

TRANS

         TRANS is string
         Specifies the form of the system of equations with respect to A:
         == 'N':  op1(A) = A
         == 'T':  op1(A) = A**T

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         Right hand side Y and the solution X are symmetric M-by-M matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDB >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension 1
         Workspace for the algorithm

INFO

         INFO is INTEGER
         == 0:  successful exit
         < 0:  if INFO == -i, the i-Th argument had an illegal value
         > 0:  The equation is not solved correctly. One of the arising inner
               system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 221 of file trlyap.c.

void mepack_single_trstein_dag (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the Stein equation with OpenMP 4.

Purpose:

mepack_single_trstein_dag solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by SGEES from LAPACK.

Remarks

The algorithm is implemented using DAG Scheduling

The routine is a wrapper around sla_trstein_dag.

See also

sla_trstein_dag

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 257 of file trstein.c.

void mepack_single_trstein_level2 (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-2 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_single_trstein_level2 solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by SGEES from LAPACK.

Remarks

The routine is a wrapper around sla_trstein_l2.

See also

sla_trstein_l2

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 255 of file trstein.c.

void mepack_single_trstein_level3 (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_single_trstein_level3 solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by SGEES from LAPACK.

Remarks

The routine is a wrapper around sla_trstein_l3.

See also

sla_trstein_l3

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 375 of file trstein.c.

void mepack_single_trstein_level3_2stage (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Level-3 Bartels-Stewart Algorithm with sub-blocking for the Stein equation.

Purpose:

mepack_single_trstein_level3_2stage solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by SGEES from LAPACK.

Remarks

The routine is a wrapper around sla_trstein_l3_2s.

See also

sla_trstein_l3_2s

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 496 of file trstein.c.

void mepack_single_trstein_recursive (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Recursive blocking level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

mepack_single_trstein_recursive solves a Stein equation of the following forms

   A * X * A^T - X  = SCALE * Y                                              (2)

or

   A^T * X * A - X  =  SCALE * Y                                             (1)

where A is a M-by-M quasi upper triangular matrix.
and X and Y are symmetric  M-by-M matrices.
Typically the matrix A is created by SGEES from LAPACK.

Remarks

The routine is a wrapper around sla_trstein_recursive.

See also

sla_trstein_recursive

Parameters

TRANSA

         TRANSA is string
         Specifies the form of the system of equations with respect to A and C:
         == 'N':  Equation (1) is solved.
         == 'T':  Equation (2) is solved.

         M is INTEGER
         The order of the matrices A and C.  M >= 0.

         A is SINGLE PRECISION array, dimension (LDA,M)
         The matrix A must be (quasi-) upper triangular.

LDA

         LDA is INTEGER
         The leading dimension of the array A.  LDA >= max(1,M).

         X is SINGLE PRECISION array, dimension (LDX,N)
         On input, the matrix X contains the right hand side Y.
         On output, the matrix X contains the solution of Equation (1) or (2)
         as selected by TRANSA, TRANSB, and SGN.
         Right hand side Y and the solution X are M-by-N matrices.

LDX

         LDX is INTEGER
         The leading dimension of the array X.  LDX >= max(1,M).

SCALE

         SCALE is SINGLE PRECISION
         SCALE is a scaling factor to prevent the overflow in the result.
         If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems
         could not be solved correctly, 0 < SCALE <= 1 holds true.

WORK

         WORK is SINGLE PRECISION array, dimension LDWORK
         Workspace for the algorithm.
         The workspace needs to queried before the running the computation.
         The query is performed by calling the subroutine with INFO == -1 on input.
         The required workspace is then returned in INFO.

INFO

         INFO is INTEGER

         On input:
           == -1 : Perform a workspace query
           <> -1 : normal operation

         On exit, workspace query:
           < 0 :  if INFO == -i, the i-Th argument had an illegal value
           >= 0:  The value of INFO is the required number of elements in the workspace.

         On exit, normal operation:
           == 0:  successful exit
           < 0:  if INFO == -i, the i-Th argument had an illegal value
           > 0:  The equation is not solved correctly. One of the arising inner
                 system got singular.

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 255 of file trstein.c.

Author

Generated automatically by Doxygen for MEPACK from the source code.

Info

Fri Feb 2 2024 00:00:00 Version 1.1.1 MEPACK

ctrlyap - Man Page

Name

Synopsis

Functions

Detailed Description

Function Documentation

void mepack_double_trlyap_dag (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trlyap_level2 (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trlyap_level2_opt (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trlyap_level3 (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trlyap_level3_2stage (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trlyap_recursive (const char * TRANS, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trstein_dag (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trstein_level2 (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trstein_level3 (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trstein_level3_2stage (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_double_trstein_recursive (const char * TRANSA, int M, double * A, int LDA, double * X, int LDX, double * SCALE, double * WORK, int * INFO)

void mepack_single_trlyap_dag (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trlyap_level2 (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trlyap_level2_opt (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trlyap_level3 (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trlyap_level3_2stage (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trlyap_recursive (const char * TRANS, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trstein_dag (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trstein_level2 (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trstein_level3 (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trstein_level3_2stage (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

void mepack_single_trstein_recursive (const char * TRANSA, int M, float * A, int LDA, float * X, int LDX, float * SCALE, float * WORK, int * INFO)

Author

Info