Update documentation including qc, debugger, and namelist table (#459)

* update documentation including qc and namelist table

* update version

cicecore/cicedynB/general/ice_init.F90

@@ -134,7 +134,7 @@ subroutine input_data
 
       integer (kind=int_kind) :: rpcesm, rplvl, rptopo 
       real (kind=dbl_kind) :: Cf, ksno, puny
-      integer :: abort_flag
+      character (len=char_len) :: abort_list
       character (len=64) :: tmpstr
 
       character(len=*), parameter :: subname='(input_data)'
@@ -220,7 +220,7 @@ subroutine input_data
       ! default values
       !-----------------------------------------------------------------
 
-      abort_flag = 0
+      abort_list = ""
 
       call icepack_query_parameters(puny_out=puny)
 ! nu_diag not yet defined
@@ -257,7 +257,7 @@ subroutine input_data
       history_file = 'iceh'  ! history file name prefix
       history_precision = 4  ! precision of history files
       write_ic = .false.     ! write out initial condition
-      cpl_bgc = .false.      ! history file name prefix
+      cpl_bgc = .false.      ! couple bgc thru driver
       incond_dir = history_dir ! write to history dir for default
       incond_file = 'iceh_ic'! file prefix
       dumpfreq='y'           ! restart frequency option
@@ -302,6 +302,8 @@ subroutine input_data
       mu_rdg = 3             ! e-folding scale of ridged ice, krdg_partic=1 (m^0.5)
       Cf = 17.0_dbl_kind     ! ratio of ridging work to PE change in ridging 
       ksno = 0.3_dbl_kind    ! snow thermal conductivity
+      dxrect = 0.0_dbl_kind  ! user defined grid spacing in cm in x direction
+      dyrect = 0.0_dbl_kind  ! user defined grid spacing in cm in y direction
       close_boundaries = .false.   ! true = set land on edges of grid
       basalstress= .false.   ! if true, basal stress for landfast is on
       k1 = 8.0_dbl_kind      ! 1st free parameter for landfast parameterization
@@ -762,7 +764,7 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR:   runtype=',trim(runtype), 'restart=',restart, 'ice_ic=',trim(ice_ic)
             write(nu_diag,*) subname//' ERROR:   Please review user guide'
          endif
-         abort_flag = 1
+         abort_list = trim(abort_list)//":1"
       endif
 
 #ifndef ncdf
@@ -771,13 +773,13 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR: ncdf CPP flag unset, data formats must be bin'
             write(nu_diag,*) subname//' ERROR:   check grid_format, atm_data_format, ocn_data_format or set ncdf CPP'
          endif
-         abort_flag = 2
+         abort_list = trim(abort_list)//":2"
       endif
 #endif
 
       if (advection /= 'remap' .and. advection /= 'upwind' .and. advection /= 'none') then
          if (my_task == master_task) write(nu_diag,*) subname//' ERROR: invalid advection=',trim(advection)
-         abort_flag = 3
+         abort_list = trim(abort_list)//":3"
       endif
 
       if (ncat == 1 .and. kitd == 1) then
@@ -787,7 +789,7 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR:   Use kitd = 0 (delta function ITD) with kcatbound = 0'
             write(nu_diag,*) subname//' ERROR:   or for column configurations use kcatbound = -1'
          endif
-         abort_flag = 4
+         abort_list = trim(abort_list)//":4"
       endif
 
       if (ncat /= 1 .and. kcatbound == -1) then
@@ -796,7 +798,7 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR:   ncat=',ncat,' kcatbound=',kcatbound
             write(nu_diag,*) subname//' ERROR:   Please review user guide'
          endif
-         abort_flag = 5
+         abort_list = trim(abort_list)//":5"
       endif
 
       if (kdyn == 2 .and. revised_evp) then
@@ -821,14 +823,14 @@ subroutine input_data
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: Must use only one melt pond scheme'
          endif
-         abort_flag = 6
+         abort_list = trim(abort_list)//":6"
       endif
 
       if (tr_pond_lvl .and. .not. tr_lvl) then
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: tr_pond_lvl=T but tr_lvl=F'
          endif
-         abort_flag = 30
+         abort_list = trim(abort_list)//":30"
       endif
 
 ! tcraig - this was originally implemented by resetting hs0=0. EH says it might be OK
@@ -839,15 +841,15 @@ subroutine input_data
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: tr_pond_lvl=T and hs0 /= 0'
          endif
-         abort_flag = 7
+         abort_list = trim(abort_list)//":7"
       endif
 
       if (trim(shortwave) /= 'dEdd' .and. tr_pond .and. calc_tsfc) then
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: tr_pond=T, calc_tsfc=T, invalid shortwave'
             write(nu_diag,*) subname//' ERROR:   Must use shortwave=dEdd'
          endif
-         abort_flag = 8
+         abort_list = trim(abort_list)//":8"
       endif
 
       if (tr_iso .and. n_iso==0) then
@@ -856,7 +858,7 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR:   not allocated in tracer array.'
             write(nu_diag,*) subname//' ERROR:   if tr_iso, n_iso must be > 0.'
          endif
-         abort_flag = 31
+         abort_list = trim(abort_list)//":31"
       endif
 
       if (tr_aero .and. n_aero==0) then
@@ -865,23 +867,52 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR:   not allocated in tracer array.'
             write(nu_diag,*) subname//' ERROR:   if tr_aero, n_aero must be > 0.'
          endif
-         abort_flag = 9
+         abort_list = trim(abort_list)//":9"
+      endif
+
+      if (ncat < 1) then
+         if (my_task == master_task) then
+            write(nu_diag,*) subname//' ERROR: ncat < 1'
+         endif
+         abort_list = trim(abort_list)//":32"
+      endif
+
+      if (nilyr < 1) then
+         if (my_task == master_task) then
+            write(nu_diag,*) subname//' ERROR: nilyr < 1'
+         endif
+         abort_list = trim(abort_list)//":33"
+      endif
+
+      if (nslyr < 1) then
+         if (my_task == master_task) then
+            write(nu_diag,*) subname//' ERROR: nslyr < 1'
+         endif
+         abort_list = trim(abort_list)//":34"
+      endif
+
+      if (nblyr < 1) then
+         if (my_task == master_task) then
+            write(nu_diag,*) subname//' ERROR: nblyr < 1'
+            write(nu_diag,*) subname//' ERROR:   not allowed due to history implementation.'
+         endif
+         abort_list = trim(abort_list)//":35"
       endif
 
       if (nfsd < 1) then
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: nfsd < 1'
             write(nu_diag,*) subname//' ERROR:   not allowed due to history implementation.'
          endif
-         abort_flag = 32
+         abort_list = trim(abort_list)//":36"
       endif
 
       if (trim(shortwave) /= 'dEdd' .and. tr_aero) then
          if (my_task == master_task) then
             write(nu_diag,*) subname//' ERROR: tr_aero=T, invalid shortwave'
             write(nu_diag,*) subname//' ERROR:   Must use shortwave=dEdd'
          endif
-         abort_flag = 10
+         abort_list = trim(abort_list)//":10"
       endif
 
       if ((rfracmin < -puny .or. rfracmin > c1+puny) .or. &
@@ -891,19 +922,19 @@ subroutine input_data
             write(nu_diag,*) subname//' ERROR: rfracmin, rfracmax must be between 0 and 1'
             write(nu_diag,*) subname//' ERROR:   and rfracmax >= rfracmin'
          endif
-         abort_flag = 11
+         abort_list = trim(abort_list)//":11"
       endif
       rfracmin = min(max(rfracmin,c0),c1)
       rfracmax = min(max(rfracmax,c0),c1)
 
       if (trim(atm_data_type) == 'monthly' .and. calc_strair) then
          if (my_task == master_task) write(nu_diag,*) subname//' ERROR: atm_data_type=monthly and calc_strair=T'
-         abort_flag = 12
+         abort_list = trim(abort_list)//":12"
       endif
 
       if (ktherm == 2 .and. .not. calc_Tsfc) then
          if (my_task == master_task) write(nu_diag,*) subname//' ERROR: ktherm = 2 and calc_Tsfc=F'
-         abort_flag = 13
+         abort_list = trim(abort_list)//":13"
       endif
 
 ! tcraig, is it really OK for users to run inconsistently?
@@ -925,38 +956,38 @@ subroutine input_data
       if (formdrag) then
          if (trim(atmbndy) == 'constant') then
             if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=T and atmbndy=constant'
-            abort_flag = 14
+            abort_list = trim(abort_list)//":14"
          endif
 
          if (.not. calc_strair) then
             if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=T and calc_strair=F'
-            abort_flag = 15
+            abort_list = trim(abort_list)//":15"
          endif
 
          if (.not. tr_pond) then
             if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=T and tr_pond=F'
-            abort_flag = 16
+            abort_list = trim(abort_list)//":16"
          endif
 
          if (tr_pond_cesm) then
             if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=T and frzpnd=cesm'
-            abort_flag = 17
+            abort_list = trim(abort_list)//":17"
          endif
 
          if (.not. tr_lvl) then
             if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=T and tr_lvl=F'
-            abort_flag = 18
+            abort_list = trim(abort_list)//":18"
          endif
       endif
 
       if (trim(fbot_xfer_type) == 'Cdn_ocn' .and. .not. formdrag)  then
          if (my_task == master_task) write(nu_diag,*) subname//' ERROR: formdrag=F and fbot_xfer_type=Cdn_ocn'
-         abort_flag = 19
+         abort_list = trim(abort_list)//":19"
       endif
 
       if(history_precision .ne. 4 .and. history_precision .ne. 8) then
          write (nu_diag,*) 'ERROR: bad value for history_precision, allowed values: 4, 8'
-         abort_flag = 22
+         abort_list = trim(abort_list)//":22"
       endif
 
       if (.not.(trim(dumpfreq) == 'y' .or. trim(dumpfreq) == 'Y' .or. &
@@ -1280,7 +1311,7 @@ subroutine input_data
           grid_type  /=  'regional'       .and. &
           grid_type  /=  'latlon' ) then
          if (my_task == master_task) write(nu_diag,*) subname//' ERROR: unknown grid_type=',trim(grid_type)
-         abort_flag = 20
+         abort_list = trim(abort_list)//":20"
       endif
 
       ! check for valid kevp_kernel
@@ -1294,16 +1325,16 @@ subroutine input_data
             if (kevp_kernel == 2) then
                 if (my_task == master_task) write(nu_diag,*) subname//' kevp_kernel=2 not validated, use kevp_kernel=102 for testing until it is validated'
             endif
-            abort_flag = 21
+            abort_list = trim(abort_list)//":21"
         endif
       endif
 
-      if (abort_flag /= 0) then
+      if (abort_list /= "") then
          call flush_fileunit(nu_diag)
       endif
       call ice_barrier()
-      if (abort_flag /= 0) then
-         write(nu_diag,*) subname,' ERROR: abort_flag=',abort_flag
+      if (abort_list /=  "") then
+         write(nu_diag,*) subname,' ERROR: abort_list = ',trim(abort_list)
          call abort_ice (subname//' ABORTING on input ERRORS', &
             file=__FILE__, line=__LINE__)
       endif

cicecore/version.txt

@@ -1 +1 @@
-CICE 6.1.1
+CICE 6.1.2

doc/source/conf.py

@@ -62,9 +62,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'6.1.1' 
+version = u'6.1.2' 
 # The full version, including alpha/beta/rc tags.
-version = u'6.1.1' 
+version = u'6.1.2' 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/developer_guide/dg_about.rst

@@ -20,9 +20,7 @@ Guiding principles for the creation of CICE include the following:
 Git workflow and Pull Requests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There is extensive Information for Developers documentation available.
-See https://github.com/CICE-Consortium/About-Us/wiki/Resource-Index#information-for-developers
-for information on:
+There is extensive Information for Developers documentation available.  See https://github.com/CICE-Consortium/About-Us/wiki/Resource-Index#information-for-developers for information on:
   - Contributing to model development
   - Software development practices guide
   - git Workflow Guide - including extensive information about the Pull Request process and requirements

doc/source/developer_guide/dg_dynamics.rst

@@ -23,8 +23,7 @@ binary and netcdf files.
 **cicecore/drivers/** contains subdirectories that support stand-alone drivers and other high level
 coupling layers.
 
-**cicecore/shared/** contains some basic methods related to grid decomposition, time managers, constants,
-kinds, and restart capabilities.
+**cicecore/shared/** contains some basic methods related to grid decomposition, time managers, constants, kinds, and restart capabilities.
 
 
 Dynamical Solvers
@@ -72,7 +71,7 @@ Constants
 while others have internal defaults and can be set thru namelist.
 
 Dynamic Array Allocation
-------------------
+-------------------------------
 
 CICE v5 and earlier was implemented using mainly static arrays and required several CPPs to be set to define grid size,
 blocks sizes, tracer numbers, and so forth.  With CICE v6 and later, arrays are dynamically allocated and those

doc/source/developer_guide/dg_other.rst

@@ -6,6 +6,27 @@ Other things
 =============
 
 
+.. _debugger:
+
+Running with a Debugger
+-------------------------
+
+Availability and usage of interactive debuggers varies across machines.  Contact your 
+system administrator for additional information about what’s available on your system.  
+To run with an interactive debugger, the following general steps should be taken.
+
+- Setup a case
+- Modify the env file and Macros file to add appropriate modules and compiler/ linker flags
+- Build the model
+- Get interactive hardware resources as needed
+- Open a csh shell
+- Source the env.${machine} file
+- Source cice.settings
+- Change directories to the run directory
+- Manually launch the executable thru the debugger
+
+
+
 Reproducible Sums
 ----------------------
 
@@ -79,6 +100,7 @@ modified. Be careful not to have one command outside of a loop and the
 other command inside. Timers can be run for individual blocks, if
 desired, by including the block ID in the timer calls.
 
+
 .. _addhist:
 
 Adding History fields
@@ -155,14 +177,14 @@ the tracer dependencies (weights), which are tracked using the arrays
 ``trcr_base`` (a dependency mask), ``n_trcr_strata`` (the number of
 underlying tracer layers), and ``nt_strata`` (indices of underlying layers). 
 Additional information about tracers can be found in the
-`Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/developer_guide/index.html>`_.
+`Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/developer_guide/index.html>`__.
 
 To add a tracer, follow these steps using one of the existing tracers as
 a pattern.
 
   1)  **icepack\_tracers.F90** and **icepack\_[tracer].F90**: declare tracers,
       add flags and indices, and create physics routines as described in the
-      `Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/developer_guide/dg_adding_tracers.html>`_
+      `Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/developer_guide/dg_adding_tracers.html>`__
 
   2)  **ice_arrays_column.F90**: declare arrays
 
@@ -211,6 +233,6 @@ a pattern.
        configuration in **configuration/scripts/options**.
 
   12)  If strict conservation is necessary, add diagnostics as noted for
-       topo ponds in the `Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/science_guide/index.html>`_.
+       topo ponds in the `Icepack documentation <https://cice-consortium-icepack.readthedocs.io/en/master/science_guide/index.html>`__.
 
   13)  Update documentation, including **cice_index.rst** and **ug_case_settings.rst**