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,flag=flag)
call psb_cdall(icontxt, desc_a, info,vl=vl)
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. Exactly 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\in \{1\dots 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.

parts

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

vl

Data allocation: the set of global indices 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.

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.

On Return

desc_a

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

info

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

Notes

1. Exactly one of the optional arguments parts, vg, vl, nl 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 containint the indices of the processes to which the global index should be assigend; each entry must satisfy $0\le 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; the size of the index space is equal to the size of vg, and each index $i$ is assigned to the process $vg(i)$. The vector vg must be identical on all calling processes; its entries may have the ranges $(0\dots np-1)$ or $(1\dots np)$ according to the value of flag.

   vl

   In this case we are specifying the list of indices assigned to the current process; thus, the global problem size $mg$ is given by the sum of the sizes of the individual vectors vl specified on the calling processes. The subroutine will check that each entry in the global index space $(1\dots mg)$ is specified exactly once.

   nl

   In this case we are implying a generalized row-block distribution in which each process $I$ gets assigned a consecutive chunk of $N_I=nl$ global indices.

   repl

   In this case we are asking 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