Netcdf History Capability (#368)

* Add primitive netcdf history capability

- Add history_cdf namelist.  This turns on netcdf history files.
  Netcdf history files are written for each column at each timestep
  for a hardcoded set of fields.  There is no control of fields,
  frequency, or averaging.  History filenames are also hardwired in
  the code.
- History netcdf files require the USE_NETCDF C Preprocessor flag.  This
  is turned on by setting ICE_IOTYPE to netcdf in icepack.settings.  In
  addition, the env and Macros files for the machine have to support
  builds with netcdf.
- Add icedrv_history.F90.  Implements history capability.
- Add set_env.ionetcdf, set_nml.ionetcdf
- Add io_suite.ts

* update documentation

* fix badger machine files

* update conda_macos

* update documentation

* update travis testing to include netcdf

* update github actions suites

Co-authored-by: Elizabeth Hunke <[email protected]>

.github/workflows/test-icepack.yml

@@ -115,7 +115,7 @@ jobs:
       - name: run suite
         run: |
           cd $HOME/icepack
-          ./icepack.setup -m conda -e ${{ matrix.envdef }} --suite travis_suite --testid ${{ matrix.os }}
+          ./icepack.setup -m conda -e ${{ matrix.envdef }} --suite travis_suite,io_suite --testid ${{ matrix.os }}
       - name: write output
         run: |
           cd $HOME/icepack

.travis.yml

@@ -31,7 +31,7 @@ script:
   - "./icepack.setup --case trcase --mach travisCI --env gnu --pes 1x1 -s diag1 && sleep 4"
   - "./icepack.setup --test smoke --testid trtest --mach travisCI --env gnu 
     --pes 1x1 -s diag1 && sleep 4"
-  - "./icepack.setup --suite travis_suite --testid travisCItest 
+  - "./icepack.setup --suite travis_suite,io_suite --testid travisCItest 
     --mach travisCI --env gnu &&
     cd testsuite.travisCItest &&
     ./results.csh"

configuration/driver/icedrv_RunMod.F90

@@ -35,6 +35,7 @@ subroutine icedrv_run
       use icedrv_forcing, only: get_forcing, get_wave_spec
       use icedrv_forcing_bgc, only: faero_default, fiso_default, get_forcing_bgc
       use icedrv_flux, only: init_flux_atm_ocn
+      use icedrv_history, only: history_cdf, history_close
 
       logical (kind=log_kind) :: skl_bgc, z_tracers, tr_aero, tr_zaero, &
                                  wave_spec, tr_fsd, tr_iso
@@ -61,7 +62,10 @@ subroutine icedrv_run
 
          call calendar(time)    ! at the end of the timestep
 
-         if (stop_now >= 1) exit timeLoop
+         if (stop_now >= 1) then
+            if (history_cdf) call history_close()
+            exit timeLoop
+         endif
 
          call icepack_query_parameters(skl_bgc_out=skl_bgc, z_tracers_out=z_tracers,&
                                        wave_spec_out=wave_spec)
@@ -97,6 +101,7 @@ subroutine ice_step
       use icedrv_diagnostics_bgc, only: hbrine_diags, zsal_diags, bgc_diags
       use icedrv_flux, only: init_history_therm, init_history_bgc, &
           daidtt, daidtd, dvidtt, dvidtd, dagedtt, dagedtd, init_history_dyn
+      use icedrv_history, only: history_cdf, history_write
       use icedrv_restart, only: dumpfile, final_restart
       use icedrv_restart_bgc, only: write_restart_bgc
       use icedrv_step, only: prep_radiation, step_therm1, step_therm2, &
@@ -219,6 +224,10 @@ subroutine ice_step
          if (skl_bgc .or. z_tracers)  call bgc_diags
          if (tr_brine)                call hbrine_diags
       endif
+
+      if (history_cdf) then
+         call history_write()
+      endif
 
       if (write_restart == 1) then
          call dumpfile     ! core variables for restarting

configuration/driver/icedrv_calendar.F90

@@ -72,6 +72,7 @@ module icedrv_calendar
       real (kind=dbl_kind), public :: &
          dt             , & ! thermodynamics timestep (s)
          dt_dyn         , & ! dynamics/transport/ridging timestep (s)
+         time0          , & ! total elapsed time at istep0 for idate0 (s)
          time           , & ! total elapsed time (s)
          time_forc      , & ! time of last forcing update (s)
          yday           , & ! day of the year
@@ -123,6 +124,7 @@ subroutine init_calendar
       !-----------------------------------------------------------------
 
       istep = 0         ! local timestep number
+      time0=istep0*dt   ! start time
       time=istep0*dt    ! s
       yday=c0           ! absolute day number
       mday=0            ! day of the month

configuration/driver/icedrv_init.F90

@@ -62,6 +62,7 @@ subroutine input_data
       use icedrv_calendar, only: year_init, istep0
       use icedrv_calendar, only: dumpfreq, diagfreq, dump_last
       use icedrv_calendar, only: npt, dt, ndtd, days_per_year, use_leap_years
+      use icedrv_history, only: history_cdf
       use icedrv_restart_shared, only: restart, restart_dir, restart_file
       use icedrv_flux, only: update_ocn_f, l_mpond_fresh, cpl_bgc
       use icedrv_flux, only: default_season
@@ -129,7 +130,7 @@ subroutine input_data
         dt,             npt,            ndtd,            dump_last,     &
         ice_ic,         restart,        restart_dir,     restart_file,  &
         dumpfreq,       diagfreq,       diag_file,       cpl_bgc,       &
-        conserv_check
+        conserv_check,  history_cdf
 
       namelist /grid_nml/ &
         kcatbound
@@ -248,6 +249,7 @@ subroutine input_data
       restart = .false.      ! if true, read restart files for initialization
       restart_dir  = './'    ! write to executable dir for default
       restart_file = 'iced'  ! restart file name prefix
+      history_cdf = .false.  ! history netcdf file flag
       ice_ic       = 'default'      ! initial conditions are specified in the code
                                     ! otherwise, the filename for reading restarts
       ndtd = 1               ! dynamic time steps per thermodynamic time step
@@ -558,6 +560,7 @@ subroutine input_data
                                trim(restart_dir)
          write(nu_diag,*)    ' restart_file              = ', &
                                trim(restart_file)
+         write(nu_diag,1010) ' history_cdf               = ', history_cdf
          write(nu_diag,*)    ' ice_ic                    = ', &
                                trim(ice_ic)
          write(nu_diag,1010) ' conserv_check             = ', conserv_check

configuration/scripts/Makefile

@@ -68,6 +68,7 @@ OBJS  := $(addsuffix .o, $(sort $(basename $(notdir $(SRCS)))))
 DEPS  := $(addsuffix .d, $(sort $(basename $(notdir $(SRCS)))))
 INCS  := $(patsubst %,-I%, $(VPATH) )
 RM    := rm
+MODDIR:= -I.
 
 .SUFFIXES:
 .SUFFIXES: .F90 .F .c .o
@@ -95,15 +96,16 @@ db_files:
 	@echo "* VPATH   := $(VPATH)"
 	@echo "* SRCFILE := $(SRCFILE)"
 	@echo "* INCS    := $(INCS)"
+	@echo "* MODDIR  := $(MODDIR)"
 	@echo "* SRCS    := $(SRCS)"
 	@echo "* OBJS    := $(OBJS)"
 	@echo "* DEPS    := $(DEPS)"
 db_flags:
 	@echo " "
-	@echo "* cpp     := $(CPP) $(CPPFLAGS) $(CPPDEFS) $(INCS) $(INCLDIR)"
-	@echo "* cc      := cc -c $(CFLAGS) $(INCS) $(INCLDIR)"
-	@echo "* .F.o    := $(FC) -c $(FFLAGS) $(FIXEDFLAGS) $(INCS) $(INCLDIR)"
-	@echo "* .F90.o  := $(FC) -c $(FFLAGS) $(FREEFLAGS) $(INCS) $(INCLDIR)"
+	@echo "* cpp     := $(CPP) $(CPPFLAGS) $(CPPDEFS) $(INCLDIR)"
+	@echo "* cc      := $(CC) -c $(CFLAGS) $(INCLDIR)"
+	@echo "* .F.o    := $(FC) -c $(FFLAGS) $(FIXEDFLAGS) $(INCLDIR)"
+	@echo "* .F90.o  := $(FC) -c $(FFLAGS) $(FREEFLAGS) $(MODDIR) $(INCLDIR)"
 
 #-------------------------------------------------------------------------------
 # build rule for makdep: MACFILE, cmd-line, or env vars must provide
@@ -121,13 +123,13 @@ $(EXEC): $(OBJS)
 	$(LD) -o $(EXEC) $(LDFLAGS) $(OBJS) $(ULIBS) $(SLIBS)
 
 .c.o:
-	cc $(CFLAGS) $(CPPDEFS) $(INCS) $(INCLDIR) $<
+	$(CC) $(CFLAGS) $(CPPDEFS) $(INCLDIR) $<
 
 .F.o:
-	$(FC) -c $(FFLAGS) $(FIXEDFLAGS) $(CPPDEFS) $(INCS) $(INCLDIR) $<
+	$(FC) -c $(FFLAGS) $(FIXEDFLAGS) $(CPPDEFS) $(INCLDIR) $<
 
 .F90.o:
-	$(FC) -c $(FFLAGS) $(FREEFLAGS) $(CPPDEFS) $(INCS) $(INCLDIR) $<
+	$(FC) -c $(FFLAGS) $(FREEFLAGS) $(CPPDEFS) $(MODDIR) $(INCLDIR) $<
 
 mostlyclean:
 	$(RM) -f *.f *.f90 

configuration/scripts/icepack.build

@@ -26,6 +26,10 @@ cd ${ICE_OBJDIR}
 
 setenv ICE_CPPDEFS "${ICE_CPPDEFS} -DNXGLOB=${ICE_NXGLOB} -DNICELYR=${NICELYR} -DNSNWLYR=${NSNWLYR} -DNICECAT=${NICECAT} -DNFSDCAT=${NFSDCAT} -DTRAGE=${TRAGE} -DTRFY=${TRFY} -DTRLVL=${TRLVL} -DTRPND=${TRPND} -DTRSNOW=${TRSNOW} -DTRBRI=${TRBRI} -DNTRISO=${NTRISO} -DNTRAERO=${NTRAERO}  -DTRZS=${TRZS} -DNBGCLYR=${NBGCLYR} -DTRALG=${TRALG} -DTRBGCZ=${TRBGCZ} -DTRDOC=${TRDOC} -DTRDOC=${TRDOC} -DTRDIC=${TRDIC} -DTRDON=${TRDON} -DTRFED=${TRFED} -DTRFEP=${TRFEP} -DTRZAERO=${TRZAERO} -DTRBGCS=${TRBGCS} "
 
+if (${ICE_IOTYPE} == 'netcdf') then
+  setenv ICE_CPPDEFS "${ICE_CPPDEFS} -DUSE_NETCDF"
+endif
+
 ### List of source code directories (in order of importance).
 cat >! Filepath << EOF
 ${ICE_SANDBOX}/configuration/driver

configuration/scripts/icepack_in

@@ -13,6 +13,7 @@
     dump_last      = .false.
     diagfreq       = 24
     diag_file      = 'ice_diag'
+    history_cdf    = .false.
     cpl_bgc        = .false.
     conserv_check  = .false.
 /

configuration/scripts/machines/Macros.badger_intel

@@ -24,28 +24,23 @@ CC := $(SCC)
 FC := $(SFC)
 LD := $(FC)
 
-# set in Macros file
-NETCDF_PATH := /usr/projects/climate/SHARED_CLIMATE/software/conejo/netcdf/3.6.3/intel-13.0.1
-PNETCDF_PATH := /usr/projects/climate/SHARED_CLIMATE/software/conejo/parallel-netcdf/1.3.1/intel-13.0.1/openmpi-1.6.3
-#LAPACK_LIBDIR := /glade/apps/opt/lapack/3.4.2/intel/12.1.5/lib
+NETCDF_PATH := /usr/projects/hpcsoft/toss3/common/netcdf/4.4.0_intel-18.0.5
+PNETCDF_PATH := /usr/projects/hpcsoft/toss3/badger/netcdf/4.4.0_intel-18.0.5_openmpi-2.1.2
 
 PIO_CONFIG_OPTS:= --enable-filesystem-hints=gpfs 
 
 ifeq ($(ICE_IOTYPE), netcdf)
-  INCLDIR := $(INCLDIR) -I$(NETCDF_PATH)/include
-#  INCLDIR := $(INCLDIR) -I/usr/projects/climate/SHARED_CLIMATE/software/conejo/netcdf/3.6.3/intel-13.0.1/include
+  INCLDIR := $(INCLDIR) -I$(NETCDF_PATH)/include -I$(PNETCDF_PATH)/include
 
   LIB_NETCDF := $(NETCDF_PATH)/lib
   LIB_PNETCDF := $(PNETCDF_PATH)/lib
   LIB_MPI := $(IMPILIBDIR)
 
-  #SLIBS   := -L$(LIB_NETCDF) -lnetcdf -L$(LIB_PNETCDF) -lpnetcdf -L$(LAPACK_LIBDIR) -llapack -lblas
-  SLIBS   := -L$(LIB_NETCDF) -lnetcdf -L$(LIB_PNETCDF) -lpnetcdf 
+  SLIBS   := -L$(LIB_NETCDF) -lnetcdf -L$(LIB_PNETCDF) -lnetcdff 
 else
   SLIBS   := 
 endif
 
-
 ifeq ($(ICE_THREADED), true) 
    LDFLAGS += -qopenmp
    CFLAGS += -qopenmp

configuration/scripts/machines/Macros.conda_macos

@@ -26,6 +26,9 @@ CC := $(SCC)
 FC := $(SFC)
 LD := $(FC)
 
+# Location of the compiled Fortran modules (NetCDF)
+MODDIR  += -I$(CONDA_PREFIX)/include
+
 # Location of the system C header files (required on recent macOS to compile makdep)
 SDKPATH = $(shell xcrun --show-sdk-path)
 ifeq ($(strip $(SDKPATH)),)
@@ -35,6 +38,9 @@ else
   LD += -L$(SDKPATH)/usr/lib
 endif
 
+# Libraries to be passed to the linker
+SLIBS   := -L$(CONDA_PREFIX)/lib -lnetcdf -lnetcdff
+
 # Necessary flag to compile with OpenMP support
 ifeq ($(ICE_THREADED), true)
    LDFLAGS += -fopenmp

configuration/scripts/machines/env.badger_intel

@@ -12,6 +12,14 @@ if ("$inp" != "-nomodules") then
 #module purge
 #module load intel
 #module load openmpi
+module unload hdf5-serial
+module unload hdf5-parallel
+module unload netcdf-serial
+module unload netcdf-h5parallel
+module load hdf5-serial
+module load netcdf-serial/4.4.0
+module load hdf5-parallel
+module load netcdf-h5parallel/4.4.0
 
 setenv NETCDF_PATH /usr/projects/climate/SHARED_CLIMATE/software/conejo/netcdf/3.6.3/intel-13.0.1
 setenv PNETCDF_PATH /usr/projects/climate/SHARED_CLIMATE/software/conejo/parallel-netcdf/1.3.1/intel-13.0.1/openmpi-1.6.3
@@ -29,7 +37,7 @@ endif
 setenv ICE_MACHINE_MACHNAME badger
 setenv ICE_MACHINE_MACHINFO "Penguin Intel Xeon Broadwell"
 setenv ICE_MACHINE_ENVNAME intel
-setenv ICE_MACHINE_ENVINFO "(Note: can vary) ifort 19.0.4.243 20190416"
+setenv ICE_MACHINE_ENVINFO "(Note: can vary) ifort 19.0.4.243 20190416, netcdf4.4.0"
 setenv ICE_MACHINE_MAKE gmake
 setenv ICE_MACHINE_WKDIR /net/scratch3/$user/ICEPACK_RUNS
 setenv ICE_MACHINE_INPUTDATA /usr/projects/climate/eclare/DATA/Consortium

configuration/scripts/machines/environment.yml

@@ -5,6 +5,8 @@ channels:
 dependencies:
 # Build dependencies
   - compilers
+  - netcdf-fortran
+  - netcdf4
   - make
 # Python dependencies for building the HTML documentation
   - sphinx

configuration/scripts/options/set_env.ionetcdf

@@ -0,0 +1 @@
+setenv ICE_IOTYPE  netcdf

configuration/scripts/options/set_nml.ionetcdf

@@ -0,0 +1 @@
+history_cdf = .true.

configuration/scripts/setup_run_dirs.csh

@@ -7,7 +7,7 @@ if !(-d ${ICE_RUNDIR}) then
   echo "mkdir ${ICE_RUNDIR}"
   mkdir -p ${ICE_RUNDIR}
 endif
-#if !(-d ${ICE_HSTDIR}) mkdir -p ${ICE_HSTDIR}
+if !(-d ${ICE_HSTDIR}) mkdir -p ${ICE_HSTDIR}
 if !(-d ${ICE_RSTDIR}) mkdir -p ${ICE_RSTDIR}
 
 exit 0

configuration/scripts/tests/io_suite.ts

@@ -0,0 +1,2 @@
+restart        col     1x1        debug,ionetcdf
+smoke          col     1x1        run1year,diag1,ionetcdf

doc/source/icepack_index.rst

@@ -210,6 +210,7 @@ either Celsius or Kelvin units).
    "highfreq", ":math:`\bullet` high-frequency atmo coupling", "F"
    "hin_old", "ice thickness prior to growth/melt", "m"
    "hin_max", "category thickness limits", "m"
