psblas3:

base/modules/psb_base_mat_mod.f90
 base/modules/psb_c_mat_mod.f90
 base/modules/psb_d_mat_mod.f90
 base/modules/psb_s_mat_mod.f90
 base/modules/psb_z_mat_mod.f90

Further description of internal structure.

base/modules/psb_base_mat_mod.f90

@@ -67,6 +67,13 @@ module psb_base_mat_mod
   
   !
   ! type psb_base_sparse_mat: the basic data about your matrix
+  !            This class is extended twice, to provide the various
+  !            data variations S/D/C/Z and to implement the actual
+  !            storage formats. The grandchild classes are then
+  !            encapsulated to implement the STATE design pattern.
+  !            We have an ambiguity in that the inner class has a
+  !            "state" variable; we hope the context will make it clear. 
+  !
   !  M:        number of rows
   !  N:        number of columns
   !  STATE:    null:   pristine
@@ -74,12 +81,23 @@ module psb_base_mat_mod
   !            assembled: ready to use in computations
   !            update: accepts coefficients but only
   !                    in already existing entries
+  !            The transitions among the states are detailed in
+  !            psb_T_mat_mod
+  !            
   !  TRIANGLE: is it triangular?
   !  UPPER:    If it is triangular, is it upper (otherwise lower)
   !  UNITD:    If it is triangular, is the diagonal assumed to 
   !            be unitary and not stored explicitly?
   !  SORTED:   are the entries guaranteed to be sorted? 
   !
+  ! DUPLICATE: How duplicate entries are to be handled when
+  !            transitioning from the BUILD to the ASSEMBLED state. 
+  !            While many formats would allow for duplicate
+  !            entries, it is much better to constrain the matrices
+  !            NOT to have duplicate entries, except while in the
+  !            BUILD state; in our overall design, only COO matrices
+  !            can ever be in the BUILD state, hence all other formats
+  !            cannot have duplicate entries.
   ! 
   type  :: psb_base_sparse_mat
     integer, private     :: m, n

base/modules/psb_c_mat_mod.f90

@@ -37,9 +37,35 @@
 ! provide a mean of switching, at run-time, among different formats,
 ! potentially unknown at the library compile-time by adding a layer of
 ! indirection. This type encapsulates the psb_c_base_sparse_mat class
-! inside another class which is the one visible to the user. All the
-! methods of the psb_c_mat_mod simply call the methods of the
-! encapsulated class, except for cscnv and cp_from/cp_to.
+! inside another class which is the one visible to the user. 
+! Most methods of the psb_c_mat_mod simply call the methods of the
+! encapsulated class.
+! The exceptions are mainly cscnv and cp_from/cp_to; these provide
+! the functionalities to have the encapsulated class change its
+! type dynamically, and to extract/input an inner object.
+!
+! A sparse matric has a state corresponding to its progression
+! through the application life.
+! In particular, computational methods can only be invoked when
+! the matrix is in the ASSEMBLED state, whereas the other states are
+! dedicated to operations on the internal matrix data. 
+! A sparse matrix can move between states according to the 
+! following state transition table. Associated with these states are
+! the possible dynamic types of the inner matrix object.
+! Only COO matrices can ever be in the BUILD state, whereas
+! the ASSEMBLED and UPDATE state can be entered by any class. 
+! 
+! In           Out        Method    
+!| ----------------------------------
+!| Null         Build      csall
+!| Build        Build      csput
+!| Build        Assembled  cscnv
+!| Assembled    Assembled  cscnv
+!| Assembled    Update     reinit
+!| Update       Update     csput
+!| Update       Assembled  cscnv
+!| *            unchanged  reall 
+!| Assembled    Null       free
 ! 
 
 

base/modules/psb_d_mat_mod.f90

@@ -37,9 +37,35 @@
 ! provide a mean of switching, at run-time, among different formats,
 ! potentially unknown at the library compile-time by adding a layer of
 ! indirection. This type encapsulates the psb_d_base_sparse_mat class
