Add atm_data_version to allow JRA55 forcing filenames to have a uniqu…

…e version string (#876)

* Add jra55date to allow JRA55 forcing to have creation date in file name

* Changed jra55_date to atm_data_date. Added atm_data_date to docs.

* Change jra55_date to atm_data_date. Update JRA55_files to include atm_data_date in file. Update case scripts/namelist.

* change atm_data_date to atm_data_version. Update set_nml.tx1 default to corrected forcing version

* Update doc to have atm_data_version in proper alphabetical order

* Re-add set_nml.jra55. Deleted accitentally

* Fix type-o in atm_data_dir documentation

* Add atm_data_version to set_nml.jra55

* fix spacing after changing atm_data_date to atm_data_version

* Change atm_data_date to atm_data_version

* Comment out JRA55 file debugging

* Update dg_forcing docs to describe atm_data_version string

* Uncomment JRA55 filename check. Added check for debug_forcing before writing output

* Correct doc format/links in dg_forcing.rst

cicecore/cicedyn/general/ice_forcing.F90

@@ -120,18 +120,19 @@ module ice_forcing
           wave_spectrum_data ! field values at 2 temporal data points
 
       character(char_len), public :: &
-         atm_data_format, & ! 'bin'=binary or 'nc'=netcdf
-         ocn_data_format, & ! 'bin'=binary or 'nc'=netcdf
-         atm_data_type, & ! 'default', 'monthly', 'ncar', 'box2001'
-                          ! 'hadgem', 'oned', 'calm', 'uniform'
-                          ! 'JRA55' or 'JRA55do'
-         bgc_data_type, & ! 'default', 'clim'
-         ocn_data_type, & ! 'default', 'clim', 'ncar', 'oned', 'calm', 'box2001'
-                          ! 'hadgem_sst' or 'hadgem_sst_uvocn', 'uniform'
-         ice_data_type, & ! 'latsst', 'box2001', 'boxslotcyl', etc
-         ice_data_conc, & ! 'p5','p8','p9','c1','parabolic', 'box2001', etc
-         ice_data_dist, & ! 'box2001','gauss', 'uniform', etc
-         precip_units     ! 'mm_per_month', 'mm_per_sec', 'mks','m_per_sec'
+         atm_data_format   , & ! 'bin'=binary or 'nc'=netcdf
+         ocn_data_format   , & ! 'bin'=binary or 'nc'=netcdf
+         atm_data_type     , & ! 'default', 'monthly', 'ncar', 'box2001'
+                               ! 'hadgem', 'oned', 'calm', 'uniform'
+                               ! 'JRA55' or 'JRA55do'
+         atm_data_version  , & ! date of atm_forcing file creation
+         bgc_data_type     , & ! 'default', 'clim'
+         ocn_data_type     , & ! 'default', 'clim', 'ncar', 'oned', 'calm', 'box2001'
+                               ! 'hadgem_sst' or 'hadgem_sst_uvocn', 'uniform'
+         ice_data_type     , & ! 'latsst', 'box2001', 'boxslotcyl', etc
+         ice_data_conc     , & ! 'p5','p8','p9','c1','parabolic', 'box2001', etc
+         ice_data_dist     , & ! 'box2001','gauss', 'uniform', etc
+         precip_units          ! 'mm_per_month', 'mm_per_sec', 'mks','m_per_sec'
 
       logical (kind=log_kind), public :: &
          rotate_wind      ! rotate wind/stress to computational grid from true north directed
@@ -2238,29 +2239,39 @@ subroutine JRA55_files(yr)
       exists = .false.
       cnt = 1
       do while (.not.exists .and. cnt <= 6)
-         if (cnt == 1) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)// &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_'//trim(grd)//'_03hr_forcing_2005.nc'
 
-         if (cnt == 2) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)// &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_03hr_forcing_'//trim(grd)//'_2005.nc'
+         if (cnt == 1) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)//     &
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_'//trim(grd)// &
+                                    '_03hr_forcing'//trim(atm_data_version)//'_2005.nc'
 