+   "history_cdf", "flag to turn on netcdf history output", "F"
    "hmix", "ocean mixed layer depth", "20. m"
    "hour", "hour of the year", ""
    "hp0", "pond depth at which shortwave transition to bare ice occurs", "0.2 m"

doc/source/user_guide/ug_case_settings.rst

@@ -31,6 +31,7 @@ can be found in :ref:`cicecpps`.  The following CPPs are available.
    "**General Macros**", ""
    "NO_I8", "Converts ``integer*8`` to ``integer*4``."
    "NO_R16", "Converts ``real*16`` to ``real*8``."
+   "USE_NETCDF", "Turns on netcdf capabilities in Icepack.  By default and generally, Icepack does not need netcdf."
    "",""
    "**Application Macros**", ""
    "CESMCOUPLED", "Turns on code changes for the CESM coupled application                          "
@@ -65,7 +66,7 @@ can be modified as needed.
    "ICE_LOGDIR", "string", "log directory", "${ICE_CASEDIR}/logs"
    "ICE_RSTPFILE", "string", "unused", "undefined"
    "ICE_DRVOPT", "string", "unused", "icepack"
-   "ICE_IOTYPE", "string", "unused", "none"
+   "ICE_IOTYPE", "none,netcdf", "IO options", "none"
    "ICE_CLEANBUILD", "true,false", "automatically clean before building", "true"
    "ICE_CPPDEFS", "string", "user defined preprocessor macros for build", "null"
    "ICE_QUIETMODE", "true, false", "reduce build output to the screen", "false"
