This section describes what you use the utility subroutines for.
IESSL gets the level of ESSL and returns it to your program. The level consists of the following: version number, release number, modification number, and number of the most recently installed ESSL PTF. You can use this function to verify that you are running on or using the capabilities of the desired level.
STRIDE is used to determine optimal stride values for your Fourier transforms when using any of the Fourier transform subroutines, except _RCFT and _CRFT. You must invoke STRIDE for each optimal stride you want computed. Sometimes you need a separate stride for your input and output data. For the three-dimensional Fourier transforms, you need an optimal stride for both the second and third dimensions of the array. The examples provided for STRIDE explain how it is used for each of the subroutines listed above.
After obtaining the optimal strides from STRIDE, you should arrange your data using these stride values. After the data is set up, call the Fourier transform subroutine. For additional information on how to set up your data, see "Setting Up Your Data".
DSRSM is used to migrate your existing program from sparse matrices stored by rows to sparse matrices stored in compressed-matrix storage mode. This converts the matrices into a storage format that is compatible with the input requirements for some ESSL sparse matrix subroutines, such as DSMMX.
DGKTRN and DSKTRN are used to convert your sparse matrix from one skyline storage mode to another, if necessary, before calling the subroutines DGKFS/DGKFSP or DSKFS/DSKFSP, respectively.
This section contains the utility subroutine descriptions.
This subroutine returns information to your program about the data involved in a computational error that occurred in an ESSL subroutine. This is the same information that is provided in the ESSL messages; however, it allows you to check the information in your program at run time and continue processing. You pass the computational error code of interest to this subroutine in icode, and it passes back one or more pieces of information in the output arguments inf1 and, optionally, inf2, as defined in Table 167. You should use this subroutine only for those computational errors listed in the table. It does not apply to computational errors that do not return information.
For multithreaded application programs, if you want the error handling
capabilities that this subroutine provides to be implemented on each thread
created by your program, this subroutine must be called from each thread. If
your application creates multiple threads, the action performed by a call to
this subroutine applies to the thread that this subroutine was invoked from.
For an example, see "Example of Handling Errors in a Multithreaded Application Program".
Table 167. Computational Error Information Returned by EINFO
| Error Code | Receiver | Type of Information |
|---|---|---|
| 2100 | inf1
inf2 | Lower range of a vector
Upper range of a vector |
| 2101 | inf1
inf2 | Index of the eigenvalue that failed to converge
Number of iterations after which it failed to converge |
| 2102 | inf1
inf2 | Index of the last eigenvector that failed to converge
Number of iterations after which it failed to converge |
| 2103 | inf1 | Index of the pivot with zero value |
| 2104 | inf1 | Index of the last pivot with nonpositive value |
| 2105 | inf1 | Index of the pivot element near zero causing factorization to fail |
| 2107 | inf1
inf2 | Index of the singular value that failed to converge
Number of iterations after which it failed to converge |
| 2109 | inf1 | Iteration count when it was determined that the matrix was not definite |
| 2114 | inf1
inf2 | Index of the last eigenvalue that failed to converge
Number of iterations after which it failed to converge |
| 2115 | inf1 | Order of the leading minor that was discovered to have a nonpositive determinant |
| 2117 | inf1 | Column number for which pivot value was near zero |
| 2118 | inf1 | Row number for which pivot value was near zero |
| 2120 | inf1 | Row number of empty row where factorization failed |
| 2121 | inf1 | Column number of empty column where factorization failed |
| 2126 | inf1 | Row number for which pivot value was unacceptable |
| 2145 | inf1 | First diagonal element with zero value |
| Fortran | CALL EINFO (icode[, inf1[, inf2]]) |
| C and C++ | einfo (icode, inf1, inf2); |
| PL/I | CALL EINFO (icode[, inf1[, inf2]]); |
If icode = 0, this indicates that the ESSL error option table is to be initialized. (You specify this value once in the beginning of your program before calls to ERRSET.)
If icode has any of the allowable error code values listed in Table 167, this is the computational error code of interest. (You specify one of these values whenever you want information returned about a computational error.)
Specified as: a fullword integer; icode = 0 or an error code value indicated in Table 167.
If icode = 0, this argument is not used in the computation. In this case, inf1 is an optional argument, except in C and C++ programs.
If icode <> 0, then inf1 is the first information receiver, containing numerical information related to the computational error.
Returned as: a fullword integer.
If icode = 0, this argument is not used in the computation.
If icode <> 0, then inf2 is the second information receiver, containing numerical information related to the computational error. It should be specified when the error code provides a second piece of information, and you want the information.
In both of these cases, inf2 is an optional argument, except in C and C++ programs. For more details, see "Notes".
Returned as: a fullword integer.
The ERRSAV subroutine copies an ESSL error option table entry into an 8-byte storage area that is accessible to your program.
For multithreaded application programs, if you want the error handling capabilities that this subroutine provides to be implemented on each thread created by your program, this subroutine must be called from each thread. If your application creates multiple threads, the action performed by a call to this subroutine applies to the thread that this subroutine was invoked from. For an example, see "Example of Handling Errors in a Multithreaded Application Program".
| Fortran | CALL ERRSAV (ierno, tabent) |
| C and C++ | errsav (ierno, tabent); |
| PL/I | CALL ERRSAV (ierno, tabent); |
Examples of how to use ERRSAV are provided in "Coding Your Program".
The ERRSET subroutine allows you to control execution when error conditions occur. It modifies the information in the ESSL error option table for the error number indicated. For a range of error messages, you can specify the following:
For multithreaded application programs, if you want the error handling capabilities that this subroutine provides to be implemented on each thread created by your program, this subroutine must be called from each thread. If your application creates multiple threads, the action performed by a call to this subroutine applies to the thread that this subroutine was invoked from. For an example, see "Example of Handling Errors in a Multithreaded Application Program".
| Fortran | CALL ERRSET (ierno, inoal, inomes, itrace, iusadr, irange) |
| C and C++ | errset (ierno, inoal, inomes, itrace, iusadr, irange); |
| PL/I | CALL ERRSET (ierno, inoal, inomes, itrace, iusadr, irange); |
If inoal <= 0, the specification is ignored, and the number-of-errors option is not changed.
If inoal = 1, execution is terminated after one error.
If 2 <= inoal <= 255, then inoal specifies the number of errors allowed before each execution is terminated.
If inoal > 255, an unlimited number of errors is allowed.
Specified as: a fullword integer, where:
If iusadr = ENOTRM, then 2 <= inoal <= 255.
If inomes < 0, all messages are suppressed.
If inomes = 0, the number-of-messages option is not changed.
If 0 < inomes <= 255, then inomes specifies the number of messages to be printed.
If inomes > 255, an unlimited number of error messages is allowed.
Specified as: a fullword integer.
If iusadr = 0, the option table is not altered.
If iusadr = 1, the option table is set to show no exit routine. Therefore, standard corrective action is to be used when continuing execution.
If iusadr = ENOTRM, the option table entry is set to the ESSL error exit routine ENOTRM. Therefore, the ENOTRM subroutine is to be invoked after the occurrence of the indicated errors. (ENOTRM must appear in an EXTERNAL statement in your program.)
Specified as: a fullword integer or the name of a subroutine; iusadr = 0, 1, or ENOTRM.
If irange < ierno, the parameter is ignored.
If irange >= ierno, the options specified for the other parameters are to be applied to the entire range of error conditions encompassed by ierno and irange.
Specified as: a fullword integer.
The ERRSTR subroutine stores an entry in the ESSL error option table.
For multithreaded application programs, if you want the error handling capabilities that this subroutine provides to be implemented on each thread created by your program, this subroutine must be called from each thread. If your application creates multiple threads, the action performed by a call to this subroutine applies to the thread that this subroutine was invoked from. For an example, see "Example of Handling Errors in a Multithreaded Application Program".
| Fortran | CALL ERRSTR (ierno, tabent) |
| C and C++ | errstr (ierno, tabent); |
| PL/I | CALL ERRSTR (ierno, tabent); |
Examples of how to use ERRSTR are provided in "Coding Your Program".
This function returns the level of ESSL installed on your system, where the level consists of a version number, release number, and modification number, plus the fix number of the most recent PTF installed.
| Fortran | CALL IESSL () |
| C and C++ | iessl (); |
| PL/I | CALL IESSL (); |
Returned as: a fullword integer; vvrrmmff > 0.
The IESSL function enables you to determine the current level of ESSL installed on your system. It is useful to you in those instances where your program is using a subroutine or feature that exists only in certain levels of ESSL. It is also useful when your program is dependent upon certain PTFs being applied to ESSL.
This example shows several ways to use the IESSL function. Most typically, you use IESSL for checking the version and release level of ESSL. Suppose you are dependent on a new capability in ESSL, such as a new subroutine or feature, provided for the first time in ESSL Version 3. You can add the following check in your program before using the new capability:
IF IESSL() >= 3010000
By specifying 0000 for mmff, the modification and fix level, you are independent of the order in which your modifications and PTFs are installed.
Less typically, you use IESSL for checking the PTF level of ESSL. Suppose you are dependent on PTF 2 being installed on your ESSL Version 3 system. You want to know whether to call a different user-callable subroutine to set up your array data. You can add the following check in your program before making the call:
IF IESSL() >= 3010002
If your system support group installed the ESSL PTFs in their proper sequential order, this test works properly; otherwise, it is unpredictable.
This subroutine determines an optimal stride value for you to use for your input or output data when you are computing large row Fourier transforms in any of the Fourier transform subroutines, except _RCFT and _CRFT. The strides determined by this subroutine allow your arrays to fit comfortably in various levels of storage hierarchy on your particular processor, thus allowing you to improve your run-time performance.
| Note: | This subroutine returns a single stride value. Where you need multiple strides, you must invoke this subroutine multiple times; for example, in the multidimensional Fourier transforms and, also, when input and output data types differ. For more details, see "Function". |
| Fortran | CALL STRIDE (n, incd, incr, dt, iopt) |
| C and C++ | stride (n, incd, incr, dt, iopt); |
| PL/I | CALL STRIDE (n, incd, incr, dt, iopt); |
Specified as: a fullword integer; n > 0.
Specified as: a fullword integer; incd > 0 or incd < 0.
If dt = 'S', the numbers are short-precision real.
If dt = 'D', the numbers are long-precision real.
If dt = 'C', the numbers are short-precision complex.
If dt = 'Z', the numbers are long-precision complex.
Specified as: a single character; dt = 'S', 'D', 'C', or 'Z'.
Returned as: a fullword integer; incr > 0 or incr < 0 and |incr| >= |incd|, where incr has the same sign (+ or -) as incd.
This subroutine determines an optimal stride, incr, for you to use for your input or output data when computing large row Fourier transforms. The stride value returned by this subroutine is based on the size and structure of your transform data, using:
This information is used in determining the optimal stride for the processor you are currently running on. The stride determined by this subroutine allows your arrays to fit comfortably in various levels of storage hierarchy for that processor, thus giving you the ability to improve your run-time performance.
You get only one stride value returned by this subroutine on each invocation. Therefore, in many instances, you may need to invoke this subroutine multiple times to obtain several stride values to use in your Fourier transform computation:
Where multiple invocations are necessary, they are explained in the examples starting on page "Example 1--SCFT". The examples also explain how to calculate the incd values for each invocation. There are nine examples to cover the Fourier transform subroutines that can use the STRIDE subroutine.
After calling this subroutine and obtaining the optimal stride value, you then set up your input or output array accordingly. This may involve movement of data for input arrays or increasing the sizes of input or output arrays. To accomplish this, you may want to set up a separate subroutine with the stride values passed into it as arguments. You can then dimension your arrays in that subroutine, depending on the values calculated by STRIDE. For additional information on how to set up your data, see "Setting Up Your Data".
None
This example shows the use of the STRIDE subroutine in computing one-dimensional row transforms using the SCFT subroutine.
If inc2x = 1, the input sequences are stored in the transposed form as rows of a two-dimensional array X(INC1X,N). In this case, the STRIDE subroutine helps in determining a good value of inc1x for this array. The required minimum value of inc1x is m, the number of Fourier transforms being computed. To find a good value of inc1x, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N , M , INC1X , 'C' , 0 )
Here, the arguments refer to the SCFT subroutine. In the following table, values of inc1x are given (as obtained from the STRIDE subroutine) for some combinations of n and m and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N M INC1X
128 64 64
240 32 32
240 64 65
256 256 264
512 60 60
1024 64 65
The above example also applies when the output sequences are stored in the transposed form (inc2y = 1). In that case, in the above example, inc1x is replaced by inc1y.
In computing column transforms (inc1x = inc1y = 1), the values of inc2x and inc2y are not very important. For these, any value over the required minimum of n can be used.
This example shows the use of the STRIDE subroutine in computing one-dimensional row transforms using the DCOSF subroutine.
If inc2x = 1, the input sequences are stored in the transposed form as rows of a two-dimensional array X(INC1X,N/2+1). In this case, the STRIDE subroutine helps in determining a good value of inc1x for this array. The required minimum value of inc1x is m, the number of Fourier transforms being computed. To find a good value of inc1x, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N/2+1 , M , INC1X , 'D' , 0 )
Here, the arguments refer to the DCOSF subroutine. In the following table, values of inc1x are given (as obtained from the STRIDE subroutine) for some combinations of n and m and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N M INC1X
128 64 64
240 32 32
240 64 64
256 256 264
512 60 60
1024 64 65
The above example also applies when the output sequences are stored in the transposed form (inc2y = 1). In that case, in the above example, inc1x is replaced by inc1y.
In computing column transforms (inc1x = inc1y = 1), the values of inc2x and inc2y are not very important. For these, any value over the required minimum of n/2+1 can be used.
This example shows the use of the STRIDE subroutine in computing one-dimensional row transforms using the DSINF subroutine.
If inc2x = 1, the input sequences are stored in the transposed form as rows of a two-dimensional array X(INC1X,N/2). In this case, the STRIDE subroutine helps in determining a good value of inc1x for this array. The required minimum value of inc1x is m, the number of Fourier transforms being computed. To find a good value of inc1x, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N/2 , M , INC1X , 'D' , 0 )
Here, the arguments refer to the DSINF subroutine. In the following table, values of inc1x are given (as obtained from the STRIDE subroutine) for some combinations of n and m and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N M INC1X
128 64 64
240 32 32
240 64 64
256 256 264
512 60 60
1024 64 65
The above example also applies when the output sequences are stored in the transposed form (inc2y = 1). In that case, in the above example, inc1x is replaced by inc1y.
In computing column transforms (inc1x = inc1y = 1), the values of inc2x and inc2y are not very important. For these, any value over the required minimum of n/2 can be used.
This example shows the use of the STRIDE subroutine in computing two-dimensional transforms using the SCFT2 subroutine.
If inc1y = 1, the two-dimensional output array is stored in the normal form. In this case, the output array can be declared as Y(INC2Y,N2), where the required minimum value of inc2y is n1. The STRIDE subroutine helps in picking a good value of inc2y. To find a good value of inc2y, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1 , INC2Y , 'C' , 0 )
Here, the arguments refer to the SCFT2 subroutine. In the following table, values of inc2y are given (as obtained from the STRIDE subroutine) for some two-dimensional arrays with n1 = n2 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1 N2 INC2Y
64 64 64
128 128 136
240 240 240
512 512 520
840 840 848
If the input array is stored in the normal form (inc1x = 1), the value of inc2x is not important. However, if you want to use the same array for input and output, you should use inc2x = inc2y.
If inc2y = 1, the two-dimensional output array is stored in the transposed form. In this case, the output array can be declared as Y(INC1Y,N1), where the required minimum value of inc1y is n2. The STRIDE subroutine helps in picking a good value of inc1y. To find a good value of inc1y, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N1 , N2 , INC1Y , 'C' , 0 )
Here, the arguments refer to the SCFT2 subroutine. In the following table, values of inc1y are given (as obtained from the STRIDE subroutine) for some combinations of n1 and n2 and for POWER2-P2SC with 64K level 1 cache using the POWER2 library for ESSL:
N1 N2 INC1Y
60 64 64
120 128 136
256 240 240
512 512 520
840 840 848
If the input array is stored in the transposed form (inc2x = 1), the value of inc1x is also important. The above example can be used to find a good value of inc1x, by replacing inc1y with inc1x. If both arrays are stored in the transposed form, a good value for inc1y is also a good value for inc1x. In that situation, the two arrays can also be made equivalent.
This example shows the use of the STRIDE subroutine in computing two-dimensional transforms using the SRCFT2 subroutine.
For this subroutine, the output array is declared as Y(INC2Y,N2), where the required minimum value of inc2y is n1/2+1. The STRIDE subroutine helps in picking a good value of inc2y. To find a good value of inc2y, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1/2 + 1 , INC2Y , 'C' , 0 )
Here, the arguments refer to the SRCFT2 subroutine. In the following table, values of inc2y are given (as obtained from the STRIDE subroutine) for some two-dimensional arrays with n1 = n2 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1 N2 INC2Y
240 240 121
420 420 211
512 512 257
840 840 421
1024 1024 513
2048 2048 1032
For this subroutine, the leading dimension of the input array (inc2x) is not important. If you want to use the same array for input and output, you should use inc2x >= 2(inc2y).
This example shows the use of the STRIDE subroutine in computing two-dimensional transforms using the SCRFT2 subroutine.
For this subroutine, the output array is declared as Y(INC2Y,N2), where the required minimum value of inc2y is n1+2. The STRIDE subroutine helps in picking a good value of inc2y. To find a good value of inc2y, use STRIDE as follows:
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1 + 2 , INC2Y , 'S' , 0 )
Here, the arguments refer to the SCRFT2 subroutine. In the following table, values of inc2y are given (as obtained from the STRIDE subroutine) for some two-dimensional arrays with n1 = n2 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1 N2 INC2Y
240 240 242
420 420 422
512 512 514
840 840 842
1024 1024 1026
2048 2048 2064
For this subroutine, the leading dimension of the input array (inc2x) is also important. In general, inc2x = inc2y/2 is a good choice. This is also the requirement if you want to use the same array for input and output.
This example shows the use of the STRIDE subroutine in computing three-dimensional transforms using the SCFT3 subroutine.
For this subroutine, the strides for the input array are not important. They are important for the output array. The STRIDE subroutine helps in picking good values of inc2y and inc3y. This requires two calls to the STRIDE subroutine as shown below. First, you should find a good value for inc2y. The minimum acceptable value for inc2y is n1.
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1 , INC2Y , 'C' , 0 )
Here, the arguments refer to the SCFT3 subroutine. Next, you should find a good value for inc3y. The minimum acceptable value for inc3y is (n2)(inc2y).
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N3 , N2*INC2Y, INC3Y , 'C' , 0 )
If inc3y turns out to be a multiple of inc2y, then Y can be declared a three-dimensional array as Y(INC2Y,INC3Y/INC2Y,N3). For large problems, this may not happen. In that case, you can declare the Y array as a two-dimensional array Y(0:INC3Y-1,0:N3-1) or a one-dimensional array Y(0:INC3Y*N3-1). Using zero-based indexing, the element y(k1,k2,k3) is stored in the following location in these arrays:
In the following table, values of inc2y and inc3y are given (as obtained from the STRIDE subroutine) for some three-dimensional arrays with n1 = n2 = n3 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1,N2,N3 INC2Y INC3Y
30 30 900
32 32 1032
64 64 4112
120 120 14400
128 136 17416
240 240 57608
256 264 67592
420 420 176400
As mentioned before, the strides of the input array are not important. The array can be declared as a three-dimensional array. If you want to use the same array for input and output, the requirements are inc2x >= inc2y and inc3x >= inc3y. A simple thing to do is to use inc2x = inc2y and make inc3x a multiple of inc2x not smaller than inc3y. Then X can be declared as a three-dimensional array X(INC2X,INC3X/INC2X,N3).
This example shows the use of the STRIDE subroutine in computing three-dimensional transforms using the SRCFT3 subroutine.
For this subroutine, the strides for the input array are not important. They are important for the output array. The STRIDE subroutine helps in picking good values of inc2y and inc3y. This requires two calls to the STRIDE subroutine as shown below. First, you should find a good value for inc2y. The minimum acceptable value for inc2y is n1/2+1.
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1/2 + 1 , INC2Y , 'C' , 0 )
Here, the arguments refer to the SRCFT3 subroutine. Next, you should find a good value for inc3y. The minimum acceptable value for inc3y is (n2)(inc2y).
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N3 , N2*INC2Y , INC3Y , 'C' , 0 )
If inc3y turns out to be a multiple of inc2y, then Y can be declared a three-dimensional array as Y(INC2Y,INC3Y/INC2Y,N3). For large problems, this may not happen. In that case, you can declare the Y array as a two-dimensional array Y(0:INC3Y-1,0:N3-1) or a one-dimensional array Y(0:INC3Y*N3-1). Using zero-based indexing, the element y(k1,k2,k3) is stored in the following location in these arrays:
In the following table, values of inc2y and inc3y are given (as obtained from the STRIDE subroutine) for some three-dimensional arrays with n1 = n2 = n3 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1,N2,N3 INC2Y INC3Y
32 17 544
64 33 2112
120 61 7320
128 65 8328
240 121 29064
256 129 33032
As mentioned before, the strides of the input array are not important. The array can be declared as a three-dimensional array. If you want to use the same array for input and output, the requirements are inc2x >= 2(inc2y) and inc3x >= 2(inc3y). A simple thing to do is to use inc2x = 2(inc2y) and make inc3x a multiple of inc2x not smaller than 2(inc3y). Then X can be declared as a three-dimensional array X(INC2X,INC3X/INC2X,N3).
This example shows the use of the STRIDE subroutine in computing three-dimensional transforms using the SCRFT3 subroutine.
The STRIDE subroutine helps in picking good values of inc2y and inc3y. This requires two calls to the STRIDE subroutine as shown below. First, you should find a good value for inc2y. The minimum acceptable value for inc2y is n1+2.
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N2 , N1 + 2 , INC2Y , 'S' , 0 )
Here, the arguments refer to the SCRFT3 subroutine. Next, you should find a good value for inc3y. The minimum acceptable value for inc3y is (n2)(inc2y).
N INCD INCR DT IOPT
| | | | |
CALL STRIDE( N3 , N2*INC2Y , INC3Y , 'S' , 0 )
If inc3y turns out to be a multiple of inc2y, then Y can be declared a three-dimensional array as Y(INC2Y,INC3Y/INC2Y,N3). For large problems, this may not happen. In that case, you can declare the Y array as a two-dimensional array Y(0:INC3Y-1,0:N3-1) or a one-dimensional array Y(0:INC3Y*N3-1). Using zero-based indexing, the element y(k1,k2,k3) is stored in the following location in these arrays:
In the following table, values of inc2y and inc3y are given (as obtained from the STRIDE subroutine) for some three-dimensional arrays with n1 = n2 = n3 and for POWER2-P2SC with 64KB level 1 cache using the POWER2 library for ESSL:
N1,N2,N3 INC2Y INC3Y
32 34 1088
64 66 4224
120 122 14640
128 130 16656
240 242 58128
256 258 66064
For this subroutine, the strides (inc2x and inc3x) of the input array are also important. In general, inc2x = inc2y/2 and inc3x = inc3y/2 are good choices. These are also the requirement if you want to use the same array for input and output.
This subroutine converts either m by n general sparse matrix A or symmetric sparse matrix A of order n from storage-by-rows to compressed-matrix storage mode, where matrix A contains long-precision real numbers.
| Fortran | CALL DSRSM (iopt, ar, ja, ia, m, nz, ac, ka, lda) |
| C and C++ | dsrsm (iopt, ar, ja, ia, m, nz, ac, ka, lda); |
| PL/I | CALL DSRSM (iopt, ar, ja, ia, m, nz, ac, ka, lda); |
If iopt = 0, matrix A is a general sparse matrix, where all the nonzero elements in matrix A are used to set up the storage arrays.
If iopt = 1, matrix A is a symmetric sparse matrix, where only the upper triangle and diagonal elements are used to set up the storage arrays.
Specified as: a fullword integer; iopt = 0 or 1.
A sparse matrix A is converted from storage-by-rows (using arrays AR, JA, and IA) to compressed-matrix storage mode (using arrays AC and KA). The argument iopt indicates whether the input matrix A is stored by rows using the storage variation for general sparse matrices or for symmetric sparse matrices. See reference [67].
This subroutine is meant for existing programs that need to convert their sparse matrices to a storage mode compatible with some of the ESSL sparse matrix subroutines, such as DSMMX.
None
This example shows a general sparse matrix A, which is stored by rows and converted to compressed-matrix storage mode, where sparse matrix A is:
* *
| 11.0 0.0 0.0 14.0 |
| 0.0 22.0 0.0 24.0 |
| 0.0 0.0 33.0 34.0 |
| 0.0 0.0 0.0 44.0 |
* *
Because there is a maximum of only two nonzero elements in each row of A, and argument nz is specified as 5, columns 3 through 5 of arrays AC and KA are not used.
IOPT AR JA IA M NZ AC KA LDA
| | | | | | | | |
CALL DSRSM( 0 , AR , JA , IA , 4 , 5 , AC , KA , 4 )
AR = (11.0, 14.0, 22.0, 24.0, 33.0, 34.0, 44.0)
JA = (1, 4, 2, 4, 3, 4, 4)
IA = (1, 3, 5, 7, 8)
NZ = 2
* *
| 11.0 14.0 . . . |
AC = | 22.0 24.0 . . . |
| 33.0 34.0 . . . |
| 44.0 0.0 . . . |
* *
* *
| 1 4 . . . |
KA = | 2 4 . . . |
| 3 4 . . . |
| 4 4 . . . |
* *
This example shows a symmetric sparse matrix A, which is stored by rows and converted to compressed-matrix storage mode, where sparse matrix A is:
* *
| 11.0 0.0 0.0 14.0 |
| 0.0 22.0 0.0 24.0 |
| 0.0 0.0 33.0 34.0 |
| 14.0 24.0 34.0 44.0 |
* *
Because there is a maximum of only four nonzero elements in each row of A, and argument nz is specified as 6, columns 5 and 6 of arrays AC and KA are not used.
IOPT AR JA IA M NZ AC KA LDA
| | | | | | | | |
CALL DSRSM( 1 , AR , JA , IA , 4 , 6 , AC , KA , 4 )
AR = (11.0, 14.0, 22.0, 24.0, 33.0, 34.0, 44.0)
JA = (1, 4, 2, 4, 3, 4, 4)
IA = (1, 3, 5, 7, 8)
NZ = 4
* *
| 11.0 14.0 0.0 0.0 . . |
AC = | 22.0 24.0 0.0 0.0 . . |
| 33.0 34.0 0.0 0.0 . . |
| 44.0 24.0 34.0 14.0 . . |
* *
* *
| 1 4 4 4 . . |
KA = | 2 4 4 4 . . |
| 3 4 4 4 . . |
| 4 2 3 1 . . |
* *
This subroutine converts general sparse matrix A of order n from one skyline storage mode to another--that is, between the following:
| Fortran | CALL DGKTRN (n, au, nu, idu, al, nl, idl, itran, aux, naux) |
| C and C++ | dgktrn (n, au, nu, idu, al, nl, idl, itran, aux, naux); |
| PL/I | CALL DGKTRN (n, au, nu, idu, al, nl, idl, itran, aux, naux); |
If ITRAN(1) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(1) = 1, A is stored in profile-in skyline storage mode.
Specified as: a one-dimensional array of (at least) length nu, containing long-precision real numbers.
If ITRAN(1) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(1) = 1, A is stored in profile-in skyline storage mode.
| Note: | Entries in AL for diagonal elements of A are assumed not to have meaningful values. |
Specified as: a one-dimensional array of (at least) length nl, containing long-precision real numbers.
If ITRAN(1) = 0, diagonal-out skyline storage mode is used.
If ITRAN(1) = 1, profile-in skyline storage mode is used.
If ITRAN(2) = 0, diagonal-out skyline storage mode is used.
If ITRAN(2) = 1, profile-in skyline storage mode is used.
If ITRAN(3) = 1, matrix A is transformed in the positive direction, starting in row or column 1 and ending in row or column n.
If ITRAN(3) = -1, matrix A is transformed in the negative direction, starting in row or column n and ending in row or column 1.
Specified as: a one-dimensional array of (at least) length 3, containing fullword integers, where:
If naux = 0 and error 2015 is unrecoverable, aux is ignored.
Otherwise, it is the storage work area used by this subroutine. Its size is specified by naux.
Specified as: an area of storage, containing naux long-precision real numbers.
If naux = 0 and error 2015 is unrecoverable, DGKTRN dynamically allocates the work area used by this subroutine. The work area is deallocated before control is returned to the calling program.
Otherwise, naux >= 2n.
If ITRAN(2) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(2) = 1, A is stored in profile-in skyline storage mode.
Returned as: a one-dimensional array of (at least) length nu, containing long-precision real numbers.
If ITRAN(2) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(2) = 1, A is stored in profile-in skyline storage mode.
| Note: | You should assume that entries in AL for diagonal elements of A do not have meaningful values. |
Returned as: a one-dimensional array of (at least) length nl, containing long-precision real numbers.
The direction specified by ITRAN(3) should be opposite the most
recent direction of access through the matrix performed by the DGKFS or DGKFSP
subroutine, as indicated in the following table:
| Most Recent Computation Performed by DGKFS/DGKFSP | Direction Used by DGKFS/DGKFSP | Direction to Specify in ITRAN(3) |
|---|---|---|
| Factor and Solve | Negative | Positive (ITRAN(3) = 1) |
| Factor Only | Positive | Negative (ITRAN(3) = -1) |
| Solve Only | Negative | Positive (ITRAN(3) = 1) |
A general sparse matrix A, stored in diagonal-out or profile-in skyline storage mode is converted to either of these same two storage modes. (Generally, you convert from one to the other, but the capability exists to specify the same storage mode for input and output.) The argument ITRAN(3) indicates the direction in which you want the transformation performed on matrix A, allowing you to optimize your performance in this subroutine. This is especially beneficial for large matrices.
This subroutine is meant to be used in conjunction with DGKFS and DGKFSP, which process matrices stored in these skyline storage modes.
Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.
None
This example shows how to convert a 9 by 9 general sparse matrix A from diagonal-out skyline storage mode to profile-in skyline storage mode. Matrix A is:
* *
| 11.0 12.0 13.0 0.0 0.0 0.0 0.0 0.0 0.0 |
| 21.0 22.0 23.0 24.0 25.0 0.0 0.0 0.0 29.0 |
| 31.0 32.0 33.0 34.0 35.0 0.0 37.0 0.0 39.0 |
| 41.0 42.0 43.0 44.0 45.0 46.0 47.0 0.0 49.0 |
| 0.0 0.0 0.0 54.0 55.0 56.0 57.0 58.0 59.0 |
| 0.0 62.0 63.0 64.0 65.0 66.0 67.0 68.0 69.0 |
| 0.0 0.0 0.0 74.0 75.0 76.0 77.0 78.0 79.0 |
| 0.0 0.0 0.0 84.0 85.0 86.0 87.0 88.0 89.0 |
| 91.0 92.0 93.0 94.0 95.0 96.0 97.0 98.0 99.0 |
* *
Assuming that DGKFS last performed a solve on matrix A, the direction of the transformation is positive; that is, ITRAN(3) is 1. This provides the best performance here.
| Note: | On input and output, the diagonal elements in AL do not have meaningful values. |
N AU NU IDU AL NL IDL ITRAN AUX NAUX
| | | | | | | | | |
CALL DGKTRN( 9 , AU , 33 , IDU , AL , 35 , IDL , ITRAN , AUX , 18
AU = (11.0, 22.0, 12.0, 33.0, 23.0, 13.0, 44.0, 34.0, 24.0,
55.0, 45.0, 35.0, 25.0, 66.0, 56.0, 46.0, 77.0, 67.0,
57.0, 47.0, 37.0, 88.0, 78.0, 68.0, 58.0, 99.0, 89.0,
79.0, 69.0, 59.0, 49.0, 39.0, 29.0)
IDU = (1, 2, 4, 7, 10, 14, 17, 22, 26, 34)
AL = ( . , . , 21.0, . , 32.0, 31.0, . , 43.0, 42.0, 41.0, . ,
54.0, . , 65.0, 64.0, 63.0, 62.0, . , 76.0, 75.0, 74.0,
. , 87.0, 86.0, 85.0, 84.0, . , 98.0, 97.0, 96.0, 95.0,
94.0, 93.0, 92.0, 91.0)
IDL = (1, 2, 4, 7, 11, 13, 18, 22, 27, 36)
ITRAN = (0, 1, 1)
AU = (11.0, 12.0, 22.0, 13.0, 23.0, 33.0, 24.0, 34.0, 44.0,
25.0, 35.0, 45.0, 55.0, 46.0, 56.0, 66.0, 37.0, 47.0,
57.0, 67.0, 77.0, 58.0, 68.0, 78.0, 88.0, 29.0, 39.0,
49.0, 59.0, 69.0, 79.0, 89.0, 99.0)
IDU = (1, 3, 6, 9, 13, 16, 21, 25, 33, 34)
AL = ( . , 21.0, . , 31.0, 32.0, . , 41.0, 42.0, 43.0, . , 54.0,
. , 62.0, 63.0, 64.0, 65.0, . , 74.0, 75.0, 76.0, . ,
84.0, 85.0, 86.0, 87.0, . , 91.0, 92.0, 93.0, 94.0, 95.0,
96.0, 97.0, 98.0, . )
IDL = (1, 3, 6, 10, 12, 17, 21, 26, 35, 36)
This example shows how to convert the same 9 by 9 general sparse matrix A in Example 1 from profile-in skyline storage mode to diagonal-out skyline storage mode.
Assuming that DGKFS last performed a factorization on matrix A, the direction of the transformation is negative; that is, ITRAN(3) is -1. This provides the best performance here.
| Note: | On input and output, the diagonal elements in AL do not have meaningful values. |
N AU NU IDU AL NL IDL ITRAN AUX NAUX
| | | | | | | | | |
CALL DGKTRN( 9 , AU , 33 , IDU , AL , 35 , IDL , ITRAN , AUX , 18
AU =(same as output AU in Example 1) IDU =(same as output IDU in Example 1) AL =(same as output AL in Example 1) IDL =(same as output IDL in Example 1) ITRAN = (1, 0, -1)
AU =(same as input AU in Example 1) IDU =(same as input IDU in Example 1) AL =(same as input AL in Example 1) IDL =(same as input IDL in Example 1)
This subroutine converts symmetric sparse matrix A of order n from one skyline storage mode to another--that is, between the following:
| Fortran | CALL DSKTRN (n, a, na, idiag, itran, aux, naux) |
| C and C++ | dsktrn (n, a, na, idiag, itran, aux, naux); |
| PL/I | CALL DSKTRN (n, a, na, idiag, itran, aux, naux); |
If ITRAN(1) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(1) = 1, A is stored in profile-in skyline storage mode.
Specified as: a one-dimensional array of (at least) length na, containing long-precision real numbers.
If ITRAN(1) = 0, diagonal-out skyline storage mode is used.
If ITRAN(1) = 1, profile-in skyline storage mode is used.
If ITRAN(2) = 0, diagonal-out skyline storage mode is used.
If ITRAN(2) = 1, profile-in skyline storage mode is used.
If ITRAN(3) = 1, matrix A is transformed in the positive direction, starting in row or column 1 and ending in row or column n.
If ITRAN(3) = -1, matrix A is transformed in the negative direction, starting in row or column n and ending in row or column 1.
Specified as: a one-dimensional array of (at least) length 3, containing fullword integers, where:
If naux = 0 and error 2015 is unrecoverable, aux is ignored.
Otherwise, it is the storage work area used by this subroutine. Its size is specified by naux.
Specified as: an area of storage, containing naux long-precision real numbers.
If naux = 0 and error 2015 is unrecoverable, DSKTRN dynamically allocates the work area used by this subroutine. The work area is deallocated before control is returned to the calling program.
Otherwise, naux >= n.
If ITRAN(2) = 0, A is stored in diagonal-out skyline storage mode.
If ITRAN(2) = 1, A is stored in profile-in skyline storage mode.
Returned as: a one-dimensional array of (at least) length na, containing long-precision real numbers.
The direction specified by ITRAN(3) should be opposite the most
recent direction of access through the matrix performed by the DSKFS or DSKFSP
subroutine, as indicated in the following table:
| Most Recent Computation Performed by DSKFS/DSKFSP | Direction Used by DSKFS/DSKFSP | Direction to Specify in ITRAN(3) |
|---|---|---|
| Factor and Solve | Negative | Positive (ITRAN(3) = 1) |
| Factor Only | Positive | Negative (ITRAN(3) = -1) |
| Solve Only | Negative | Positive (ITRAN(3) = 1) |
A symmetric sparse matrix A, stored in diagonal-out or profile-in skyline storage mode is converted to either of these same two storage modes. (Generally, you convert from one to the other, but the capability exists to specify the same storage mode for input and output.) The argument ITRAN(3) indicates the direction in which you want the transformation performed on matrix A, allowing you to optimize your performance in this subroutine. This is especially beneficial for large matrices.
This subroutine is meant to be used in conjunction with DSKFS and DSKFSP, which process matrices stored in these skyline storage modes.
Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.
None
This example shows how to convert a 9 by 9 symmetric sparse matrix A from diagonal-out skyline storage mode to profile-in skyline storage mode. Matrix A is:
* *
| 11.0 12.0 13.0 14.0 0.0 0.0 0.0 0.0 0.0 |
| 12.0 22.0 23.0 24.0 25.0 26.0 0.0 28.0 0.0 |
| 13.0 23.0 33.0 34.0 35.0 36.0 0.0 38.0 0.0 |
| 14.0 24.0 34.0 44.0 45.0 46.0 0.0 48.0 0.0 |
| 0.0 25.0 35.0 45.0 55.0 56.0 57.0 58.0 0.0 |
| 0.0 26.0 36.0 46.0 56.0 66.0 67.0 68.0 69.0 |
| 0.0 0.0 0.0 0.0 57.0 67.0 77.0 78.0 79.0 |
| 0.0 28.0 38.0 48.0 58.0 68.0 78.0 88.0 89.0 |
| 0.0 0.0 0.0 0.0 0.0 69.0 79.0 89.0 99.0 |
* *
Assuming that DSKFS last performed a factorization on matrix A, the direction of the transformation is negative; that is, ITRAN(3) is -1. This provides the best performance here.
N A NA IDIAG ITRAN AUX NAUX
| | | | | | |
CALL DSKTRN( 9 , A , 33 , IDIAG , ITRAN , AUX , 9 )
A = (11.0, 22.0, 12.0, 33.0, 23.0, 13.0, 44.0, 34.0, 24.0,
14.0, 55.0, 45.0, 35.0, 25.0, 66.0, 56.0, 46.0, 36.0,
26.0, 77.0, 67.0, 57.0, 88.0, 78.0, 68.0, 58.0, 48.0,
38.0, 28.0, 99.0, 89.0, 79.0, 69.0)
IDIAG = (1, 2, 4, 7, 11, 15, 20, 23, 30, 34)
ITRAN = (0, 1, -1)
A = (11.0, 12.0, 22.0, 13.0, 23.0, 33.0, 14.0, 24.0, 34.0,
44.0, 25.0, 35.0, 45.0, 55.0, 26.0, 36.0, 46.0, 56.0,
66.0, 57.0, 67.0, 77.0, 28.0, 38.0, 48.0, 58.0, 68.0,
78.0, 88.0, 69.0, 79.0, 89.0, 99.0)
IDIAG = (1, 3, 6, 10, 14, 19, 22, 29, 33, 34)
This example shows how to convert the same 9 by 9 symmetric sparse matrix A in Example 1 from profile-in skyline storage mode to diagonal-out skyline storage mode.
Assuming that DSKFS last performed a solve on matrix A, the direction of the transformation is positive; that is, ITRAN(3) is 1. This provides the best performance here.
N A NA IDIAG ITRAN AUX NAUX
| | | | | | |
CALL DSKTRN( 9 , A , 33 , IDIAG , ITRAN , AUX , 9
A =(same as output A in Example 1) IDIAG =(same as output IDIAG in Example 1) ITRAN = (1, 0, 1)
A =(same as input A in Example 1) IDIAG =(same as input IDIAG in Example 1)