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

### 6 Data management routines

#### 6.1 psb_cdall — Allocates a communication descriptor

    call psb_cdall(icontxt, desc_a, info,mg=mg,parts=parts)
    call psb_cdall(icontxt, desc_a, info,vg=vg,[mg=mg,flag=flag])
    call psb_cdall(icontxt, desc_a, info,vl=vl,[nl=nl,globalcheck=.false.,lidx=lidx])
    call psb_cdall(icontxt, desc_a, info,nl=nl)
    call psb_cdall(icontxt, desc_a, info,mg=mg,repl=.true.)

This subroutine initializes the communication descriptor associated with an index space. One of the optional arguments parts, vg, vl, nl or repl must be specified, thereby choosing the specific initialization strategy.

On Entry

Type:

  Synchronous.

icontxt

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

vg

  Data allocation: each index i ∈{1…mg} is allocated to process vg(i).
  Scope:global.
  Type:optional.
  Intent: in.
  Specified as: an integer array.

flag

  Specifies whether entries in vg are zero- or one-based.
  Scope:global.
  Type:optional.
  Intent: in.
  Specified as: an integer value 0,1, default 0.

mg

  the (global) number of rows of the problem.
  Scope:global.
  Type:optional.
  Intent: in.
  Specified as: an integer value. It is required if parts or repl is specified, it is optional if vg is specified.

parts

  the subroutine that defines the partitioning scheme.
  Scope:global.
  Type:required.
  Specified as: a subroutine.

vl

  Data allocation: the set of global indices vl(1 : nl) belonging to the calling process.
  Scope:local.
  Type:optional.
  Intent: in.
  Specified as: an integer array.

nl

  Data allocation: in a generalized block-row distribution the number of indices belonging to the current process.
  Scope:local.
  Type:optional.
  Intent: in.
  Specified as: an integer value. May be specified together with vl.

repl

  Data allocation: build a replicated index space (i.e. all processes own all indices).
  Scope:global.
  Type:optional.
  Intent: in.
  Specified as: the logical value .true.

globalcheck

  Data allocation: do global checks on the local index lists vl
  Scope:global.
  Type:optional.
  Intent: in.
  Specified as: a logical value, default: .false.

lidx

  Data allocation: the set of local indices lidx(1 : nl) to be assigned to the global indices vl.
  Scope:local.
  Type:optional.
  Intent: in.
  Specified as: an integer array.

On Return

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: out.
  Specified as: a structured data of type psb_desc_type.

info

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

Notes

1. One of the optional arguments parts, vg, vl, nl or repl must be specified, thereby choosing the initialization strategy as follows:

   parts

     In this case we have a subroutine specifying the mapping between global indices and process/local index pairs. If this optional argument is specified, then it is mandatory to specify the argument mg as well. The subroutine must conform to the following interface:

                    interface
                       subroutine psb_parts(glob_index,mg,np,pv,nv)
                         integer, intent (in)  :: glob_index,np,mg
                         integer, intent (out) :: nv, pv(*)
                       end subroutine psb_parts
                    end interface

     The input arguments are:

     glob_index

       The global index to be mapped;

     np

       The number of processes in the mapping;

     mg

       The total number of global rows in the mapping;

     The output arguments are:

     nv

       The number of entries in pv;

     pv

       A vector containing the indices of the processes to which the global index should be assigend; each entry must satisfy 0 ≤ pv(i) < np; if nv > 1 we have an index assigned to multiple processes, i.e. we have an overlap among the subdomains.

   vg

     In this case the association between an index and a process is specified via an integer vector vg(1:mg); each index i ∈{1…mg} is assigned to process vg(i). The vector vg must be identical on all calling processes; its entries may have the ranges (0…np - 1) or (1…np) according to the value of flag. The size mg may be specified via the optional argument mg; the default is to use the entire vector vg, thus having mg=size(vg).

   vl

     In this case we are specifying the list of indices vl(1:nl) assigned to the current process; thus, the global problem size mg is given by the range of the aggregate of the individual vectors vl specified in the calling processes. The size may be specified via the optional argument nl; the default is to use the entire vector vl, thus having nl=size(vl). If globalcheck=.true. the subroutine will check how many times each entry in the global index space (1…mg) is specified in the input lists vl, thus allowing for the presence of overlap in the input, and checking for “orphan” indices. If globalcheck=.false., the subroutine will not check for overlap, and may be significantly faster, but the user is implicitly guaranteeing that there are neither orphan nor overlap indices.

   lidx

     The optional argument lidx is available for those cases in which the user has already established a global-to-local mapping; if it is specified, each index in vl(i) will be mapped to the corresponding local index lidx(i). When specifying the argument lidx the user would also likely employ lidx in calls to psb_cdins and local in calls to psb_spins and psb_geins; see also sec. 2.3.1.

   nl

     If this argument is specified alone (i.e. without vl) the result is a generalized row-block distribution in which each process I gets assigned a consecutive chunk of NI = nl global indices.

   repl

     This arguments specifies to replicate all indices on all processes. This is a special purpose data allocation that is useful in the construction of some multilevel preconditioners.

