[prev] [prev-tail] [tail] [up]

### 10 Preconditioner routines

The base PSBLAS library contains the implementation of some simple preconditioning techniques:

- Diagonal Scaling

- Block Jacobi with ILU(0) factorization

- Block Jacobi with an approximate inverse

The supporting data type and subroutine interfaces are defined in the module psb_prec_mod. The old interfaces psb_precinit and psb_precbld are still supported for backward compatibility

#### 10.1 init — Initialize a preconditioner

    call prec%init(icontxt,ptype, info)

Type:

  Asynchronous.

On Entry

icontxt

  the communication context.
  Scope:global.
  Type:required.
  Intent: in.
  Specified as: an integer value.

ptype

  the type of preconditioner. Scope: global
  Type: required
  Intent: in.
  Specified as: a character string, see usage notes.

On Exit

prec

  Scope: local
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

info

  Scope: global
  Type: required
  Intent: out.
  Error code: if no error, 0 is returned.

Notes Legal inputs to this subroutine are interpreted depending on the ptype string as follows4 :

NONE

  No preconditioning, i.e. the preconditioner is just a copy operator.

DIAG

  Diagonal scaling; each entry of the input vector is multiplied by the reciprocal of the sum of the absolute values of the coefficients in the corresponding row of matrix A;

BJAC

  Precondition by a factorization or an approximante inverse of the block-diagonal of matrix A, where block boundaries are determined by the data allocation boundaries for each process; requires no communication. See also Table-21.

#### 10.2 Set — set preconditioner parameters

`call p%set(what,val,info)`

This method sets the parameters defining the subdomain solver when the preconditioner type is BJAC. More precisely, the parameter identified by `what` is assigned the value contained in `val`.

Arguments

`what` | `character(len=*)`.
| The parameter to be set. It can be specified through its name; the string is case-insensitive. See Table 21.
`val` | `integer` or `character(len=*)` or `real(psb_spk_)` or `real(psb_dpk_)`, `intent(in)`.
| The value of the parameter to be set. The list of allowed values and the corresponding data types is given in Table 21. When the value is of type `character(len=*)`, it is also treated as case insensitive.
`info` | `integer, intent(out)`.
| Error code. If no error, 0 is returned. See Section 8 for details.

A number of subdomain solvers can be chosen with this method; a list of the parameters that can be set, along with their allowed and default values, is given in Table-21.

`what` | d a t a t y p e | `val` | d e f a u l t | c o m m e n t s
`’SUB_SOLVE’` | `character(len=*)` | `’ILU’` `’ILUT’` `’INVT’` `’INVK’` `’AINV’` |  | The local solver to be used with the smoother or one-level preconditioner ILU(p), ILU(p, t), Approximate Inverses INVK(p, q), INVT(p1, p 2, t1, t2) and AINV(t); note that approximate inverses are specifically suited for GPUs since they do not employ triangular system solve kernels, see [2].
`’SUB_FILLIN’` | `integer` | Any integer number ≥ 0 | 0 | Fill-in level p of the incomplete LU factorizations.
`’SUB_ILUTHRS’` | `real(kind_parameter)` | Any real number ≥ 0 | 0 | Drop tolerance t in the ILU(p, t) factorization.
`’ILU_ALG’` | `character(len=*)` | `’MILU’` | `’NONE’` | ILU algorithmic variant
`’ILUT_SCALE’` | `character(len=*)` | `’MAXVAL’` `’DIAG’` `’ARSWUM’` `’ARCSUM’` `’ACLSUM’` `’NONE’` | `’NONE’` | ILU scaling strategy
`’INV_FILLIN’` | `integer` | Any integer number ≥ 0 | 0 | Second fill-in level q of the INVK(p, q) approximate inverse.
`’INV_ILUTHRS’` | `real(kind_parameter)` | Any real number ≥ 0 | 0 | Second drop tolerance s in the INVT(t, s) approximate inverse.
`’AINV_ALG’` | `character(len=*)` | `’LLK’` `’SYM-LLK’` `’STAB-LLK’` `’MLK,LMX’` | `’LLK’` | AINV algorithmic strategy.

Table 21: Parameters defining the solver of the BJAC preconditioner.

#### 10.3 build — Builds a preconditioner

    call prec%build(a, desc_a, info[,amold,vmold,imold])

Type:

  Synchronous.

On Entry

a

  the system sparse matrix. Scope: local
  Type: required
  Intent: in, target.
  Specified as: a sparse matrix data structure psb_Tspmat_type.

prec

  the preconditioner.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: an already initialized precondtioner data structure psb_Tprec_type

desc_a

  the problem communication descriptor. Scope: local
  Type: required
  Intent: in, target.
  Specified as: a communication descriptor data structure psb_desc_type.

amold

  The desired dynamic type for the internal matrix storage.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an object of a class derived from psb_T_base_sparse_mat.