-         if (cnt == 3) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)// &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//                '_03hr_forcing_2005.nc'
+         if (cnt == 2) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)//                  &
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_03hr_forcing_'//trim(grd)// &
+                                    trim(atm_data_version)//'_2005.nc'
 
-         if (cnt == 4) uwind_file = trim(atm_data_dir)//                                  &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_'//trim(grd)//'_03hr_forcing_2005.nc'
+         if (cnt == 3) uwind_file = trim(atm_data_dir)//'/'//trim(atm_data_type_prefix)// &
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//             &
+                                    '_03hr_forcing'//trim(atm_data_version)//'_2005.nc'
+
+         if (cnt == 4) uwind_file = trim(atm_data_dir)//                                      &
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_'//trim(grd)// &
+                                    '_03hr_forcing'//trim(atm_data_version)//'_2005.nc'
 
-         if (cnt == 5) uwind_file = trim(atm_data_dir)//                                  &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_03hr_forcing_'//trim(grd)//'_2005.nc'
+         if (cnt == 5) uwind_file = trim(atm_data_dir)//                                                   &
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//'_03hr_forcing_'//trim(grd)// &
+                                    trim(atm_data_version)//'_2005.nc'
 
          if (cnt == 6) uwind_file = trim(atm_data_dir)//                                  &
-                                    '/8XDAILY/'//trim(atm_data_type_prefix)//                '_03hr_forcing_2005.nc'
+                                    '/8XDAILY/'//trim(atm_data_type_prefix)//             &
+                                    '_03hr_forcing'//trim(atm_data_version)//'_2005.nc'
+
 
          call file_year(uwind_file,yr)
          INQUIRE(FILE=uwind_file,EXIST=exists)
-!         if (my_task == master_task) then
-!            write(nu_diag,*) subname,cnt,exists,trim(uwind_file)
-!         endif
+
+         if (debug_forcing .and. (my_task == master_task)) then
+            write(nu_diag,*) subname,cnt,exists,trim(uwind_file)
+         endif
+
          cnt = cnt + 1
       enddo
 

cicecore/cicedyn/general/ice_init.F90

@@ -88,7 +88,7 @@ subroutine input_data
       use ice_forcing, only: &
           ycycle,          fyear_init,    debug_forcing, &
           atm_data_type,   atm_data_dir,  precip_units, rotate_wind, &
-          atm_data_format, ocn_data_format, &
+          atm_data_format, ocn_data_format, atm_data_version, &
           bgc_data_type, &
           ocn_data_type, ocn_data_dir, wave_spec_file,  &
           oceanmixed_file, restore_ocn, trestore, &
@@ -273,7 +273,7 @@ subroutine input_data
         fyear_init,     ycycle,          wave_spec_file,restart_coszen, &
         atm_data_dir,   ocn_data_dir,    bgc_data_dir,                  &
         atm_data_format, ocn_data_format, rotate_wind,                  &
-        oceanmixed_file
+        oceanmixed_file, atm_data_version
 
       !-----------------------------------------------------------------
       ! default values
@@ -501,6 +501,7 @@ subroutine input_data
       atm_data_format = 'bin'     ! file format ('bin'=binary or 'nc'=netcdf)
       atm_data_type   = 'default'
       atm_data_dir    = ' '
+      atm_data_version = '_undef'  ! date atm_data_file was generated. 
       rotate_wind     = .true.    ! rotate wind/stress composants to computational grid orientation
       calc_strair     = .true.    ! calculate wind stress
       formdrag        = .false.   ! calculate form drag
@@ -1064,6 +1065,7 @@ subroutine input_data
       call broadcast_scalar(atm_data_format,      master_task)
       call broadcast_scalar(atm_data_type,        master_task)
       call broadcast_scalar(atm_data_dir,         master_task)
+      call broadcast_scalar(atm_data_version,     master_task)
       call broadcast_scalar(rotate_wind,          master_task)
       call broadcast_scalar(calc_strair,          master_task)
       call broadcast_scalar(calc_Tsfc,            master_task)
