Optional Data
This additional optional argument (available for some routines) is further distinguished—a derived type array that contains a number of parameters to modify the internal algorithm of a routine. This derived type has the name ?_options, where “?_” is either “s_” or “d_”. The choice depends on the precision of the data type. The declaration of this derived type is packaged within the modules for these codes.
The definition of the derived types is:
type ?_options
integer idummy; real(kind(?)) rdummy
end type
where the “?_” is either “s_” or “d_”, and the kind value matches the desired data type indicated by the choice of “s” or “d”.
Example 3 of LIN_SOL_GEN in
Chapter 1, “Linear Systems” illustrates the use of iterative refinement to compute a double-precision solution based on a single-precision factorization of the matrix. This is communicated to the routine using an optional argument with optional data. For efficiency of iterative refinement, perform the factorization step once, and then save the factored matrix in the array
A and the pivoting information in the rank-1 integer array,
ipivots. By default, the factorization is normally discarded. To enable the routine to be re-entered with a previously computed factorization of the matrix, optional data are used as array entries in the “
iopt=” optional argument. The packaging of
LIN_SOL_GEN includes the definitions of the self-documenting integer parameters
lin_sol_gen_save_LU and
lin_sol_gen_solve_A. These parameters have the values 2 and 3, but the programmer usually does not need to be aware of it.
The following rules apply to the “
iopt=iopt” optional argument:
1. Define a relative index, for example IO, for placing option numbers and data into the array argument iopt. Initially, set IO = 1. Before a call to the IMSL Library routine, follow Steps 2 through 4.
2. The data structure for the optional data array has the following form:
iopt (IO) = ?_options (Option_number, Optional_data)
[iopt (IO + 1) =?_options (Option_number, Optional_data)]
The length of the data set is specified by the documentation for an individual routine. (The Optional_data is output in some cases and may not be used in other cases.) The square braces […] denote optional items.
Illustration:
Example 3 of LIN_EIG_SELF in
Chapter 2, “Singular Value and Eigenvalue Decomposition”, a new definition for a small diagonal term is passed to
lin_sol_self. There is one line of code required for the change and the new tolerance:
iopt (1) = d_options(d_lin_sol_self_set_small,
epsilon(one) *abs (d(i)))
3. The internal processing of option numbers stops when Option_number == 0 or when IO > SIZE(iopt). This signals each routine having this optional argument that all desired changes to default values of internal parameters have been made. This implies that the last option number is the value zero or the value of SIZE(iopt) matches the last optional value changed.
4. To add more options, replace IO with IO + n, where n is the number of items required for the previous option. Go to Step 2.
Option numbers can be written in any order, and any selected set of options can be changed from the defaults. They may be repeated.
Example 3 in of LIN_SOL_SELF in
Chapter 1, “Linear Systems” uses three and then four option numbers for purposes of computing an eigenvector associated with a known eigenvalue.