2. On exit from this routine the descriptor is in the build state.

3. Calling the routine with vg or parts implies that every process will scan the entire index space to figure out the local indices.

4. Overlapped indices are possible with both parts and vl invocations.

5. When the subroutine is invoked with vl in conjunction with globalcheck=.true., it will perform a scan of the index space to search for overlap or orphan indices.

6. When the subroutine is invoked with vl in conjunction with globalcheck=.false., no index space scan will take place. Thus it is the responsibility of the user to make sure that the indices specified in vl have neither orphans nor overlaps; if this assumption fails, results will be unpredictable.

7. Orphan and overlap indices are impossible by construction when the subroutine is invoked with nl (alone), or vg.

#### 6.2 psb_cdins — Communication descriptor insert routine

    call psb_cdins(nz, ia, ja, desc_a, info [,ila,jla])
    call psb_cdins(nz,ja,desc,info[,jla,mask,lidx])

This subroutine examines the edges of the graph associated with the discretization mesh (and isomorphic to the sparsity pattern of a linear system coefficient matrix), storing them as necessary into the communication descriptor. In the first form the edges are specified as pairs of indices ia(i),ja(i); the starting index ia(i) should belong to the current process. In the second form only the remote indices ja(i) are specified.

Type:

  Asynchronous.

On Entry

nz

  the number of points being inserted.
  Scope: local.
  Type: required.
  Intent: in.
  Specified as: an integer value.

ia

  the indices of the starting vertex of the edges being inserted.
  Scope: local.
  Type: required.
  Intent: in.
  Specified as: an integer array of length nz.

ja

  the indices of the end vertex of the edges being inserted.
  Scope: local.
  Type: required.
  Intent: in.
  Specified as: an integer array of length nz.

mask

  Mask entries in ja, they are inserted only when the corresponding mask entries are .true.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: a logical array of length nz, default .true..

lidx

  User defined local indices for ja.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an integer array of length nz.

On Return

desc_a

  the updated communication descriptor.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a structured data of type psb_desc_type.

info

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

ila

  the local indices of the starting vertex of the edges being inserted.
  Scope: local.
  Type: optional.
  Intent: out.
  Specified as: an integer array of length nz.

jla

  the local indices of the end vertex of the edges being inserted.
  Scope: local.
  Type: optional.
  Intent: out.
  Specified as: an integer array of length nz.

Notes

1. This routine may only be called if the descriptor is in the build state;

2. This routine automatically ignores edges that do not insist on the current process, i.e. edges for which neither the starting nor the end vertex belong to the current process.

3. The second form of this routine will be useful when dealing with user-specified index mappings; see also 2.3.1.

#### 6.3 psb_cdasb — Communication descriptor assembly routine

    call psb_cdasb(desc_a, info [, mold])

Type:

  Synchronous.

On Entry

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a structured data of type psb_desc_type.

mold

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

On Return

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a structured data of type psb_desc_type.

info

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

Notes

1. On exit from this routine the descriptor is in the assembled state.

