refactor(ListModule): trim dependencies, add defaults, add docstrings (…

…MODFLOW-USGS#1484)

* add/format docstrings for ListType type-bound procedures
* add default equality predicate associated(x, y) for ListType%ContainsObject
* just print programmer errors instead of using sim_message() in ArrayHandlersModule
* move/refactor stop_with_error() -> ErrorUtilModule pstop()... avoid sim-related dependencies

make/makefile

@@ -6,35 +6,35 @@ include ./makedefaults
 # Define the source file directories
 SOURCEDIR1=../src
 SOURCEDIR2=../src/Exchange
-SOURCEDIR3=../src/Model
-SOURCEDIR4=../src/Model/Geometry
-SOURCEDIR5=../src/Model/TransportModel
-SOURCEDIR6=../src/Model/ModelUtilities
-SOURCEDIR7=../src/Model/Connection
-SOURCEDIR8=../src/Model/GroundWaterTransport
-SOURCEDIR9=../src/Model/GroundWaterFlow
-SOURCEDIR10=../src/Distributed
-SOURCEDIR11=../src/Solution
-SOURCEDIR12=../src/Solution/PETSc
-SOURCEDIR13=../src/Solution/LinearMethods
-SOURCEDIR14=../src/Timing
-SOURCEDIR15=../src/Utilities
-SOURCEDIR16=../src/Utilities/TimeSeries
-SOURCEDIR17=../src/Utilities/Libraries
-SOURCEDIR18=../src/Utilities/Libraries/rcm
-SOURCEDIR19=../src/Utilities/Libraries/sparsekit
-SOURCEDIR20=../src/Utilities/Libraries/sparskit2
-SOURCEDIR21=../src/Utilities/Libraries/blas
-SOURCEDIR22=../src/Utilities/Libraries/daglib
-SOURCEDIR23=../src/Utilities/Idm
-SOURCEDIR24=../src/Utilities/Idm/selector
-SOURCEDIR25=../src/Utilities/Idm/mf6blockfile
-SOURCEDIR26=../src/Utilities/Matrix
-SOURCEDIR27=../src/Utilities/Vector
-SOURCEDIR28=../src/Utilities/Observation
-SOURCEDIR29=../src/Utilities/OutputControl
-SOURCEDIR30=../src/Utilities/Memory
-SOURCEDIR31=../src/Utilities/ArrayRead
+SOURCEDIR3=../src/Distributed
+SOURCEDIR4=../src/Solution
+SOURCEDIR5=../src/Solution/LinearMethods
+SOURCEDIR6=../src/Solution/PETSc
+SOURCEDIR7=../src/Timing
+SOURCEDIR8=../src/Utilities
+SOURCEDIR9=../src/Utilities/Idm
+SOURCEDIR10=../src/Utilities/Idm/selector
+SOURCEDIR11=../src/Utilities/Idm/mf6blockfile
+SOURCEDIR12=../src/Utilities/TimeSeries
+SOURCEDIR13=../src/Utilities/Memory
+SOURCEDIR14=../src/Utilities/OutputControl
+SOURCEDIR15=../src/Utilities/ArrayRead
+SOURCEDIR16=../src/Utilities/Libraries
+SOURCEDIR17=../src/Utilities/Libraries/rcm
+SOURCEDIR18=../src/Utilities/Libraries/blas
+SOURCEDIR19=../src/Utilities/Libraries/sparskit2
+SOURCEDIR20=../src/Utilities/Libraries/daglib
+SOURCEDIR21=../src/Utilities/Libraries/sparsekit
+SOURCEDIR22=../src/Utilities/Vector
+SOURCEDIR23=../src/Utilities/Matrix
+SOURCEDIR24=../src/Utilities/Observation
+SOURCEDIR25=../src/Model
+SOURCEDIR26=../src/Model/Connection
+SOURCEDIR27=../src/Model/GroundWaterTransport
+SOURCEDIR28=../src/Model/ModelUtilities
+SOURCEDIR29=../src/Model/GroundWaterFlow
+SOURCEDIR30=../src/Model/TransportModel
+SOURCEDIR31=../src/Model/Geometry
 
 VPATH = \
 ${SOURCEDIR1} \
@@ -75,6 +75,7 @@ OBJECTS = \
 $(OBJDIR)/kind.o \
 $(OBJDIR)/Constants.o \
 $(OBJDIR)/SimVariables.o \
+$(OBJDIR)/ErrorUtil.o \
 $(OBJDIR)/genericutils.o \
 $(OBJDIR)/defmacro.o \
 $(OBJDIR)/compilerversion.o \

msvs/mf6core.vfproj

@@ -385,6 +385,7 @@
 				<Tool Name="VFFortranCompilerTool" Preprocess="preprocessYes"/></FileConfiguration></File>
 		<File RelativePath="..\src\Utilities\DevFeature.f90"/>
 		<File RelativePath="..\src\Utilities\genericutils.f90"/>
+		<File RelativePath="..\src\Utilities\ErrorUtil.f90"/>
 		<File RelativePath="..\src\Utilities\GeomUtil.f90"/>
 		<File RelativePath="..\src\Utilities\HashTable.f90"/>
 		<File RelativePath="..\src\Utilities\HeadFileReader.f90"/>

msvs/mf6lib.vfproj

@@ -144,6 +144,7 @@
 		<File RelativePath="..\src\Utilities\compilerversion.fpp"/>
 		<File RelativePath="..\src\Utilities\Constants.f90"/>
 		<File RelativePath="..\src\Utilities\genericutils.f90"/>
+		<File RelativePath="..\src\Utilities\ErrorUtil.f90"/>
 		<File RelativePath="..\src\Utilities\GeomUtil.f90"/>
 		<File RelativePath="..\src\Utilities\HashTable.f90"/>
 		<File RelativePath="..\src\Utilities\InputOutput.f90"/>

src/Model/Connection/ConnectionBuilder.f90

@@ -2,7 +2,7 @@ module ConnectionBuilderModule
   use KindModule, only: I4B, LGP
   use SimModule, only: store_error, count_errors, ustop
   use SimVariablesModule, only: iout
-  use ListModule, only: ListType, arePointersEqual, isEqualIface, ListNodeType
+  use ListModule, only: ListType, isEqualIface, ListNodeType
   use BaseSolutionModule, only: BaseSolutionType
   use NumericalSolutionModule, only: NumericalSolutionType
   use BaseExchangeModule, only: BaseExchangeType, GetBaseExchangeFromList

src/Model/Connection/GridConnection.f90

@@ -9,7 +9,7 @@ module GridConnectionModule
   use CharacterStringModule
   use MemoryManagerModule, only: mem_allocate, mem_deallocate
   use MemoryHelperModule, only: create_mem_path
-  use ListModule, only: ListType, isEqualIface, arePointersEqual
+  use ListModule, only: ListType, isEqualIface
   use NumericalModelModule
   use GwfDisuModule
   use DisConnExchangeModule
@@ -218,11 +218,9 @@ subroutine addToRegionalModels(this, v_model)
     class(VirtualModelType), pointer :: v_model !< the model to add to the region
     ! local
     class(*), pointer :: vm_obj
-    procedure(isEqualIface), pointer :: areEqualMethod
 
     vm_obj => v_model
-    areEqualMethod => arePointersEqual
-    if (.not. this%regionalModels%ContainsObject(vm_obj, areEqualMethod)) then
+    if (.not. this%regionalModels%ContainsObject(vm_obj)) then
       call this%regionalModels%Add(vm_obj)
     end if
 

src/Solution/NumericalSolution.f90

@@ -2,6 +2,7 @@
 
 module NumericalSolutionModule
   use KindModule, only: DP, I4B, LGP
+  use ErrorUtilModule, only: pstop
   use TimerModule, only: code_timer
   use ConstantsModule, only: LINELENGTH, LENSOLUTIONNAME, LENPAKLOC, &
                              DPREC, DZERO, DEM20, DEM15, DEM6, &
@@ -12,7 +13,7 @@ module NumericalSolutionModule
                              LENMEMPATH
   use MemoryHelperModule, only: create_mem_path
   use TableModule, only: TableType, table_cr
-  use GenericUtilitiesModule, only: is_same, sim_message, stop_with_error
+  use GenericUtilitiesModule, only: is_same, sim_message
   use VersionModule, only: IDEVELOPMODE
   use BaseModelModule, only: BaseModelType
   use BaseExchangeModule, only: BaseExchangeType
@@ -1610,7 +1611,7 @@ subroutine solve(this, kiter)
       WRITE (99, *) 'MATRIX SOLUTION FOLLOWS'
       WRITE (99, '(10(I8,G15.4))') (n, this%x(N), N=1, this%NEQ)
       close (99)
-      call stop_with_error()
+      call pstop()
     end if
     !-------------------------------------------------------
     !

src/Utilities/ArrayHandlers.f90

@@ -1,9 +1,8 @@
 module ArrayHandlersModule
 
   use KindModule, only: DP, I4B, LGP
+  use ErrorUtilModule, only: pstop
   use ConstantsModule, only: LINELENGTH, MAXCHARLEN, DZERO, DTEN
-  use SimVariablesModule, only: iout
-  use GenericUtilitiesModule, only: sim_message, stop_with_error
   implicit none
   private
   public :: ExpandArray, ExpandArray2D, ExpandArrayWrapper, ExtendPtrArray
@@ -200,7 +199,6 @@ subroutine expand_character(array, increment)
     character(len=*), allocatable, intent(inout) :: array(:)
     integer(I4B), optional, intent(in) :: increment
     ! -- local
-    character(len=LINELENGTH) :: line
     character(len=MAXCHARLEN), allocatable, dimension(:) :: array_temp
     integer(I4B) :: i, inclocal, isize, lenc, newsize
     ! -- format
@@ -209,16 +207,8 @@ subroutine expand_character(array, increment)
     ! -- check character length
     lenc = len(array)
     if (lenc > MAXCHARLEN) then
-      write (line, '(a)') 'Error in ArrayHandlersModule: '// &
-        'Need to increase MAXCHARLEN'
-      call sim_message(line, iunit=iout, fmt=stdfmt)
-      call sim_message(line, fmt=stdfmt)
-      !
-      ! -- stop message
-      write (line, '(a)') 'Stopping...'
-      call sim_message(line, iunit=iout)
-      call sim_message(line)
-      call stop_with_error(138)
+      call pstop(138, 'Error in ArrayHandlersModule: '// &
+                 'Need to increase MAXCHARLEN. Stopping...')
     end if
     !
     ! -- initialize
@@ -339,7 +329,6 @@ subroutine extend_double(array, increment)
     real(DP), dimension(:), pointer, contiguous, intent(inout) :: array
     integer(I4B), optional, intent(in) :: increment
     ! -- local
-    character(len=LINELENGTH) :: line
     character(len=100) :: ermsg
     integer(I4B) :: i, inclocal, isize, istat, newsize
     real(DP), dimension(:), pointer, contiguous :: array_temp => null()
@@ -375,20 +364,8 @@ subroutine extend_double(array, increment)
     ! -- Error reporting
 99  continue
 
-    write (line, '(a)') 'Error in ArrayHandlersModule: '// &
-      'Could not increase array size'
-    call sim_message(line, iunit=iout, fmt=stdfmt)
-    call sim_message(line, fmt=stdfmt)
-    !
-    ! -- error message
-    call sim_message(ermsg, iunit=iout)
-    call sim_message(ermsg)
-    !
-    ! -- stop message
-    write (line, '(a)') 'Stopping...'
-    call sim_message(line, iunit=iout)
-    call sim_message(line)
-    call stop_with_error(138)
+    call pstop(138, 'Error in ArrayHandlersModule: '// &
+               'Could not increase array size. Stopping...')
 
   end subroutine extend_double
 
@@ -397,7 +374,6 @@ subroutine extend_integer(array, increment)
     integer(I4B), dimension(:), pointer, contiguous, intent(inout) :: array
     integer(I4B), optional, intent(in) :: increment
     ! -- local
-    character(len=LINELENGTH) :: line
     character(len=100) :: ermsg
     integer(I4B) :: i, inclocal, isize, istat, newsize
     integer(I4B), dimension(:), pointer, contiguous :: array_temp => null()
@@ -433,20 +409,8 @@ subroutine extend_integer(array, increment)
     ! -- Error reporting
 99  continue
 
-    write (line, '(a)') 'Error in ArrayHandlersModule: '// &
-      'Could not increase array size'
-    call sim_message(line, iunit=iout, fmt=stdfmt)
-    call sim_message(line, fmt=stdfmt)
-    !
-    ! -- error message
-    call sim_message(ermsg, iunit=iout)
-    call sim_message(ermsg)
-    !
-    ! -- stop message
-    write (line, '(a)') 'Stopping...'
-    call sim_message(line, iunit=iout)
-    call sim_message(line)
-    call stop_with_error(138)
+    call pstop(138, 'Error in ArrayHandlersModule: '// &
+               'Could not increase array size. Stopping ...')
 
   end subroutine extend_integer
 
@@ -536,7 +500,6 @@ subroutine remove_character(array, ipos)
     character(len=*), allocatable, intent(inout) :: array(:)
     integer(I4B), intent(in) :: ipos
     ! -- local
-    character(len=LINELENGTH) :: line
     character(len=MAXCHARLEN), allocatable, dimension(:) :: array_temp
     integer(I4B) :: i, isize, lenc, newsize, inew
     ! -- format
@@ -546,16 +509,8 @@ subroutine remove_character(array, ipos)
     lenc = len(array)
     if (lenc > MAXCHARLEN) then
 
-      write (line, '(a)') 'Error in ArrayHandlersModule: '// &
-        'Need to increase MAXCHARLEN'
-      call sim_message(line, iunit=iout, fmt=stdfmt)
-      call sim_message(line, fmt=stdfmt)
-      !
-      ! -- stop message
-      write (line, '(a)') 'Stopping...'
-      call sim_message(line, iunit=iout)
-      call sim_message(line)
-      call stop_with_error(138)
+      call pstop(138, 'Error in ArrayHandlersModule: '// &
+                 'Need to increase MAXCHARLEN. Stopping...')
     end if
     !
     ! -- calculate sizes

src/Utilities/DevFeature.f90

@@ -9,7 +9,7 @@ module DevFeatureModule
 
 contains
 
-  !> @ brief Development feature, terminate if in release mode
+  !> @brief Terminate if in release mode (guard development features)
   !!
   !! Terminate the program with an error if the IDEVELOPMODE flag
   !! is set to 0. This allows developing features on the mainline
@@ -21,7 +21,7 @@ subroutine dev_feature(errmsg, iunit)
     ! -- dummy
     character(len=*), intent(in) :: errmsg
     integer(I4B), intent(in), optional :: iunit
-    !
+
     ! -- store error and terminate if in release mode
     if (IDEVELOPMODE == 0) then
       if (present(iunit)) then
@@ -31,9 +31,7 @@ subroutine dev_feature(errmsg, iunit)
         call store_error(errmsg, terminate=.true.)
       end if
     end if
-    !
-    ! -- return
-    return
+
   end subroutine dev_feature
 
 end module DevFeatureModule

src/Utilities/ErrorUtil.f90

@@ -0,0 +1,26 @@
+module ErrorUtilModule
+  use KindModule, only: I4B
+  implicit none
+contains
+
+  !> @brief Stop the program, optionally specifying an error status code.
+  !!
+  !! If a non-zero status is specified, the program is terminated with the
+  !! error status code. If no status is specified or status=0, the program
+  !! stops with code 0. A message may be provided to print before exiting,
+  !! useful e.g. for "contact developer" messages upon programming errors.
+  !<
+  subroutine pstop(status, message)
+    integer(I4B), intent(in), optional :: status !< optional error code to return (default=0)
+    character(len=*), intent(in), optional :: message !< optional message to print before stopping
+
+    if (present(message)) print *, message
+    if (present(status)) then
+      if (status == 0) stop
+      call exit(status)
+    else
+      stop
+    end if
+  end subroutine pstop
+
+end module ErrorUtilModule