-! inside another class which is the one visible to the user. All the
-! methods of the psb_d_mat_mod simply call the methods of the
-! encapsulated class, except for cscnv and cp_from/cp_to.
+! inside another class which is the one visible to the user. 
+! Most methods of the psb_d_mat_mod simply call the methods of the
+! encapsulated class.
+! The exceptions are mainly cscnv and cp_from/cp_to; these provide
+! the functionalities to have the encapsulated class change its
+! type dynamically, and to extract/input an inner object.
+!
+! A sparse matric has a state corresponding to its progression
+! through the application life.
+! In particular, computational methods can only be invoked when
+! the matrix is in the ASSEMBLED state, whereas the other states are
+! dedicated to operations on the internal matrix data. 
+! A sparse matrix can move between states according to the 
+! following state transition table. Associated with these states are
+! the possible dynamic types of the inner matrix object.
+! Only COO matrices can ever be in the BUILD state, whereas
+! the ASSEMBLED and UPDATE state can be entered by any class. 
+! 
+! In           Out        Method    
+!| ----------------------------------
+!| Null         Build      csall
+!| Build        Build      csput
+!| Build        Assembled  cscnv
+!| Assembled    Assembled  cscnv
+!| Assembled    Update     reinit
+!| Update       Update     csput
+!| Update       Assembled  cscnv
+!| *            unchanged  reall 
+!| Assembled    Null       free
 ! 
 
 

base/modules/psb_s_mat_mod.f90

@@ -37,9 +37,35 @@
 ! provide a mean of switching, at run-time, among different formats,
 ! potentially unknown at the library compile-time by adding a layer of
 ! indirection. This type encapsulates the psb_s_base_sparse_mat class
-! inside another class which is the one visible to the user. All the
-! methods of the psb_s_mat_mod simply call the methods of the
-! encapsulated class, except for cscnv and cp_from/cp_to.
+! inside another class which is the one visible to the user. 
+! Most methods of the psb_s_mat_mod simply call the methods of the
+! encapsulated class.
+! The exceptions are mainly cscnv and cp_from/cp_to; these provide
+! the functionalities to have the encapsulated class change its
+! type dynamically, and to extract/input an inner object.
+!
+! A sparse matric has a state corresponding to its progression
+! through the application life.
+! In particular, computational methods can only be invoked when
+! the matrix is in the ASSEMBLED state, whereas the other states are
+! dedicated to operations on the internal matrix data. 
+! A sparse matrix can move between states according to the 
+! following state transition table. Associated with these states are
+! the possible dynamic types of the inner matrix object.
+! Only COO matrices can ever be in the BUILD state, whereas
+! the ASSEMBLED and UPDATE state can be entered by any class. 
+! 
+! In           Out        Method    
+!| ----------------------------------
+!| Null         Build      csall
+!| Build        Build      csput
+!| Build        Assembled  cscnv
+!| Assembled    Assembled  cscnv
+!| Assembled    Update     reinit
+!| Update       Update     csput
+!| Update       Assembled  cscnv
+!| *            unchanged  reall 
+!| Assembled    Null       free
 ! 
 
 

base/modules/psb_z_mat_mod.f90

@@ -37,9 +37,35 @@
 ! provide a mean of switching, at run-time, among different formats,
 ! potentially unknown at the library compile-time by adding a layer of
 ! indirection. This type encapsulates the psb_z_base_sparse_mat class
-! inside another class which is the one visible to the user. All the
-! methods of the psb_z_mat_mod simply call the methods of the
-! encapsulated class, except for cscnv and cp_from/cp_to.
+! inside another class which is the one visible to the user. 
+! Most methods of the psb_z_mat_mod simply call the methods of the
+! encapsulated class.
+! The exceptions are mainly cscnv and cp_from/cp_to; these provide
+! the functionalities to have the encapsulated class change its
+! type dynamically, and to extract/input an inner object.
+!
+! A sparse matric has a state corresponding to its progression
+! through the application life.
+! In particular, computational methods can only be invoked when
+! the matrix is in the ASSEMBLED state, whereas the other states are
+! dedicated to operations on the internal matrix data. 
+! A sparse matrix can move between states according to the 
+! following state transition table. Associated with these states are
+! the possible dynamic types of the inner matrix object.
+! Only COO matrices can ever be in the BUILD state, whereas
+! the ASSEMBLED and UPDATE state can be entered by any class. 
+! 
+! In           Out        Method    
+!| ----------------------------------
+!| Null         Build      csall
+!| Build        Build      csput
+!| Build        Assembled  cscnv
+!| Assembled    Assembled  cscnv
+!| Assembled    Update     reinit
+!| Update       Update     csput
+!| Update       Assembled  cscnv
+!| *            unchanged  reall 
+!| Assembled    Null       free
 !