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
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.
On exit from this routine the descriptor is in the build state.
Calling the routine with vg or parts implies that every process will scan the entire index space to figure out the local indices.
Overlapped indices are possible with both parts and vl invocations.
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.
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.
Orphan and overlap indices are impossible by construction when the subroutine is invoked with nl (alone), or vg.
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
This routine may only be called if the descriptor is in the build state;
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.
The second form of this routine will be useful when dealing with user-specified index mappings; see also 2.3.1.
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
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.
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.
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.
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
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;
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.
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
On exit from this routine the sparse matrix is in the build state.
The descriptor may be in either the build or assembled state.
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;
Using psb_matbld_remote_ is likely to cause a runtime overhead at assembly time;
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
On entry to this routine the descriptor may be in either the build or assembled state.
On entry to this routine the sparse matrix may be in either the build or update state.
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;
The input data can be passed in either COO or CSR formats;
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;
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;
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);
Coefficients from different rows may also be mixed up freely in a single call, according to the application needs;
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;
If the descriptor is in the assembled state, then any entries in the sparse matrix that would generate additional communication requirements are ignored;
If the matrix is in the update state, any entries in positions that were not present in the original matrix are ignored.
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
On entry to this routine the descriptor must be in the assembled state, i.e. psb_cdasb must already have been called.
The sparse matrix may be in either the build or update state;
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;
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;
The output storage format need not be the same on all processes;
On exit from this routine the matrix is in the assembled state, and thus is suitable for the computational routines;
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.
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.
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
On exit from this routine the sparse matrix is in the update state.
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
Using psb_matbld_remote_ is likely to cause a runtime overhead at assembly time;
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
Dense vectors/matrices do not have an associated state;
Duplicate entries are either overwritten or added, there is no provision for raising an error condition.
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
On entry to this routine the descriptor must be in the assembled state, i.e. psb_cdasb must already have been called.
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_.
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.
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.
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
If an input index is out of range, then the corresponding output index is set to a negative number;
The default Ignore means that the negative output is the only action taken on an out-of-range input.
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.
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
This routine returns a .true. value for an index that is strictly owned by the current process, excluding the halo indices
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
This routine returns a .true. value for those indices that are strictly owned by the current process, excluding the halo indices
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
This routine returns a .true. value for an index that is local to the current process, including the halo indices
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
This routine returns a .true. value for those indices that are local to the current process, including the halo indices.
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
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.
Otherwise the size of bndel will be exactly equal to the number of boundary 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
If there are no overlap elements the output vector is set to the “not allocated” state.
Otherwise the size of ovrel will be exactly equal to the number of overlap elements.
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
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;
When append=.true. the output arrays are reallocated as necessary;
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.
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.
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
For integer or real data the sorting can be performed in the up/down direction, on the natural or absolute values;
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;
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;
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;
If flag = psb_sort_keep_idx_ the routine will assume that the entries in ix(:) have already been initialized by the user;
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:
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;
The worst case running time for merge-sort and heap-sort is O(nlog n) as the average case;
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.