This call will set up all the necessary information for the halo data exchanges. In doing so, the library will need to identify the set of processes owning the halo indices through the use of the desc%fnd_owner() method; the owning processes are the topological neighbours of the calling process. If the user has some background information on the processes that are neighbours of the current one, it is possible to specify explicitly the list of adjacent processes with a call to desc%set_p_adjcncy(list); this will speed up the subsequent call to psb_cdasb.

#### 6.4 psb_cdcpy — Copies a communication descriptor

    call psb_cdcpy(desc_in, desc_out, info)

Type:

  Asynchronous.

On Entry

desc_in

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

desc_out

  the communication descriptor copy.
  Scope:local.
  Type:required.
  Intent: out.
  Specified as: a structured data of type psb_desc_type.

info

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

#### 6.5 psb_cdfree — Frees a communication descriptor

    call psb_cdfree(desc_a, info)

Type:

  Synchronous.

On Entry

desc_a

  the communication descriptor to be freed.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a structured data of type psb_desc_type.

On Return

info

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

#### 6.6 psb_cdbldext — Build an extended communication descriptor

    call psb_cdbldext(a,desc_a,nl,desc_out, info, extype)

This subroutine builds an extended communication descriptor, based on the input descriptor desc_a and on the stencil specified through the input sparse matrix a.

Type:

  Synchronous.

On Entry

a

  A sparse matrix Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data type.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_Tspmat_type.

nl

  the number of additional layers desired.
  Scope:global.
  Type:required.
  Intent: in.
  Specified as: an integer value nl ≥ 0.

extype

  the kind of estension required.
  Scope:global.
  Type:optional .
  Intent: in.
  Specified as: an integer value psb_ovt_xhal_, psb_ovt_asov_, default: psb_ovt_xhal_

On Return

desc_out

  the extended communication descriptor.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a structured data of type psb_desc_type.

info

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

Notes

1. Specifying psb_ovt_xhal_ for the extype argument the user will obtain a descriptor for a domain partition in which the additional layers are fetched as part of an (extended) halo; however the index-to-process mapping is identical to that of the base descriptor;

2. Specifying psb_ovt_asov_ for the extype argument the user will obtain a descriptor with an overlapped decomposition: the additional layer is aggregated to the local subdomain (and thus is an overlap), and a new halo extending beyond the last additional layer is formed.

#### 6.7 psb_spall — Allocates a sparse matrix

    call psb_spall(a, desc_a, info [, nnz, dupl, bldmode])

Type:

  Synchronous.

On Entry

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

nnz

  An estimate of the number of nonzeroes in the local part of the assembled matrix.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: an integer value.

dupl

  How to handle duplicate coefficients.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: integer, possible values: psb_dupl_ovwrt_, psb_dupl_add_, psb_dupl_err_.

bldmode

  Whether to keep track of matrix entries that do not belong to the current process.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: an integer value psb_matbld_noremote_, psb_matbld_remote_. Default: psb_matbld_noremote_.

On Return

a

  the matrix to be allocated.
  Scope:local
  Type:required
  Intent: out.
  Specified as: a structured data of type psb_Tspmat_type.

info

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

Notes

1. On exit from this routine the sparse matrix is in the build state.

2. The descriptor may be in either the build or assembled state.

3. Providing a good estimate for the number of nonzeroes nnz in the assembled matrix may substantially improve performance in the matrix build phase, as it will reduce or eliminate the need for (potentially multiple) data reallocations;

4. Using psb_matbld_remote_ is likely to cause a runtime overhead at assembly time;

#### 6.8 psb_spins — Insert a set of coefficients into a sparse matrix

    call psb_spins(nz, ia, ja, val, a, desc_a, info [,local])
    call psb_spins(nr, irw, irp, ja, val, a, desc_a, info [,local])

Type:

  Asynchronous.

On Entry

nz

  the number of coefficients to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer scalar.

nr

  the number of rows to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer scalar.

irw

  the first row to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer scalar.

ia

  the row indices of the coefficients to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer array of size nz.

irp

  the row pointers of the coefficients to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer array of size nr + 1.

ja

  the column indices of the coefficients to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer array of size nz.