@@ -2380,6 +2382,8 @@ subroutine input_data
          write(nu_diag,1021) ' fyear_init       = ', fyear_init
          write(nu_diag,1021) ' ycycle           = ', ycycle
          write(nu_diag,1031) ' atm_data_type    = ', trim(atm_data_type)
+         write(nu_diag,1031) ' atm_data_version = ', trim(atm_data_version)
+
          if (trim(atm_data_type) /= 'default') then
             write(nu_diag,1031) ' atm_data_dir     = ', trim(atm_data_dir)
             write(nu_diag,1031) ' precip_units     = ', trim(precip_units)

configuration/scripts/ice_in

@@ -271,6 +271,7 @@
     precip_units    = 'mm_per_month'
     default_season  = 'winter'
     atm_data_type   = 'ncar'
+    atm_data_version = '_undef'
     ocn_data_type   = 'default'
     bgc_data_type   = 'default'
     fe_data_type    = 'default'

configuration/scripts/options/set_nml.gx1

@@ -15,6 +15,7 @@ maskhalo_bound = .true.
 fyear_init      = 2005
 atm_data_format = 'nc'
 atm_data_type   = 'JRA55'
+atm_data_version = ''
 atm_data_dir    = 'ICE_MACHINE_INPUTDATA/CICE_data/forcing/gx1'
 precip_units    = 'mks'
 ocn_data_dir    = 'ICE_MACHINE_INPUTDATA/CICE_data/forcing/gx1/CESM/MONTHLY'

configuration/scripts/options/set_nml.gx3

@@ -12,6 +12,7 @@ bathymetry_file = 'ICE_MACHINE_INPUTDATA/CICE_data/grid/gx3/global_gx3.bathy.nc'
 fyear_init      = 2005
 atm_data_format = 'nc'
 atm_data_type   = 'JRA55'
+atm_data_version = ''
 atm_data_dir    = 'ICE_MACHINE_INPUTDATA/CICE_data/forcing/gx3'
 precip_units    = 'mks'
 ocn_data_format = 'bin'

configuration/scripts/options/set_nml.jra55

@@ -1,2 +1,4 @@
 atm_data_format = 'nc'
 atm_data_type   = 'JRA55'
+atm_data_version = ''
+

configuration/scripts/options/set_nml.jra55do

@@ -1,2 +1,3 @@
 atm_data_format = 'nc'
 atm_data_type   = 'JRA55do'
+atm_data_version = ''

configuration/scripts/options/set_nml.tx1

@@ -9,5 +9,6 @@ kmt_file    = 'ICE_MACHINE_INPUTDATA/CICE_data/grid/tx1/kmt_tx1.bin'
 atm_data_dir    = 'ICE_MACHINE_INPUTDATA/CICE_data/forcing/tx1'
 atm_data_format = 'nc'
 atm_data_type   = 'JRA55'
+atm_data_version = '_20230919'
 year_init      = 2005
 fyear_init      = 2005

doc/source/developer_guide/dg_forcing.rst

@@ -21,10 +21,12 @@ primitive, in part due to historical reasons and in part because standalone runs
 are discouraged for evaluating complex science.  In general, most implementations
 use aspects of the following approach,
 