@@ -139,6 +140,7 @@ setup_nml
    "", "``y``", "write restart every ``dumpfreq_n`` years", ""
    "``dump_last``", "true/false", "write restart at end of run", "false"
    "``dt``", "seconds", "thermodynamics time step length", "3600."
+   "``history_cdf``", "logical", "netcdf history output", "``.false.``"
    "``ice_ic``", "``default``", "latitude and sst dependent initial condition", "``default``"
    "", "``none``", "no ice", ""
    "", "'path/file'", "restart file name", ""

doc/source/user_guide/ug_implementation.rst

@@ -150,9 +150,9 @@ default in this distribution, this is not a stringent limitation:
 Model output
 ------------
 
-History output from Icepack is not currently supported in the Icepack driver, except
-in restart files.
-The sea ice model `CICE <https://github.com/CICE-Consortium/CICE>`_ provides extensive 
+The Icepack model provides diagnostic output files, binary restart files, and a primitive
+netcdf history file capability.
+The sea ice model `CICE <https://github.com/CICE-Consortium/CICE>`_ provides more extensive 
 options for model output, including many derived output variables.
 
 Diagnostic files
@@ -176,6 +176,30 @@ the namelist option ``restart`` must be set to ``.true.`` to use the file.
 ``dump_last`` namelist can also be set to true to trigger restarts automatically
 at then end of runs.
 
