2.3.3.2 Using the Black-Box Routine

The purpose of the black-box wrapper is to twofold:

1.

to provide a simpler interface to the solver routines (one that tries to use reasonable default values for as many control parameters as possible), and

2.

to provide a more robust solver (one that uses algorithms that tend to be fast first, then progressively using more and more agressive techniques if the faster methods fail).

The argument list for all the black-box wrapper for the nonstationary solvers is similar to that for the solvers themselves, with the addition of two new arguments:

      call JT_Nonstationary (method, mode, b, a, ia, ja, iparm, rparm,
     &     x, cpu, rnormt, errt, rnorm, err, ap, iap, jap, status)

Details about new arguments follow:

• mode - operational mode
  • Intent: In
  • Type: Integer scalar
  • Values:

    0 $\Longrightarrow$ black-box mode

    Control parameters (iparm and rparm values) are set by the routine to reasonable defaults, depending on method. One parameter, however, must still be set. That is, the maximum number of iterations to allow, iparm(_JT_ itmax_).

    1 $\Longrightarrow$ hybrid, or partial black-box, mode

    Control parameters related to output, and overall convergence criterion, are set by user. Remainder are set automatically by the routine. Parameters that can be set are:

    iparm(_JT_ out_)
    iparm(_JT_ luout_)
    iparm(_JT_ luerr_)
    iparm(_JT_ itmax_)
    iparm(_JT_ stop_) (see Note)
    iparm(_JT_ pre_)
    rparm(_JT_ eps_) (see Note)

    Note: Defaults can be used for iparm(_JT_ stop_) and rparm(_JT_ eps_) by by setting them to zero.

    2 $\Longrightarrow$ full manual mode

    iparm and rparm are assumed to be set on entry.

• method - indicates solver to use
  • Intent: In/Out
  • Type: Integer scalar
  • Values:

    0	$\Longrightarrow$	unspecified (black-box)
    1	$\Longrightarrow$	standard conjugate gradients (CG)
    2	$\Longrightarrow$	transpose-free quasi-minimal residuals method (TFQMR)
    3	$\Longrightarrow$	generalized minimal residual (GMRES)

  In black-box mode, the following sequence is taken:
  • TFQMR is first attempted. If it breaks down, fails to converge, or converges falsely,
  • GMRES is attempted with a subspace size of either the default value, 20, or the user-set value, using the final iterate obtained from the previous attempt. If it fails to converge,
  • GMRES is attempted with twice the subspace size, using the final iterate from the previous attempt. In addition, m-step SSOR preconditioning is turned applied if no preconditioning had been used in previous attempts. If m-step Jacobi or SSOR preconditioning had been used, then the number of steps is doubled. If it again fails to converge,
  • GMRES is attempted with twice again the subspace size, using the final iterate from the previous attempt. If m-step Jacobi or SSOR preconditioning had been used, then the number of steps is doubled once again. If it again fails to converge, the routine exits with an appropriate return status.