val

  the coefficients to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an array of size nz. Must be of the same type and kind of the coefficients of the sparse matrix a.

desc_a

  The communication descriptor.
  Scope: local.
  Type: required.
  Intent: inout.
  Specified as: a variable of type psb_desc_type.

local

  Whether the entries in the indices vectors ia, ja are already in local numbering.
  Scope:local.
  Type:optional.
  Specified as: a logical value; default: .false..

On Return

a

  the matrix into which coefficients will be inserted.
  Scope:local
  Type:required
  Intent: inout.
  Specified as: a structured data of type psb_Tspmat_type.

desc_a

  The communication descriptor.
  Scope: local.
  Type: required.
  Intent: inout.
  Specified as: a variable of type psb_desc_type.

info

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

Notes

1. On entry to this routine the descriptor may be in either the build or assembled state.

2. On entry to this routine the sparse matrix may be in either the build or update state.

3. If the descriptor is in the build state, then the sparse matrix must also be in the build state; the action of the routine is to (implicitly) call psb_cdins to add entries to the sparsity pattern; each sparse matrix entry implicitly defines a graph edge, that is passed to the descriptor routine for the appropriate processing;

4. The input data can be passed in either COO or CSR formats;

5. In COO format the coefficients to be inserted are represented by the ordered triples ia(i),ja(i),val(i), for i = 1,…,nz; these triples are arbitrary;

6. In CSR format the coefficients to be inserted for each input row i = 1,nr are represented by the ordered triples (i + irw - 1),ja(j),val(j), for j = irp(i),…,irp(i + 1) - 1; these triples should belong to the current process, i.e. i+irw-1 should be one of the local indices, but are otherwise arbitrary;

7. There is no requirement that a given row must be passed in its entirety to a single call to this routine: the buildup of a row may be split into as many calls as desired (even in the CSR format);

8. Coefficients from different rows may also be mixed up freely in a single call, according to the application needs;

9. Coefficients from matrix rows not owned by the calling process are treated according to the value of bldmode specified at allocation time; if bldmode was chosen as psb_matbld_remote_ the library will keep track of them, otherwise they are silently ignored;

10. If the descriptor is in the assembled state, then any entries in the sparse matrix that would generate additional communication requirements are ignored;

11. If the matrix is in the update state, any entries in positions that were not present in the original matrix are ignored.

#### 6.9 psb_spasb — Sparse matrix assembly routine

    call psb_spasb(a, desc_a, info [, afmt, upd,  mold])

Type:

  Synchronous.

On Entry

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in/out.
  Specified as: a structured data of type psb_desc_type.

afmt

  the storage format for the sparse matrix.
  Scope: local.
  Type: optional.
  Intent: in.
  Specified as: an array of characters. Defalt: ’CSR’.

upd

  Provide for updates to the matrix coefficients.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: integer, possible values: psb_upd_srch_, psb_upd_perm_

mold

  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.

On Return

a

  the matrix to be assembled.
  Scope:local
  Type:required
  Intent: inout.
  Specified as: a structured data of type psb_Tspmat_type.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in/out.
  Specified as: a structured data of type psb_desc_type. If the matrix was allocated with bldmode=psb_matbld_remote_, then the descriptor will be reassembled.

info

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

Notes

1. On entry to this routine the descriptor must be in the assembled state, i.e. psb_cdasb must already have been called.

2. The sparse matrix may be in either the build or update state;

3. Duplicate entries are detected and handled in both build and update state, with the exception of the error action that is only taken in the build state, i.e. on the first assembly;

4. If the update choice is psb_upd_perm_, then subsequent calls to psb_spins to update the matrix must be arranged in such a way as to produce exactly the same sequence of coefficient values as encountered at the first assembly;

5. The output storage format need not be the same on all processes;

6. On exit from this routine the matrix is in the assembled state, and thus is suitable for the computational routines;

7. If the bldmode=psb_matbld_remote_ value was specified at allocation time, contributions defined on the current process but belonging to a remote process will be handled accordingly. This is most likely to occur in finite element applications, with dupl=psb_dupl_add_; it is necessary to check for possible updates needed in the descriptor, hence there will be a runtime overhead.

