mld2p4-2:

mlprec/mld_c_as_smoother.f90
 mlprec/mld_c_base_smoother_mod.f90
 mlprec/mld_c_diag_solver.f90
 mlprec/mld_c_gs_solver.f90
 mlprec/mld_c_id_solver.f90
 mlprec/mld_c_ilu_fact_mod.f90
 mlprec/mld_c_ilu_solver.f90
 mlprec/mld_c_inner_mod.f90
 mlprec/mld_c_jac_smoother.f90
 mlprec/mld_c_mumps_solver.F90
 mlprec/mld_c_slu_solver.F90
 mlprec/mld_c_sludist_solver.F90
 mlprec/mld_c_umf_solver.F90
 mlprec/mld_d_as_smoother.f90
 mlprec/mld_d_base_smoother_mod.f90
 mlprec/mld_d_diag_solver.f90
 mlprec/mld_d_gs_solver.f90
 mlprec/mld_d_id_solver.f90
 mlprec/mld_d_ilu_fact_mod.f90
 mlprec/mld_d_ilu_solver.f90
 mlprec/mld_d_inner_mod.f90
 mlprec/mld_d_jac_smoother.f90
 mlprec/mld_d_mumps_solver.F90
 mlprec/mld_d_slu_solver.F90
 mlprec/mld_d_sludist_solver.F90
 mlprec/mld_d_umf_solver.F90
 mlprec/mld_s_as_smoother.f90
 mlprec/mld_s_base_smoother_mod.f90
 mlprec/mld_s_diag_solver.f90
 mlprec/mld_s_gs_solver.f90
 mlprec/mld_s_id_solver.f90
 mlprec/mld_s_ilu_fact_mod.f90
 mlprec/mld_s_ilu_solver.f90
 mlprec/mld_s_inner_mod.f90
 mlprec/mld_s_jac_smoother.f90
 mlprec/mld_s_mumps_solver.F90
 mlprec/mld_s_slu_solver.F90
 mlprec/mld_s_sludist_solver.F90
 mlprec/mld_s_umf_solver.F90
 mlprec/mld_z_as_smoother.f90
 mlprec/mld_z_base_smoother_mod.f90
 mlprec/mld_z_diag_solver.f90
 mlprec/mld_z_gs_solver.f90
 mlprec/mld_z_id_solver.f90
 mlprec/mld_z_ilu_fact_mod.f90
 mlprec/mld_z_ilu_solver.f90
 mlprec/mld_z_inner_mod.f90
 mlprec/mld_z_jac_smoother.f90
 mlprec/mld_z_mumps_solver.F90
 mlprec/mld_z_slu_solver.F90
 mlprec/mld_z_sludist_solver.F90
 mlprec/mld_z_umf_solver.F90

Refined file prologues.

mlprec/mld_c_as_smoother.f90

@@ -37,10 +37,25 @@
 !!$ 
 !!$
 !
+! File: mld_c_as_smoother_mod.f90
 !
+! Module: mld_c_as_smoother_mod
 !
+!  This module defines: 
+!    the mld_c_as_smoother_type data structure containing the
+!    smoother for an Additive Schwarz smoother.
 !
+!  To begin with, the build procedure constructs the extended
+!  matrix A and its corresponding descriptor (this has multiple
+!  halo layers duplicated across different processes); it then 
+!  stores in ND the block off-diagonal matrix, and builds the solver
+!  on the (extended) block diagonal matrix.
 !
+!  The code allows for the variations of Additive Schwartz, Restricted
+!  Additive Schwartz and Additive Schwartz with Harmonic Extensions.
+!  From an implementation point of view, these are handled by
+!  combining application/non-application of the prolongator/restrictor
+!  operators.
 !  
 module mld_c_as_smoother
 

mlprec/mld_c_base_smoother_mod.f90

@@ -50,7 +50,14 @@
 !  - printing a	description of the preconditioner;
 !  - deallocating the preconditioner data structure.
 !
-
+!  What is the difference between a smoother and a solver?
+!  In the mathematics literature the two concepts are treated
+!  essentially as synonymous, but here we are using them in a more
+!  computer-science oriented fashion. In particular, a SMOOTHER object
+!  contains a SOLVER object: the SOLVER operates locally within the
+!  current process, whereas the SMOOTHER object accounts for (possible)
+!  interactions between processes.
+!
 module mld_c_base_smoother_mod
 
   use mld_c_base_solver_mod

mlprec/mld_c_diag_solver.f90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_c_diag_solver_mod.f90
 !
+! Module: mld_c_diag_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_diag_solver_type data structure containing the 
+!    simple diagonal solver. This extracts the main diagonal of a matrix
+!    and precomputes its inverse. Combined with a Jacobi "smoother" generates
+!    what are commonly known as the classic Jacobi iterations
 !
-!
-!
-
 module mld_c_diag_solver
 
   use mld_c_base_solver_mod

mlprec/mld_c_gs_solver.f90

@@ -38,11 +38,19 @@
 !!$
 !
 !
+! File: mld_c_gs_solver_mod.f90
 !
