@@ -63,7 +63,7 @@ necessary for implementing the various algorithms of interest to us.
The data structure itself psb_desc_type can be treated as an
opaque object handled via the tools routines of
-Sec. 6 or the query routines detailed below;
+Sec. 6 or the query routines detailed below;
nevertheless we include here a description for the curious
reader.
@@ -114,7 +114,7 @@ All methods but the last are purely local; the last method potentially
requires communication among processes, and thus is a synchronous
method. The choice of a specific dynamic type for the index map is
made at the time the descriptor is initially allocated, according to
-the mode of initialization (see also 6).
+the mode of initialization (see also 6).
The descriptor contents are as follows:
@@ -240,57 +240,57 @@ state, which can take the following values:
Subsections
-This subroutine initializes the PSBLAS parallel environment, defining
-a virtual parallel machine.
Type:
-
Synchronous.
+
Asynchronous.
-
On Entry
+
On Entry
-
np
-
Number of processes in the PSBLAS virtual parallel machine.
+
a
+
A sparse matrix
+.
-Scope: global.
+Scope: local
-Type: optional.
+Type: required
Intent: in.
-Specified as: an integer value. Default: use all available processes.
+Specified as: a structured data of type spdatapsb_Tspmat_type.
-
basectxt
-
the initial communication context. The new context
- will be defined from the processes participating in the initial one.
+
desc_a
+
Communication descriptor.
-Scope: global.
+Scope: local
-Type: optional.
+Type: required
Intent: in.
-Specified as: an integer value. Default: use MPI_COMM_WORLD.
+Specified as: a structured data of type descdatapsb_desc_type.
-
ids
-
Identities of the processes to use for the new context; the
- argument is ignored when np is not specified. This allows the
- processes in the new environment to be in an order different from the
- original one.
-
-Scope: global.
+
prec
+
Scope: local
-Type: optional.
+Type: required
Intent: in.
-Specified as: an integer array. Default: use the indices .
+Specified as: a preconditioner data structure precdatapsb_prec_type.
-
-
-
-
On Return
-
icontxt
-
the communication context identifying the virtual
- parallel machine. Note that this is always a duplicate of
- basectxt, so that library communications are completely
- separated from other communication operations.
-
-Scope: global.
+
Function value
+
The memory occupation of the object specified in
+ the calling sequence, in bytes.
-Type: required.
+Scope: local
-Intent: out.
-
-Specified as: an integer variable.
+Returned as: an integer(psb_long_int_k_) number.
-Notes
-
-
-
A call to this routine must precede any other PSBLAS call.
-
-
It is an error to specify a value for greater than the
- number of processes available in the underlying base parallel
- environment.
-
-This subroutine returns information about the PSBLAS parallel environment, defining
-a virtual parallel machine.
+These serial routines sort a sequence 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.
@@ -68,17 +82,53 @@ a virtual parallel machine.
On Entry
-
icontxt
-
the communication context identifying the virtual
- parallel machine.
+
x
+
The sequence to be sorted.
-Scope: global.
+Type:required.
-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 .
+
+
dir
+
The desired ordering.
+
+Type:optional.
+
+Specified as: an integer value:
Whether to keep the original values in .
-Intent: in.
+Type:optional.
-Specified as: an integer variable.
+Specified as: an integer value psb_sort_ovw_idx_ or
+psb_sort_keep_idx_; default psb_sort_ovw_idx_.
+
+
@@ -87,60 +137,155 @@ Specified as: an integer variable.
On Return
-
iam
-
Identifier of current process in the PSBLAS virtual parallel machine.
+
x
+
The sequence of values, in the chosen ordering.
-Scope: local.
+Type:required.
-Type: required.
-
-Intent: out.
-
-Specified as: an integer value.
-
-
np
-
Number of processes in the PSBLAS virtual parallel machine.
-
-Scope: global.
-
-Type: required.
+Specified as: an integer, real or complex array of rank 1.
+
+
ix
+
A vector of indices.
-Intent: out.
+Type: Optional
-Specified as: an integer variable.
+An integer array of rank 1, whose entries are moved to the same
+position as the corresponding entries in .
+
+
+
Notes
-
For processes in the virtual parallel machine the identifier
- will satisfy
;
+ WIDTH="180" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img131.png"
+ ALT="$flag = psb\_sort\_ovw\_idx\_$"> then the entries in
+ where is the size of are initialized to
+; thus, upon return from the subroutine, for each
+ index we have in the position that the item
+ occupied in the original data sequence;
-
If the user has requested on psb_init a number of
- processes less than the total available in the parallel execution
- environment, the remaining processes will have on return If
+ the routine will assume that
+ the entries in ;
- the only call involving icontxt that any such process may
- execute is to psb_exit.
+ ALT="$ix(:)$"> have already been initialized by the user;
+
+
The three sorting algorithms have a similar 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 ; 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
+ 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.
-This subroutine exits from the PSBLAS parallel virtual machine.
-
-
Type:
-
Synchronous.
-
-
On Entry
-
-
-
icontxt
-
the communication context identifying the virtual
- parallel machine.
+
+
-Scope: global.
-
-Type: required.
-
-Intent: in.
-
-Specified as: an integer variable.
-
-
close
-
Whether to close all data structures related to the
- virtual parallel machine, besides those associated with icontxt.
-
-Scope: global.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: a logical variable, default value: true.
-
-
-
-
-Notes
-
-
-
This routine may be called even if a previous call to
- psb_info has returned with ; indeed, it it is the only
- routine that may be called with argument icontxt in this
- situation.
-
-
A call to this routine with close=.true. implies a call
- to MPI_Finalize, after which no parallel routine may be called.
-
-
If the user whishes to use multiple communication contexts in the
- same program, or to enter and exit multiple times into the parallel
- environment, this routine may be called to
- selectively close the contexts with close=.false., while on
- the last call it should be called with close=.true. to
- shutdown in a clean way the entire parallel environment.
-
-This subroutine returns the MPI communicator associated with a PSBLAS context
+This subroutine initializes the PSBLAS parallel environment, defining
+a virtual parallel machine.
Type:
-
Asynchronous.
+
Synchronous.
On Entry
-
icontxt
-
the communication context identifying the virtual
- parallel machine.
+
np
+
Number of processes in the PSBLAS virtual parallel machine.
Scope: global.
-Type: required.
+Type: optional.
Intent: in.
-Specified as: an integer variable.
+Specified as: an integer value. Default: use all available processes.
+
+
basectxt
+
the initial communication context. The new context
+ will be defined from the processes participating in the initial one.
+
+Scope: global.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: an integer value. Default: use MPI_COMM_WORLD.
+
+
ids
+
Identities of the processes to use for the new context; the
+ argument is ignored when np is not specified. This allows the
+ processes in the new environment to be in an order different from the
+ original one.
+
+Scope: global.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: an integer array. Default: use the indices .
@@ -85,19 +115,63 @@ Specified as: an integer variable.
On Return
-
icomm
-
The MPI communicator associated with the PSBLAS virtual parallel machine.
+
icontxt
+
the communication context identifying the virtual
+ parallel machine. Note that this is always a duplicate of
+ basectxt, so that library communications are completely
+ separated from other communication operations.
Scope: global.
Type: required.
Intent: out.
-
+
+Specified as: an integer variable.
+
-
+Notes
+
+
+
A call to this routine must precede any other PSBLAS call.
+
+
It is an error to specify a value for greater than the
+ number of processes available in the underlying base parallel
+ environment.
+
-This subroutine returns the MPI rank of the PSBLAS process
+This subroutine returns information about the PSBLAS parallel environment, defining
+a virtual parallel machine.
Type:
Asynchronous.
@@ -81,43 +80,65 @@ Intent: in.
Specified as: an integer variable.
-
id
-
Identifier of a process in the PSBLAS virtual parallel machine.
+
+
+
+
+
On Return
+
+
+
iam
+
Identifier of current process in the PSBLAS virtual parallel machine.
Scope: local.
Type: required.
-Intent: in.
+Intent: out.
Specified as: an integer value.
-
-
-
-
-
On Return
-
-
-
rank
-
The MPI rank associated with the PSBLAS process .
+ WIDTH="139" HEIGHT="31" ALIGN="MIDDLE" BORDER="0"
+ SRC="img141.png"
+ ALT="$-1 \le iam \le np-1$">
+
np
+
Number of processes in the PSBLAS virtual parallel machine.
-Scope: local.
+Scope: global.
Type: required.
Intent: out.
-
+
+Specified as: an integer variable.
+
+Notes
+
+
+
For processes in the virtual parallel machine the identifier
+ will satisfy
+;
+
+
If the user has requested on psb_init a number of
+ processes less than the total available in the parallel execution
+ environment, the remaining processes will have on return ;
+ the only call involving icontxt that any such process may
+ execute is to psb_exit.
+
-This function returns a wall clock timer. The resolution of the timer
-is dependent on the underlying parallel environment implementation.
+This subroutine exits from the PSBLAS parallel virtual machine.
Type:
-
Asynchronous.
+
Synchronous.
-
On Exit
+
On Entry
-
Function value
-
the elapsed time in seconds.
+
icontxt
+
the communication context identifying the virtual
+ parallel machine.
-Returned as: a real(psb_dpk_) variable.
+Scope: global.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer variable.
+
+
close
+
Whether to close all data structures related to the
+ virtual parallel machine, besides those associated with icontxt.
+
+Scope: global.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: a logical variable, default value: true.
-
+Notes
+
+
+
This routine may be called even if a previous call to
+ psb_info has returned with ; indeed, it it is the only
+ routine that may be called with argument icontxt in this
+ situation.
+
+
A call to this routine with close=.true. implies a call
+ to MPI_Finalize, after which no parallel routine may be called.
+
+
If the user whishes to use multiple communication contexts in the
+ same program, or to enter and exit multiple times into the parallel
+ environment, this routine may be called to
+ selectively close the contexts with close=.false., while on
+ the last call it should be called with close=.true. to
+ shutdown in a clean way the entire parallel environment.
+
-This subroutine acts as an explicit synchronization point for the PSBLAS
-parallel virtual machine.
+This subroutine returns the MPI communicator associated with a PSBLAS context
Type:
-
Synchronous.
+
Asynchronous.
On Entry
@@ -82,6 +80,22 @@ Specified as: an integer variable.
+
+
+
On Return
+
+
+
icomm
+
The MPI communicator associated with the PSBLAS virtual parallel machine.
+
+Scope: global.
+
+Type: required.
+
+Intent: out.
+
+
+
diff --git a/docs/html/node107.html b/docs/html/node107.html
index 0f37acf3..a7b9c720 100644
--- a/docs/html/node107.html
+++ b/docs/html/node107.html
@@ -3,8 +3,8 @@
-psb_abort -- Abort a computation
-
+psb_get_rank -- Get the MPI rank
+
@@ -16,49 +16,52 @@
-
+
-This subroutine aborts computation on the parallel virtual machine.
+This subroutine returns the MPI rank of the PSBLAS process
Type:
Asynchronous.
@@ -78,6 +81,41 @@ Intent: in.
Specified as: an integer variable.
+
id
+
Identifier of a process in the PSBLAS virtual parallel machine.
+
+Scope: local.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer value.
+
+
+
+
+
+
On Return
+
+
+
rank
+
The MPI rank associated with the PSBLAS process .
+
+Scope: local.
+
+Type: required.
+
+Intent: out.
+
-This subroutine implements a broadcast operation based on the
-underlying communication library.
+This function returns a wall clock timer. The resolution of the timer
+is dependent on the underlying parallel environment implementation.
Type:
-
Synchronous.
+
Asynchronous.
-
On Entry
+
On Exit
-
icontxt
-
the communication context identifying the virtual
- parallel machine.
+
Function value
+
the elapsed time in seconds.
-Scope: global.
-
-Type: required.
-
-Intent: in.
-
-Specified as: an integer variable.
-
-
dat
-
On the root process, the data to be broadcast.
-
-Scope: global.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array, or a character or logical variable,
-which may be a scalar or rank 1 array. Type, kind, rank and size must agree on all processes.
-
-
root
-
Root process holding data to be broadcast.
-
-Scope: global.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: an integer value
-, default 0
-
-
-
-
-
On Return
-
-
-
dat
-
On processes other than root, the data to be broadcast.
-
-Scope: global.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array, or a character or logical scalar. Type, kind, rank and size must agree on all processes.
+Returned as: a real(psb_dpk_) variable.
diff --git a/docs/html/node109.html b/docs/html/node109.html
index c023b27a..e9725952 100644
--- a/docs/html/node109.html
+++ b/docs/html/node109.html
@@ -3,8 +3,8 @@
-psb_sum -- Global sum
-
+psb_barrier -- Sinchronization point parallel environment
+
@@ -16,50 +16,51 @@
-
+
-This subroutine implements a sum reduction operation based on the
-underlying communication library.
+This subroutine acts as an explicit synchronization point for the PSBLAS
+parallel virtual machine.
Type:
Synchronous.
@@ -79,99 +80,10 @@ Intent: in.
Specified as: an integer variable.
-
dat
-
The local contribution to the global sum.
-
-Scope: global.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
-
-
root
-
Process to hold the final sum, or to make it available
- on all processes.
-
-Scope: global.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: an integer value
-, default -1.
-
-
-
-
-
On Return
-
-
-
dat
-
On destination process(es), the result of the sum operation.
-
-Scope: global.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array.
-
-Type, kind, rank and size must agree on all processes.
-
-Notes
-
-
-
The dat argument is both input and output, and its
- value may be changed even on processes different from the final
- result destination.
-
-
The dat argument may also be a long integer scalar.
-
-This subroutine implements a maximum valuereduction
-operation based on the underlying communication library.
+This subroutine aborts computation on the parallel virtual machine.
Type:
-
Synchronous.
+
Asynchronous.
On Entry
@@ -79,98 +78,10 @@ Intent: in.
Specified as: an integer variable.
-
dat
-
The local contribution to the global maximum.
-
-Scope: local.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: an integer or real variable, which may be a
-scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
-
-
root
-
Process to hold the final maximum, or to make it available
- on all processes.
-
-Scope: global.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: an integer value
-, default -1.
-
-
-
On Return
-
-
-
dat
-
On destination process(es), the result of the maximum operation.
-
-Scope: global.
-
-Type: required.
-
-Intent: in.
-
-Specified as: an integer or real variable, which may be a
-scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
-
-
-
-
-Notes
-
-
-
The dat argument is both input and output, and its
- value may be changed even on processes different from the final
- result destination.
-
-
The dat argument may also be a long integer scalar.
-
-This subroutine implements a minimum value reduction
-operation based on the underlying communication library.
+This subroutine implements a broadcast operation based on the
+underlying communication library.
Type:
Synchronous.
@@ -80,23 +80,20 @@ Intent: in.
Specified as: an integer variable.
dat
-
The local contribution to the global minimum.
+
On the root process, the data to be broadcast.
-Scope: local.
+Scope: global.
Type: required.
Intent: inout.
-Specified as: an integer or real variable, which may be a
-scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
+Specified as: an integer, real or complex variable, which may be a
+scalar, or a rank 1 or 2 array, or a character or logical variable,
+which may be a scalar or rank 1 array. Type, kind, rank and size must agree on all processes.
root
-
Process to hold the final value, or to make it available
- on all processes.
+
Root process holding data to be broadcast.
Scope: global.
@@ -105,13 +102,12 @@ Type: optional.
Intent: in.
Specified as: an integer value
, default -1.
-
-This subroutine implements a maximum absolute value reduction
-operation based on the underlying communication library.
+This subroutine implements a sum reduction operation based on the
+underlying communication library.
Type:
Synchronous.
@@ -80,9 +80,9 @@ Intent: in.
Specified as: an integer variable.
dat
-
The local contribution to the global maximum.
+
The local contribution to the global sum.
-Scope: local.
+Scope: global.
Type: required.
@@ -92,9 +92,9 @@ Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
root
-
Process to hold the final value, or Process to hold the final sum, or to make it available
on all processes.
@@ -108,10 +108,9 @@ Specified as: an integer value
, default -1.
-
-This subroutine implements a minimum absolute value reduction
+This subroutine implements a maximum valuereduction
operation based on the underlying communication library.
Type:
@@ -80,7 +80,7 @@ Intent: in.
Specified as: an integer variable.
dat
-
The local contribution to the global minimum.
+
The local contribution to the global maximum.
Scope: local.
@@ -88,13 +88,13 @@ Type: required.
Intent: inout.
-Specified as: an integer, real or complex variable, which may be a
+Specified as: an integer or real variable, which may be a
scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
root
-
Process to hold the final value, or Process to hold the final maximum, or to make it available
on all processes.
@@ -108,8 +108,8 @@ Specified as: an integer value
, default -1.
-This subroutine implements a 2-norm value reduction
+This subroutine implements a minimum value reduction
operation based on the underlying communication library.
Type:
@@ -88,13 +88,13 @@ Type: required.
Intent: inout.
-Specified as: a real variable, which may be a
-scalar, or a rank 1 array. Kind, rank and size must agree on all processes.
+Specified as: an integer or real variable, which may be a
+scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
root
Process to hold the final value, or to make it available
on all processes.
@@ -108,8 +108,8 @@ Specified as: an integer value
, default -1.
@@ -120,7 +120,7 @@ Specified as: an integer value
-
-
-
-
-
-with care taken to avoid unnecessary overflow.
-
The dat argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
+
The dat argument may also be a long integer scalar.
+
-call psb_snd(icontxt, dat, dst, m)
+call psb_amx(icontxt, dat, root)
-This subroutine sends a packet of data to a destination.
+This subroutine implements a maximum absolute value reduction
+operation based on the underlying communication library.
Type:
-
Synchronous: see usage notes.
+
Synchronous.
On Entry
@@ -79,65 +80,38 @@ Intent: in.
Specified as: an integer variable.
dat
-
The data to be sent.
+
The local contribution to the global maximum.
Scope: local.
Type: required.
-Intent: in.
+Intent: inout.
Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array, or a character or logical scalar. Type, kind and rank must agree on sender and receiver process; if is
-not specified, size must agree as well.
+scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
-
dst
-
Destination process.
-
-Scope: global.
-
-Type: required.
-
-Intent: in.
-
-Specified as: an integer value
-.
-
-
m
-
Number of rows.
+
root
+
Process to hold the final value, or to make it available
+ on all processes.
Scope: global.
-Type: Optional.
+Type: optional.
Intent: in.
Specified as: an integer value
.
-
-When is a rank 2 array, specifies the number of rows to be sent
-independently of the leading dimension ; must have the
-same value on sending and receiving processes.
-
+ ALT="$-1<= root <= np-1$">, default -1.
+
@@ -145,17 +119,29 @@ same value on sending and receiving processes.
On Return
+
dat
+
On destination process(es), the result of the maximum operation.
+
+Scope: global.
+
+Type: required.
+
+Intent: inout.
+
+Specified as: an integer, real or complex variable, which may be a
+scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
+
Notes
-
This subroutine implies a synchronization, but only between the
- calling process and the destination process .
+
The dat argument is both input and output, and its
+ value may be changed even on processes different from the final
+ result destination.
+
+
The dat argument may also be a long integer scalar.
@@ -163,26 +149,26 @@ same value on sending and receiving processes.
-call psb_rcv(icontxt, dat, src, m)
+call psb_amn(icontxt, dat, root)
-This subroutine receives a packet of data to a destination.
+This subroutine implements a minimum absolute value reduction
+operation based on the underlying communication library.
Type:
-
Synchronous: see usage notes.
+
Synchronous.
On Entry
@@ -77,50 +79,39 @@ Intent: in.
Specified as: an integer variable.
-
src
-
Source process.
+
dat
+
The local contribution to the global minimum.
-Scope: global.
+Scope: local.
Type: required.
-Intent: in.
+Intent: inout.
-Specified as: an integer value
-.
-
-
m
-
Number of rows.
+Specified as: an integer, real or complex variable, which may be a
+scalar, or a rank 1 or 2 array. Type, kind, rank and size must agree on all processes.
+
+
root
+
Process to hold the final value, or to make it available
+ on all processes.
Scope: global.
-Type: Optional.
+Type: optional.
Intent: in.
Specified as: an integer value
.
-
-When is a rank 2 array, specifies the number of rows to be sent
-independently of the leading dimension ; must have the
-same value on sending and receiving processes.
-
+ ALT="$-1<= root <= np-1$">, default -1.
+
@@ -129,20 +120,18 @@ same value on sending and receiving processes.
dat
-
The data to be received.
+
On destination process(es), the result of the minimum operation.
-Scope: local.
+Scope: global.
Type: required.
Intent: inout.
Specified as: an integer, real or complex variable, which may be a
-scalar, or a rank 1 or 2 array, or a character or logical scalar. Type, kind and rank must agree on sender and receiver process; if is
-not specified, size must agree as well.
+scalar, or a rank 1 or 2 array.
+
+Type, kind, rank and size must agree on all processes.
@@ -150,11 +139,11 @@ not specified, size must agree as well.
Notes
-
This subroutine implies a synchronization, but only between the
- calling process and the source process .
+
The dat argument is both input and output, and its
+ value may be changed even on processes different from the final
+ result destination.
+
+
The dat argument may also be a long integer scalar.
@@ -162,26 +151,26 @@ not specified, size must agree as well.
-The PSBLAS library error handling policy has been completely rewritten
-in version 2.0. The idea behind the design of this new error handling
-strategy is to keep error messages on a stack allowing the user to
-trace back up to the point where the first error message has been
-generated. Every routine in the PSBLAS-2.0 library has, as last
-non-optional argument, an integer info variable; whenever,
-inside the routine, an error is detected, this variable is set to a
-value corresponding to a specific error code. Then this error code is
-also pushed on the error stack and then either control is returned to
-the caller routine or the execution is aborted, depending on the users
-choice. At the time when the execution is aborted, an error message is
-printed on standard output with a level of verbosity than can be
-chosen by the user. If the execution is not aborted, then, the caller
-routine checks the value returned in the info variable and, if
-not zero, an error condition is raised. This process continues on all the
-levels of nested calls until the level where the user decides to abort
-the program execution.
-
-
-Figure 9 shows the layout of a generic psb_foo
-routine with respect to the PSBLAS-2.0 error handling policy. It is
-possible to see how, whenever an error condition is detected, the
-info variable is set to the corresponding error code which is,
-then, pushed on top of the stack by means of the
-psb_errpush. An error condition may be directly detected inside
-a routine or indirectly checking the error code returned returned by a
-called routine. Whenever an error is encountered, after it has been
-pushed on stack, the program execution skips to a point where the
-error condition is handled; the error condition is handled either by
-returning control to the caller routine or by calling the
-psb\_error routine which prints the content of the error stack
-and aborts the program execution, according to the choice made by the
-user with psb_set_erraction. The default is to print the error
-and terminate the program, but the user may choose to handle the error
-explicitly.
-
-
-
-
-
-
Figure 9:
-The layout of a generic psb_foo
- routine with respect to PSBLAS-2.0 error handling policy.
-
-
-
-
-
-
-
-
-
-
-
-Figure 10 reports a sample error message generated by
-the PSBLAS-2.0 library. This error has been generated by the fact that
-the user has chosen the invalid “FOO” storage format to represent
-the sparse matrix. From this error message it is possible to see that
-the error has been detected inside the psb_cest subroutine
-called by psb_spasb ... by process 0 (i.e. the root process).
-
-
-
-
-
-
Figure 10:
-A sample PSBLAS-2.0 error
- message. Process 0 detected an error condition inside the psb_cest subroutine
-
-
-
-
-
-
-
-
-
-
-
-ifstarsubroutinesubroutinepsb_errpushPushes an error code onto the error
- stack
-
-
-
-
-
+
+call psb_nrm2(icontxt, dat, root)
+
+This subroutine implements a 2-norm value reduction
+operation based on the underlying communication library.
Type:
-
Asynchronous.
+
Synchronous.
-
On Entry
+
On Entry
-
err_c
-
the error code
+
icontxt
+
the communication context identifying the virtual
+ parallel machine.
-Scope: local
+Scope: global.
-Type: required
+Type: required.
Intent: in.
-Specified as: an integer.
+Specified as: an integer variable.
-
r_name
-
the soutine where the error has been caught.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a string.
-
-
i_err
-
addional info for error code
-
-Scope: local
-
-Type: optional
-
-Specified as: an integer array
-
-
a_err
-
addional info for error code
-
-Scope: local
+
dat
+
The local contribution to the global minimum.
-Type: optional
+Scope: local.
-Specified as: a string.
-
-
-
-
-ifstarsubroutinesubroutinepsb_errorPrints the error stack content and aborts
- execution
-
-
+Type: required.
-
+Intent: inout.
-
-
-
-
Type:
-
Asynchronous.
+Specified as: a real variable, which may be a
+scalar, or a rank 1 array. Kind, rank and size must agree on all processes.
-
On Entry
-
-
-
icontxt
-
the communication context.
+
root
+
Process to hold the final value, or to make it available
+ on all processes.
-Scope: global
+Scope: global.
-Type: optional
+Type: optional.
Intent: in.
-Specified as: an integer.
-
+Specified as: an integer value
+, default -1.
+
-
-ifstarsubroutinesubroutinepsb_set_errverbositySets the verbosity of error
- messages.
-
-
-
-
-
-
-
Type:
-
Asynchronous.
-
-
On Entry
+
On Return
-
v
-
the verbosity level
+
dat
+
On destination process(es), the result of the 2-norm reduction.
-Scope: global
+Scope: global.
-Type: required
+Type: required.
-Intent: in.
+Intent: inout.
+
+Specified as: a real variable, which may be a
+scalar, or a rank 1 array.
-Specified as: an integer.
+Kind, rank and size must agree on all processes.
-ifstarsubroutinesubroutinepsb_set_erractionSet the type of action to be
- taken upon error condition.
+Notes
+
+
+
This reduction is appropriate to compute the results of multiple
+ (local) NRM2 operations at the same time.
+
+
Denoting by the value of the variable on process
+ , the output is equivalent to the computation of
+
+
+
-
-
-
-
-
-
-
Type:
-
Asynchronous.
-
-
On Entry
-
-
-
err_act
-
the type of action.
-
-Scope: global
-
-Type: required
-
-Intent: in.
-
-Specified as: an integer. Possible values: psb_act_ret,
-psb_act_abort.
-
+This subroutine sends a packet of data to a destination.
+
+
Type:
+
Synchronous: see usage notes.
+
+
On Entry
+
+
+
icontxt
+
the communication context identifying the virtual
+ parallel machine.
+
+Scope: global.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer variable.
+
+
dat
+
The data to be sent.
+
+Scope: local.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer, real or complex variable, which may be a
+scalar, or a rank 1 or 2 array, or a character or logical scalar. Type, kind and rank must agree on sender and receiver process; if is
+not specified, size must agree as well.
+
+
dst
+
Destination process.
+
+Scope: global.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer value
+.
+
+
m
+
Number of rows.
-Utilities
-
+Scope: global.
+
+Type: Optional.
+
+Intent: in.
+
+Specified as: an integer value
+.
+
+When is a rank 2 array, specifies the number of rows to be sent
+independently of the leading dimension ; must have the
+same value on sending and receiving processes.
+
+
-We have some utilities available for input and output of
-sparse matrices; the interfaces to these routines are available in the
-module psb_util_mod.
+
+This subroutine receives a packet of data to a destination.
Type:
-
Asynchronous.
+
Synchronous: see usage notes.
On Entry
-
filename
-
The name of the file to be read.
+
icontxt
+
the communication context identifying the virtual
+ parallel machine.
-Type:optional.
+Scope: global.
-Specified as: a character variable containing a valid file name, or
--, in which case the default input unit 5 (i.e. standard input
-in Unix jargon) is used. Default: -.
-
-
iunit
-
The Fortran file unit number.
+Type: required.
-Type:optional.
+Intent: in.
-Specified as: an integer value. Only meaningful if filename is not -.
+Specified as: an integer variable.
+
+
src
+
Source process.
+
+Scope: global.
+
+Type: required.
+
+Intent: in.
+
+Specified as: an integer value
+.
+
+
m
+
Number of rows.
+
+Scope: global.
+
+Type: Optional.
+
+Intent: in.
+
+Specified as: an integer value
+.
+
+When is a rank 2 array, specifies the number of rows to be sent
+independently of the leading dimension ; must have the
+same value on sending and receiving processes.
@@ -94,64 +128,60 @@ Specified as: an integer value. Only meaningful if filename is not -On Return
-
a
-
the sparse matrix read from file.
+
dat
+
The data to be received.
-Type:required.
+Scope: local.
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
b
-
Rigth hand side(s).
+Type: required.
-Type: Optional
+Intent: inout.
-An array of type real or complex, rank 2 and having the ALLOCATABLE
-attribute; will be allocated and filled in if the input file contains
-a right hand side, otherwise will be left in the UNALLOCATED state.
-
-
mtitle
-
Matrix title.
-
-Type: Optional
-
-A charachter variable of length 72 holding a copy of the
-matrix title as specified by the Harwell-Boeing format and contained
-in the input file.
-
-
iret
-
Error code.
-
-Type: required
-
-An integer value; 0 means no error has been detected.
+Specified as: an integer, real or complex variable, which may be a
+scalar, or a rank 1 or 2 array, or a character or logical scalar. Type, kind and rank must agree on sender and receiver process; if is
+not specified, size must agree as well.
+
+Notes
+
+
+
This subroutine implies a synchronization, but only between the
+ calling process and the source process .
+
@@ -84,7 +84,7 @@ Scope: local.
$|{\cal I}_i| + |{\cal B}_i|$
-->
. The returned value is
specific to the calling process.
diff --git a/docs/html/node120.html b/docs/html/node120.html
index 11e1a5b6..21a186b7 100644
--- a/docs/html/node120.html
+++ b/docs/html/node120.html
@@ -3,8 +3,8 @@
-hb_write -- Write a sparse matrix to a file in the Harwell-Boeing format
-
+Error handling
+
@@ -15,51 +15,143 @@
-
-
+
+
+The PSBLAS library error handling policy has been completely rewritten
+in version 2.0. The idea behind the design of this new error handling
+strategy is to keep error messages on a stack allowing the user to
+trace back up to the point where the first error message has been
+generated. Every routine in the PSBLAS-2.0 library has, as last
+non-optional argument, an integer info variable; whenever,
+inside the routine, an error is detected, this variable is set to a
+value corresponding to a specific error code. Then this error code is
+also pushed on the error stack and then either control is returned to
+the caller routine or the execution is aborted, depending on the users
+choice. At the time when the execution is aborted, an error message is
+printed on standard output with a level of verbosity than can be
+chosen by the user. If the execution is not aborted, then, the caller
+routine checks the value returned in the info variable and, if
+not zero, an error condition is raised. This process continues on all the
+levels of nested calls until the level where the user decides to abort
+the program execution.
+
+
+Figure 9 shows the layout of a generic psb_foo
+routine with respect to the PSBLAS-2.0 error handling policy. It is
+possible to see how, whenever an error condition is detected, the
+info variable is set to the corresponding error code which is,
+then, pushed on top of the stack by means of the
+psb_errpush. An error condition may be directly detected inside
+a routine or indirectly checking the error code returned returned by a
+called routine. Whenever an error is encountered, after it has been
+pushed on stack, the program execution skips to a point where the
+error condition is handled; the error condition is handled either by
+returning control to the caller routine or by calling the
+psb\_error routine which prints the content of the error stack
+and aborts the program execution, according to the choice made by the
+user with psb_set_erraction. The default is to print the error
+and terminate the program, but the user may choose to handle the error
+explicitly.
+
+
+
+
+
+
Figure 9:
+The layout of a generic psb_foo
+ routine with respect to PSBLAS-2.0 error handling policy.
+
+
+
+
+
+
+
+
+
+
+
+Figure 10 reports a sample error message generated by
+the PSBLAS-2.0 library. This error has been generated by the fact that
+the user has chosen the invalid “FOO” storage format to represent
+the sparse matrix. From this error message it is possible to see that
+the error has been detected inside the psb_cest subroutine
+called by psb_spasb ... by process 0 (i.e. the root process).
+
+
+
+
+
+
Figure 10:
+A sample PSBLAS-2.0 error
+ message. Process 0 detected an error condition inside the psb_cest subroutine
+
+
+
+
+
+
+
+
+
+
+
+ifstarsubroutinesubroutinepsb_errpushPushes an error code onto the error
+ stack
the error code
-Type:required.
+Scope: local
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
b
-
Rigth hand side.
+Type: required
-Type: Optional
+Intent: in.
-An array of type real or complex, rank 1 and having the ALLOCATABLE
-attribute; will be allocated and filled in if the input file contains
-a right hand side.
+Specified as: an integer.
-
filename
-
The name of the file to be written to.
+
r_name
+
the soutine where the error has been caught.
+
+Scope: local
+
+Type: required
-Type:optional.
+Intent: in.
-Specified as: a character variable containing a valid file name, or
--, in which case the default output unit 6 (i.e. standard output
-in Unix jargon) is used. Default: -.
+Specified as: a string.
+
+
i_err
+
addional info for error code
+
+Scope: local
+
+Type: optional
+
+Specified as: an integer array
+
+
a_err
+
addional info for error code
+
+Scope: local
+
+Type: optional
+
+Specified as: a string.
+
+
+
+
+ifstarsubroutinesubroutinepsb_errorPrints the error stack content and aborts
+ execution
+
+
+
+
+
+
+
+
+
Type:
+
Asynchronous.
-
iunit
-
The Fortran file unit number.
+
On Entry
+
+
+
icontxt
+
the communication context.
+
+Scope: global
-Type:optional.
+Type: optional
-Specified as: an integer value. Only meaningful if filename is not -.
+Intent: in.
+
+Specified as: an integer.
-
key
-
Matrix key.
+
+
+
+ifstarsubroutinesubroutinepsb_set_errverbositySets the verbosity of error
+ messages.
+
+
-Type: Optional
+
-A charachter variable of length 8 holding the
-matrix key as specified by the Harwell-Boeing format and to be
-written to file.
+
+
+
+
Type:
+
Asynchronous.
-
mtitle
-
Matrix title.
+
On Entry
+
+
+
v
+
the verbosity level
+
+Scope: global
-Type: Optional
+Type: required
-A charachter variable of length 72 holding the
-matrix title as specified by the Harwell-Boeing format and to be
-written to file.
+Intent: in.
+
+Specified as: an integer.
+
+ifstarsubroutinesubroutinepsb_set_erractionSet the type of action to be
+ taken upon error condition.
+
+
+
+
+
+
-
On Return
+
Type:
+
Asynchronous.
+
+
On Entry
-
iret
-
Error code.
+
err_act
+
the type of action.
+
+Scope: global
+
+Type: required
-Type: required
+Intent: in.
-An integer value; 0 means no error has been detected.
+Specified as: an integer. Possible values: psb_act_ret,
+psb_act_abort.
@@ -141,26 +315,26 @@ An integer value; 0 means no error has been detected.
The name of the file to be read.
-
-Type:optional.
-
-Specified as: a character variable containing a valid file name, or
--, in which case the default input unit 5 (i.e. standard input
-in Unix jargon) is used. Default: -.
-
-
iunit
-
The Fortran file unit number.
-
-Type:optional.
-
-Specified as: an integer value. Only meaningful if filename is not -.
-
-
+We have some utilities available for input and output of
+sparse matrices; the interfaces to these routines are available in the
+module psb_util_mod.
-
-
On Return
-
-
-
a
-
the sparse matrix read from file.
-
-Type:required.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
iret
-
Error code.
-
-Type: required
-
-An integer value; 0 means no error has been detected.
-
+
diff --git a/docs/html/node122.html b/docs/html/node122.html
index 5a57cd34..b3438b33 100644
--- a/docs/html/node122.html
+++ b/docs/html/node122.html
@@ -3,8 +3,8 @@
-mm_array_read -- Read a dense array from a file in the MatrixMarket format
-
+hb_read -- Read a sparse matrix from a file in the Harwell-Boeing format
+
@@ -16,50 +16,50 @@
-
+
@@ -94,15 +94,31 @@ Specified as: an integer value. Only meaningful if filename is not -On Return
+
a
+
the sparse matrix read from file.
+
+Type:required.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
b
Rigth hand side(s).
-Type: required
+Type: Optional
-An array of type real or complex, rank 1 or 2 and having the ALLOCATABLE
+An array of type real or complex, rank 2 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side, otherwise will be left in the UNALLOCATED state.
+
mtitle
+
Matrix title.
+
+Type: Optional
+
+A charachter variable of length 72 holding a copy of the
+matrix title as specified by the Harwell-Boeing format and contained
+in the input file.
+
iret
Error code.
@@ -113,7 +129,31 @@ An integer value; 0 means no error has been detected.
+
diff --git a/docs/html/node123.html b/docs/html/node123.html
index 4dd5f34e..f8e65c33 100644
--- a/docs/html/node123.html
+++ b/docs/html/node123.html
@@ -3,8 +3,8 @@
-mm_mat_write -- Write a sparse matrix to a file in the MatrixMarket format
-
+hb_write -- Write a sparse matrix to a file in the Harwell-Boeing format
+
@@ -16,52 +16,54 @@
-
+
Asynchronous.
@@ -76,13 +78,14 @@ Type:required.
Specified as: a structured data of type spdatapsb_Tspmat_type.
-
mtitle
-
Matrix title.
+
b
+
Rigth hand side.
-Type: required
+Type: Optional
-A charachter variable holding a descriptive title for the matrix to be
- written to file.
+An array of type real or complex, rank 1 and having the ALLOCATABLE
+attribute; will be allocated and filled in if the input file contains
+a right hand side.
filename
The name of the file to be written to.
@@ -100,6 +103,24 @@ Type:optional.
Specified as: an integer value. Only meaningful if filename is not -.
+
key
+
Matrix key.
+
+Type: Optional
+
+A charachter variable of length 8 holding the
+matrix key as specified by the Harwell-Boeing format and to be
+written to file.
+
+
mtitle
+
Matrix title.
+
+Type: Optional
+
+A charachter variable of length 72 holding the
+matrix title as specified by the Harwell-Boeing format and to be
+written to file.
+
@@ -117,7 +138,31 @@ An integer value; 0 means no error has been detected.
+
diff --git a/docs/html/node124.html b/docs/html/node124.html
index e7e3f85f..f1307a9d 100644
--- a/docs/html/node124.html
+++ b/docs/html/node124.html
@@ -3,8 +3,8 @@
-mm_array_write -- Write a dense array from a file in the MatrixMarket format
-
+mm_mat_read -- Read a sparse matrix from a file in the MatrixMarket format
+
@@ -14,51 +14,52 @@
+
-
+
-The base PSBLAS library contains the implementation of two simple
-preconditioning techniques:
+
+
+
-
-
Diagonal Scaling
-
-
Block Jacobi with ILU(0) factorization
-
-
-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
+
+
+
Type:
+
Asynchronous.
+
+
On Entry
+
+
+
filename
+
The name of the file to be read.
+
+Type:optional.
+
+Specified as: a character variable containing a valid file name, or
+-, in which case the default input unit 5 (i.e. standard input
+in Unix jargon) is used. Default: -.
+
+
iunit
+
The Fortran file unit number.
+
+Type:optional.
+
+Specified as: an integer value. Only meaningful if filename is not -.
+
Rigth hand side(s).
+
+Type: required
+
+An array of type real or complex, rank 1 or 2 and having the ALLOCATABLE
+attribute; will be allocated and filled in if the input file contains
+a right hand side, otherwise will be left in the UNALLOCATED state.
+
+
iret
+
Error code.
+
+Type: required
+
+An integer value; 0 means no error has been detected.
+
the sparse matrix to be written.
Type:required.
-Intent: in.
-
-Specified as: an integer value.
+Specified as: a structured data of type spdatapsb_Tspmat_type.
-
ptype
-
the type of preconditioner.
-Scope: global
+
mtitle
+
Matrix title.
-Type: required
+Type: required
-Intent: in.
-
-Specified as: a character string, see usage notes.
-
-
On Exit
-
+A charachter variable holding a descriptive title for the matrix to be
+ written to file.
-
prec
-
Scope: local
+
filename
+
The name of the file to be written to.
-Type: required
+Type:optional.
-Intent: inout.
-
-Specified as: a preconditioner data structure precdatapsb_prec_type.
+Specified as: a character variable containing a valid file name, or
+-, in which case the default output unit 6 (i.e. standard output
+in Unix jargon) is used. Default: -.
-
info
-
Scope: global
-
-Type: required
+
iunit
+
The Fortran file unit number.
-Intent: out.
+Type:optional.
-Error code: if no error, 0 is returned.
+Specified as: an integer value. Only meaningful if filename is not -.
-Notes
-Legal inputs to this subroutine are interpreted depending on the
- 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 ;
+
On Return
+
-
BJAC
-
Precondition by a factorization of the
- block-diagonal of matrix , where block boundaries are determined
- by the data allocation boundaries for each process; requires no
- communication. Only the incomplete factorization is
- currently implemented.
+
iret
+
Error code.
+
+Type: required
+
+An integer value; 0 means no error has been detected.
diff --git a/docs/html/node127.html b/docs/html/node127.html
index e6a55901..2f598cdf 100644
--- a/docs/html/node127.html
+++ b/docs/html/node127.html
@@ -3,8 +3,8 @@
-build -- Builds a preconditioner
-
+mm_array_write -- Write a dense array from a file in the MatrixMarket format
+
@@ -14,120 +14,83 @@
-
-
+
the system sparse matrix.
-Scope: local
-
-Type: required
-
-Intent: in, target.
-
-Specified as: a sparse matrix data structure spdatapsb_Tspmat_type.
-
-
prec
-
the preconditioner.
-
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: an already initialized precondtioner data structure precdatapsb_prec_type
-
-
desc_a
-
the problem communication descriptor.
-Scope: local
-
-Type: required
-
-Intent: in, target.
-
-Specified as: a communication descriptor data structure descdatapsb_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 spbasedatapsb_T_base_sparse_mat.
-
-
vmold
-
The desired dynamic type for the internal vector storage.
+
b
+
Rigth hand side(s).
-Scope: local.
+Type: required
-Type: optional.
+An array of type real or complex, rank 1 or 2; will be written..
+
filename
+
The name of the file to be written.
-Intent: in.
+Type:optional.
-Specified as: an object of a class derived from vbasedatapsb_T_base_vect_type.
+Specified as: a character variable containing a valid file name, or
+-, in which case the default input unit 5 (i.e. standard input
+in Unix jargon) is used. Default: -.
-
imold
-
The desired dynamic type for the internal integer vector storage.
-
-Scope: local.
-
-Type: optional.
+
iunit
+
The Fortran file unit number.
-Intent: in.
+Type:optional.
-Specified as: an object of a class derived from (integer) vbasedatapsb_T_base_vect_type.
+Specified as: an integer value. Only meaningful if filename is not -.
@@ -136,59 +99,17 @@ Specified as: an object of a class derived from (integer) vbasedatapsb_T_bas
On Return
-
prec
-
the preconditioner.
-
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a precondtioner data structure precdatapsb_prec_type
-
-
info
+
iret
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.
+The base PSBLAS library contains the implementation of two simple
+preconditioning techniques:
-
-
-
Type:
-
Synchronous.
-
-
On Entry
-
-
-
prec
-
the preconditioner.
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a preconditioner data structure precdatapsb_prec_type.
-
-
x
-
the source vector.
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
-
desc_a
-
the problem communication descriptor.
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a communication data structure descdatapsb_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.
-
-
+
+
Diagonal Scaling
+
+
Block Jacobi with ILU(0) factorization
+
+
+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
-
-
On Return
-
-
-
y
-
the destination vector.
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
-
info
-
Error code.
-
-Scope: local
-
-Type: required
-
-Intent: out.
-
-An integer value; 0 means no error has been detected.
-
the communication context.
-Type: required
+Scope:global.
+
+Type:required.
Intent: in.
-Specified as: a preconditioner data structure precdatapsb_prec_type.
+Specified as: an integer value.
-
iout
-
output unit.
-Scope: local
+
ptype
+
the type of preconditioner.
+Scope: global
-Type: optional
+Type: required
Intent: in.
-Specified as: an integer number. Default: default output unit.
+Specified as: a character string, see usage notes.
-
root
-
Process from which to print
-Scope: local
+
On Exit
+
+
+
prec
+
Scope: local
-Type: optional
+Type: required
-Intent: in.
+Intent: inout.
-Specified as: an integer number between 0 and , in which case
-the specified process will print the description, or , in which case
-all processes will print. Default: 0.
+Specified as: a preconditioner data structure precdatapsb_prec_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
+ 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 ;
+
+
BJAC
+
Precondition by a factorization of the
+ block-diagonal of matrix , where block boundaries are determined
+ by the data allocation boundaries for each process; requires no
+ communication. Only the incomplete factorization is
+ currently implemented.
the system sparse matrix.
+Scope: local
+
+Type: required
+
+Intent: in, target.
+
+Specified as: a sparse matrix data structure spdatapsb_Tspmat_type.
+
prec
the preconditioner.
-Scope: local.
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: an already initialized precondtioner data structure precdatapsb_prec_type
+
desc_a
+
the problem communication descriptor.
+Scope: local
+
+Type: required
+
+Intent: in, target.
+
+Specified as: a communication descriptor data structure descdatapsb_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 spbasedatapsb_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 vbasedatapsb_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) vbasedatapsb_T_base_vect_type.
+
@@ -77,16 +136,59 @@ Scope: local.
On Return
-
precout
-
A copy of the input object.
-
+
prec
+
the preconditioner.
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: a precondtioner data structure precdatapsb_prec_type
+
info
-
Return code.
+
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.
the preconditioner.
+Scope: local
+
+Type: required
+
+Intent: in.
-Scope: local.
+Specified as: a preconditioner data structure precdatapsb_prec_type.
+
+
x
+
the source vector.
+Scope: local
Type: required
Intent: inout.
-Specified as: a preconditioner data structure precdatapsb_prec_type.
+Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
On Exit
-
+
desc_a
+
the problem communication descriptor.
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a communication data structure descdatapsb_desc_type.
-
prec
-
Scope: local
+
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 preconditioner data structure precdatapsb_prec_type.
+Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
info
-
Scope: global
+
Error code.
-Type: required
+Scope: local
+
+Type: required
Intent: out.
-Error code: if no error, 0 is returned.
+An integer value; 0 means no error has been detected.
-Notes
-Releases all internal storage.
diff --git a/docs/html/node132.html b/docs/html/node132.html
index 9c42bbe2..6244d986 100644
--- a/docs/html/node132.html
+++ b/docs/html/node132.html
@@ -3,8 +3,8 @@
-Iterative Methods
-
+descr -- Prints a description of current preconditioner
+
@@ -14,62 +14,100 @@
-
-
-
+
+
+
-In this chapter we provide routines for preconditioners and iterative
-methods. The interfaces for Krylov subspace methods are available in
-the module psb_krylov_mod.
+
the preconditioner.
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a preconditioner data structure precdatapsb_prec_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 , in which case
+the specified process will print the description, or , in which case
+all processes will print. Default: 0.
+
-This subroutine is a driver that provides a general interface for all
-the Krylov-Subspace family methods implemented in PSBLAS version 2.
-
-
-The stopping criterion can take the following values:
-
-
1
-
normwise backward error in the infinity
-norm; the iteration is stopped when
-
-
-
-
-
-
-
-
-
-
2
-
Relative residual in the 2-norm; the iteration is stopped
-when
-
-
-
-
-
-
-
-
-
-
3
-
Relative residual reduction in the 2-norm; the iteration is stopped
-when
-
-
-
-
-
-
-
-
-
-
-The behaviour is controlled by the istop argument (see
-later). In the above formulae, is the tentative solution and
- the corresponding residual at the -th iteration.
-
-
-
-
-
+
+call prec%clone(precout,info)
+
Type:
-
Synchronous.
+
Asynchronous.
On Entry
-
method
-
a string that defines the iterative method to be
- used. Supported values are:
-
the Bi-Conjugate Gradient Stabilized method with restarting;
-
-
-
RGMRES:
-
the Generalized Minimal Residual method with restarting.
-
-
-
-
-
a
-
the local portion of global sparse matrix
-.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
prec
-
The data structure containing the preconditioner.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a structured data of type precdatapsb_prec_type.
-
-
b
-
The RHS vector.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
-
x
-
The initial guess.
-
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
-
eps
-
The stopping tolerance.
-
-Scope: global
-
-Type: required
-
-Intent: in.
-
-Specified as: a real number.
-
-
desc_a
-
contains data structures for communications.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a structured data of type descdatapsb_desc_type.
-
-
itmax
-
The maximum number of iterations to perform.
+
the preconditioner.
-Scope: global
-
-Type: optional
-
-Intent: in.
-
-Default: .
-
-Specified as: an integer variable .
-
-
itrace
-
If print out an informational message about
- convergence every iterations. If print a message in
- case of convergence failure.
-
-Scope: global
-
-Type: optional
-
-Intent: in.
-
-Default: .
+Scope: local.
-
irst
-
An integer specifying the restart parameter.
-
-Scope: global
-
-Type: optional.
-
-Intent: in.
-
-Values: . This is employed for the BiCGSTABL or RGMRES
-methods, otherwise it is ignored.
+
-
-
istop
-
An integer specifying the stopping criterion.
-
-Scope: global
-
-Type: optional.
-
-Intent: in.
-
-Values: 1: use the normwise backward error, 2: use the scaled 2-norm
-of the residual, 3: use the residual reduction in the 2-norm. Default: 2.
-
+
On Return
-
x
-
The computed solution.
-
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
-
-
iter
-
The number of iterations performed.
-
-Scope: global
-
-Type: optional
-
-Intent: out.
-
-Returned as: an integer variable.
-
-
err
-
The convergence estimate on exit.
-
-Scope: global
-
-Type: optional
-
-Intent: out.
-
-Returned as: a real number.
-
-
cond
-
An estimate of the condition number of matrix ; only
- available with the method on real data.
-
-Scope: global
-
-Type: optional
-
-Intent: out.
-
-Returned as: a real number. A correct result will be greater than or
-equal to one; if specified for non-real data, or an error occurred,
-zero is returned.
+
precout
+
A copy of the input object.
info
-
Error code.
-
-Scope: local
-
-Type: required
-
-Intent: out.
-
-An integer value; 0 means no error has been detected.
+
- D. Barbieri, V. Cardellini, S. Filippone and D. Rouson
-Design Patterns for Scientific Computations on Sparse Matrices,
- HPSS 2011, Algorithms and Programming Tools for Next-Generation High-Performance Scientific Software, Bordeaux, Sep. 2011
+
+
-G. Bella, S. Filippone, A. De Maio and M. Testa,
-A Simulation Model for Forest Fires,
-in J. Dongarra, K. Madsen, J. Wasniewski, editors,
-Proceedings of PARA 04 Workshop on State of the Art
-in Scientific Computing, pp. 546-553, Lecture Notes in Computer Science,
-Springer, 2005.
-
A. Buttari, D. di Serafino, P. D'Ambra, S. Filippone,
-2LEV-D2P4: a package of high-performance preconditioners,
-Applicable Algebra in Engineering, Communications and Computing,
-Volume 18, Number 3, May, 2007, pp. 223-239
-
P. D'Ambra, S. Filippone, D. Di Serafino
-On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners
-
-Applied Numerical Mathematics, Elsevier Science,
-Volume 57, Issues 11-12, November-December 2007, Pages 1181-1196.
+
- Dongarra, J. J., DuCroz, J., Hammarling, S. and Hanson, R.,
-An Extended Set of Fortran Basic Linear Algebra Subprograms,
-ACM Trans. Math. Softw. vol. 14, 1-17, 1988.
-
- Dongarra, J., DuCroz, J., Hammarling, S. and Duff, I.,
-A Set of level 3 Basic Linear Algebra Subprograms,
-ACM Trans. Math. Softw. vol. 16, 1-17, 1990.
-
-J. J. Dongarra and R. C. Whaley,
-A User's Guide to the BLACS v. 1.1,
-Lapack Working Note 94, Tech. Rep. UT-CS-95-281, University of
-Tennessee, March 1995 (updated May 1997).
-
-I. Duff, M. Marrone, G. Radicati and C. Vittoli,
-Level 3 Basic Linear Algebra Subprograms for Sparse Matrices:
-a User Level Interface,
-ACM Transactions on Mathematical Software, 23(3), pp. 379-401, 1997.
-
-I. Duff, M. Heroux and R. Pozo,
-An Overview of the Sparse Basic Linear
-Algebra Subprograms: the New Standard from the BLAS Technical Forum,
-ACM Transactions on Mathematical Software, 28(2), pp. 239-267, 2002.
-
-S. Filippone and A. Buttari,
-Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003,
+Scope: local.
-ACM Transactions on Mathematical Software, 38(4), 2012.
-
-S. Filippone, P. D'Ambra, M. Colajanni,
-Using a Parallel Library of Sparse Linear Algebra in a Fluid Dynamics
-Applications Code on Linux Clusters,
-in G. Joubert, A. Murli, F. Peters, M. Vanneschi, editors,
-Parallel Computing - Advances & Current Issues,
-pp. 441-448, Imperial College Press, 2002.
-
-Karypis, G. and Kumar, V.,
-METIS: Unstructured Graph Partitioning and Sparse Matrix
- Ordering System.
-Minneapolis, MN 55455: University of Minnesota, Department of
- Computer Science, 1995.
-Internet Address: http://www.cs.umn.edu/~karypis.
-
-Machiels, L. and Deville, M.
-Fortran 90: An entry to object-oriented programming for the solution
- of partial differential equations.
-ACM Trans. Math. Softw. vol. 23, 32-49.
-
-M. Snir, S. Otto, S. Huss-Lederman, D. Walker and J. Dongarra,
-MPI: The Complete Reference. Volume 1 - The MPI Core, second edition,
-MIT Press, 1998.
+Type: required
+
+Intent: inout.
+
+Specified as: a preconditioner data structure precdatapsb_prec_type.
+
+
On Exit
+
+
+
prec
+
Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: a preconditioner data structure precdatapsb_prec_type.
+
+
info
+
Scope: global
+
+Type: required
+
+Intent: out.
+
+Error code: if no error, 0 is returned.
+
-The command line arguments were:
- latex2html-local_icons -noaddress -dir ../../html userhtml.tex
+In this chapter we provide routines for preconditioners and iterative
+methods. The interfaces for Krylov subspace methods are available in
+the module psb_krylov_mod.
+
+This subroutine is a driver that provides a general interface for all
+the Krylov-Subspace family methods implemented in PSBLAS version 2.
+
+
+The stopping criterion can take the following values:
+
+
1
+
normwise backward error in the infinity
+norm; the iteration is stopped when
+
+
+
+
+
+
+
+
+
+
2
+
Relative residual in the 2-norm; the iteration is stopped
+when
+
+
+
+
+
+
+
+
+
+
3
+
Relative residual reduction in the 2-norm; the iteration is stopped
+when
+
+
+
+
+
+
+
+
+
+
+The behaviour is controlled by the istop argument (see
+later). In the above formulae, is the tentative solution and
+ the corresponding residual at the -th iteration.
+
+
+
+
+
+
+
+
+
Type:
+
Synchronous.
+
+
On Entry
+
+
+
method
+
a string that defines the iterative method to be
+ used. Supported values are:
+
the Bi-Conjugate Gradient Stabilized method with restarting;
+
+
+
RGMRES:
+
the Generalized Minimal Residual method with restarting.
+
+
+
+
+
a
+
the local portion of global sparse matrix
+.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
+
prec
+
The data structure containing the preconditioner.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a structured data of type precdatapsb_prec_type.
+
+
b
+
The RHS vector.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
+
+
x
+
The initial guess.
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
+
+
eps
+
The stopping tolerance.
+
+Scope: global
+
+Type: required
+
+Intent: in.
+
+Specified as: a real number.
+
+
desc_a
+
contains data structures for communications.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
itmax
+
The maximum number of iterations to perform.
+
+Scope: global
+
+Type: optional
+
+Intent: in.
+
+Default: .
+
+Specified as: an integer variable .
+
+
itrace
+
If print out an informational message about
+ convergence every iterations. If print a message in
+ case of convergence failure.
+
+Scope: global
+
+Type: optional
+
+Intent: in.
+
+Default: .
+
+
irst
+
An integer specifying the restart parameter.
+
+Scope: global
+
+Type: optional.
+
+Intent: in.
+
+Values: . This is employed for the BiCGSTABL or RGMRES
+methods, otherwise it is ignored.
+
+
+
+
istop
+
An integer specifying the stopping criterion.
+
+Scope: global
+
+Type: optional.
+
+Intent: in.
+
+Values: 1: use the normwise backward error, 2: use the scaled 2-norm
+of the residual, 3: use the residual reduction in the 2-norm. Default: 2.
+
+
On Return
+
+
+
x
+
The computed solution.
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: a rank one array or an object of type vdatapsb_T_vect_type.
+
+
iter
+
The number of iterations performed.
+
+Scope: global
+
+Type: optional
+
+Intent: out.
+
+Returned as: an integer variable.
+
+
err
+
The convergence estimate on exit.
+
+Scope: global
+
+Type: optional
+
+Intent: out.
+
+Returned as: a real number.
+
+
cond
+
An estimate of the condition number of matrix ; only
+ available with the method on real data.
+
+Scope: global
+
+Type: optional
+
+Intent: out.
+
+Returned as: a real number. A correct result will be greater than or
+equal to one; if specified for non-real data, or an error occurred,
+zero is returned.
+
+
info
+
Error code.
+
+Scope: local
+
+Type: required
+
+Intent: out.
+
+An integer value; 0 means no error has been detected.
+
+ D. Barbieri, V. Cardellini, S. Filippone and D. Rouson
+Design Patterns for Scientific Computations on Sparse Matrices,
+ HPSS 2011, Algorithms and Programming Tools for Next-Generation High-Performance Scientific Software, Bordeaux, Sep. 2011
+
+
+G. Bella, S. Filippone, A. De Maio and M. Testa,
+A Simulation Model for Forest Fires,
+in J. Dongarra, K. Madsen, J. Wasniewski, editors,
+Proceedings of PARA 04 Workshop on State of the Art
+in Scientific Computing, pp. 546-553, Lecture Notes in Computer Science,
+Springer, 2005.
+
A. Buttari, D. di Serafino, P. D'Ambra, S. Filippone,
+2LEV-D2P4: a package of high-performance preconditioners,
+Applicable Algebra in Engineering, Communications and Computing,
+Volume 18, Number 3, May, 2007, pp. 223-239
+
P. D'Ambra, S. Filippone, D. Di Serafino
+On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners
+
+Applied Numerical Mathematics, Elsevier Science,
+Volume 57, Issues 11-12, November-December 2007, Pages 1181-1196.
+
+
+ Dongarra, J. J., DuCroz, J., Hammarling, S. and Hanson, R.,
+An Extended Set of Fortran Basic Linear Algebra Subprograms,
+ACM Trans. Math. Softw. vol. 14, 1-17, 1988.
+
+ Dongarra, J., DuCroz, J., Hammarling, S. and Duff, I.,
+A Set of level 3 Basic Linear Algebra Subprograms,
+ACM Trans. Math. Softw. vol. 16, 1-17, 1990.
+
+J. J. Dongarra and R. C. Whaley,
+A User's Guide to the BLACS v. 1.1,
+Lapack Working Note 94, Tech. Rep. UT-CS-95-281, University of
+Tennessee, March 1995 (updated May 1997).
+
+I. Duff, M. Marrone, G. Radicati and C. Vittoli,
+Level 3 Basic Linear Algebra Subprograms for Sparse Matrices:
+a User Level Interface,
+ACM Transactions on Mathematical Software, 23(3), pp. 379-401, 1997.
+
+I. Duff, M. Heroux and R. Pozo,
+An Overview of the Sparse Basic Linear
+Algebra Subprograms: the New Standard from the BLAS Technical Forum,
+ACM Transactions on Mathematical Software, 28(2), pp. 239-267, 2002.
+
+S. Filippone and M. Colajanni,
+PSBLAS: A Library for Parallel Linear Algebra
+Computation on Sparse Matrices,
+
+ACM Transactions on Mathematical Software, 26(4), pp. 527-550, 2000.
+
+S. Filippone and A. Buttari,
+Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003,
+
+ACM Transactions on Mathematical Software, 38(4), 2012.
+
+S. Filippone, P. D'Ambra, M. Colajanni,
+Using a Parallel Library of Sparse Linear Algebra in a Fluid Dynamics
+Applications Code on Linux Clusters,
+in G. Joubert, A. Murli, F. Peters, M. Vanneschi, editors,
+Parallel Computing - Advances & Current Issues,
+pp. 441-448, Imperial College Press, 2002.
+
+Karypis, G. and Kumar, V.,
+METIS: Unstructured Graph Partitioning and Sparse Matrix
+ Ordering System.
+Minneapolis, MN 55455: University of Minnesota, Department of
+ Computer Science, 1995.
+Internet Address: http://www.cs.umn.edu/~karypis.
+
+Machiels, L. and Deville, M.
+Fortran 90: An entry to object-oriented programming for the solution
+ of partial differential equations.
+ACM Trans. Math. Softw. vol. 23, 32-49.
+
+M. Snir, S. Otto, S. Huss-Lederman, D. Walker and J. Dongarra,
+MPI: The Complete Reference. Volume 1 - The MPI Core, second edition,
+MIT Press, 1998.
+
The PSBLAS library version 3 is implemented in
the Fortran 2003 [17] programming language, with reuse and/or
+ HREF="node137.html#metcalf">17] programming language, with reuse and/or
adaptation of existing Fortran 77 and Fortran 95 software, plus a
handful of C routines.
@@ -78,11 +78,11 @@ mostly in the handling of requirements for evolution and adaptation of
the library to new computing architectures and integration of
new algorithms.
For a detailed discussion of our design see [11]; other
+ HREF="node137.html#Sparse03">11]; other
works discussing advanced programming in Fortran 2003
include [1,18]; sufficient support for
+ HREF="node137.html#DesPat:11">1,18]; sufficient support for
Fortran 2003 is now available from many compilers, including the GNU
Fortran compiler from the Free Software Foundation (as of version 4.8).
@@ -91,7 +91,7 @@ Previous approaches have been based on mixing Fortran 95, with its
support for object-based design, with other languages; these have
been advocated by a number of authors,
e.g. [16]. Moreover, the Fortran 95 facilities for dynamic
+ HREF="node137.html#machiels">16]. Moreover, the Fortran 95 facilities for dynamic
memory management and interface overloading greatly enhance the
usability of the PSBLAS
subroutines. In this way, the library can take care of runtime memory
@@ -102,12 +102,12 @@ implementation or compilation time.
The presentation of the
PSBLAS library follows the general structure of the proposal for
serial Sparse BLAS [8,9], which in its turn is based on the
+ HREF="node137.html#sblas97">8,9], which in its turn is based on the
proposal for BLAS on dense matrices [15,5,6].
+ HREF="node137.html#BLAS1">15,5,6].
The applicability of sparse iterative solvers to many different areas
@@ -142,26 +142,26 @@ computational fluid dynamics applications.
@@ -57,9 +57,9 @@ The spdatapsb_Tspmat_type class
contains all information about the local portion of the sparse matrix and
its storage mode. Its design is
based on the STATE design pattern [13] as detailed
+ HREF="node137.html#DesignPatterns">13] as detailed
in [11]; the type declaration is shown in
+ HREF="node137.html#Sparse03">11]; the type declaration is shown in
figure 4 where T is a placeholder for the
data type and precision variants
@@ -141,74 +141,74 @@ variants are obtained by conversion to/from it.
Subsections
@@ -56,7 +56,7 @@ General overview
The PSBLAS library is designed to handle the implementation of
iterative solvers for sparse linear systems on distributed memory
parallel computers. The system coefficient matrix must be square;
it may be real or complex, nonsymmetric, and its sparsity pattern
@@ -75,10 +75,10 @@ calls to the serial sparse BLAS subroutines.
In a similar way, the inter-process message exchanges are encapsulated
in an applicaiton layer that has been strongly inspired by the Basic
Linear Algebra Communication Subroutines (BLACS) library [7].
+ HREF="node137.html#BLACS">7].
Usually there is no need to deal directly with MPI; however, in some
cases, MPI routines are used directly to improve efficiency. For
-further details on our communication layer see Sec. 7.
+further details on our communication layer see Sec. 7.
@@ -131,7 +131,7 @@ equation indices to processes.
In particular it is consistent with the
usage of graph partitioning tools commonly available in the
literature, e.g. METIS [14].
+ HREF="node137.html#METIS">14].
Dense vectors conform to sparse
matrices, that is, the entries of a vector follow the same distribution
of the matrix rows.
@@ -151,44 +151,44 @@ bottleneck would make this option unattractive in most cases.
Subsections
@@ -62,21 +62,21 @@ PDE.
Each point of the discretization mesh will have (at least) one
associated equation/variable, and therefore one index. We say that
point depends on point if the equation for a
variable associated with contains a term in , or equivalently
if .
After the partition of the discretization mesh into sub-domains
@@ -123,25 +123,25 @@ Overlap points do not usually exist in the basic data
distributions; however they are a feature of Domain Decomposition
Schwarz preconditioners which are the subject of related research
work [4,3].
+ HREF="node137.html#2007c">4,3].
We denote the sets of internal, boundary and halo points for a given
subdomain by , and .
Each subdomain is assigned to one process; each process usually
owns one subdomain, although the user may choose to assign more than
one subdomain to a process. If each process owns one
subdomain, the number of rows in the local sparse matrix is
@@ -149,7 +149,7 @@ subdomain, the number of rows in the local sparse matrix is
$|{\cal I}_i| + |{\cal B}_i|$
-->
, and the number of local columns
(i.e. those for which there exists at least one non-zero entry in the
@@ -157,7 +157,7 @@ local rows) is
.
@@ -170,7 +170,7 @@ Point classfication.
@@ -57,7 +57,7 @@ The vdatapsb_T_vect_type data structure
encapsulates the dense vectors in a way similar to sparse matrices,
i.e. including a base type vbasedata psb_T_base_vect_type.
The user will not, in general, access the vector components directly,
-but rather via the routines of sec. 6. Among other
+but rather via the routines of sec. 6. Among other
simple things, we define here an extraction method that can be used to
get a full copy of the part of the vector stored on the local
process.
@@ -119,44 +119,44 @@ private memory.
Subsections
An allocatable array holding a copy of the dense
vector contents. If the argument is specified, the size of the
returned array equals the minimum between and the internal size
of the vector, or 0 if is negative; otherwise, the size of the
array is the same as the internal size of the vector.
diff --git a/docs/html/node49.html b/docs/html/node49.html
index 08d0b52c..8344bc75 100644
--- a/docs/html/node49.html
+++ b/docs/html/node49.html
@@ -22,26 +22,26 @@
@@ -125,7 +125,7 @@ internally defined in the PSBLAS software package:
For example the psb_geins, psb_spins and
- psb_cdins perform the same action (see 6) on
+ psb_cdins perform the same action (see 6) on
dense matrices, sparse matrices and communication descriptors
respectively.
Interface overloading allows the usage of the same subroutine
@@ -167,26 +167,26 @@ whose current value is 3.4.0
-Among the tools routines of sec. 6, we have a number
+Among the tools routines of sec. 6, we have a number
of sorting utilities; the heap sort is implemented in terms of heaps
having the following signatures:
the scalar .
@@ -145,7 +145,7 @@ type indicated in Table 1.
x
the local portion of global dense matrix
.
@@ -158,16 +158,16 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type
specified in Table 1. The rank of must be the same of .
This function computes dot product between two vectors and
.
If and are real vectors
it computes dot-product as:
@@ -86,10 +86,10 @@ dot \leftarrow x^T y
Else if and are complex vectors then it computes dot-product as:
@@ -101,7 +101,7 @@ dot \leftarrow x^H y
-->
@@ -113,7 +113,7 @@ dot \leftarrow x^H y
psb_gedot(x, y, desc_a, info [,global])
-
+
Table 2:
Data types
@@ -121,13 +121,13 @@ Data types
, ,
Function
@@ -162,7 +162,7 @@ Data types
x
the local portion of global dense matrix
.
@@ -175,17 +175,17 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 2. The rank of must be the same of .
y
the local portion of global dense matrix
.
@@ -198,10 +198,10 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 2. The rank of must be the same of .
@@ -236,10 +236,10 @@ Default: global=.true.
Function value
is the dot product of vectors and .
@@ -272,7 +272,7 @@ An integer value; 0 means no error has been detected.
by using the following scheme:
-
-
-
-
- Next: Next: psb_gedots Generalized
- Up: Up: Computational routines
- Previous: Previous: psb_geaxpby General
- Contents
diff --git a/docs/html/node55.html b/docs/html/node55.html
index f14e7e64..1244a8d8 100644
--- a/docs/html/node55.html
+++ b/docs/html/node55.html
@@ -23,26 +23,26 @@
This subroutine computes a series of dot products among the columns of
two dense matrices and :
@@ -70,7 +70,7 @@ res(i) \leftarrow x(:,i)^T y(:,i)
-->
@@ -78,17 +78,17 @@ res(i) \leftarrow x(:,i)^T y(:,i)
If the matrices are complex, then the
usual convention applies, i.e. the conjugate transpose of is
used. If and are of rank one, then is a scalar, else it
is a rank one array.
@@ -98,7 +98,7 @@ is a rank one array.
call psb_gedots(res, x, y, desc_a, info)
-
+
Table 3:
Data types
@@ -106,13 +106,13 @@ Data types
, ,
Subroutine
@@ -147,7 +147,7 @@ Data types
x
the local portion of global dense matrix
.
@@ -160,17 +160,17 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 3. The rank of must be the same of .
y
the local portion of global dense matrix
.
@@ -183,10 +183,10 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 3. The rank of must be the same of .
@@ -206,10 +206,10 @@ Specified as: an object of type descdatapsb_desc_type.
res
is the dot product of vectors and .
@@ -237,26 +237,26 @@ An integer value; 0 means no error has been detected.
@@ -55,12 +55,12 @@ psb_normi -- Infinity-Norm of Vector
This function computes
the infinity-norm of a vector .
If is a real vector
it computes infinity norm as:
@@ -73,14 +73,14 @@ amax \leftarrow \max_i |x_i|
-->
else if is a complex vector then it computes the infinity-norm as:
@@ -92,7 +92,7 @@ amax \leftarrow \max_i {(|re(x_i)| + |im(x_i)|)}
-->
@@ -107,7 +107,7 @@ psb_normi(x, desc_a, info [,global])
-
+
Table 4:
Data types
@@ -115,11 +115,11 @@ Data types
Function
@@ -158,7 +158,7 @@ Data types
x
the local portion of global dense matrix
.
@@ -205,7 +205,7 @@ Default: global=.true.
Function value
is the infinity norm of vector .
@@ -238,7 +238,7 @@ An integer value; 0 means no error has been detected.
by using the following scheme:
-
-
-
-
- Next: Next: psb_geamaxs Generalized
- Up: Up: Computational routines
- Previous: Previous: psb_gedots Generalized
- Contents
diff --git a/docs/html/node57.html b/docs/html/node57.html
index fdd2f842..60bc14e4 100644
--- a/docs/html/node57.html
+++ b/docs/html/node57.html
@@ -23,26 +23,26 @@
This function computes the 1-norm of a vector .
If is a real vector
it computes 1-norm as:
@@ -72,14 +72,14 @@ asum \leftarrow \|x_i\|
-->
else if is a complex vector then it computes 1-norm as:
@@ -91,7 +91,7 @@ asum \leftarrow \|re(x)\|_1 + \|im(x)\|_1
-->
@@ -106,7 +106,7 @@ psb_norm1(x, desc_a, info [,global])
-
+
Table 6:
Data types
@@ -114,11 +114,11 @@ Data types
Function
@@ -157,7 +157,7 @@ Data types
x
the local portion of global dense matrix
.
@@ -203,7 +203,7 @@ Default: global=.true.
Function value
is the 1-norm of vector .
@@ -236,7 +236,7 @@ An integer value; 0 means no error has been detected.
by using the following scheme:
-
-
-
-
- Next: Next: psb_geasums Generalized
- Up: Up: Computational routines
- Previous: Previous: psb_geamaxs Generalized
- Contents
diff --git a/docs/html/node59.html b/docs/html/node59.html
index 4ab320ea..bed7c250 100644
--- a/docs/html/node59.html
+++ b/docs/html/node59.html
@@ -23,26 +23,26 @@
@@ -55,7 +55,7 @@ psb_geasums -- Generalized 1-Norm of Vector
This subroutine computes a series of 1-norms on the columns of
a dense matrix :
@@ -67,19 +67,19 @@ res(i) \leftarrow \max_k |x(k,i)|
-->
This function computes the 1-norm of a vector .
If is a real vector
it computes 1-norm as:
@@ -92,14 +92,14 @@ res(i) \leftarrow \|x_i\|
-->
else if is a complex vector then it computes 1-norm as:
@@ -111,7 +111,7 @@ res(i) \leftarrow \|re(x)\|_1 + \|im(x)\|_1
-->
@@ -125,7 +125,7 @@ call psb_geasums(res, x, desc_a, info)
-
+
Table 7:
Data types
@@ -133,11 +133,11 @@ Data types
Subroutine
@@ -176,7 +176,7 @@ Data types
x
the local portion of global dense matrix
.
@@ -209,7 +209,7 @@ Specified as: an object of type descdatapsb_desc_type.
res
contains the 1-norm of (the columns of) .
@@ -237,26 +237,26 @@ An integer value; 0 means no error has been detected.
@@ -61,7 +61,7 @@ space to which there corresponds an index space and a matrix sparsity
pattern. As an example, consider a cell-centered finite-volume
discretization of the Navier-Stokes equations on a simulation domain;
the index space is isomorphic to the set of cell centers,
whereas the pattern of the associated linear system matrix is
@@ -72,7 +72,7 @@ by the discretization stencil.
Thus the first order of business is to establish an index space, and
this is done with a call to psb_cdall in which we specify the
size of the index space and the allocation of the elements of the
index space to the various processes making up the MPI (virtual)
@@ -81,22 +81,22 @@ parallel machine.
The index space is partitioned among processes, and this creates a
mapping from the “global” numbering to a numbering
“local” to each process; each process will own a certain subset
, each element of which corresponds to a certain
element of . The user does not set explicitly this mapping;
when the application needs to indicate to which element of the index
@@ -106,7 +106,7 @@ library will translate into the appropriate “local” numbering.
For a given index space there are many possible associated
topologies, i.e. many different discretization stencils; thus the
@@ -115,7 +115,7 @@ defined a sparsity pattern, either explicitly through psb_cdins
or implicitly through psb_spins. The descriptor is finalized
with a call to psb_cdasb and a sparse matrix with a call to
psb_spasb. After psb_cdasb each process will have
defined a set of “halo” (or “ghost”) indices
@@ -123,16 +123,16 @@ defined a set of “halo” (or “ghost”) indices
$n_{\hbox{row}_i}+1\dots n_{\hbox{col}_i}$
-->
, denoting elements of the index
space that are not assigned to process ; however the
variables associated with them are needed to complete computations
associated with the sparse matrix , and thus they have to be
fetched from (neighbouring) processes. The descriptor of the index
@@ -247,33 +247,33 @@ from optimal.
Subsections
This function computes the 2-norm of a vector .
If is a real vector
it computes 2-norm as:
@@ -72,14 +72,14 @@ nrm2 \leftarrow \sqrt{x^T x}
-->
else if is a complex vector then it computes 2-norm as:
@@ -91,7 +91,7 @@ nrm2 \leftarrow \sqrt{x^H x}
-->
@@ -100,7 +100,7 @@ nrm2 \leftarrow \sqrt{x^H x}
-
+
Table 8:
Data types
@@ -108,11 +108,11 @@ Data types
Function
@@ -157,7 +157,7 @@ psb_norm2(x, desc_a, info [,global])
x
the local portion of global dense matrix
.
@@ -203,7 +203,7 @@ Default: global=.true.
Function Value
is the 2-norm of vector .
@@ -238,7 +238,7 @@ An integer value; 0 means no error has been detected.
by using the following scheme:
-
-
-
-
- Next: Next: psb_genrm2s Generalized
- Up: Up: Computational routines
- Previous: Previous: psb_geasums Generalized
- Contents
diff --git a/docs/html/node61.html b/docs/html/node61.html
index 867d4545..bdbc1061 100644
--- a/docs/html/node61.html
+++ b/docs/html/node61.html
@@ -23,26 +23,26 @@
This function computes the infinity-norm of a matrix :
@@ -68,7 +68,7 @@ nrmi \leftarrow \|A\|_\infty
-->
@@ -77,11 +77,11 @@ nrmi \leftarrow \|A\|_\infty
where:
represents the global matrix
@@ -89,7 +89,7 @@ where:
-
+
Table 11:
Data types
@@ -97,7 +97,7 @@ Data types
Function
@@ -138,7 +138,7 @@ psb_normi(A, desc_a, info)
a
the local portion of the global sparse matrix
.
@@ -166,7 +166,7 @@ Specified as: an object of type descdatapsb_desc_type.
Function value
is the infinity-norm of sparse submatrix .
diff --git a/docs/html/node64.html b/docs/html/node64.html
index 9f15d14c..12cdf45b 100644
--- a/docs/html/node64.html
+++ b/docs/html/node64.html
@@ -23,26 +23,26 @@
the local portion of the sparse matrix
.
@@ -244,7 +244,7 @@ Specified as: an object of type spdatapsb_Tspmat_type.
x
the local portion of global dense matrix
.
@@ -258,16 +258,16 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 12. The rank of must be the same of .
@@ -336,7 +336,7 @@ Type: optional
Intent: in.
Default:
@@ -354,10 +354,10 @@ Type: optional
Intent: inout.
Specified as: a rank one array of the same type of and with
the TARGET attribute.
@@ -369,7 +369,7 @@ the TARGET attribute.
y
the local portion of result matrix .
@@ -400,26 +400,26 @@ An integer value; 0 means no error has been detected.
the global portion of the sparse matrix
.
@@ -218,7 +219,7 @@ Specified as: an object type specified in
x
the local portion of global dense matrix
.
@@ -232,16 +233,16 @@ Intent: in.
Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
containing numbers of type specified in
Table 13. The rank of must be the same of .
@@ -308,7 +309,7 @@ Type: optional
Intent: in.
Default:
@@ -334,7 +335,7 @@ Type: optional
Intent: in.
Default:
@@ -380,7 +381,7 @@ Default:
@@ -397,7 +398,7 @@ Type: optional
Intent: inout.
Specified as: a rank one array of the same type of with the
TARGET attribute.
@@ -410,7 +411,7 @@ TARGET attribute.
y
the local portion of global dense matrix
.
@@ -442,26 +443,26 @@ An integer value; 0 means no error has been detected.
-The routines in this chapter implement various global communication operators
-on vectors associated with a discretization mesh. For auxiliary communication
-routines not tied to a discretization space see 6.
+
the local portion of global dense vector
+ .
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: an object of type vdatapsb_T_vect_type
+ containing numbers of type specified in
+ Table 2.
+
+
+
y
+
the local portion of global dense vector
+ .
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: an object of type vdatapsb_T_vect_type
+ containing numbers of type specified in
+ Table 2.
+
+
+
desc_a
+
contains data structures for communications.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: an object of type descdatapsb_desc_type.
+
+
+
On Return
+
+
+
y
+
the local portion of result submatrix .
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: an object of type vdatapsb_T_vect_type containing numbers of the type
+ indicated in Table 14.
+
+
+
info
+
Error code.
+
+Scope: local
+
+Type: required
+
+Intent: out.
+
+An integer value; 0 means no error has been detected.
+
global dense matrix the local portion of global dense vector
+ .
+
+Scope: local
+
+Type: required
+Intent: in.
+
+Specified as: an object of type vdatapsb_T_vect_type
+ containing numbers of type specified in
+ Table 2.
+
+
+
y
+
the local portion of global dense vector
+ .
+
Scope: local
Type: required
-Intent: inout.
+Intent: in.
-Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
-containing numbers of type specified in
-Table 14.
+Specified as: an object of type vdatapsb_T_vect_type
+ containing numbers of type specified in
+ Table 2.
+
desc_a
contains data structures for communications.
@@ -166,41 +173,29 @@ Type: required
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
+Specified as: an object of type descdatapsb_desc_type.
+
-
work
-
the work array.
+
flag
+
check if any of the , and in case returns error halting the computation.
Scope: local
Type: optional
+ Intent: in.
-Intent: inout.
-
-Specified as: a rank one array of the same type of .
-
-
data
-
index list selector.
-
-Scope: global
-
-Type: optional
-
-Specified as: an integer. Values:psb_comm_halo_,psb_comm_mov_,
-psb_comm_ext_, default: psb_comm_halo_. Chooses the
-index list on which to base the data exchange.
-
-
+Specified as: the logical value flag=.true.
+
On Return
x
-
global dense result matrix the local portion of result submatrix .
@@ -210,15 +205,12 @@ Type: required
Intent: inout.
-Returned as: a rank one or two array
-containing numbers of type specified in
-Table 14.
+Specified as: an object of type vdatapsb_T_vect_type containing numbers of the type
+ indicated in Table 14.
+
info
-
the local portion of result submatrix .
+
Error code.
Scope: local
@@ -226,406 +218,34 @@ Type: required
Intent: out.
-An integer value that contains an error code.
+An integer value; 0 means no error has been detected.
-
-
-
Figure 7:
-Sample discretization mesh.
-
-
-
-
-
-
-
-
-
-
-
-Usage Example
-Consider the discretization mesh depicted in fig. 7,
-partitioned among two processes as shown by the dashed line; the data
-distribution is such that each process will own 32 entries in the
-index space, with a halo made of 8 entries placed at local indices 33
-through 40. If process 0 assigns an initial value of 1 to its entries
-in the vector, and process 1 assigns a value of 2, then after a
-call to psb_halo the contents of the local vectors will be the
-following:
-
-
is the overlap operator; it is the composition of two
-operators and .
-
-
+
+psb_geinv(x, y, desc_a, info, [flag)
+
-
+
-
Table 15:
+
Table 16:
Data types
-
-
+
,
-
Subroutine
+ ALT="$x$">,
+
Function
Short Precision Real
-
psb_ovrl
+
psb_geinv
Long Precision Real
-
psb_ovrl
+
psb_geinv
Short Precision Complex
-
psb_ovrl
+
psb_geinv
Long Precision Complex
-
psb_ovrl
+
psb_geinv
-
+
-
-
-
-
-
Type:
Synchronous.
+
On Entry
x
-
global dense matrix the local portion of global dense vector
+ .
-
+
Scope: local
Type: required
-Intent: inout.
+Intent: in.
-Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
-containing numbers of type specified in
-Table 15.
+Specified as: an object of type vdatapsb_T_vect_type
+ containing numbers of type specified in
+ Table 2.
+
desc_a
contains data structures for communications.
@@ -175,65 +154,29 @@ Type: required
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
-
-
update
-
Update operator.
-
-
update = psb_none_
-
Do nothing;
-
-
update = psb_add_
-
Sum overlap entries, i.e. apply ;
-
-
update = psb_avg_
-
Average overlap entries, i.e. apply ;
-
-
-Scope: global
-
-Intent: in.
-
-Default:
-
-
-Scope: global
-
-Specified as: a integer variable.
+Specified as: an object of type descdatapsb_desc_type.
+
-
work
-
the work array.
+
flag
+
check if any of the , and in case returns error halting the computation.
Scope: local
Type: optional
+ Intent: in.
-Intent: inout.
-
-Specified as: a one dimensional array of the same type of .
-
-
+Specified as: the logical value flag=.true.
+
On Return
-
x
-
global dense result matrix y
+
the local portion of result submatrix .
@@ -241,11 +184,11 @@ Scope: local
Type: required
-Intent: inout.
+Intent: out.
-Specified as: an array of rank one or two
-containing numbers of type specified in
-Table 15.
+Specified as: an object of type vdatapsb_T_vect_type containing numbers of the type
+ indicated in Table 16.
+
info
Error code.
@@ -260,500 +203,30 @@ An integer value; 0 means no error has been detected.
-
-Notes
-
-
-
If there is no overlap in the data distribution associated with
- the descriptor, no operations are performed;
-
-
The operator performs the reduction sum of overlap
-elements; it is a “prolongation” operator that
-replicates overlap elements, accounting for the physical replication
-of data;
-
-
The operator performs a scaling on the overlap elements by
-the amount of replication; thus, when combined with the reduction
-operator, it implements the average of replicated elements over all of
-their instances.
-
-
-
-
-
-
-
-
Figure 8:
-Sample discretization mesh.
-
-
-
-
-
-
-
-
-
-
-Example of use
-Consider the discretization mesh depicted in fig. 8,
-partitioned among two processes as shown by the dashed lines, with an
-overlap of 1 extra layer with respect to the partition of
-fig. 7; the data
-distribution is such that each process will own 40 entries in the
-index space, with an overlap of 16 entries placed at local indices 25
-through 40; the halo will run from local index 41 through local index 48.. If process 0 assigns an initial value of 1 to its entries
-in the vector, and process 1 assigns a value of 2, then after a
-call to psb_ovrl with psb_avg_ and a call to
-psb_halo_ the contents of the local vectors will be the
-following (showing a transition among the two subdomains)
-
-
+The routines in this chapter implement various global communication operators
+on vectors associated with a discretization mesh. For auxiliary communication
+routines not tied to a discretization space see 6.
-
-
-
-
Table 16:
-Data types
-
-
-
-
-
Subroutine
-
-
Integer
-
psb_gather
-
-
Short Precision Real
-
psb_gather
-
-
Long Precision Real
-
psb_gather
-
-
Short Precision Complex
-
psb_gather
-
-
Long Precision Complex
-
psb_gather
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Type:
-
Synchronous.
-
-
On Entry
-
-
-
loc_x
-
the local portion of global dense matrix
-.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
-indicated in Table 16.
-
-
desc_a
-
contains data structures for communications.
-
-Scope: local
-
-Type: required
-
-Intent: in.
-
-Specified as: a structured data of type descdatapsb_desc_type.
-
-
root
-
The process that holds the global copy. If all
- the processes will have a copy of the global vector.
-
-Scope: global
-
-Type: optional
-
-Intent: in.
-
-Specified as: an integer variable
-, default .
-
-
On Return
-
-
-
glob_x
-
The array where the local parts must be gathered.
-
-Scope: global
-
-Type: required
-
-Intent: out.
-
-Specified as: a rank one or two array with the ALLOCATABLE attribute.
-
-
info
-
Error code.
-
-Scope: local
-
-Type: required
-
-Intent: out.
-
-An integer value; 0 means no error has been detected.
-
-These subroutines scatters the portions of global dense matrix owned
-by a process to all the processes in the processes grid.
+These subroutines gathers the values of the halo
+elements:
The array that must be scattered into local pieces.
+
x
+
global dense matrix .
-Scope: global
+Scope: local
-Type: required
+Type: required
-Intent: in.
+Intent: inout.
-Specified as: a rank one or two array.
+Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
+containing numbers of type specified in
+Table 17.
desc_a
contains data structures for communications.
@@ -180,61 +168,57 @@ Intent: in.
Specified as: a structured data of type descdatapsb_desc_type.
-
root
-
The process that holds the global copy. If all
- the processes have a copy of the global vector.
+
work
+
the work array.
-Scope: global
+Scope: local
Type: optional
-Intent: in.
+Intent: inout.
-Specified as: an integer variable
-, default
-psb_root_, i.e. process 0.
+Specified as: a rank one array of the same type of .
-
mold
-
The desired dynamic type for the internal vector storage.
+
data
+
index list selector.
-Scope: local.
-
-Type: optional.
+Scope: global
-Intent: in.
+Type: optional
-Specified as: an object of a class derived from vbasedatapsb_T_base_vect_type; this is
-only allowed when loc_x is of type vdatapsb_T_vect_type.
+Specified as: an integer. Values:psb_comm_halo_,psb_comm_mov_,
+psb_comm_ext_, default: psb_comm_halo_. Chooses the
+index list on which to base the data exchange.
+
+
On Return
-
loc_x
-
the local portion of global dense matrix
-.
+
x
+
global dense result matrix .
Scope: local
-Type: required
+Type: required
-Intent: out.
+Intent: inout.
-Specified as: a rank one or two ALLOCATABLE array or an object of type vdatapsb_T_vect_type containing numbers of the type
-indicated in Table 17.
+Returned as: a rank one or two array
+containing numbers of type specified in
+Table 17.
info
-
Error code.
+
the local portion of result submatrix .
Scope: local
@@ -242,34 +226,406 @@ Type: required
Intent: out.
-An integer value; 0 means no error has been detected.
+An integer value that contains an error code.
+
+
+
Figure 7:
+Sample discretization mesh.
+
+
+
+
+
+
+
+
+
+
+
+Usage Example
+Consider the discretization mesh depicted in fig. 7,
+partitioned among two processes as shown by the dashed line; the data
+distribution is such that each process will own 32 entries in the
+index space, with a halo made of 8 entries placed at local indices 33
+through 40. If process 0 assigns an initial value of 1 to its entries
+in the vector, and process 1 assigns a value of 2, then after a
+call to psb_halo the contents of the local vectors will be the
+following:
+
+
+These subroutines applies an overlap operator to the input vector:
+
+
+
+
+
+
+
+
+
+
+where:
+
+
+
is the global dense submatrix
+
+
+
is the overlap operator; it is the composition of two
+operators and .
+
+
+
+
+
+
+
+
Table 18:
+Data types
+
+
+
+
+
Subroutine
+
+
Short Precision Real
+
psb_ovrl
+
+
Long Precision Real
+
psb_ovrl
+
+
Short Precision Complex
+
psb_ovrl
+
+
Long Precision Complex
+
psb_ovrl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Type:
+
Synchronous.
+
+
On Entry
+
+
+
x
+
global dense matrix .
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
+containing numbers of type specified in
+Table 18.
+
+
desc_a
+
contains data structures for communications.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
update
+
Update operator.
+
+
update = psb_none_
+
Do nothing;
+
+
update = psb_add_
+
Sum overlap entries, i.e. apply ;
+
+
update = psb_avg_
+
Average overlap entries, i.e. apply ;
+
+
+Scope: global
+
+Intent: in.
+
+Default:
+
+
+Scope: global
+
+Specified as: a integer variable.
+
+
work
+
the work array.
+
+Scope: local
+
+Type: optional
+
+Intent: inout.
+
+Specified as: a one dimensional array of the same type of .
+
+
+
+
On Return
+
+
+
x
+
global dense result matrix .
+
+Scope: local
+
+Type: required
+
+Intent: inout.
+
+Specified as: an array of rank one or two
+containing numbers of type specified in
+Table 18.
+
+
info
+
Error code.
+
+Scope: local
+
+Type: required
+
+Intent: out.
-Data management routines
-
+An integer value; 0 means no error has been detected.
+
If there is no overlap in the data distribution associated with
+ the descriptor, no operations are performed;
+
+
The operator performs the reduction sum of overlap
+elements; it is a “prolongation” operator that
+replicates overlap elements, accounting for the physical replication
+of data;
+
+
The operator performs a scaling on the overlap elements by
+the amount of replication; thus, when combined with the reduction
+operator, it implements the average of replicated elements over all of
+their instances.
+
+
+
+
+
+
+
+
Figure 8:
+Sample discretization mesh.
+
+
+
+
+
+
+
+
+
+
+Example of use
+Consider the discretization mesh depicted in fig. 8,
+partitioned among two processes as shown by the dashed lines, with an
+overlap of 1 extra layer with respect to the partition of
+fig. 7; the data
+distribution is such that each process will own 40 entries in the
+index space, with an overlap of 16 entries placed at local indices 25
+through 40; the halo will run from local index 41 through local index 48.. If process 0 assigns an initial value of 1 to its entries
+in the vector, and process 1 assigns a value of 2, then after a
+call to psb_ovrl with psb_avg_ and a call to
+psb_halo_ the contents of the local vectors will be the
+following (showing a transition among the two subdomains)
+
+
+These subroutines collect the portions of global dense matrix
+distributed over all process into one single array stored on one
+process.
-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.
+
+
+
+
+
+
+
+
+where:
-
On Entry
-
-
-
Type:
-
Synchronous.
-
-
icontxt
-
the communication context.
-
-Scope:global.
-
-Type:required.
-
-Intent: in.
-
-Specified as: an integer value.
-
-
vg
-
Data allocation: each index
is allocated
- to process .
-
-Scope:global.
-
-Type:optional.
-
-Intent: in.
-
-Specified as: an integer array.
+ WIDTH="90" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img81.png"
+ ALT="$glob\_x_{1:m,1:n}$">
-
flag
-
Specifies whether entries in are zero- or one-based.
-
-Scope:global.
-
-Type:optional.
-
-Intent: in.
-
-Specified as: an integer value , default .
-
-
-
-
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.
+
+
is the local portion of global dense matrix on
+process .
-
parts
-
the subroutine that defines the partitioning scheme.
-
-Scope:global.
-
-Type:required.
-
-Specified as: a subroutine.
+
+
is the collect function.
-
vl
-
Data allocation: the set of global indices
- belonging to the calling process.
-
-Scope:local.
+
+
+
+
+
+
+
Table 19:
+Data types
+
+
+
+
+
Subroutine
+
+
Integer
+
psb_gather
+
+
Short Precision Real
+
psb_gather
+
+
Long Precision Real
+
psb_gather
+
+
Short Precision Complex
+
psb_gather
+
+
Long Precision Complex
+
psb_gather
+
+
+
+
+
+
-Type:optional.
+
+
-Intent: in.
+
-Specified as: an integer array.
+
+
+
+
Type:
+
Synchronous.
-
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.
+
On Entry
+
-
repl
-
Data allocation: build a replicated index space
- (i.e. all processes own all indices).
+
loc_x
+
the local portion of global dense matrix
+.
-Scope:global.
+Scope: local
-Type:optional.
+Type: required
Intent: in.
-Specified as: the logical value .true.
+Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type
+indicated in Table 19.
-
globalcheck
-
Data allocation: do global checks on the local
- index lists vl
+
desc_a
+
contains data structures for communications.
-Scope:global.
+Scope: local
-Type:optional.
+Type: required
Intent: in.
-Specified as: a logical value, default: .false.
+Specified as: a structured data of type descdatapsb_desc_type.
-
lidx
-
Data allocation: the set of local indices
- to be assigned to the global indices .
+
root
+
The process that holds the global copy. If all
+ the processes will have a copy of the global vector.
-Scope:local.
+Scope: global
-Type:optional.
+Type: optional
Intent: in.
-Specified as: an integer array.
+Specified as: an integer variable
+, default .
-
-
-
-
On Return
-
desc_a
-
the communication descriptor.
+
glob_x
+
The array where the local parts must be gathered.
-Scope:local.
+Scope: global
-Type:required.
+Type: required
Intent: out.
-Specified as: a structured data of type descdatapsb_desc_type.
+Specified as: a rank one or two array with the ALLOCATABLE attribute.
info
Error code.
@@ -250,199 +239,30 @@ 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:
-
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
-
-; if 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
- is assigned to process .
- The vector vg must be identical on all
- calling processes; its entries may have the ranges
- or according to the value of flag.
- The size 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 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 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 gets assigned a consecutive chunk of 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])
-
+These subroutines scatters the portions of global dense matrix owned
+by a process to all the processes in the processes grid.
-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 ; the starting index should
-belong to the current process.
-In the second form only the remote indices are specified.
+
+
+
-
+
+
+
+
+where:
-
Type:
-
Asynchronous.
+
+
is the global matrix
+
-
On Entry
-
+
+
is the local portion of global dense matrix on
+process .
-
nz
-
the number of points being inserted.
-
-Scope: local.
+
+
is the scatter function.
+
+
+
+
+
+
+
+
Table 20:
+Data types
+
+
+
+
+
Subroutine
+
+
Integer
+
psb_scatter
+
+
Short Precision Real
+
psb_scatter
+
+
Long Precision Real
+
psb_scatter
+
+
Short Precision Complex
+
psb_scatter
+
+
Long Precision Complex
+
psb_scatter
+
+
+
+
+
+
-Type: required.
+
+
-Intent: in.
+
-Specified as: an integer value.
+
+
+
+
Type:
+
Synchronous.
+
+
On Entry
+
-
ia
-
the indices of the starting vertex of the edges being inserted.
+
glob_x
+
The array that must be scattered into local pieces.
-Scope: local.
+Scope: global
-Type: required.
+Type: required
Intent: in.
-Specified as: an integer array of length .
+Specified as: a rank one or two array.
-
ja
-
the indices of the end vertex of the edges being inserted.
+
desc_a
+
contains data structures for communications.
-Scope: local.
+Scope: local
-Type: required.
+Type: required
Intent: in.
-Specified as: an integer array of length .
+Specified as: a structured data of type descdatapsb_desc_type.
-
mask
-
Mask entries in ja, they are inserted only when the
- corresponding mask entries are .true.
+
root
+
The process that holds the global copy. If all
+ the processes have a copy of the global vector.
-Scope: local.
+Scope: global
-Type: optional.
+Type: optional
Intent: in.
-Specified as: a logical array of length , default .true..
+Specified as: an integer variable
+, default
+psb_root_, i.e. process 0.
-
lidx
-
User defined local indices for ja.
+
mold
+
The desired dynamic type for the internal vector storage.
Scope: local.
@@ -148,28 +211,27 @@ Type: optional.
Intent: in.
-Specified as: an integer array of length .
+Specified as: an object of a class derived from vbasedatapsb_T_base_vect_type; this is
+only allowed when loc_x is of type vdatapsb_T_vect_type.
-
-
-
-
On Return
-
desc_a
-
the updated communication descriptor.
+
loc_x
+
the local portion of global dense matrix
+.
-Scope:local.
+Scope: local
-Type:required.
+Type: required
-Intent: inout.
+Intent: out.
-Specified as: a structured data of type descdatapsb_desc_type.
+Specified as: a rank one or two ALLOCATABLE array or an object of type vdatapsb_T_vect_type containing numbers of the type
+indicated in Table 20.
info
Error code.
@@ -182,76 +244,32 @@ 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 .
-
-
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 .
-
-
-
-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.
-
+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.
-
Type:
-
Asynchronous.
-
-
On Entry
+
On Entry
-
desc_in
-
the communication descriptor.
+
Type:
+
Synchronous.
+
+
icontxt
+
the communication context.
-Scope:local.
+Scope:global.
Type:required.
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
+Specified as: an integer value.
+
+
vg
+
Data allocation: each index
+ is allocated
+ to process .
+
+Scope:global.
+
+Type:optional.
+
+Intent: in.
+
+Specified as: an integer array.
+
+
flag
+
Specifies whether entries in are zero- or one-based.
+
+Scope:global.
+
+Type:optional.
+
+Intent: in.
+
+Specified as: an integer value , default .
+
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
+ 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
+ to be assigned to the global indices .
+
+Scope:local.
+
+Type:optional.
+
+Intent: in.
+
+Specified as: an integer array.
+
@@ -85,8 +226,8 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
-
desc_out
-
the communication descriptor copy.
+
desc_a
+
the communication descriptor.
Scope:local.
@@ -110,7 +251,200 @@ 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:
+
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
+
+; if 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
+ is assigned to process .
+ The vector vg must be identical on all
+ calling processes; its entries may have the ranges
+ or according to the value of flag.
+ The size 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 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 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 gets assigned a consecutive chunk of 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.
+
+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 ; the starting index should
+belong to the current process.
+In the second form only the remote indices are specified.
+
Type:
-
Synchronous.
+
Asynchronous.
On Entry
-
desc_a
-
the communication descriptor to be freed.
+
nz
+
the number of points being inserted.
-Scope:local.
+Scope: local.
-Type:required.
+Type: required.
-Intent: inout.
+Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
+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 .
+
+
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 .
+
+
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 , default .true..
+
+
lidx
+
User defined local indices for ja.
+
+Scope: local.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: an integer array of length .
@@ -83,6 +160,17 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
+
desc_a
+
the updated communication descriptor.
+
+Scope:local.
+
+Type:required.
+
+Intent: inout.
+
+Specified as: a structured data of type descdatapsb_desc_type.
+
info
Error code.
@@ -94,10 +182,78 @@ 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 .
+
+
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 .
+
+
+
+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_cdbldext(a,desc_a,nl,desc_out, info, extype)
+call psb_cdasb(desc_a, info [, mold])
-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.
@@ -69,16 +66,6 @@ through the input sparse matrix a.
On Entry
-
a
-
A sparse matrix
-Scope:local.
-
-Type:required.
-
-Intent: in.
-
-Specified as: a structured data type.
-
desc_a
the communication descriptor.
@@ -86,37 +73,20 @@ Scope:local.
Type:required.
-Intent: in.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
nl
-
the number of additional layers desired.
-
-Scope:global.
-
-Type:required.
-
-Intent: in.
+Intent: inout.
-Specified as: an integer value .
+Specified as: a structured data of type descdatapsb_desc_type.
-
extype
-
the kind of estension required.
+
mold
+
The desired dynamic type for the internal index storage.
-Scope:global.
+Scope: local.
-Type:optional .
+Type: optional.
Intent: in.
-Specified as: an integer value
-psb_ovt_xhal_, psb_ovt_asov_, default: psb_ovt_xhal_
-
-
+Specified as: a object of type derived from (integer) vbasedatapsb_T_base_vect_type.
@@ -125,8 +95,8 @@ Specified as: an integer value
On Return
-
desc_out
-
the extended communication descriptor.
+
desc_a
+
the communication descriptor.
Scope:local.
@@ -148,51 +118,16 @@ 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.
+
On exit from this routine the descriptor is in the assembled
+ state.
the communication descriptor.
Scope:local.
@@ -75,18 +75,8 @@ Type:required.
Intent: in.
Specified as: a structured data of type descdatapsb_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.
+
+
@@ -95,16 +85,16 @@ Specified as: an integer value.
On Return
-
a
-
the matrix to be allocated.
+
desc_out
+
the communication descriptor copy.
-Scope:local
+Scope:local.
-Type:required
+Type:required.
Intent: out.
-Specified as: a structured data of type spdatapsb_Tspmat_type.
+Specified as: a structured data of type descdatapsb_desc_type.
info
Error code.
@@ -118,23 +108,6 @@ 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 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.
-
-
diff --git a/docs/html/node79.html b/docs/html/node79.html
index 562a80b0..17081ee5 100644
--- a/docs/html/node79.html
+++ b/docs/html/node79.html
@@ -3,8 +3,8 @@
-psb_spins -- Insert a set of coefficients into a sparse matrix
-
+psb_cdfree -- Frees a communication descriptor
+
@@ -16,169 +16,65 @@
-
+
-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])
+call psb_cdfree(desc_a, info)
Type:
-
Asynchronous.
+
Synchronous.
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 .
-
-
irp
-
the row pointers of the coefficients to be inserted.
-
-Scope:local.
-
-Type:required.
-
-Intent: in.
-
-Specified as: an integer array of size .
-
-
ja
-
the column indices of the coefficients to be inserted.
-
-Scope:local.
-
-Type:required.
-
-Intent: in.
-
-Specified as: an integer array of size .
-
-
val
-
the coefficients to be inserted.
+
desc_a
+
the communication descriptor to be freed.
Scope:local.
Type:required.
-Intent: in.
-
-Specified as: an array of size . Must be of the same type and kind
-of the coefficients of the sparse matrix .
-
-
desc_a
-
The communication descriptor.
-
-Scope: local.
-
-Type: required.
-
Intent: inout.
-Specified as: a variable of type descdatapsb_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..
-
-
+Specified as: a structured data of type descdatapsb_desc_type.
the matrix into which coefficients will be inserted.
-
-Scope:local
-
-Type:required
-
-Intent: inout.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
desc_a
-
The communication descriptor.
-
-Scope: local.
-
-Type: required.
-
-Intent: inout.
-
-Specified as: a variable of type descdatapsb_desc_type.
-
info
Error code.
@@ -223,98 +97,7 @@ 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
-, for ;
- these triples should belong to the current process, i.e.
- should be one of the local indices, but are otherwise arbitrary;
-
-
In CSR format the coefficients to be inserted for each input row
- are represented by the ordered triples
-, for
-
-;
- these triples should belong to the current process, i.e.
- 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;
-
-
Any coefficients from matrix rows not owned by the calling
- process 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.
-
+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.
A sparse matrix
Scope:local.
Type:required.
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
-
-
afmt
-
the storage format for the sparse matrix.
-
-Scope: local.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: an array of characters. Defalt: 'CSR'.
+Specified as: a structured data type.
-
upd
-
Provide for updates to the matrix coefficients.
+
desc_a
+
the communication descriptor.
-Scope: global.
+Scope:local.
-Type: optional.
+Type:required.
Intent: in.
-Specified as: integer, possible values: psb_upd_srch_, psb_upd_perm_
+Specified as: a structured data of type spdatapsb_Tspmat_type.
-
dupl
-
How to handle duplicate coefficients.
+
nl
+
the number of additional layers desired.
-Scope: global.
+Scope:global.
-Type: optional.
+Type:required.
Intent: in.
-Specified as: integer, possible values: psb_dupl_ovwrt_,
-psb_dupl_add_, psb_dupl_err_.
+Specified as: an integer value .
-
mold
-
The desired dynamic type for the internal matrix storage.
+
extype
+
the kind of estension required.
-Scope: local.
+Scope:global.
-Type: optional.
+Type:optional .
Intent: in.
-Specified as: an object of a class derived from spbasedatapsb_T_base_sparse_mat.
+Specified as: an integer value
+psb_ovt_xhal_, psb_ovt_asov_, default: psb_ovt_xhal_
+
+
@@ -128,16 +125,16 @@ Specified as: an object of a class derived from spbasedatapsb_T_base_sparse_
On Return
-
a
-
the matrix to be assembled.
+
desc_out
+
the extended communication descriptor.
-Scope:local
+Scope:local.
-Type:required
+Type:required.
Intent: inout.
-Specified as: a structured data of type spdatapsb_Tspmat_type.
+Specified as: a structured data of type descdatapsb_desc_type.
info
Error code.
@@ -156,25 +153,17 @@ 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;
+
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;
-
On exit from this routine the matrix is in the assembled state,
- and thus is suitable for the computational routines.
+
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.
@@ -182,26 +171,26 @@ An integer value; 0 means no error has been detected.
the matrix to be freed.
-
-Scope:local
-
-Type:required
-
-Intent: inout.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
desc_a
the communication descriptor.
@@ -87,6 +76,18 @@ Intent: in.
Specified as: a structured data of type descdatapsb_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.
+
@@ -94,6 +95,17 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
+
a
+
the matrix to be allocated.
+
+Scope:local
+
+Type:required
+
+Intent: out.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
info
Error code.
@@ -106,6 +118,23 @@ 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 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.
+
+
diff --git a/docs/html/node82.html b/docs/html/node82.html
index e966ada4..fb0084f4 100644
--- a/docs/html/node82.html
+++ b/docs/html/node82.html
@@ -3,8 +3,8 @@
-psb_sprn -- Reinit sparse matrix structure for psblas routines.
-
+psb_spins -- Insert a set of coefficients into a sparse matrix
+
@@ -16,69 +16,70 @@
-
+
-call psb_sprn(a, decsc_a, info, clear)
+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:
-
Synchronous.
+
Asynchronous.
On Entry
-
a
-
the matrix to be reinitialized.
+
nz
+
the number of coefficients to be inserted.
-Scope:local
+Scope:local.
-Type:required
+Type:required.
-Intent: inout.
+Intent: in.
-Specified as: a structured data of type spdatapsb_Tspmat_type.
+Specified as: an integer scalar.
-
desc_a
-
the communication descriptor.
+
nr
+
the number of rows to be inserted.
Scope:local.
@@ -86,18 +87,101 @@ Type:required.
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
+Specified as: an integer scalar.
-
clear
-
Choose whether to zero out matrix coefficients
+
irw
+
the first row to be inserted.
Scope:local.
-Type:optional.
+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 .
+
+
irp
+
the row pointers of the coefficients to be inserted.
+
+Scope:local.
+
+Type:required.
+
+Intent: in.
+
+Specified as: an integer array of size .
+
+
ja
+
the column indices of the coefficients to be inserted.
+
+Scope:local.
+
+Type:required.
+
+Intent: in.
+
+Specified as: an integer array of size .
+
+
val
+
the coefficients to be inserted.
+
+Scope:local.
+
+Type:required.
Intent: in.
-Default: true.
+Specified as: an array of size . Must be of the same type and kind
+of the coefficients of the sparse matrix .
+
+
desc_a
+
The communication descriptor.
+
+Scope: local.
+
+Type: required.
+
+Intent: inout.
+
+Specified as: a variable of type descdatapsb_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..
+
+
@@ -106,6 +190,28 @@ Default: true.
On Return
+
a
+
the matrix into which coefficients will be inserted.
+
+Scope:local
+
+Type:required
+
+Intent: inout.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
+
desc_a
+
The communication descriptor.
+
+Scope: local.
+
+Type: required.
+
+Intent: inout.
+
+Specified as: a variable of type descdatapsb_desc_type.
+
info
Error code.
@@ -118,16 +224,112 @@ 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.
+
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
+, for ;
+ these triples should belong to the current process, i.e.
+ should be one of the local indices, but are otherwise arbitrary;
+
+
In CSR format the coefficients to be inserted for each input row
+ are represented by the ordered triples
+, for
+
+;
+ these triples should belong to the current process, i.e.
+ 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;
+
+
Any coefficients from matrix rows not owned by the calling
+ process 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.
@@ -66,51 +66,60 @@ call psb_geall(x, desc_a, info, n, lb)
desc_a
-
The communication descriptor.
+
the communication descriptor.
-Scope: local
+Scope:local.
-Type: required
+Type:required.
Intent: in.
-Specified as: a variable of type descdatapsb_desc_type.
-
-
n
-
The number of columns of the dense matrix to be allocated.
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
afmt
+
the storage format for the sparse matrix.
-Scope: local
+Scope: local.
-Type: optional
+Type: optional.
Intent: in.
-Specified as: Integer scalar, default . It is not a valid argument if is a
-rank-1 array.
+Specified as: an array of characters. Defalt: 'CSR'.
-
lb
-
The lower bound for the column index range of the dense matrix to be allocated.
+
upd
+
Provide for updates to the matrix coefficients.
-Scope: local
+Scope: global.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: integer, possible values: psb_upd_srch_, psb_upd_perm_
+
+
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_.
+
+
mold
+
The desired dynamic type for the internal matrix storage.
+
+Scope: local.
-Type: optional
+Type: optional.
Intent: in.
-Specified as: Integer scalar, default . It is not a valid argument if is a
-rank-1 array.
+Specified as: an object of a class derived from spbasedatapsb_T_base_sparse_mat.
@@ -119,18 +128,17 @@ rank-1 array.
On Return
-
x
-
The dense matrix to be allocated.
+
a
+
the matrix to be assembled.
-Scope: local
+Scope:local
-Type: required
+Type:required
-Intent: out.
+Intent: inout.
-Specified as: a rank one or two array with the ALLOCATABLE attribute
-or an object of type vdatapsb_T_vect_type, of type real, complex or integer.
-
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
info
Error code.
@@ -145,7 +153,57 @@ 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.
+
the matrix to be freed.
-Scope:local.
-
-Type:required.
-
-Intent: in.
-
-Specified as: an integer value.
-
-
irw
-
Indices of the rows to be inserted. Specifically, row
- of will be inserted into the local row corresponding to the
- global row index .
-Scope:local.
-
-Type:required.
-
-Intent: in.
-
-Specified as: an integer array.
-
-
val
-
the dense submatrix to be inserted.
-
-Scope:local.
+Scope:local
-Type:required.
+Type:required
-Intent: in.
+Intent: inout.
-Specified as: a rank 1 or 2 array.
-Specified as: an integer value.
+Specified as: a structured data of type spdatapsb_Tspmat_type.
desc_a
the communication descriptor.
@@ -123,30 +87,6 @@ Intent: in.
Specified as: a structured data of type descdatapsb_desc_type.
-
dupl
-
How to handle duplicate coefficients.
-
-Scope: global.
-
-Type: optional.
-
-Intent: in.
-
-Specified as: integer, possible values: psb_dupl_ovwrt_,
-psb_dupl_add_.
-
-
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..
-
-
the output dense matrix.
-
-Scope: local
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one or two array or an object of type vdatapsb_T_vect_type, of
-type real, complex or integer.
-
info
Error code.
@@ -180,42 +108,7 @@ 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.
-
the matrix to be reinitialized.
+
+Scope:local
+
+Type:required
+
+Intent: inout.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
desc_a
-
The communication descriptor.
+
the communication descriptor.
-Scope: local
+Scope:local.
-Type: required
+Type:required.
Intent: in.
-Specified as: a variable of type descdatapsb_desc_type.
-
-
mold
-
The desired dynamic type for the internal vector storage.
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
clear
+
Choose whether to zero out matrix coefficients
-Scope: local.
+Scope:local.
-Type: optional.
+Type:optional.
Intent: in.
-Specified as: an object of a class derived from vbasedatapsb_T_base_vect_type; this is
-only allowed when is of type vdatapsb_T_vect_type.
+Default: true.
@@ -98,18 +106,6 @@ only allowed when 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 vdatapsb_T_vect_type, of type real, complex or integer.
-
info
Error code.
@@ -122,6 +118,15 @@ 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.
+
The communication descriptor.
Scope: local
Type: required
-Intent: inout.
+Intent: in.
-Specified as: a rank one or two array with the ALLOCATABLE or an
-object of type vdatapsb_T_vect_type, of type real, complex or integer.
+Specified as: a variable of type descdatapsb_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 . It is not a valid argument if is a
+rank-1 array.
-
desc_a
-
The communication descriptor.
+
lb
+
The lower bound for the column index range of the dense matrix to be allocated.
Scope: local
-Type: required
+Type: optional
Intent: in.
-Specified as: a variable of type descdatapsb_desc_type.
-
+Specified as: Integer scalar, default . It is not a valid argument if is a
+rank-1 array.
+
@@ -98,6 +119,18 @@ Specified as: a variable of type descdatapsb_desc_type.
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 vdatapsb_T_vect_type, of type real, complex or integer.
+
info
Error code.
diff --git a/docs/html/node87.html b/docs/html/node87.html
index dbb80998..7e7dff18 100644
--- a/docs/html/node87.html
+++ b/docs/html/node87.html
@@ -3,8 +3,8 @@
-psb_gelp -- Applies a left permutation to a dense matrix
-
+psb_geins -- Dense matrix insertion routine
+
@@ -16,46 +16,45 @@
-
+
A character that specifies whether to permute or .
+
m
+
Number of rows in to be inserted.
-Scope: local
+Scope:local.
-Type: required
+Type:required.
Intent: in.
-Specified as: a single character with value 'N' for or 'T' for .
-
-
iperm
-
An integer array containing permutation information.
+Specified as: an integer value.
+
+
irw
+
Indices of the rows to be inserted. Specifically, row
+ of will be inserted into the local row corresponding to the
+ global row index .
+Scope:local.
+
+Type:required.
-Scope: local
+Intent: in.
-Type: required
+Specified as: an integer array.
+
+
val
+
the dense submatrix to be inserted.
+
+Scope:local.
+
+Type:required.
Intent: in.
-Specified as: an integer one-dimensional array.
-
-
x
-
The dense matrix to be permuted.
+Specified as: a rank 1 or 2 array.
+Specified as: an integer value.
+
+
desc_a
+
the communication descriptor.
-Scope: local
+Scope:local.
-Type: required
+Type:required.
-Intent: inout.
+Intent: in.
-Specified as: a one or two dimensional array.
-
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
dupl
+
How to handle duplicate coefficients.
+
+Scope: global.
+
+Type: optional.
+
+Intent: in.
+
+Specified as: integer, possible values: psb_dupl_ovwrt_,
+psb_dupl_add_.
+
+
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..
+
+
+
@@ -118,6 +154,18 @@ Specified as: a one or two dimensional array.
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 vdatapsb_T_vect_type, of
+type real, complex or integer.
+
info
Error code.
@@ -132,7 +180,42 @@ 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.
+
The communication descriptor.
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 descdatapsb_desc_type.
-
-
iact
-
specifies action to be taken in case of range errors.
-Scope: global
-
-Type: optional
-
-Intent: in.
+Specified as: a variable of type descdatapsb_desc_type.
+
+
mold
+
The desired dynamic type for the internal vector storage.
-Specified as: a character variable Ignore, Warning or
-Abort, default Ignore.
-
-
owned
-
Specfies valid range of input
-Scope: global
+Scope: local.
-Type: optional
+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.
+Specified as: an object of a class derived from vbasedatapsb_T_base_vect_type; this is
+only allowed when is of type vdatapsb_T_vect_type.
@@ -120,43 +99,17 @@ accepted. Default: false.
x
-
If is not present,
- then is overwritten with the translated integer indices.
-Scope: global
+
The dense matrix to be assembled.
+
+Scope: local
Type: required
Intent: inout.
-Specified as: a rank one integer array.
-
-
y
-
If is present,
- then is overwritten with the translated integer indices, and
- is left unchanged.
-Scope: global
-
-Type: optional
-
-Intent: out.
-
-Specified as: a rank one integer array.
-
+Specified as: a rank one or two array with the ALLOCATABLE or an
+object of type vdatapsb_T_vect_type, of type real, complex or integer.
+
info
Error code.
@@ -169,45 +122,7 @@ 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.
-
The dense matrix to
+ be freed.
Scope: local
Type: required
-Intent: in, inout.
-
-Specified as: a rank one integer array.
-
-
desc_a
-
the communication descriptor.
-
-Scope:local.
-
-Type:required.
+Intent: inout.
-Intent: in.
+Specified as: a rank one or two array with the ALLOCATABLE or an
+object of type vdatapsb_T_vect_type, of type real, complex or integer.
-Specified as: a structured data of type descdatapsb_desc_type.
+
-
iact
-
specifies action to be taken in case of range errors.
-Scope: global
+
desc_a
+
The communication descriptor.
+
+Scope: local
-Type: optional
+Type: required
Intent: in.
-Specified as: a character variable Ignore, Warning or
-Abort, default Ignore.
-
+Specified as: a variable of type descdatapsb_desc_type.
+
@@ -107,44 +98,6 @@ Specified as: a character variable Ignore, Warning or
On Return
-
x
-
If is not present,
- then is overwritten with the translated integer indices.
-Scope: global
-
-Type: required
-
-Intent: inout.
-
-Specified as: a rank one integer array.
-
-
y
-
If is not present,
- then is overwritten with the translated integer indices, and
- is left unchanged.
-Scope: global
-
-Type: optional
-
-Intent: out.
-
-Specified as: a rank one integer array.
-
A character that specifies whether to permute or .
Scope: local
@@ -74,19 +81,36 @@ Type: required
Intent: in.
-Specified as: a scalar integer.
+Specified as: a single character with value 'N' for or 'T' for .
-
desc_a
-
the communication descriptor.
+
iperm
+
An integer array containing permutation information.
-Scope:local.
+Scope: local
-Type:required.
+Type: required
Intent: in.
-Specified as: a structured data of type descdatapsb_desc_type.
-
+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.
+
@@ -94,30 +118,19 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
-
Function value
-
A logical mask which is true if
- is owned by the current process
+
An integer vector of indices to be converted.
Scope: local
@@ -74,7 +76,7 @@ Type: required
Intent: in, inout.
-Specified as: a scalar or a rank one integer array.
+Specified as: a rank one integer array.
desc_a
the communication descriptor.
@@ -98,6 +100,18 @@ 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.
+
@@ -105,19 +119,43 @@ Specified as: a character variable Ignore, Warning or
On Return
-
y
-
A logical mask which is true for all corresponding entries of
- x
+
If is not present,
+ then that are owned by the current process
-Scope: local
+ ALT="$x$">
is overwritten with the translated integer indices.
+Scope: global
Type: required
+Intent: inout.
+
+Specified as: a rank one integer array.
+
+
y
+
If is present,
+ then is overwritten with the translated integer indices, and
+ is left unchanged.
+Scope: global
+
+Type: optional
+
Intent: out.
-Specified as: a scalar or rank one logical array.
+Specified as: a rank one integer array.
info
Error code.
@@ -136,14 +174,40 @@ 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
+
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.
An integer vector of indices to be converted.
Scope: local
Type: required
-Intent: in.
+Intent: in, inout.
-Specified as: a scalar integer.
+Specified as: a rank one integer array.
desc_a
the communication descriptor.
@@ -87,6 +89,17 @@ Intent: in.
Specified as: a structured data of type descdatapsb_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.
+
@@ -94,30 +107,57 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
-
Function value
-
A logical mask which is true if
- x
+
If is not present,
+ then is local to the current process
-Scope: local
+ ALT="$x$">
is overwritten with the translated integer indices.
+Scope: global
Type: required
+Intent: inout.
+
+Specified as: a rank one integer array.
+
+
y
+
If is not present,
+ then is overwritten with the translated integer indices, and
+ 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
-
-
-
This routine returns a .true. value for an index
- that is local to the current process, including the halo
- indices
-
Integer index.
Scope: local
Type: required
-Intent: in, inout.
+Intent: in.
-Specified as: a scalar or a rank one integer array.
+Specified as: a scalar integer.
desc_a
the communication descriptor.
@@ -87,17 +87,6 @@ Intent: in.
Specified as: a structured data of type descdatapsb_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.
-
@@ -105,40 +94,27 @@ Specified as: a character variable Ignore, Warning or
On Return
-
y
-
A logical mask which is true for all corresponding entries of
+
Function value
+
A logical mask which is true if
that are local to the current process
+ ALT="$x$">
is 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 local to the current process, including the halo
- indices.
+
This routine returns a .true. value for an index
+ that is strictly owned by the current process, excluding the halo
+ indices
diff --git a/docs/html/node94.html b/docs/html/node94.html
index 41a1b858..56bfb76f 100644
--- a/docs/html/node94.html
+++ b/docs/html/node94.html
@@ -3,8 +3,8 @@
-psb_get_boundary -- Extract list of boundary elements
-
+psb_owned_index --
+
@@ -16,46 +16,45 @@
-
+
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.
@@ -77,6 +87,17 @@ Intent: in.
Specified as: a structured data of type descdatapsb_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.
+
@@ -84,19 +105,20 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
-
bndel
-
The list of boundary elements on the calling process, in
- local numbering.
-
+
y
+
A logical mask which is true for all corresponding entries of
+ that are owned by the current process
Scope: local
Type: required
Intent: out.
-Specified as: a rank one array with the ALLOCATABLE
-attribute, of type integer.
-
+Specified as: a scalar or rank one logical array.
+
info
Error code.
@@ -114,12 +136,9 @@ 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.
+
This routine returns a .true. value for those indices
+ that are strictly owned by the current process, excluding the halo
+ indices
diff --git a/docs/html/node95.html b/docs/html/node95.html
index 07d57981..79dba935 100644
--- a/docs/html/node95.html
+++ b/docs/html/node95.html
@@ -3,8 +3,8 @@
-psb_get_overlap -- Extract list of overlap elements
-
+psb_is_local --
+
@@ -16,46 +16,45 @@
-
+
Integer index.
+
+Scope: local
+
+Type: required
+
+Intent: in.
+
+Specified as: a scalar integer.
+
+
desc_a
the communication descriptor.
Scope:local.
@@ -84,41 +94,27 @@ Specified as: a structured data of type descdatapsb_desc_type.
On Return
-
ovrel
-
The list of overlap elements on the calling process, in
- local numbering.
-
+
Function value
+
A logical mask which is true if
+ is local to the current process
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.
+
This routine returns a .true. value for an index
+ that is local to the current process, including the halo
+ indices
Integer indices.
-Scope:local
-
-Type:required
-
-Intent: in.
-
-Specified as: an integer .
-
-
a
-
the matrix from which to get rows.
-
-Scope:local
-
-Type:required
-
-Intent: in.
-
-Specified as: a structured data of type spdatapsb_Tspmat_type.
-
-
append
-
Whether to append or overwrite existing output.
-
-Scope:local
+Scope: local
-Type:optional
+Type: required
-Intent: in.
+Intent: in, inout.
-Specified as: a logical value default: false (overwrite).
-
-
nzin
-
Input size to be appended to.
+Specified as: a scalar or a rank one integer array.
+
+
desc_a
+
the communication descriptor.
-Scope:local
+Scope:local.
-Type:optional
+Type:required.
Intent: in.
-Specified as: an integer . When append is true, specifies how many
-entries in the output vectors are already filled.
+Specified as: a structured data of type descdatapsb_desc_type.
-
lrw
-
The last row to be extracted.
+
iact
+
specifies action to be taken in case of range errors.
+Scope: global
-Scope:local
-
-Type:optional
+Type: optional
Intent: in.
-Specified as: an integer , default: .
-
-
+Specified as: a character variable Ignore, Warning or
+Abort, default Ignore.
@@ -144,49 +105,19 @@ Specified as: an integer On Return
-
nz
-
the number of elements returned by this call.
-
-Scope:local.
+
y
+
A logical mask which is true for all corresponding entries of
+ that are local to the current process
+Scope: local
-Type:required.
+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.
+Specified as: a scalar or rank one logical array.
info
Error code.
@@ -205,52 +136,14 @@ An integer value; 0 means no error has been detected.
Notes
-
The output is always the size of the output generated by
- the current call; thus, if append=.true., the total output
- size will be , 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 routine returns a .true. value for those indices
+ that are local to the current process, including the halo
+ indices.
the communication descriptor.
-Scope: local
+Scope:local.
-Type: required
+Type:required.
Intent: in.
-Specified as: a structured data of type spdatapsb_Tspmat_type.
+Specified as: a structured data of type descdatapsb_desc_type.
+
+
+
+
+
+
On Return
+
-
desc_a
-
Communication descriptor.
+
bndel
+
The list of boundary elements on the calling process, in
+ local numbering.
Scope: local
Type: required
-Intent: in.
+Intent: out.
-Specified as: a structured data of type descdatapsb_desc_type.
-
-
prec
-
Scope: local
+Specified as: a rank one array with the ALLOCATABLE
+attribute, of type integer.
+
+
info
+
Error code.
-Type: required
+Scope: local
-Intent: in.
+Type: required
-Specified as: a preconditioner data structure precdatapsb_prec_type.
-
-
On Return
-
-
-
Function value
-
The memory occupation of the object specified in
- the calling sequence, in bytes.
-
-Scope: local
+Intent: out.
-Returned as: an integer(psb_long_int_k_) number.
+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.
+
+
+
diff --git a/docs/html/node98.html b/docs/html/node98.html
index 5625baef..4f8e6938 100644
--- a/docs/html/node98.html
+++ b/docs/html/node98.html
@@ -3,8 +3,8 @@
-Sorting utilities --
-
+psb_get_overlap -- Extract list of overlap elements
+
@@ -14,121 +14,68 @@
+
-
+
-These serial routines sort a sequence 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
+
On Entry
-
x
-
The sequence to be sorted.
+
desc
+
the communication descriptor.
-Type:required.
+Scope:local.
-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 .
-
-
dir
-
The desired ordering.
-
-Type:optional.
-
-Specified as: an integer value:
Whether to keep the original values in .
+Type:required.
-Type:optional.
+Intent: in.
-Specified as: an integer value psb_sort_ovw_idx_ or
-psb_sort_keep_idx_; default psb_sort_ovw_idx_.
-
-
+Specified as: a structured data of type descdatapsb_desc_type.
@@ -137,155 +84,46 @@ Specified as: an integer value psb_sort_ovw_idx_ or
On Return
-
x
-
The sequence of values, in the chosen ordering.
+
ovrel
+
The list of overlap elements on the calling process, in
+ local numbering.
-Type:required.
+Scope: local
-Specified as: an integer, real or complex array of rank 1.
-
-
ix
-
A vector of indices.
+Type: required
+
+Intent: out.
+
+Specified as: a rank one array with the ALLOCATABLE
+attribute, of type integer.
+
+
info
+
Error code.
+
+Scope: local
+
+Type: required
-Type: Optional
+Intent: out.
-An integer array of rank 1, whose entries are moved to the same
-position as the corresponding entries in .
+An integer value; 0 means no error has been detected.
-
-
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
- then the entries in
- where is the size of are initialized to
-; thus, upon return from the subroutine, for each
- index we have in the position that the item
- occupied in the original data sequence;
-
-
If
- the routine will assume that
- the entries in have already been initialized by the user;
-
-
The three sorting algorithms have a similar 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 ; the algorithm
- implemented here follows the well-known median-of-three heuristics,
- but the worst case may still apply;
+
If there are no overlap elements the output vector is set
+ to the “not allocated” state.
-
The worst case running time for merge-sort and heap-sort is
- 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.
-
-
+
Otherwise the size of ovrel will be exactly equal to the
+ number of overlap elements.
The (first) row to be extracted.
+
+Scope:local
+
+Type:required
+
+Intent: in.
+
+Specified as: an integer .
+
+
a
+
the matrix from which to get rows.
+
+Scope:local
+
+Type:required
+
+Intent: in.
+
+Specified as: a structured data of type spdatapsb_Tspmat_type.
+
+
append
+
Whether to append or overwrite existing output.
+
+Scope:local
+
+Type:optional
+
+Intent: in.
-Parallel environment routines
-
+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 . 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 , default: .
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 is always the size of the output generated by
+ the current call; thus, if append=.true., the total output
+ size will be , 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.
+