#### 6.10 psb_spfree — Frees a sparse matrix

    call psb_spfree(a, desc_a, info)

Type:

  Synchronous.

On Entry

a

  the matrix to be freed.
  Scope:local
  Type:required
  Intent: inout.
  Specified as: a structured data of type psb_Tspmat_type.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

info

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

#### 6.11 psb_sprn — Reinit sparse matrix structure for psblas routines.

    call psb_sprn(a, decsc_a, info, clear)

Type:

  Synchronous.

On Entry

a

  the matrix to be reinitialized.
  Scope:local
  Type:required
  Intent: inout.
  Specified as: a structured data of type psb_Tspmat_type.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

clear

  Choose whether to zero out matrix coefficients
  Scope:local.
  Type:optional.
  Intent: in.
  Default: true.

On Return

info

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

Notes

1. On exit from this routine the sparse matrix is in the update state.

#### 6.12 psb_geall — Allocates a dense matrix

    call psb_geall(x, desc_a, info[, dupl, bldmode, n, lb])

Type:

  Synchronous.

On Entry

desc_a

  The communication descriptor.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a variable of type psb_desc_type.

n

  The number of columns of the dense matrix to be allocated.
  Scope: local
  Type: optional
  Intent: in.
  Specified as: Integer scalar, default 1. It is not a valid argument if x is a rank-1 array.

lb

  The lower bound for the column index range of the dense matrix to be allocated.
  Scope: local
  Type: optional
  Intent: in.
  Specified as: Integer scalar, default 1. It is not a valid argument if x is a rank-1 array.

dupl

  How to handle duplicate coefficients.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: integer, possible values: psb_dupl_ovwrt_, psb_dupl_add_; psb_dupl_err_ has no effect.

bldmode

  Whether to keep track of matrix entries that do not belong to the current process.
  Scope: global.
  Type: optional.
  Intent: in.
  Specified as: an integer value psb_matbld_noremote_, psb_matbld_remote_. Default: psb_matbld_noremote_.

On Return

x

  The dense matrix to be allocated.
  Scope: local
  Type: required
  Intent: out.
  Specified as: a rank one or two array with the ALLOCATABLE attribute or an object of type psb_T_vect_type, of type real, complex or integer.

info

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

Notes

1. Using psb_matbld_remote_ is likely to cause a runtime overhead at assembly time;

#### 6.13 psb_geins — Dense matrix insertion routine

    call psb_geins(m, irw, val, x, desc_a, info [,local])

Type:

  Asynchronous.

On Entry

m

  Number of rows in val to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer value.

irw

  Indices of the rows to be inserted. Specifically, row i of val will be inserted into the local row corresponding to the global row index irw(i). Scope:local.
  Type:required.
  Intent: in.
  Specified as: an integer array.

val

  the dense submatrix to be inserted.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a rank 1 or 2 array. Specified as: an integer value.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

local

  Whether the entries in the index vector irw, are already in local numbering.
  Scope:local.
  Type:optional.
  Specified as: a logical value; default: .false..

On Return

x

  the output dense matrix.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: a rank one or two array or an object of type psb_T_vect_type, of type real, complex or integer.

info

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

Notes

1. Dense vectors/matrices do not have an associated state;

2. Duplicate entries are either overwritten or added, there is no provision for raising an error condition.

#### 6.14 psb_geasb — Assembly a dense matrix

    call psb_geasb(x, desc_a, info, mold)

Type:

  Synchronous.

On Entry

desc_a

  The communication descriptor.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a variable of type psb_desc_type.

mold

  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; this is only allowed when x is of type psb_T_vect_type.

On Return

x

  The dense matrix to be assembled.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: a rank one or two array with the ALLOCATABLE or an object of type psb_T_vect_type, of type real, complex or integer.

info

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

Notes

1. On entry to this routine the descriptor must be in the assembled state, i.e. psb_cdasb must already have been called.

2. If the bldmode=psb_matbld_remote_ value was specified at allocation time, contributions defined on the current process but belonging to a remote process will be handled accordingly. This is most likely to occur in finite element applications, with dupl=psb_dupl_add_.

