Add zero_gradient and linear_extrap boundary conditions (#1094)

PR checklist

    Short (1 sentence) summary of your PR:
    Add zero_gradient and linear_extrap boundary conditions
    Developer(s):
    apcraig
    Suggest PR reviewers from list in the column to the right.
    Please copy the PR test results link or provide a summary of testing completed below.
    All tests pass and bit-for-bit as expected. https://github.com/CICE-Consortium/Test-Results/wiki/cice_by_hash_forks#0e59535ce2009a3175e67156793b3ec83f2a3c69
    How much do the PR code changes differ from the unmodified code?
        bit for bit
        different at roundoff level
        more substantial
    Does this PR create or have dependencies on Icepack or any other models?
        Yes
        No
    Does this PR update the Icepack submodule? If so, the Icepack submodule must point to a hash on Icepack's main branch.
        Yes
        No
    Does this PR add any new test cases?
        Yes
        No
    Is the documentation being updated? ("Documentation" includes information on the wiki or in the .rst files from doc/source/, which are used to create the online technical docs at https://readthedocs.org/projects/cice-consortium-cice/. A test build of the technical docs will be performed as part of the PR testing.)
        Yes
        No, does the documentation need to be updated at a later time?
            Yes
            No
    Please document the changes in detail, including why the changes are made. This will become part of the PR commit log.

Add zero_gradient and linear_extrap boundary conditions

This provides options to set the boundary conditions around the edge for a regional grid. Only halo values on the outside halo are affected. This is implemented largely in the HaloUpdates in ice_boundary.F90, both in the mpi and serial implementations. The boundary conditions are computed locally for each block and don't require any explicit communications. They are implemented consistent with mixing boundary conditions in the ew and ns directions. The zero_gradient boundary condition sets the halo equal to the values on the boundary of the domain, basically zero gradient into the halo. The linear_extrap boundary condition sets the halo values such that the gradient across the halo matches the gradient on the edge of the active domain, basically constant gradient.

The zero_gradient and linear_extrap boundary conditions have been implemented as an interim step toward a regional grid capability. Until restoring options are complete and the regional capability is fully tested, these boundary conditions may produce nonphysical values such as negative ice thickness.

-    Added zero_gradient and linear_extrap code to HaloUpdate subroutines.
-    Refactored the ice_boundary.F90 to leverage automated code generation and sync the mpi and serial versions of the code.
-    Created a generate_haloUpdates.sh script to generate the various haloUpdate subroutines quickly and consistently. This script lives in cicecore/cicedyn/infrastructure/comm/mpi and has a README. This reduces effort and risk if the haloUpdate needs to be updated in the future.
-    Synchronized the mpi and serial versions of ice_boundary.F90. Now the only difference in the files is a #define in the serial version to turn off the MPI code.
-    Update the halochk subroutines to validate zero_gradient and linear_extrap boundary condition options.
-    Updated some initialization to account for the new boundary condition options.
-    Added explicit checks for valid boundary_type settings in ice_domain.F90. This means checks for invalid values later in the code can be removed.
-    Add set_nml.boxgauss which is a box test with a gauss distibution of ice in the center. Added several tests leveraging this new configuration. Added bczerogradient and bclinearextrap set_nml options and tests.
-    Update the set_nml filenames for boundary condition settings, add "bc" to start of string.
-    Update the test suite to cover the new boundary conditions and improve halochk unit test coverage overall.
-    Update the documentation.

Improved the plabeld argument type in debug_ice so the string length is more flexible. This issue was detected while testing.

Update initialization of uvmCD in ice_grid.F90 due to uninitialized values triggering and error in some compilers.

Author: apcraig

cicecore/cicedyn/analysis/ice_diagnostics.F90

@@ -1722,7 +1722,7 @@ end subroutine init_diags
 
       subroutine debug_ice(iblk, plabeld)
 
-      character (char_len), intent(in) :: plabeld
+      character (len=*), intent(in) :: plabeld
       integer (kind=int_kind), intent(in) :: iblk
 
       ! local
@@ -1772,7 +1772,7 @@ subroutine print_state(plabel,i,j,iblk)
           fsens, flat, evap, flwout, swvdr, swvdf, swidr, swidf, rhoa, &
           frzmlt, sst, sss, Tf, Tref, Qref, Uref, uocn, vocn, strtltxU, strtltyU
 
-      character (len=20), intent(in) :: plabel
+      character (len=*), intent(in) :: plabel
 
       integer (kind=int_kind), intent(in) :: &
           i, j       , & ! horizontal indices
@@ -1791,7 +1791,7 @@ subroutine print_state(plabel,i,j,iblk)
       logical (kind=log_kind) :: tr_fsd, tr_iso, tr_snow
 
       type (block) :: &
-         this_block           ! block information for current block
+           this_block    ! block information for current block
 
       character(len=*), parameter :: subname = '(print_state)'
 

cicecore/cicedyn/infrastructure/comm/mpi/README.generate_haloupdates

@@ -0,0 +1,80 @@
+
+How to Generate the ice_HaloUpdate subroutines quickly
+
+generate_haloUpdates.sh is a script that can generate the multiple
+ice_HaloUpdate calls in ice_boundary.F90 to keep them all self-consistent.  
+The script uses a template to generate the various haloUpdate subroutines 
+depending on dimension and data type.  It is implemented so it can be
+used in both the mpi and serial directories.
+
+generate_haloUpdates.sh creates a file for each subroutine with a
+name like HaloUpdate2DR8.subr.  Those files are catted into HaloUpdate_all.subr
+in the order those subroutines appear in ice_boundary.F90.  The main
+template in generate_haloUpdates.sh creates all the subroutines except
+the 2DL1 subroutine.  That subroutine is generated directly via a cat
+near the bottom of the script because the 2DL1 implementation is unique.
+It converts the logicals to integers, calls 2DI4, and then converts the 
+integers back to logicals.
+
+Remember that there are mpi and serial version of the ice_boundary.F90
+file and both should be updated and synchronized at the same time.
+
+The recommended usage is described below.
+
+1. Compare mpi and serial versions
+
+  cd cicecore/cicedyn/infrastructure/comm/mpi
+  diff ../serial/ice_boundary.F90 ./ice_boundary.F90
+
+  ! The only difference should be a #define at the top of the file.
+  ! If there are other differences, it suggests someone updated one
+  ! file and not the other.  Try to reconcile this first.
+
+2. Verify the current version of generate_haloUpdates.sh
+
+  cd cicecore/cicedyn/infrastructure/comm/mpi
+  sed -n '/subroutine ice_HaloUpdate2DR8/,/end subroutine ice_HaloUpdate4DI4/p' ice_boundary.F90 >! HaloUpdate_all.current
+  ./generate_haloUpdates.sh
+  diff HaloUpdate_all.current HaloUpdate_all.subr
+
+  ! Verify generate_haloUpdates.sh produces code that matches the current implementation in
+  ! ice_boundary.F90.  If it doesn't, it suggests someone made manual changes to the subroutines 
+  ! in ice_boundary.F90.  Try to reconcile those differences and update generate_haloUpdates.sh first
+
+3. Update generate_haloUpdates.sh and generate new subroutines
+
+  ! Modify generate_haloUpdates.sh to generate updated code then run
+
+  ./generate_haloUpdates.sh
+  diff haloUpdate_all.current haloUpdate_all.subr
+
+  ! Review diffences with the current code (HaloUpdate_all.current)
+
+4. Update ice_boundary.F90
+
+  ! When the changes are reasonable and as expected, edit ice_boundary.F90, cut out the code
+  !  between "subroutine ice_HaloUpdate2DR8" and "end subroutine ice_HaloUpdate4DI4" and replace
+  !  that code with the latest HaloUpdate_all.subr file.  You can do it manually or try
+
+  sed -e '/subroutine ice_HaloUpdate2DR8/,/end subroutine ice_HaloUpdate4DI4/c REPLACEHERE' ice_boundary.F90 >! tmpfile
+  sed -e '/REPLACEHERE/r HaloUpdate_all.subr' -e '/REPLACEHERE/d' tmpfile >! ice_boundary.F90.new
+  rm tmpfile
+  diff ice_boundary.F90 ice_boundary.F90.new
+
+  ! There may be some extra blank lines or subroutine separators that need to be cleaned up at the
+  ! start or end of the replacement code, but then
+
+  mv ice_boundary.F90.new ice_boundary.F90
+
+5. Update serial version of ice_boundary.F90
+
+  ! Copy mpi/ice_boundary.F90 to serial/ice_boundary.F90 and add
+
+  #define SERIAL_REMOVE_MPI
+
+  ! to the top of the serial/ice_boundary.F90 code to turn off MPI in that version
+
+6. Test and test again
+
+  ! Run both single and multi processor tests and iterate until done.
+