Additional improvements to internal docs.

base/tools/psb_casb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_casb.f90
 !
-! Subroutine: psb_casb
+! Subroutine: psb_casb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - complex, allocatable    The matrix to be assembled.
+!    x       - type(psb_c_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_c_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_casb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_casb_vect
   implicit none

base/tools/psb_cins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_cinsvi
+! Subroutine: psb_cins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - complex               The source dense submatrix.  
+!    val(:)  - complex               The source vector
-!    x(:)    - complex               The destination dense matrix.  
+!    x       - type(psb_c_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_cins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_cins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_cins_vect
 
+! Subroutine: psb_cins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_c_vect_type) The source vector
+!    x       - type(psb_c_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_cins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_cins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_cins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_cins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_cins_vect_r2
 
-
-
 subroutine psb_cins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_cins_multivect
   use psi_mod

base/tools/psb_dasb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_dasb.f90
 !
-! Subroutine: psb_dasb
+! Subroutine: psb_dasb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - real, allocatable    The matrix to be assembled.
+!    x       - type(psb_d_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_d_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_dasb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_dasb_vect
   implicit none

base/tools/psb_dins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_dinsvi
+! Subroutine: psb_dins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - real               The source dense submatrix.  
+!    val(:)  - real               The source vector
-!    x(:)    - real               The destination dense matrix.  
+!    x       - type(psb_d_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_dins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_dins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_dins_vect
 
+! Subroutine: psb_dins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_d_vect_type) The source vector
+!    x       - type(psb_d_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_dins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_dins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_dins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_dins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_dins_vect_r2
 
-
-
 subroutine psb_dins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_dins_multivect
   use psi_mod

base/tools/psb_iasb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_iasb.f90
 !
-! Subroutine: psb_iasb
+! Subroutine: psb_iasb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - integer, allocatable    The matrix to be assembled.
+!    x       - type(psb_i_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_i_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_iasb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_iasb_vect
   implicit none

base/tools/psb_iins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_iinsvi
+! Subroutine: psb_iins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - integer               The source dense submatrix.  
+!    val(:)  - integer               The source vector
-!    x(:)    - integer               The destination dense matrix.  
+!    x       - type(psb_i_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_iins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_iins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_iins_vect
 
+! Subroutine: psb_iins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_i_vect_type) The source vector
+!    x       - type(psb_i_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_iins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_iins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_iins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_iins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_iins_vect_r2
 
-
-
 subroutine psb_iins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_iins_multivect
   use psi_mod

base/tools/psb_lasb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_lasb.f90
 !
-! Subroutine: psb_lasb
+! Subroutine: psb_lasb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - integer, allocatable    The matrix to be assembled.
+!    x       - type(psb_l_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_l_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_lasb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_lasb_vect
   implicit none

base/tools/psb_lins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_linsvi
+! Subroutine: psb_lins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - integer               The source dense submatrix.  
+!    val(:)  - integer               The source vector
-!    x(:)    - integer               The destination dense matrix.  
+!    x       - type(psb_l_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_lins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_lins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_lins_vect
 
+! Subroutine: psb_lins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_l_vect_type) The source vector
+!    x       - type(psb_l_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_lins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_lins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_lins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_lins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_lins_vect_r2
 
-
-
 subroutine psb_lins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_lins_multivect
   use psi_mod

base/tools/psb_sasb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_sasb.f90
 !
-! Subroutine: psb_sasb
+! Subroutine: psb_sasb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - real, allocatable    The matrix to be assembled.
+!    x       - type(psb_s_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_s_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_sasb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_sasb_vect
   implicit none

base/tools/psb_sins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_sinsvi
+! Subroutine: psb_sins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - real               The source dense submatrix.  
+!    val(:)  - real               The source vector
-!    x(:)    - real               The destination dense matrix.  
+!    x       - type(psb_s_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_sins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_sins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_sins_vect
 
+! Subroutine: psb_sins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_s_vect_type) The source vector
+!    x       - type(psb_s_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_sins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_sins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_sins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_sins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_sins_vect_r2
 
-
-
 subroutine psb_sins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_sins_multivect
   use psi_mod

base/tools/psb_zasb.f90

@@ -31,17 +31,26 @@
 !    
 ! File: psb_zasb.f90
 !
-! Subroutine: psb_zasb
+! Subroutine: psb_zasb_vect, _vect_r2 and _multivect
-!    Assembles a dense matrix for PSBLAS routines
+!    Assembles a dense vector, an array of vectors or a multivector
+!    for PSBLAS routines. 
 !    Since the allocation may have been called with the desciptor 
 !    in the build state we make sure that X has a number of rows 
 !    allowing for the halo indices, reallocating if necessary. 
 !    We also call the halo routine for good measure.
+!    However, sometimes we need to create temporary vectors whose contents
+!    will be initialized through some subsequent call to geaxpby or similar;
+!    for this situation we provide the SCRATCH flag. 
+!    
 ! 
 ! Arguments: 
-!    x(:,:)  - complex, allocatable    The matrix to be assembled.
+!    x       - type(psb_z_vect_type) The matrix to be assembled.
 !    desc_a  - type(psb_desc_type).    The communication descriptor.
 !    info    - integer.                return code
+!    mold    - type(psb_z_base_vect_type), optional   A mold for the inner storage format
+!    scratch - logical, optional       If true, allocate without checking/zeroing contents.
+!                                      default: .false.
+!    
 subroutine psb_zasb_vect(x, desc_a, info, mold, scratch)
   use psb_base_mod, psb_protect_name => psb_zasb_vect
   implicit none

base/tools/psb_zins.f90

@@ -29,17 +29,17 @@
 !    POSSIBILITY OF SUCH DAMAGE.
 !   
 !    
-! Subroutine: psb_zinsvi
+! Subroutine: psb_zins_vect
-!    Insert dense submatrix to dense matrix. Note: the row indices in IRW 
+!    Insert entries into a dense  vector. Note: the row indices in IRW 
 !    are assumed to be in global numbering and are converted on the fly. 
 !    Row indices not belonging to the current process are silently discarded.
 ! 
 ! Arguments: 
 !    m       - integer.        Number of rows of submatrix belonging to 
 !                              val to be inserted.
-!    irw(:)  - integer          Row indices of rows of val (global numbering)
+!    irw(:)  - integer(psb_lpk_) Row indices of rows of val (global numbering)
-!    val(:)  - complex               The source dense submatrix.  
+!    val(:)  - complex               The source vector
-!    x(:)    - complex               The destination dense matrix.  
+!    x       - type(psb_z_vect_type) The destination vector
 !    desc_a  - type(psb_desc_type).         The communication descriptor.
 !    info    - integer.                       return code
 !    dupl    - integer               What to do with duplicates: 
@@ -50,10 +50,6 @@ subroutine psb_zins_vect(m, irw, val, x, desc_a, info, dupl,local)
   use psi_mod
   implicit none
 
-  ! m rows number of submatrix belonging to val to be inserted
-  ! ix  x global-row corresponding to position at which val submatrix
-  !     must be inserted
-
   !....parameters...
   integer(psb_ipk_), intent(in)                  :: m
   integer(psb_lpk_), intent(in)                  :: irw(:)
@@ -155,6 +151,23 @@ subroutine psb_zins_vect(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_zins_vect
 
+! Subroutine: psb_zins_vect_v
+!    Insert entries into a vector from another encapsulated vector.
+!    Note: the row indices in IRW 
+!    are assumed to be in global numbering and are converted on the fly. 
+!    Row indices not belonging to the current process are silently discarded.
+! 
+! Arguments: 
+!    m       - integer.        Number of rows of submatrix belonging to 
+!                              val to be inserted.
+!    irw     - type(psb_l_vect_type) Row indices of rows of val (global numbering)
+!    val     - type(psb_z_vect_type) The source vector
+!    x       - type(psb_z_vect_type) The destination vector
+!    desc_a  - type(psb_desc_type).         The communication descriptor.
+!    info    - integer.                       return code
+!    dupl    - integer               What to do with duplicates: 
+!                                     psb_dupl_ovwrt_    overwrite
+!                                     psb_dupl_add_      add         
 subroutine psb_zins_vect_v(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_zins_vect_v
   use psi_mod
@@ -329,7 +342,6 @@ subroutine psb_zins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
   mglob    = desc_a%get_global_rows()
 
 
-
   n = min(size(x),size(val,2))
   allocate(irl(m),stat=info) 
   if (info /= psb_success_) then 
@@ -375,8 +387,6 @@ subroutine psb_zins_vect_r2(m, irw, val, x, desc_a, info, dupl,local)
 
 end subroutine psb_zins_vect_r2
 
-
-
 subroutine psb_zins_multivect(m, irw, val, x, desc_a, info, dupl,local)
   use psb_base_mod, psb_protect_name => psb_zins_multivect
   use psi_mod