#### 6.15 psb_gefree — Frees a dense matrix

    call psb_gefree(x, desc_a, info)

Type:

  Synchronous.

On Entry

x

  The dense matrix to be freed.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: a rank one or two array with the ALLOCATABLE or an object of type psb_T_vect_type, of type real, complex or integer.

desc_a

  The communication descriptor.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a variable of type psb_desc_type.

On Return

info

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

#### 6.16 psb_gelp — Applies a left permutation to a dense matrix

    call psb_gelp(trans, iperm, x, info)

Type:

  Asynchronous.

On Entry

trans

  A character that specifies whether to permute A or AT.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a single character with value ’N’ for A or ’T’ for AT.

iperm

  An integer array containing permutation information.
  Scope: local
  Type: required
  Intent: in.
  Specified as: an integer one-dimensional array.

x

  The dense matrix to be permuted.
  Scope: local
  Type: required
  Intent: inout.
  Specified as: a one or two dimensional array.

On Return

info

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

#### 6.17 psb_glob_to_loc — Global to local indices convertion

    call psb_glob_to_loc(x, y, desc_a, info, iact,owned)
    call psb_glob_to_loc(x, desc_a, info, iact,owned)

Type:

  Asynchronous.

On Entry

x

  An integer vector of indices to be converted.
  Scope: local
  Type: required
  Intent: in, inout.
  Specified as: a rank one integer array.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

iact

  specifies action to be taken in case of range errors. Scope: global
  Type: optional
  Intent: in.
  Specified as: a character variable Ignore, Warning or Abort, default Ignore.

owned

  Specfies valid range of input Scope: global
  Type: optional
  Intent: in.
  If true, then only indices strictly owned by the current process are considered valid, if false then halo indices are also accepted. Default: false.

On Return

x

  If y is not present, then x is overwritten with the translated integer indices. Scope: global
  Type: required
  Intent: inout.
  Specified as: a rank one integer array.

y

  If y is present, then y is overwritten with the translated integer indices, and x is left unchanged. Scope: global
  Type: optional
  Intent: out.
  Specified as: a rank one integer array.

info

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

Notes

1. If an input index is out of range, then the corresponding output index is set to a negative number;

2. The default Ignore means that the negative output is the only action taken on an out-of-range input.

#### 6.18 psb_loc_to_glob — Local to global indices conversion

    call psb_loc_to_glob(x, y, desc_a, info, iact)
    call psb_loc_to_glob(x, desc_a, info, iact)

Type:

  Asynchronous.

On Entry

x

  An integer vector of indices to be converted.
  Scope: local
  Type: required
  Intent: in, inout.
  Specified as: a rank one integer array.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

iact

  specifies action to be taken in case of range errors. Scope: global
  Type: optional
  Intent: in.
  Specified as: a character variable Ignore, Warning or Abort, default Ignore.

On Return

x

  If y is not present, then x is overwritten with the translated integer indices. Scope: global
  Type: required
  Intent: inout.
  Specified as: a rank one integer array.

y

  If y is not present, then y is overwritten with the translated integer indices, and x is left unchanged. Scope: global
  Type: optional
  Intent: out.
  Specified as: a rank one integer array.

info

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

#### 6.19 psb_is_owned —

    call psb_is_owned(x, desc_a)

Type:

  Asynchronous.

On Entry

x

  Integer index.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a scalar integer.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

Function value

  A logical mask which is true if x is owned by the current process Scope: local
  Type: required
  Intent: out.

Notes

1. This routine returns a .true. value for an index that is strictly owned by the current process, excluding the halo indices

#### 6.20 psb_owned_index —

    call psb_owned_index(y, x, desc_a, info)

Type:

  Asynchronous.

On Entry

x

  Integer indices.
  Scope: local
  Type: required
  Intent: in, inout.
  Specified as: a scalar or a rank one integer array.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

iact

  specifies action to be taken in case of range errors. Scope: global
  Type: optional
  Intent: in.
  Specified as: a character variable Ignore, Warning or Abort, default Ignore.

On Return