-- Input files are organized by year.  The underlying implementation provides for some flexibility and extensibility in filenames.  For instance, JRA55 and JRA55do filenames can have syntax like ``[JRA55,JRA55do][_$grid,'']_03hr_forcing[_$grid,'']_$year.nc`` where $grid is optional or may be present at one of two locations within the filename.  This implementation exists to support the current naming conventions within the gx1, gx3, and tx1 JRA55 and JRA55do CICE_DATA directory structure automatically.  See **JRA55_files** in **ice_forcing.F90** for more details.
-- Namelist inputs ``fyear`` and ``ycycle`` specify the forcing year dataset.
-- The forcing year is computed on the fly and is assumed to be cyclical over the forcing dataset length defined by ``ycycle``.
-- The namelist ``atm_data_dir`` specifies the path or partial path for the atmosphere input data files and the namelist ``atm_data_type`` defines the atmospheric forcing mode.  ``atm_data_type`` values of ``JRA55``, ``JRA55do``, or ``ncar`` provide some flexibility for directory paths and filenames.  Many details can be gleaned from the CICE_data directory structure and file names as well as from the implementation in **ice_forcing.F90**.  But the main point is that atm_data_dir should be set to ${CICE_DATA_root}/forcing/$grid/[JRA55,JRA55do,NCAR_bulk,''] where [JRA55,JRA55do,NCAR_bulk] are optional but provided for backwards compatibility.  grid is typically gx1, gx3, tx1, or similar.
+- Input files are organized by year.  The underlying implementation
+  provides for some flexibility and extensibility in filenames. For instance, JRA55 and JRA55do filenames can have syntax like [JRA55,JRA55do][_$grid]_03hr_forcing_$year.nc or [JRA55,JRA55do]_03hr_forcing[_$grid]_$year.nc, where [_$grid] is optional and may be present at one of two locations within the filename. This implementation exists to support the current naming conventions within the gx1, gx3, and tx1 JRA55 and JRA55do CICE_data directory structure automatically. See **JRA55_files** in **ice_forcing.F90** for more details.- Namelist inputs ``fyear`` and ``ycycle`` specify the forcing year dataset.
+- The forcing year is computed on the fly and is assumed to be
+  cyclical over the forcing dataset length defined by ``ycycle``.
+- The namelist ``atm_data_dir`` specifies the full or partial path for the atmosphere input data files, and the namelist ``atm_data_type`` defines the atmospheric forcing mode (see ``forcing_nml`` in
+  :ref:`tabnamelist`). Many of the forcing options are generated internally. For atmospheric forcing read from files, the directory structure and filenames depend on the grid and ``atm_data_type``. Many details can be gleaned from the CICE_data directory and filenames as well as from the implementation in **ice_forcing.F90**. The primary ``atm_data_type`` forcing for gx1, gx3, and tx1 test grids are ``JRA55`` and ``JRA55do``. For those configurations, the ``atm_data_dir`` should be set to ${CICE_data_root}/forcing/${grid}/[JRA55,JRA55do] and the filenames should be of the form [JRA55,JRA55do]_${grid}_03hr_forcing${atm_data_version}_yyyy.nc where yyyy is the forcing year. Those files should be placed under ``atm_data_dir/8XDAILY``. ``atm_data_version`` is a string defined in ``forcing_nml`` namelist that supports versioning of the forcing data. ``atm_data_version`` could be any string including the null string. It typically will be something like _yyyymmdd to indicate the date the forcing data was generated.
 - The namelist ``ocn_data_dir`` specifies the directory of the ocean input data files and the namelist ``ocn_data_type`` defines the ocean forcing mode.
 - The filenames follow a particular naming convention that is defined in the source code (ie. subroutine **JRA55_files**).  The forcing year is typically found just before the **.nc** part of the filename and there are tools (subroutine **file_year**) to update the filename based on the model year and appropriate forcing year.
 - The input data time axis is generally NOT read by the forcing subroutine.  The forcing frequency is hardwired into the model and the file record number is computed based on the forcing frequency and model time.  Mixing leap year input data and noleap model calendars (and vice versa) is not handled particularly gracefully.  The CICE model does not read or check against the input data time axis.

doc/source/user_guide/ug_case_settings.rst

@@ -621,6 +621,7 @@ forcing_nml
    "", "``monthly``", "monthly forcing data", ""
    "", "``ncar``", "NCAR bulk forcing data", ""
    "", "``oned``", "column forcing data", ""
+   "``atm_data_version``","string", "date of atm data forcing file creation", "``_undef``"
    "``bgc_data_dir``", "string", "path to oceanic forcing data directory", "'unknown_bgc_data_dir'"
    "``bgc_data_type``", "``clim``", "bgc climatological data", "``default``"
    "", "``default``", "constant values defined in the code", ""