+! Module: mld_c_gs_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_gs_solver_type data structure containing the ingredients
+!    for a local Gauss-Seidel iteration. We provide Forward GS (FWGS) and
+!    backward GS (BWGS). The iterations are local to a process (they operate
+!    on the block diagonal). Combined with a Jacobi smoother will generate a
+!    hybrid-Gauss-Seidel solver, i.e. Gauss-Seidel within each process, Jacobi
+!    among the processes. 
 !
 !
-
 module mld_c_gs_solver
 
   use mld_c_base_solver_mod

mlprec/mld_c_id_solver.f90

@@ -42,7 +42,6 @@
 ! Identity solver. Reference for nullprec. 
 !
 !
-
 module mld_c_id_solver
 
   use mld_c_base_solver_mod

mlprec/mld_c_ilu_fact_mod.f90

@@ -36,6 +36,16 @@
 !!$  POSSIBILITY OF SUCH DAMAGE.
 !!$ 
 !!$
+!
+!
+! File: mld_c_ilu_fact_mod.f90
+!
+! Module: mld_c_ilu_fact_mod
+!
+!  This module defines some interfaces used internally by the implementation if
+!  mld_c_ilu_solver, but not visible to the end user. 
+!
+!
 module mld_c_ilu_fact_mod
 
   use mld_c_base_solver_mod 

mlprec/mld_c_ilu_solver.f90

@@ -38,11 +38,23 @@
 !!$
 !
 !
+! File: mld_c_ilu_solver_mod.f90
 !
+! Module: mld_c_ilu_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_ilu_solver_type data structure containing the ingredients
+!    for a local Incomplete LU factorization.
+!    1. The factorization is always restricted to the diagonal block of the
+!       current image (coherently with the definition of a SOLVER as a local
+!       object)
+!    2. The code provides support for both pattern-based ILU(K) and
+!       threshold base ILU(T,L)
+!    3. The diagonal is stored separately, so strictly speaking this is
+!       an incomplete LDU factorization; 
+!    4. The application phase is shared;
 !
 !
-
 module mld_c_ilu_solver
 
   use mld_base_prec_type, only : mld_fact_names

mlprec/mld_c_inner_mod.f90

@@ -41,8 +41,8 @@
 ! Module: mld_inner_mod
 !
 !  This module defines the interfaces to the real/complex, single/double
-!  precision versions of the MLD2P4 routines, except those of the user level,
-!  whose interfaces are defined in mld_prec_mod.f90.
+!  precision versions of inner MLD2P4 routines.
+!  The interfaces  of the user level routines are defined in mld_prec_mod.f90.
 !
 module mld_c_inner_mod
   use mld_c_prec_type
@@ -94,34 +94,6 @@ module mld_c_inner_mod
     end subroutine mld_cmlprec_aply_vect
   end interface mld_mlprec_aply
  