y

  A logical mask which is true for all corresponding entries of x that are owned by the current process Scope: local
  Type: required
  Intent: out.
  Specified as: a scalar or rank one logical array.

info

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

Notes

1. This routine returns a .true. value for those indices that are strictly owned by the current process, excluding the halo indices

#### 6.21 psb_is_local —

    call psb_is_local(x, desc_a)

Type:

  Asynchronous.

On Entry

x

  Integer index.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a scalar integer.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

Function value

  A logical mask which is true if x is local to the current process Scope: local
  Type: required
  Intent: out.

Notes

1. This routine returns a .true. value for an index that is local to the current process, including the halo indices

#### 6.22 psb_local_index —

    call psb_local_index(y, x, desc_a, info)

Type:

  Asynchronous.

On Entry

x

  Integer indices.
  Scope: local
  Type: required
  Intent: in, inout.
  Specified as: a scalar or a rank one integer array.

desc_a

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

iact

  specifies action to be taken in case of range errors. Scope: global
  Type: optional
  Intent: in.
  Specified as: a character variable Ignore, Warning or Abort, default Ignore.

On Return

y

  A logical mask which is true for all corresponding entries of x that are local to the current process Scope: local
  Type: required
  Intent: out.
  Specified as: a scalar or rank one logical array.

info

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

Notes

1. This routine returns a .true. value for those indices that are local to the current process, including the halo indices.

#### 6.23 psb_get_boundary — Extract list of boundary elements

    call psb_get_boundary(bndel, desc, info)

Type:

  Asynchronous.

On Entry

desc

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

bndel

  The list of boundary elements on the calling process, in local numbering.
  Scope: local
  Type: required
  Intent: out.
  Specified as: a rank one array with the ALLOCATABLE attribute, of type integer.

info

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

Notes

1. If there are no boundary elements (i.e., if the local part of the connectivity graph is self-contained) the output vector is set to the “not allocated” state.

2. Otherwise the size of bndel will be exactly equal to the number of boundary elements.

#### 6.24 psb_get_overlap — Extract list of overlap elements

    call psb_get_overlap(ovrel, desc, info)

Type:

  Asynchronous.

On Entry

desc

  the communication descriptor.
  Scope:local.
  Type:required.
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

On Return

ovrel

  The list of overlap elements on the calling process, in local numbering.
  Scope: local
  Type: required
  Intent: out.
  Specified as: a rank one array with the ALLOCATABLE attribute, of type integer.

info

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

Notes

1. If there are no overlap elements the output vector is set to the “not allocated” state.

2. Otherwise the size of ovrel will be exactly equal to the number of overlap elements.

#### 6.25 psb_sp_getrow — Extract row(s) from a sparse matrix

    call psb_sp_getrow(row, a, nz, ia, ja, val, info, &
                  & append, nzin, lrw)

Type:

  Asynchronous.

On Entry

row

  The (first) row to be extracted.
  Scope:local
  Type:required
  Intent: in.
  Specified as: an integer > 0.

a

  the matrix from which to get rows.
  Scope:local
  Type:required
  Intent: in.
  Specified as: a structured data of type psb_Tspmat_type.

append

  Whether to append or overwrite existing output.
  Scope:local
  Type:optional
  Intent: in.
  Specified as: a logical value default: false (overwrite).

nzin

  Input size to be appended to.
  Scope:local
  Type:optional
  Intent: in.
  Specified as: an integer > 0. When append is true, specifies how many entries in the output vectors are already filled.

lrw

  The last row to be extracted.
  Scope:local
  Type:optional
  Intent: in.
  Specified as: an integer > 0, default: row.

On Return

nz

  the number of elements returned by this call.
  Scope:local.
  Type:required.
  Intent: out.
  Returned as: an integer scalar.

ia

  the row indices.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: an integer array with the ALLOCATABLE attribute.

ja

  the column indices of the elements to be inserted.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: an integer array with the ALLOCATABLE attribute.

val

  the elements to be inserted.
  Scope:local.
  Type:required.
  Intent: inout.
  Specified as: a real array with the ALLOCATABLE attribute.

info

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

Notes

