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 in Chapter
1, “Linear Systems”
of lin_sol_gen
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 in Chapter 2, “Singular Value and Eigenvalue
Decomposition” of lin_eig_self, 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 Chapter 1, “Linear Solvers” of lin_sol_self uses three and then four option numbers for purposes of computing an eigenvector associated with a known eigenvalue.
|
Visual Numerics, Inc. PHONE: 713.784.3131 FAX:713.781.9260 |