-  interface mld_bld_mlhier_aggsize
-    subroutine mld_c_bld_mlhier_aggsize(casize,mxplevs,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_cspmat_type, psb_desc_type,psb_spk_
-      use mld_c_prec_type, only : mld_c_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(in)    :: casize,mxplevs
-      real(psb_spk_)                   :: mnaggratio
-      type(psb_cspmat_type),intent(in), target           :: a
-      type(psb_desc_type), intent(inout), target         :: desc_a
-      type(mld_c_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_c_bld_mlhier_aggsize
-  end interface mld_bld_mlhier_aggsize
-
-  interface mld_bld_mlhier_array
-    subroutine mld_c_bld_mlhier_array(nplevs,casize,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_cspmat_type, psb_desc_type, psb_spk_
-      use mld_c_prec_type, only : mld_c_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(inout)            :: nplevs, casize
-      real(psb_spk_)                              :: mnaggratio
-      type(psb_cspmat_type),intent(in), target :: a
-      type(psb_desc_type), intent(inout), target  :: desc_a
-      type(mld_c_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_c_bld_mlhier_array
-  end interface mld_bld_mlhier_array
-  
   interface mld_aggrmap_bld
     subroutine mld_c_lev_aggrmap_bld(p,a,desc_a,ilaggr,nlaggr,op_prol,info)
       use psb_base_mod, only : psb_cspmat_type, psb_desc_type, psb_spk_, psb_ipk_
@@ -191,8 +163,6 @@ module mld_c_inner_mod
     end subroutine mld_caggrmat_asb
   end interface mld_aggrmat_asb
 
-  
-
   abstract interface
     subroutine mld_caggrmat_var_asb(a,desc_a,ilaggr,nlaggr,parms,ac,op_prol,op_restr,info)
       use psb_base_mod, only : psb_cspmat_type, psb_desc_type, psb_spk_, psb_ipk_
@@ -207,10 +177,8 @@ module mld_c_inner_mod
     end subroutine mld_caggrmat_var_asb
   end interface
 
-
   procedure(mld_caggrmat_var_asb) ::  mld_caggrmat_nosmth_asb, &
        & mld_caggrmat_smth_asb, mld_caggrmat_minnrg_asb, &
        & mld_caggrmat_biz_asb
 
-
 end module mld_c_inner_mod

mlprec/mld_c_jac_smoother.f90

@@ -37,10 +37,18 @@
 !!$ 
 !!$
 !
+! File: mld_c_jac_smoother_mod.f90
 !
+! Module: mld_c_jac_smoother_mod
 !
-!
-!
+!  This module defines: 
+!    the mld_c_jac_smoother_type data structure containing the
+!    smoother for a Jacobi/block Jacobi smoother.
+!  The smoother stores in ND the block off-diagonal matrix.
+!  One special case is treated separately, when the solver is DIAG
+!  then the ND is the entire off-diagonal part of the matrix (including the
+!  main diagonal block), so that it becomes possible to implement
+!  pure Jacobi global solver. 
 ! 
 module mld_c_jac_smoother
 

mlprec/mld_c_mumps_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_c_mumps_solver_mod.f90
 !
+! Module: mld_c_mumps_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_mumps_solver_type data structure containing the ingredients
+!    to interface with the MUMPS package. 
+!    1. The factorization can be either restricted to the diagonal block of the
+!       current image or distributed (and thus exact)
 !
-!
-!
-
 module mld_c_mumps_solver
 #if defined(HAVE_MUMPS_)
   use cmumps_struc_def

mlprec/mld_c_slu_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_c_slu_solver_mod.f90
 !
+! Module: mld_c_slu_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_slu_solver_type data structure containing the ingredients
+!    to interface with the SuperLU package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_c_slu_solver
 
   use iso_c_binding

mlprec/mld_c_sludist_solver.F90

@@ -37,12 +37,17 @@
 !!$ 
 !!$
 !
+! File: mld_c_sludist_solver_mod.f90
 !
+! Module: mld_c_sludist_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_sludist_solver_type data structure containing the ingredients
+!    to interface with the SuperLU_Dist package. 
+!    1. The factorization is distributed (and thus exact)
 !
 !
 !
-
 module mld_c_sludist_solver
 
   use iso_c_binding

mlprec/mld_c_umf_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_c_umf_solver_mod.f90
 !
+! Module: mld_c_umf_solver_mod
 !
+!  This module defines: 
+!  - the mld_c_umf_solver_type data structure containing the ingredients
+!    to interface with the UMFPACK package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_c_umf_solver
 
   use iso_c_binding

mlprec/mld_d_as_smoother.f90

@@ -37,10 +37,25 @@
 !!$ 
 !!$
 !
+! File: mld_d_as_smoother_mod.f90
 !
+! Module: mld_d_as_smoother_mod
 !
+!  This module defines: 
+!    the mld_d_as_smoother_type data structure containing the
+!    smoother for an Additive Schwarz smoother.
 !
+!  To begin with, the build procedure constructs the extended
+!  matrix A and its corresponding descriptor (this has multiple
+!  halo layers duplicated across different processes); it then 
+!  stores in ND the block off-diagonal matrix, and builds the solver
+!  on the (extended) block diagonal matrix.
 !
+!  The code allows for the variations of Additive Schwartz, Restricted
+!  Additive Schwartz and Additive Schwartz with Harmonic Extensions.
+!  From an implementation point of view, these are handled by
+!  combining application/non-application of the prolongator/restrictor
+!  operators.
 !  
 module mld_d_as_smoother
 

mlprec/mld_d_base_smoother_mod.f90

@@ -50,7 +50,14 @@
 !  - printing a	description of the preconditioner;
 !  - deallocating the preconditioner data structure.
 !
-
+!  What is the difference between a smoother and a solver?
+!  In the mathematics literature the two concepts are treated
+!  essentially as synonymous, but here we are using them in a more
+!  computer-science oriented fashion. In particular, a SMOOTHER object
+!  contains a SOLVER object: the SOLVER operates locally within the
+!  current process, whereas the SMOOTHER object accounts for (possible)
+!  interactions between processes.
+!
 module mld_d_base_smoother_mod
 
   use mld_d_base_solver_mod

mlprec/mld_d_diag_solver.f90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_d_diag_solver_mod.f90
 !
+! Module: mld_d_diag_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_diag_solver_type data structure containing the 
+!    simple diagonal solver. This extracts the main diagonal of a matrix
+!    and precomputes its inverse. Combined with a Jacobi "smoother" generates
+!    what are commonly known as the classic Jacobi iterations
 !
-!
-!
-
 module mld_d_diag_solver
 
   use mld_d_base_solver_mod

mlprec/mld_d_gs_solver.f90

@@ -38,11 +38,19 @@
 !!$
 !
 !
+! File: mld_d_gs_solver_mod.f90
 !
+! Module: mld_d_gs_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_gs_solver_type data structure containing the ingredients
+!    for a local Gauss-Seidel iteration. We provide Forward GS (FWGS) and
+!    backward GS (BWGS). The iterations are local to a process (they operate
+!    on the block diagonal). Combined with a Jacobi smoother will generate a
+!    hybrid-Gauss-Seidel solver, i.e. Gauss-Seidel within each process, Jacobi
+!    among the processes. 
 !
 !
-
 module mld_d_gs_solver
 
   use mld_d_base_solver_mod

mlprec/mld_d_id_solver.f90

@@ -42,7 +42,6 @@
 ! Identity solver. Reference for nullprec. 
 !
 !
-
 module mld_d_id_solver
 
   use mld_d_base_solver_mod

mlprec/mld_d_ilu_fact_mod.f90

@@ -36,6 +36,16 @@
 !!$  POSSIBILITY OF SUCH DAMAGE.
 !!$ 
 !!$
+!
+!
+! File: mld_d_ilu_fact_mod.f90
+!
+! Module: mld_d_ilu_fact_mod
+!
+!  This module defines some interfaces used internally by the implementation if
+!  mld_d_ilu_solver, but not visible to the end user. 
+!
+!
 module mld_d_ilu_fact_mod
 
   use mld_d_base_solver_mod 

mlprec/mld_d_ilu_solver.f90

@@ -38,11 +38,23 @@
 !!$
 !
 !
+! File: mld_d_ilu_solver_mod.f90
 !
+! Module: mld_d_ilu_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_ilu_solver_type data structure containing the ingredients
+!    for a local Incomplete LU factorization.
+!    1. The factorization is always restricted to the diagonal block of the
+!       current image (coherently with the definition of a SOLVER as a local
+!       object)
+!    2. The code provides support for both pattern-based ILU(K) and
+!       threshold base ILU(T,L)
+!    3. The diagonal is stored separately, so strictly speaking this is
+!       an incomplete LDU factorization; 
+!    4. The application phase is shared;
 !
 !
-
 module mld_d_ilu_solver
 
   use mld_base_prec_type, only : mld_fact_names

mlprec/mld_d_inner_mod.f90

@@ -41,8 +41,8 @@
 ! Module: mld_inner_mod
 !
 !  This module defines the interfaces to the real/complex, single/double
-!  precision versions of the MLD2P4 routines, except those of the user level,
-!  whose interfaces are defined in mld_prec_mod.f90.
+!  precision versions of inner MLD2P4 routines.
+!  The interfaces  of the user level routines are defined in mld_prec_mod.f90.
 !
 module mld_d_inner_mod
   use mld_d_prec_type
@@ -94,34 +94,6 @@ module mld_d_inner_mod
     end subroutine mld_dmlprec_aply_vect
   end interface mld_mlprec_aply
  
-  interface mld_bld_mlhier_aggsize
-    subroutine mld_d_bld_mlhier_aggsize(casize,mxplevs,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_dspmat_type, psb_desc_type,psb_dpk_
-      use mld_d_prec_type, only : mld_d_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(in)    :: casize,mxplevs
-      real(psb_dpk_)                   :: mnaggratio
-      type(psb_dspmat_type),intent(in), target           :: a
-      type(psb_desc_type), intent(inout), target         :: desc_a
-      type(mld_d_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_d_bld_mlhier_aggsize
-  end interface mld_bld_mlhier_aggsize
-
-  interface mld_bld_mlhier_array
-    subroutine mld_d_bld_mlhier_array(nplevs,casize,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_dspmat_type, psb_desc_type, psb_dpk_
-      use mld_d_prec_type, only : mld_d_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(inout)            :: nplevs, casize
-      real(psb_dpk_)                              :: mnaggratio
-      type(psb_dspmat_type),intent(in), target :: a
-      type(psb_desc_type), intent(inout), target  :: desc_a
-      type(mld_d_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_d_bld_mlhier_array
-  end interface mld_bld_mlhier_array
-  
   interface mld_aggrmap_bld
     subroutine mld_d_lev_aggrmap_bld(p,a,desc_a,ilaggr,nlaggr,op_prol,info)
       use psb_base_mod, only : psb_dspmat_type, psb_desc_type, psb_dpk_, psb_ipk_
@@ -191,8 +163,6 @@ module mld_d_inner_mod
     end subroutine mld_daggrmat_asb
   end interface mld_aggrmat_asb
 
-  
-
   abstract interface
     subroutine mld_daggrmat_var_asb(a,desc_a,ilaggr,nlaggr,parms,ac,op_prol,op_restr,info)
       use psb_base_mod, only : psb_dspmat_type, psb_desc_type, psb_dpk_, psb_ipk_
@@ -207,10 +177,8 @@ module mld_d_inner_mod
     end subroutine mld_daggrmat_var_asb
   end interface
 
-
   procedure(mld_daggrmat_var_asb) ::  mld_daggrmat_nosmth_asb, &
        & mld_daggrmat_smth_asb, mld_daggrmat_minnrg_asb, &
        & mld_daggrmat_biz_asb
 
-
 end module mld_d_inner_mod

mlprec/mld_d_jac_smoother.f90

@@ -37,10 +37,18 @@
 !!$ 
 !!$
 !
+! File: mld_d_jac_smoother_mod.f90
 !
+! Module: mld_d_jac_smoother_mod
 !
-!
-!
+!  This module defines: 
+!    the mld_d_jac_smoother_type data structure containing the
+!    smoother for a Jacobi/block Jacobi smoother.
+!  The smoother stores in ND the block off-diagonal matrix.
+!  One special case is treated separately, when the solver is DIAG
+!  then the ND is the entire off-diagonal part of the matrix (including the
+!  main diagonal block), so that it becomes possible to implement
+!  pure Jacobi global solver. 
 ! 
 module mld_d_jac_smoother
 

mlprec/mld_d_mumps_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_d_mumps_solver_mod.f90
 !
+! Module: mld_d_mumps_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_mumps_solver_type data structure containing the ingredients
+!    to interface with the MUMPS package. 
+!    1. The factorization can be either restricted to the diagonal block of the
+!       current image or distributed (and thus exact)
 !
-!
-!
-
 module mld_d_mumps_solver
 #if defined(HAVE_MUMPS_)
   use dmumps_struc_def

mlprec/mld_d_slu_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_d_slu_solver_mod.f90
 !
+! Module: mld_d_slu_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_slu_solver_type data structure containing the ingredients
+!    to interface with the SuperLU package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_d_slu_solver
 
   use iso_c_binding

mlprec/mld_d_sludist_solver.F90

@@ -37,12 +37,17 @@
 !!$ 
 !!$
 !
+! File: mld_d_sludist_solver_mod.f90
 !
+! Module: mld_d_sludist_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_sludist_solver_type data structure containing the ingredients
+!    to interface with the SuperLU_Dist package. 
+!    1. The factorization is distributed (and thus exact)
 !
 !
 !
-
 module mld_d_sludist_solver
 
   use iso_c_binding

mlprec/mld_d_umf_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_d_umf_solver_mod.f90
 !
+! Module: mld_d_umf_solver_mod
 !
+!  This module defines: 
+!  - the mld_d_umf_solver_type data structure containing the ingredients
+!    to interface with the UMFPACK package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_d_umf_solver
 
   use iso_c_binding

mlprec/mld_s_as_smoother.f90

@@ -37,10 +37,25 @@
 !!$ 
 !!$
 !
+! File: mld_s_as_smoother_mod.f90
 !
+! Module: mld_s_as_smoother_mod
 !
+!  This module defines: 
+!    the mld_s_as_smoother_type data structure containing the
+!    smoother for an Additive Schwarz smoother.
 !
+!  To begin with, the build procedure constructs the extended
+!  matrix A and its corresponding descriptor (this has multiple
+!  halo layers duplicated across different processes); it then 
+!  stores in ND the block off-diagonal matrix, and builds the solver
+!  on the (extended) block diagonal matrix.
 !
+!  The code allows for the variations of Additive Schwartz, Restricted
+!  Additive Schwartz and Additive Schwartz with Harmonic Extensions.
+!  From an implementation point of view, these are handled by
+!  combining application/non-application of the prolongator/restrictor
+!  operators.
 !  
 module mld_s_as_smoother
 

mlprec/mld_s_base_smoother_mod.f90

@@ -50,7 +50,14 @@
 !  - printing a	description of the preconditioner;
 !  - deallocating the preconditioner data structure.
 !
-
+!  What is the difference between a smoother and a solver?
+!  In the mathematics literature the two concepts are treated
+!  essentially as synonymous, but here we are using them in a more
+!  computer-science oriented fashion. In particular, a SMOOTHER object
+!  contains a SOLVER object: the SOLVER operates locally within the
+!  current process, whereas the SMOOTHER object accounts for (possible)
+!  interactions between processes.
+!
 module mld_s_base_smoother_mod
 
   use mld_s_base_solver_mod

mlprec/mld_s_diag_solver.f90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_s_diag_solver_mod.f90
 !
+! Module: mld_s_diag_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_diag_solver_type data structure containing the 
+!    simple diagonal solver. This extracts the main diagonal of a matrix
+!    and precomputes its inverse. Combined with a Jacobi "smoother" generates
+!    what are commonly known as the classic Jacobi iterations
 !
-!
-!
-
 module mld_s_diag_solver
 
   use mld_s_base_solver_mod

mlprec/mld_s_gs_solver.f90

@@ -38,11 +38,19 @@
 !!$
 !
 !
+! File: mld_s_gs_solver_mod.f90
 !
+! Module: mld_s_gs_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_gs_solver_type data structure containing the ingredients
+!    for a local Gauss-Seidel iteration. We provide Forward GS (FWGS) and
+!    backward GS (BWGS). The iterations are local to a process (they operate
+!    on the block diagonal). Combined with a Jacobi smoother will generate a
+!    hybrid-Gauss-Seidel solver, i.e. Gauss-Seidel within each process, Jacobi
+!    among the processes. 
 !
 !
-
 module mld_s_gs_solver
 
   use mld_s_base_solver_mod

mlprec/mld_s_id_solver.f90

@@ -42,7 +42,6 @@
 ! Identity solver. Reference for nullprec. 
 !
 !
-
 module mld_s_id_solver
 
   use mld_s_base_solver_mod

mlprec/mld_s_ilu_fact_mod.f90

@@ -36,6 +36,16 @@
 !!$  POSSIBILITY OF SUCH DAMAGE.
 !!$ 
 !!$
+!
+!
+! File: mld_s_ilu_fact_mod.f90
+!
+! Module: mld_s_ilu_fact_mod
+!
+!  This module defines some interfaces used internally by the implementation if
+!  mld_s_ilu_solver, but not visible to the end user. 
+!
+!
 module mld_s_ilu_fact_mod
 
   use mld_s_base_solver_mod 

mlprec/mld_s_ilu_solver.f90

@@ -38,11 +38,23 @@
 !!$
 !
 !
+! File: mld_s_ilu_solver_mod.f90
 !
+! Module: mld_s_ilu_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_ilu_solver_type data structure containing the ingredients
+!    for a local Incomplete LU factorization.
+!    1. The factorization is always restricted to the diagonal block of the
+!       current image (coherently with the definition of a SOLVER as a local
+!       object)
+!    2. The code provides support for both pattern-based ILU(K) and
+!       threshold base ILU(T,L)
+!    3. The diagonal is stored separately, so strictly speaking this is
+!       an incomplete LDU factorization; 
+!    4. The application phase is shared;
 !
 !
-
 module mld_s_ilu_solver
 
   use mld_base_prec_type, only : mld_fact_names

mlprec/mld_s_inner_mod.f90

@@ -41,8 +41,8 @@
 ! Module: mld_inner_mod
 !
 !  This module defines the interfaces to the real/complex, single/double
-!  precision versions of the MLD2P4 routines, except those of the user level,
-!  whose interfaces are defined in mld_prec_mod.f90.
+!  precision versions of inner MLD2P4 routines.
+!  The interfaces  of the user level routines are defined in mld_prec_mod.f90.
 !
 module mld_s_inner_mod
   use mld_s_prec_type
@@ -94,34 +94,6 @@ module mld_s_inner_mod
     end subroutine mld_smlprec_aply_vect
   end interface mld_mlprec_aply
  
-  interface mld_bld_mlhier_aggsize
-    subroutine mld_s_bld_mlhier_aggsize(casize,mxplevs,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_sspmat_type, psb_desc_type,psb_spk_
-      use mld_s_prec_type, only : mld_s_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(in)    :: casize,mxplevs
-      real(psb_spk_)                   :: mnaggratio
-      type(psb_sspmat_type),intent(in), target           :: a
-      type(psb_desc_type), intent(inout), target         :: desc_a
-      type(mld_s_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_s_bld_mlhier_aggsize
-  end interface mld_bld_mlhier_aggsize
-
-  interface mld_bld_mlhier_array
-    subroutine mld_s_bld_mlhier_array(nplevs,casize,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_sspmat_type, psb_desc_type, psb_spk_
-      use mld_s_prec_type, only : mld_s_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(inout)            :: nplevs, casize
-      real(psb_spk_)                              :: mnaggratio
-      type(psb_sspmat_type),intent(in), target :: a
-      type(psb_desc_type), intent(inout), target  :: desc_a
-      type(mld_s_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_s_bld_mlhier_array
-  end interface mld_bld_mlhier_array
-  
   interface mld_aggrmap_bld
     subroutine mld_s_lev_aggrmap_bld(p,a,desc_a,ilaggr,nlaggr,op_prol,info)
       use psb_base_mod, only : psb_sspmat_type, psb_desc_type, psb_spk_, psb_ipk_
@@ -191,8 +163,6 @@ module mld_s_inner_mod
     end subroutine mld_saggrmat_asb
   end interface mld_aggrmat_asb
 
-  
-
   abstract interface
     subroutine mld_saggrmat_var_asb(a,desc_a,ilaggr,nlaggr,parms,ac,op_prol,op_restr,info)
       use psb_base_mod, only : psb_sspmat_type, psb_desc_type, psb_spk_, psb_ipk_
@@ -207,10 +177,8 @@ module mld_s_inner_mod
     end subroutine mld_saggrmat_var_asb
   end interface
 
-
   procedure(mld_saggrmat_var_asb) ::  mld_saggrmat_nosmth_asb, &
        & mld_saggrmat_smth_asb, mld_saggrmat_minnrg_asb, &
        & mld_saggrmat_biz_asb
 
-
 end module mld_s_inner_mod

mlprec/mld_s_jac_smoother.f90

@@ -37,10 +37,18 @@
 !!$ 
 !!$
 !
+! File: mld_s_jac_smoother_mod.f90
 !
+! Module: mld_s_jac_smoother_mod
 !
-!
-!
+!  This module defines: 
+!    the mld_s_jac_smoother_type data structure containing the
+!    smoother for a Jacobi/block Jacobi smoother.
+!  The smoother stores in ND the block off-diagonal matrix.
+!  One special case is treated separately, when the solver is DIAG
+!  then the ND is the entire off-diagonal part of the matrix (including the
+!  main diagonal block), so that it becomes possible to implement
+!  pure Jacobi global solver. 
 ! 
 module mld_s_jac_smoother
 

mlprec/mld_s_mumps_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_s_mumps_solver_mod.f90
 !
+! Module: mld_s_mumps_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_mumps_solver_type data structure containing the ingredients
+!    to interface with the MUMPS package. 
+!    1. The factorization can be either restricted to the diagonal block of the
+!       current image or distributed (and thus exact)
 !
-!
-!
-
 module mld_s_mumps_solver
 #if defined(HAVE_MUMPS_)
   use smumps_struc_def

mlprec/mld_s_slu_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_s_slu_solver_mod.f90
 !
+! Module: mld_s_slu_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_slu_solver_type data structure containing the ingredients
+!    to interface with the SuperLU package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_s_slu_solver
 
   use iso_c_binding

mlprec/mld_s_sludist_solver.F90

@@ -37,12 +37,17 @@
 !!$ 
 !!$
 !
+! File: mld_s_sludist_solver_mod.f90
 !
+! Module: mld_s_sludist_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_sludist_solver_type data structure containing the ingredients
+!    to interface with the SuperLU_Dist package. 
+!    1. The factorization is distributed (and thus exact)
 !
 !
 !
-
 module mld_s_sludist_solver
 
   use iso_c_binding

mlprec/mld_s_umf_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_s_umf_solver_mod.f90
 !
+! Module: mld_s_umf_solver_mod
 !
+!  This module defines: 
+!  - the mld_s_umf_solver_type data structure containing the ingredients
+!    to interface with the UMFPACK package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_s_umf_solver
 
   use iso_c_binding

mlprec/mld_z_as_smoother.f90

@@ -37,10 +37,25 @@
 !!$ 
 !!$
 !
+! File: mld_z_as_smoother_mod.f90
 !
+! Module: mld_z_as_smoother_mod
 !
+!  This module defines: 
+!    the mld_z_as_smoother_type data structure containing the
+!    smoother for an Additive Schwarz smoother.
 !
+!  To begin with, the build procedure constructs the extended
+!  matrix A and its corresponding descriptor (this has multiple
+!  halo layers duplicated across different processes); it then 
+!  stores in ND the block off-diagonal matrix, and builds the solver
+!  on the (extended) block diagonal matrix.
 !
+!  The code allows for the variations of Additive Schwartz, Restricted
+!  Additive Schwartz and Additive Schwartz with Harmonic Extensions.
+!  From an implementation point of view, these are handled by
+!  combining application/non-application of the prolongator/restrictor
+!  operators.
 !  
 module mld_z_as_smoother
 

mlprec/mld_z_base_smoother_mod.f90

@@ -50,7 +50,14 @@
 !  - printing a	description of the preconditioner;
 !  - deallocating the preconditioner data structure.
 !
-
+!  What is the difference between a smoother and a solver?
+!  In the mathematics literature the two concepts are treated
+!  essentially as synonymous, but here we are using them in a more
+!  computer-science oriented fashion. In particular, a SMOOTHER object
+!  contains a SOLVER object: the SOLVER operates locally within the
+!  current process, whereas the SMOOTHER object accounts for (possible)
+!  interactions between processes.
+!
 module mld_z_base_smoother_mod
 
   use mld_z_base_solver_mod

mlprec/mld_z_diag_solver.f90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_z_diag_solver_mod.f90
 !
+! Module: mld_z_diag_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_diag_solver_type data structure containing the 
+!    simple diagonal solver. This extracts the main diagonal of a matrix
+!    and precomputes its inverse. Combined with a Jacobi "smoother" generates
+!    what are commonly known as the classic Jacobi iterations
 !
-!
-!
-
 module mld_z_diag_solver
 
   use mld_z_base_solver_mod

mlprec/mld_z_gs_solver.f90

@@ -38,11 +38,19 @@
 !!$
 !
 !
+! File: mld_z_gs_solver_mod.f90
 !
+! Module: mld_z_gs_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_gs_solver_type data structure containing the ingredients
+!    for a local Gauss-Seidel iteration. We provide Forward GS (FWGS) and
+!    backward GS (BWGS). The iterations are local to a process (they operate
+!    on the block diagonal). Combined with a Jacobi smoother will generate a
+!    hybrid-Gauss-Seidel solver, i.e. Gauss-Seidel within each process, Jacobi
+!    among the processes. 
 !
 !
-
 module mld_z_gs_solver
 
   use mld_z_base_solver_mod

mlprec/mld_z_id_solver.f90

@@ -42,7 +42,6 @@
 ! Identity solver. Reference for nullprec. 
 !
 !
-
 module mld_z_id_solver
 
   use mld_z_base_solver_mod

mlprec/mld_z_ilu_fact_mod.f90

@@ -36,6 +36,16 @@
 !!$  POSSIBILITY OF SUCH DAMAGE.
 !!$ 
 !!$
+!
+!
+! File: mld_z_ilu_fact_mod.f90
+!
+! Module: mld_z_ilu_fact_mod
+!
+!  This module defines some interfaces used internally by the implementation if
+!  mld_z_ilu_solver, but not visible to the end user. 
+!
+!
 module mld_z_ilu_fact_mod
 
   use mld_z_base_solver_mod 

mlprec/mld_z_ilu_solver.f90

@@ -38,11 +38,23 @@
 !!$
 !
 !
+! File: mld_z_ilu_solver_mod.f90
 !
+! Module: mld_z_ilu_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_ilu_solver_type data structure containing the ingredients
+!    for a local Incomplete LU factorization.
+!    1. The factorization is always restricted to the diagonal block of the
+!       current image (coherently with the definition of a SOLVER as a local
+!       object)
+!    2. The code provides support for both pattern-based ILU(K) and
+!       threshold base ILU(T,L)
+!    3. The diagonal is stored separately, so strictly speaking this is
+!       an incomplete LDU factorization; 
+!    4. The application phase is shared;
 !
 !
-
 module mld_z_ilu_solver
 
   use mld_base_prec_type, only : mld_fact_names

mlprec/mld_z_inner_mod.f90

@@ -41,8 +41,8 @@
 ! Module: mld_inner_mod
 !
 !  This module defines the interfaces to the real/complex, single/double
-!  precision versions of the MLD2P4 routines, except those of the user level,
-!  whose interfaces are defined in mld_prec_mod.f90.
+!  precision versions of inner MLD2P4 routines.
+!  The interfaces  of the user level routines are defined in mld_prec_mod.f90.
 !
 module mld_z_inner_mod
   use mld_z_prec_type
@@ -94,34 +94,6 @@ module mld_z_inner_mod
     end subroutine mld_zmlprec_aply_vect
   end interface mld_mlprec_aply
  
-  interface mld_bld_mlhier_aggsize
-    subroutine mld_z_bld_mlhier_aggsize(casize,mxplevs,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_zspmat_type, psb_desc_type,psb_dpk_
-      use mld_z_prec_type, only : mld_z_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(in)    :: casize,mxplevs
-      real(psb_dpk_)                   :: mnaggratio
-      type(psb_zspmat_type),intent(in), target           :: a
-      type(psb_desc_type), intent(inout), target         :: desc_a
-      type(mld_z_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_z_bld_mlhier_aggsize
-  end interface mld_bld_mlhier_aggsize
-
-  interface mld_bld_mlhier_array
-    subroutine mld_z_bld_mlhier_array(nplevs,casize,mnaggratio,a,desc_a,precv,info)
-      use psb_base_mod, only : psb_ipk_, psb_zspmat_type, psb_desc_type, psb_dpk_
-      use mld_z_prec_type, only : mld_z_onelev_type
-      implicit none 
-      integer(psb_ipk_), intent(inout)            :: nplevs, casize
-      real(psb_dpk_)                              :: mnaggratio
-      type(psb_zspmat_type),intent(in), target :: a
-      type(psb_desc_type), intent(inout), target  :: desc_a
-      type(mld_z_onelev_type), allocatable, target, intent(inout)  :: precv(:)
-      integer(psb_ipk_), intent(out)   :: info
-    end subroutine mld_z_bld_mlhier_array
-  end interface mld_bld_mlhier_array
-  
   interface mld_aggrmap_bld
     subroutine mld_z_lev_aggrmap_bld(p,a,desc_a,ilaggr,nlaggr,op_prol,info)
       use psb_base_mod, only : psb_zspmat_type, psb_desc_type, psb_dpk_, psb_ipk_
@@ -191,8 +163,6 @@ module mld_z_inner_mod
     end subroutine mld_zaggrmat_asb
   end interface mld_aggrmat_asb
 
-  
-
   abstract interface
     subroutine mld_zaggrmat_var_asb(a,desc_a,ilaggr,nlaggr,parms,ac,op_prol,op_restr,info)
       use psb_base_mod, only : psb_zspmat_type, psb_desc_type, psb_dpk_, psb_ipk_
@@ -207,10 +177,8 @@ module mld_z_inner_mod
     end subroutine mld_zaggrmat_var_asb
   end interface
 
-
   procedure(mld_zaggrmat_var_asb) ::  mld_zaggrmat_nosmth_asb, &
        & mld_zaggrmat_smth_asb, mld_zaggrmat_minnrg_asb, &
        & mld_zaggrmat_biz_asb
 
-
 end module mld_z_inner_mod

mlprec/mld_z_jac_smoother.f90

@@ -37,10 +37,18 @@
 !!$ 
 !!$
 !
+! File: mld_z_jac_smoother_mod.f90
 !
+! Module: mld_z_jac_smoother_mod
 !
-!
-!
+!  This module defines: 
+!    the mld_z_jac_smoother_type data structure containing the
+!    smoother for a Jacobi/block Jacobi smoother.
+!  The smoother stores in ND the block off-diagonal matrix.
+!  One special case is treated separately, when the solver is DIAG
+!  then the ND is the entire off-diagonal part of the matrix (including the
+!  main diagonal block), so that it becomes possible to implement
+!  pure Jacobi global solver. 
 ! 
 module mld_z_jac_smoother
 

mlprec/mld_z_mumps_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_z_mumps_solver_mod.f90
 !
+! Module: mld_z_mumps_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_mumps_solver_type data structure containing the ingredients
+!    to interface with the MUMPS package. 
+!    1. The factorization can be either restricted to the diagonal block of the
+!       current image or distributed (and thus exact)
 !
-!
-!
-
 module mld_z_mumps_solver
 #if defined(HAVE_MUMPS_)
   use zmumps_struc_def

mlprec/mld_z_slu_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_z_slu_solver_mod.f90
 !
+! Module: mld_z_slu_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_slu_solver_type data structure containing the ingredients
+!    to interface with the SuperLU package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_z_slu_solver
 
   use iso_c_binding

mlprec/mld_z_sludist_solver.F90

@@ -37,12 +37,17 @@
 !!$ 
 !!$
 !
+! File: mld_z_sludist_solver_mod.f90
 !
+! Module: mld_z_sludist_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_sludist_solver_type data structure containing the ingredients
+!    to interface with the SuperLU_Dist package. 
+!    1. The factorization is distributed (and thus exact)
 !
 !
 !
-
 module mld_z_sludist_solver
 
   use iso_c_binding

mlprec/mld_z_umf_solver.F90

@@ -37,12 +37,16 @@
 !!$ 
 !!$
 !
+! File: mld_z_umf_solver_mod.f90
 !
+! Module: mld_z_umf_solver_mod
 !
+!  This module defines: 
+!  - the mld_z_umf_solver_type data structure containing the ingredients
+!    to interface with the UMFPACK package. 
+!    1. The factorization is restricted to the diagonal block of the
+!       current image.
 !
-!
-!
-
 module mld_z_umf_solver
 
   use iso_c_binding