1. The output nz is always the size of the output generated by the current call; thus, if append=.true., the total output size will be nzin + nz, with the newly extracted coefficients stored in entries nzin+1:nzin+nz of the array arguments;

2. When append=.true. the output arrays are reallocated as necessary;

3. The row and column indices are returned in the local numbering scheme; if the global numbering is desired, the user may employ the psb_loc_to_glob routine on the output.

#### 6.26 psb_sizeof — Memory occupation

This function computes the memory occupation of a PSBLAS object.

    isz = psb_sizeof(a)
    isz = psb_sizeof(desc_a)
    isz = psb_sizeof(prec)

Type:

  Asynchronous.

On Entry

a

  A sparse matrix A.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a structured data of type psb_Tspmat_type.

desc_a

  Communication descriptor.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a structured data of type psb_desc_type.

prec

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

On Return

Function value

  The memory occupation of the object specified in the calling sequence, in bytes.
  Scope: local
  Returned as: an integer(psb_long_int_k_) number.

#### 6.27 Sorting utilities —

psb_msort — Sorting by the Merge-sort algorithm

psb_qsort — Sorting by the Quicksort algorithm

psb_hsort — Sorting by the Heapsort algorithm

    call psb_msort(x,ix,dir,flag)
    call psb_qsort(x,ix,dir,flag)
    call psb_hsort(x,ix,dir,flag)

These serial routines sort a sequence X into ascending or descending order. The argument meaning is identical for the three calls; the only difference is the algorithm used to accomplish the task (see Usage Notes below).

Type:

  Asynchronous.

On Entry

x

  The sequence to be sorted.
  Type:required.
  Specified as: an integer, real or complex array of rank 1.

ix

  A vector of indices.
  Type:optional.
  Specified as: an integer array of (at least) the same size as X.

dir

  The desired ordering.
  Type:optional.
  Specified as: an integer value:

  Integer and real data:

    psb_sort_up_, psb_sort_down_, psb_asort_up_, psb_asort_down_; default psb_sort_up_.

  Complex data:

    psb_lsort_up_, psb_lsort_down_, psb_asort_up_, psb_asort_down_; default psb_lsort_up_.

flag

  Whether to keep the original values in IX.
  Type:optional.
  Specified as: an integer value psb_sort_ovw_idx_ or psb_sort_keep_idx_; default psb_sort_ovw_idx_.

On Return

x

  The sequence of values, in the chosen ordering.
  Type:required.
  Specified as: an integer, real or complex array of rank 1.

ix

  A vector of indices.
  Type: Optional
  An integer array of rank 1, whose entries are moved to the same position as the corresponding entries in x.

Notes

1. For integer or real data the sorting can be performed in the up/down direction, on the natural or absolute values;

2. For complex data the sorting can be done in a lexicographic order (i.e.: sort on the real part with ties broken according to the imaginary part) or on the absolute values;

3. The routines return the items in the chosen ordering; the output difference is the handling of ties (i.e. items with an equal value) in the original input. With the merge-sort algorithm ties are preserved in the same relative order as they had in the original sequence, while this is not guaranteed for quicksort or heapsort;

4. If flag = psb_sort_ovw_idx_ then the entries in ix(1 : n) where n is the size of x are initialized to ix(i) ← i; thus, upon return from the subroutine, for each index i we have in ix(i) the position that the item x(i) occupied in the original data sequence;

5. If flag = psb_sort_keep_idx_ the routine will assume that the entries in ix(:) have already been initialized by the user;

6. The three sorting algorithms have a similar O(nlog n) expected running time; in the average case quicksort will be the fastest and merge-sort the slowest. However note that:

   1. The worst case running time for quicksort is O(n2); the algorithm implemented here follows the well-known median-of-three heuristics, but the worst case may still apply;

   2. The worst case running time for merge-sort and heap-sort is O(nlog n) as the average case;

   3. The merge-sort algorithm is implemented to take advantage of subsequences that may be already in the desired ordering prior to the subroutine call; this situation is relatively common when dealing with groups of indices of sparse matrix entries, thus merge-sort is the preferred choice when a sorting is needed by other routines in the library.

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