Fix minor issues in documentation, key_ CPPs, bfbcomp return codes (#532

)

* Fix minor issues in documentation, key_ CPPs, bfbcomp return codes

quickstart documentation points to porting (#529)
check additional return codes in the bfbcomp tool (#524)
fix undefined variable in ice_init output (#520)
add documentation about aliases (#523)
remove key_ CPPS, can be handled by passing communicator thru interface (#498)

* update alias documentation

cicecore/cicedynB/general/ice_init.F90

@@ -1169,6 +1169,7 @@ subroutine input_data
          if (trim(grid_type) == 'tripole') then
          write(nu_diag,*)    'grid_type        = ', &
                                trim(grid_type),': user-defined grid with northern hemisphere zipper'
+            tmpstr2 = ' '
             if (trim(ns_boundary_type) == 'tripole') then
                tmpstr2 = '  on U points (nodes)'
             elseif (trim(ns_boundary_type) == 'tripoleT') then

cicecore/cicedynB/infrastructure/comm/mpi/ice_communicate.F90

@@ -13,18 +13,6 @@ module ice_communicate
    use ice_exit, only: abort_ice
    use icepack_intfc, only: icepack_warnings_flush, icepack_warnings_aborted
 
-#if defined key_oasis3 || key_oasis3mct
-   use cpl_oasis3
-#endif
-
-#if defined key_oasis4
-   use cpl_oasis4
-#endif
-
-#if defined key_iomput
-   use lib_mpp, only:   mpi_comm_opa      ! MPP library
-#endif
-
    implicit none
    private
 
@@ -83,13 +71,7 @@ subroutine init_communicate(mpicom)
    if (present(mpicom)) then
      ice_comm = mpicom
    else
-#if (defined key_oasis3 || defined key_oasis3mct || defined key_oasis4)
-     ice_comm = localComm       ! communicator from NEMO/OASISn 
-#elif defined key_iomput
-     ice_comm = mpi_comm_opa    ! communicator from NEMO/XIOS
-#else
      ice_comm = MPI_COMM_WORLD  ! Global communicator 
-#endif 
    endif
 
    call MPI_INITIALIZED(flag,ierr)

configuration/scripts/tests/test_decomp.script

@@ -75,10 +75,16 @@ foreach decomp (${decomps})
       set bfbstatus = $status
       if ($bfbstatus == 0) then
         set grade = PASS
-        echo "bfb baseline and test dataset are identical"
+        echo "bfbcomp baseline and test dataset are identical"
+      else if ( ${bfbstatus} == 1 ) then
+        set grade = FAIL
+        echo "bfbcomp baseline and test dataset are different"
+      else if ( ${bfbstatus} == 2 ) then
+        set grade = FAIL
+        echo "bfbcomp baseline missing data"
       else
         set grade = FAIL
-        echo "bfbcomp and test dataset are different"
+        echo "bfbcomp script failed"
       endif
       echo "$grade ${ICE_TESTNAME}_${decomp} bfbcomp ${base_case}" >> ${ICE_CASEDIR}/test_output
     endif

doc/source/intro/quickstart.rst

@@ -16,19 +16,21 @@ You will probably have to download some inputdata, see the `CICE wiki <https://g
 
 Software requirements are noted in this :ref:`software` section.
 
+Porting information can be found in the :ref:`porting` section.  A special porting section for personal computers 
+is in the :ref:`laptops` section.
+
 From your main CICE directory, execute::
 
   ./cice.setup -c ~/mycase1 -g gx3 -m testmachine -s diag1,thread -p 8x1
   cd ~/mycase1
   ./cice.build
   ./cice.submit
 
-
 ``testmachine`` is a generic machine name included with the cice scripts.
 The local machine name will have to be substituted for ``testmachine`` and
-there are working ports for several different machines.  However, it may be necessary
-to port the model to a new machine.  See :ref:`porting` for 
-more information about how to port. See :ref:`scripts` for more information about 
+there are working ports for several different machines.  If you need to
+port, see the :ref:`porting` section as noted above.
+:ref:`scripts` provides more information about 
 how to use the cice.setup and cice.submit scripts.
 
 Please cite any use of the CICE code. More information can be found at :ref:`citing`.

doc/source/user_guide/ug_case_settings.rst

@@ -33,10 +33,6 @@ can be found in :ref:`cicecpps`.  The following CPPs are available.
    "ESMF_INTERFACE", "Turns on ESMF support in a subset of driver code.  Also USE_ESMF_LIB and USE_ESMF_METADATA"
    "FORTRANUNDERSCORE", "Used in ice_shr_reprosum86.c to support Fortran-C interfaces.  This should generally be turned on at all times.  There are other CPPs (FORTRANDOUBULEUNDERSCORE, FORTRANCAPS, etc) in ice_shr_reprosum.c that are generally not used in CICE but could be useful if problems arise in the Fortran-C interfaces"
    "GPTL", "Turns on GPTL initialization if needed for PIO"
-   "key_oasis3", "Leverages Oasis CPPs to define the local MPI communicator"
-   "key_oasis3mct", "Leverages Oasis CPPs to define the local MPI communicator"
-   "key_oasis4", "Leverages Oasis CPPs to define the local MPI communicator"
-   "key_iomput", "Leverages Oasis CPPs to define the local MPI communicator"
    "NO_F2003", "Turns off some Fortran 2003 features"
    "NO_I8", "Converts integer*8 to integer*4.  This could have adverse affects for certain algorithms including the ddpdd implementation associated with the ``bfbflag``"
    "NO_R16", "Converts real*16 to real*8.  This could have adverse affects for certain algorithms including the lsum16 implementation associated with the ``bfbflag``"

doc/source/user_guide/ug_running.rst

@@ -143,11 +143,8 @@ Some hints:
 
 - To change namelist, manually edit the **ice_in** file
 - To change batch settings, manually edit the top of the **cice.run** or **cice.test** (if running a test) file
-- When the run scripts are submitted, the current **ice_in**, **cice.settings**, and **env.[machine]** files are copied from the case directory into the run directory.  Users should generally not edit files in the run directory as these are overwritten when following the standard workflow.  **cice.settings** can be sourced to establish the case values in the login shell.  An alias like the following can be established to quickly switch between case and run directories::
-
-    alias  cdrun 'cd `\grep "setenv ICE_RUNDIR"  cice.settings | awk "{print "\$"NF}"`'
-    alias cdcase 'cd `\grep "setenv ICE_CASEDIR" cice.settings | awk "{print "\$"NF}"`'
-
+- When the run scripts are submitted, the current **ice_in**, **cice.settings**, and **env.[machine]** files are copied from the case directory into the run directory.  Users should generally not edit files in the run directory as these are overwritten when following the standard workflow.  **cice.settings** can be sourced to establish the case values in the login shell.
+- Some useful aliases can be found in the :ref:`aliases` section
 - To turn on the debug compiler flags, set ``ICE_BLDDEBUG`` in **cice.setttings** to true.  It is also possible to use the ``debug`` option  (``-s debug``) when creating the case with **cice.setup** to set this option automatically.
 - To change compiler options, manually edit the Macros file. To add user defined preprocessor macros, modify ``ICE_CPPDEFS`` in **cice.settings** using the syntax ``-DCICE_MACRO``.
 - To clean the build before each compile, set ``ICE_CLEANBUILD`` in **cice.settings** to true (this is the default value), or use the ``buildclean`` option (``-s buildclean``)  when creating the case with **cice.setup**.  To not clean before the build, set ``ICE_CLEANBUILD`` in **cice.settings** to false, or use the ``buildincremental`` option  (``-s buildincremental``) when creating the case with **cice.setup**.  It is recommended that the ``ICE_CLEANBUILD`` be set to true if there are any questions about whether the build is proceeding properly.
@@ -496,8 +493,9 @@ in the **env.[machine]** file.  This can also be manually changed in the **cice.
 
 .. _laptops:
 
-Porting to Laptop or Personal Computers
+Porting to Laptops or Personal Computers
 -----------------------------------------
+
 To get the required software necessary to build and run CICE, and use the plotting and quality control scripts included in the repository, a `conda <https://docs.conda.io/en/latest/>`_ environment file is available at :
 
 ``configuration/scripts/machines/environment.yml``.
@@ -837,6 +835,50 @@ modify the scripts and input settings in the case directory, NOT the run directo
 In general, files in the run directory are overwritten by versions in the case
 directory when the model is built, submitted, and run.
 
+.. _aliases:
+
+Use of Shell Aliases
+-------------------------
+
+This section provides a list of some potentially useful shell aliases that leverage the CICE 
+scripts.  These are not defined by CICE and are not required for using CICE.  They
+are provided as an example of what can be done by users.
+The current **ice_in**, **cice.settings**, and **env.[machine]** files are copied from 
+the case directory into the run directory when the model is run.  Users can create aliases 
+leveraging the variables in these files.  Aliases like the following can be established 
+in shell startup files or otherwise at users discretion:
+
+.. code-block:: bash
+
+  #!/bin/tcsh
+  # From a case or run directory, source the necessary environment files to run CICE
+  alias cice_env 'source env.*; source cice.settings'
+  # Go from case directory to run directory and back (see https://stackoverflow.com/a/34874698/)
+  alias cdrun  'set rundir=`\grep "setenv ICE_RUNDIR" cice.settings | awk "{print "\$"NF}"` && cd $rundir'
+  alias cdcase 'set casedir=`\grep "setenv ICE_CASEDIR" cice.settings | awk "{print "\$"NF}"` && cd $casedir'
+
+  #!/bin/bash
+  # From case/test directory, go to run directory
+  alias cdrun='cd $(cice_var ICE_RUNDIR)'
+  # From run directory, go to case/test directory
+  alias cdcase='cd $(cice_var ICE_CASEDIR)'
+  # monitor current cice run (from ICE_RUNDIR directory)
+  alias cice_tail='tail -f $(ls -1t cice.runlog.* |head -1)'
+  # open log from last CICE run (from ICE_CASEDIR directory)
+  alias cice_lastrun='$EDITOR $(ls -1t logs/cice.runlog.* |head -1)'
+  # open log from last CICE build (from ICE_CASEDIR directory)
+  alias cice_lastbuild='$EDITOR $(ls -1t logs/cice.bldlog.* |head -1)'
+  # show CICE run directory when run in the case directory
+  alias cice_rundir='cice_var ICE_RUNDIR'
+  # open a tcsh shell and source env.* and cice.settings (useful for launching CICE in a debugger)
+  alias cice_shell='tcsh -c "cice_env; tcsh"'
+
+  ## Functions
+  # Print the value of a CICE variable ($1) from cice.settings
+  cice_var() {
+  \grep "setenv $1" cice.settings | awk "{print "\$"3}"
+  }
+
 .. _timeseries:
 
 Timeseries Plotting