vmold

  The desired dynamic type for the internal vector storage.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an object of a class derived from psb_T_base_vect_type.

imold

  The desired dynamic type for the internal integer vector storage.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an object of a class derived from (integer) psb_T_base_vect_type.

On Return

prec

  the preconditioner.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: a precondtioner data structure psb_Tprec_type

info

  Error code.
  Scope: local
  Type: required
  Intent: out.
  An integer value; 0 means no error has been detected.

The amold, vmold and imold arguments may be employed to interface with special devices, such as GPUs and other accelerators.

#### 10.4 apply — Preconditioner application routine

    call prec%apply(x,y,desc_a,info,trans,work)
    call prec%apply(x,desc_a,info,trans)

Type:

  Synchronous.

On Entry

prec

  the preconditioner. Scope: local
  Type: required
  Intent: in.
  Specified as: a preconditioner data structure psb_Tprec_type.

x

  the source vector. Scope: local
  Type: required
  Intent: inout.
  Specified as: a rank one array or an object of type psb_T_vect_type.

desc_a

  the problem communication descriptor. Scope: local
  Type: required
  Intent: in.
  Specified as: a communication data structure psb_desc_type.

trans

  Scope:
  Type: optional
  Intent: in.
  Specified as: a character.

work

  an optional work space Scope: local
  Type: optional
  Intent: inout.
  Specified as: a double precision array.

On Return

y

  the destination vector. Scope: local
  Type: required
  Intent: inout.
  Specified as: a rank one array or an object of type psb_T_vect_type.

info

  Error code.
  Scope: local
  Type: required
  Intent: out.
  An integer value; 0 means no error has been detected.

Notes This method is almost always called by the iterative methods of Sec. 11, and practically never directly by the user.

#### 10.5 descr — Prints a description of current preconditioner

    call prec%descr(info)
    call prec%descr(info,iout, root)

Type:

  Asynchronous.

On Entry

prec

  the preconditioner. Scope: local
  Type: required
  Intent: in.
  Specified as: a preconditioner data structure psb_Tprec_type.

iout

  output unit. Scope: local
  Type: optional
  Intent: in.
  Specified as: an integer number. Default: default output unit.

root

  Process from which to print Scope: local
  Type: optional
  Intent: in.
  Specified as: an integer number between 0 and np- 1, in which case the specified process will print the description, or -1, in which case all processes will print. Default: 0.

On Return

info

  Error code.
  Scope: local
  Type: required
  Intent: out.
  An integer value; 0 means no error has been detected.

#### 10.6 clone — clone current preconditioner

    call  prec%clone(precout,info)

Type:

  Asynchronous.

On Entry

prec

  the preconditioner.
  Scope: local.

On Return

precout

  A copy of the input object.

info

  Return code.

#### 10.7 free — Free a preconditioner

    call prec%free(info)

Type:

  Asynchronous.

On Entry

prec

  the preconditioner.
  Scope: local.
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

On Exit

prec

  Scope: local
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

info

  Scope: global
  Type: required
  Intent: out.
  Error code: if no error, 0 is returned.

Notes Releases all internal storage.

#### 10.8 allocate_wrk — preconditioner

    call prec%allocate_wrk(info[,vmold])

Type:

  Synchronous.

On Entry

prec

  the preconditioner.
  Scope: local.
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

vmold

  The desired dynamic type for the internal vector storage.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an object of a class derived from psb_T_base_vect_type.

On Exit

prec

  Scope: local
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

info

  Scope: global
  Type: required
  Intent: out.
  Error code: if no error, 0 is returned.

Notes Preconditioners often need internal work storage during their application at each iteration of a linear solver method: in many situations this can be accomplished by allocating and releasing memory “on the fly”. However, when running on an accelerator through e.g. the CUDA enabled data strutures of Sec. 12.4 and 13, memory allocation and deallocation usually have a much larger overhead, significantly affecting performance. To alleviate this problem we define this method that preallocates internal storage; it is intended to be invoked prior to the iterative solver method, so that the necessary internal work storage is available throughout the iterative method application.

When using GPUs or other specialized devices, the `vmold` argument is also necessary to ensure the internal work vectors are of the appropriate dynamic type to exploit the accelerator hardware.

#### 10.9 deallocate_wrk — preconditioner

    call prec%allocate_wrk(info)
    call prec%free_wrk(info)

Type:

  Synchronous.

On Entry

prec

  the preconditioner.
  Scope: local.
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

On Exit

prec

  Scope: local
  Type: required
  Intent: inout.
  Specified as: a preconditioner data structure psb_Tprec_type.

info

  Scope: global
  Type: required
  Intent: out.
  Error code: if no error, 0 is returned.

Notes Deallocates preconditioner internal work storage; to be invoked after an iterative solver has completed execution, see the discussion in Sec. 10.8.

[prev] [prev-tail] [front] [up]