+History files
+~~~~~~~~~~~~~
+
+Icepack has a primitive netcdf history capability that is turned on with the
+``history_cdf`` namelist.  When ``history_cdf`` is set to true, history files
+are created for each run with a naming convention of **icepack.h.yyyymmdd.nc**
+in the run directory history directory.  The yyyymmdd is the start date for each run.
+
+When Icepack history files are turned on, data for a set of fixed fields is written 
+to the history file for each column at every timestep without ability to control
+fields, frequencies, or temporal averaging.  All output fields are hardwired into
+the implementation in **configuration/driver/icedrv_history.F90** file.  The netcdf file 
+does NOT meet NetCDF CF conventions and is provided as an amenity in the standalone
+Icepack model.  Users are free to modify the output fields or
+extend the implementation and are encouraged to share any updates with the Consortium.
+
+The default configuration of Icepack does not require NetCDF.  If history files are
+written, the USE_NETCDF C preprocessor directive must be set during compilation.  This
+is done by setting ``ICE_IOTYPE`` to ``netcdf`` in **icepack.settings**.  In addition,
+the machine env and Macros files must include support for compilation with NetCDF.  The
+``icepack.setup -s`` option ``ionetcdf`` will set the ICE_IOTYPE to netcdf, which turns on 
+the USE_NETCDF C preprocessor.  ``ionetcdf`` also sets the ``history_cdf`` flag to true.
+
+
 .. _bgc-hist:
 
 Biogeochemistry History Fields

doc/source/user_guide/ug_running.rst

@@ -585,7 +585,12 @@ Next, create the "icepack" conda environment from the ``environment.yml`` file i
 
   conda env create -f configuration/scripts/machines/environment.yml
 
-This step needs to be done only once.
+This step needs to be done only once.  If you ever need to update the conda environment
+because the required packages change or packages are out of date, do
+
+.. code-block:: bash
+
+  conda env update -f configuration/scripts/machines/environment.yml
 
 .. _using_conda_env: