adding CMIP variable documentation

doc/source/developer_guide/dg_documentation.rst

@@ -142,7 +142,7 @@ Here are some resources for using RST files:
 Building documentation
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Once you've committed and pushed changes to the documentation *.rst files on your personal development fork. 
+Once you've committed and pushed changes to the documentation `*.rst` files on your personal development fork. 
 Go to your readthedocs.org site and then select your project "Overview". Whenever you commit to your fork
 the documents will automatically build. There is also an option to "Build a Version". Choose "latest" 
 and then click the green "Build version" button. 

doc/source/developer_guide/dg_driver.rst

@@ -14,7 +14,7 @@ coupled.  Within the **cicecore/drivers/cice/** directory, the following files a
 **CICE.F90** is the top level program file and that calls CICE_Initialize, CICE_Run, and CICE_Finalize methods.
 **CICE_InitMod.F90** contains the CICE_Initialize method and other next level source code.
 **CICE_RunMod.F90** contains the CICE_Run method and other next level source code.
-**CICE_FinalMod.F90 ** contains the CICE_Finalize method and other next level source code.
+**CICE_FinalMod.F90** contains the CICE_Finalize method and other next level source code.
 
 Other **cicecore/drivers/** directories are similarly implemented with a top level coupling layer,
 that is largely specified by an external coupled system and then some version of the **CICE_InitMod.F90**,
@@ -87,4 +87,4 @@ The run sequence within a time loop looks something like::
             call coupling_prep (iblk)
          enddo ! iblk
 
-See a **CICE_RunMod.F90** file for the latest.
+See a **CICE_RunMod.F90** file for the latest.

doc/source/developer_guide/dg_dynamics.rst

@@ -70,7 +70,10 @@ block size and tracer count.  Those block sizes and tracer counts are defined in
 **cice.settings** file, are passed to the build script as CPPs, like
 ::
 
-ftn -c ... -DNXGLOB=100 -DNYGLOB=116 -DBLCKX=25 -DBLCKY=29 -DMXBLCKS=4 -DNICELYR=7 -DNSNWLYR=1 -DNICECAT=5 -DTRAGE=1 -DTRFY=1 -DTRLVL=1 -DTRPND=1 -DTRBRI=0 -DNTRAERO=1  -DTRZS=0 -DNBGCLYR=7 -DTRALG=0 -DTRBGCZ=0 -DTRDOC=0 -DTRDOC=0 -DTRDIC=0 -DTRDON=0 -DTRFED=0 -DTRFEP=0 -DTRZAERO=0 -DTRBGCS=0 -DNUMIN=11 -DNUMAX=99 ...
+       ftn -c ... -DNXGLOB=100 -DNYGLOB=116 -DBLCKX=25 -DBLCKY=29 -DMXBLCKS=4 -DNICELYR=7
+       -DNSNWLYR=1 -DNICECAT=5 -DTRAGE=1 -DTRFY=1 -DTRLVL=1 -DTRPND=1 -DTRBRI=0 -DNTRAERO=1
+       -DTRZS=0 -DNBGCLYR=7 -DTRALG=0 -DTRBGCZ=0 -DTRDOC=0 -DTRDOC=0 -DTRDIC=0 -DTRDON=0
+       -DTRFED=0 -DTRFEP=0 -DTRZAERO=0 -DTRBGCS=0 -DNUMIN=11 -DNUMAX=99 ...
 
 and then those CPPs replace variable strings in the file **cicecore/shared/ice_domain_size.F90**.
 Data in **ice_domain_size.F90** provides parameters for static array allocations throughout CICE.

doc/source/developer_guide/dg_scripts.rst

@@ -29,7 +29,7 @@ The directory structure under configure/scripts is as follows.
 |        **parse_namelist.sh**     replaces namelist with command-line configuration
 |        **parse_namelist_from_settings.sh**   replaces namelist with values from cice.settings
 |        **parse_settings.sh**     replaces settings with command-line configuration
-|        **setup_run_dirs.csh      creates the case run directories
+|        **setup_run_dirs.csh**    creates the case run directories
 |        **set_version_number.csh** updates the model version number from the **cice.setup** command line
 |        **tests/**                scripts for configuring and running basic tests
 
@@ -51,7 +51,7 @@ The file **cice.settings** specifies a set of env defaults for the case.  The fi
 **ice_in** defines the namelist input for the cice driver.
 
 
-.. _dev_options:
+.. _dev_preset_options:
 
 Preset Case Options
 ---------------------
@@ -89,7 +89,7 @@ One other files will need to be
 changed to support a port, that is **configuration/scripts/cice.batch.csh**.
 To port to a new machine, see :ref:`porting`.  
 
-.. _dev_options:
+.. _dev_test_options:
 
 Test Options
 ---------------

doc/source/master_list.bib

@@ -45,12 +45,14 @@ @string{JPD
 @string{NTN = {NCAR Tech. Note}}
 @string{BGC = {Biogeochemistry}}
 @string{EFM = {Eng. Fract. Mech.}}
+@string{GMD = {Geosci. Model Dev.}}
+@string{CRST = {Cold Reg. Sci. Technol.}}
 
-% Individual entries (roughly sequential, then alphabetical but first-author’s last name)
+% Individual entries (roughly sequential, then alphabetical by first-author's last name)
 @incollection{Assur58,
   author =  "A. Assur",
   title  = "Composition of sea ice and its tensile strength",
-  booktitle = "Arctic sea ice; conference held at Easton, Maryland, February 24–27, 1958",
+  booktitle = "Arctic sea ice; conference held at Easton, Maryland, February 24-27, 1958",
   publisher = "Publs. Natl. Res. Coun. Wash.",
   address = "Washington, D.C.",
   year =  "1958",
@@ -292,6 +294,16 @@ @Manual{SKM95
   year = "1995",
   url = {https://github.com/CICE-Consortium/CICE/blob/master/doc/PDF/LAUR-95-1146.pdf}
 }
+@article{ZvS95,
+  author = "F.W. Zwiers and H. von Storch",
+  title = "{Taking serial correlation into account in tests of the mean}",  
+  journal = JC,
+  year = "1995",
+  volume = {8},  
+  number = {2},
+  pages = {336-351},
+  url = {https://doi.org/10.1175/1520-0442(1995)008<0336:TSCIAI>2.0.CO;2}
+}
 @Article{Murray96
   author = "R.J. Murray",
   title = "{Explicit generation of orthogonal grids for ocean models}",
@@ -420,6 +432,16 @@ @Article{Schulson01
   pages = {1839-1887},
   url = {http://dx.doi.org/10.1016/S0013-7944(01)00037-6}
 }
+@article{Taylor01,
+  author = "K.E. Taylor",
+  title = {Summarizing multiple aspects of model performance in a single diagram},
+  journal = JGRA,
+  year = "2001",
+  volume = {106},
+  number = {D7},
+  pages = {7183-7192},
+  url = {https://doi.org/10.1029/2000JD900719}
+}
 @Article{TWMH01
   author = "H.J. Trodahl and S.O.F. Wilkinson and M.J. McGuinness and T.G. Haskeel",
   title = "{Thermal conductivity of sea ice: dependence on temperature and depth}",
@@ -550,6 +572,14 @@ @incollection{GLBA06
   year =  "2006",
   volume = {4},
 }
+@article{HRHPSL06,
+  author = "W.D. Hibler and A. Roberts and P. Heil and A.Y. Proshutinsky and H.L. Simmons and J. Lovick",
+  title = "{Modeling M2 tidal variability in Arctic sea-ice drift and deformation}",
+  journal = AG,
+  volume = {44},
+  year = {2006},
+  url = {https://doi.org/10.3189/172756406781811178}
+}
 @Article{WF06
   author = "A.V. Wilchinsky and D.L. Feltham",
   title = "{Modelling the rheology of sea ice as a collection of diamond-shaped floes}",
@@ -646,6 +676,15 @@ @Article{FFT10
   number = {C8},
   url = {http://dx.doi.org/10.1029/2009JC005568}
 }
+@Article{KH10
+  author = "C. Konig Beatty and D.M. Holland",
+  title = "{Modeling landfast ice by adding tensile strength}",
+  journal = JPO,
+  year = "2010",
+  volume = {40},
+  pages = {185-198},
+  url = {https://doi.org/10.1175/2009JPO4105.1}
+}
 @Article{ABTH11
   author = "K.C. Armour and C.M. Bitz and L. Thompson and E.C. Hunke",
   title = "{Controls on Arctic sea ice from first-year and multi-year ice survivability}",
@@ -665,7 +704,7 @@ @Article{DJEHMJ11
   url = {http://dx.doi.org/10.1029/2010JC006409}
 }
 @Article{LLCL11
-  author = "P. Lu and Z. Li and B. Cheng and M. Lepparanta",
+  author = "P. Lu and Z. Li and B. Cheng and M. Lepp{\"{a}}ranta",
   title = "{A parametrization fo the ice-ocean drag coefficient}",
   journal = JGRO,
   year = "2011",
@@ -700,6 +739,15 @@ @Article{HBBLH12
   pages = {1413-1430},
   url = {http://dx.doi.org/10.1175/JCLI-D-11-00078.1}
 }
+@article{LOSF12,
+  author = "M. Lepp{\"{a}}ranta and A. Oikkonen and K. Shirasawa and Y. Fukamachi",
+  title = "{A treatise on frequency spectrum of drift ice velocity}",
+  year = "2012",
+  journal = CRST,
+  volume = {76-77},
+  pages = {83-91},
+  doi = {https://doi.org/10.1016/j.coldregions.2011.12.005}
+}
 @Article{LGHA12
   author = "C. Lüpkes and V.M. Gryanik and  J. Hartmann and E.L. Andreas",
   title = "{A parametrization, based on sea ice morphology, of the neutral atmospheric drag coefficients for weather prediction and climate models}",
@@ -754,128 +802,55 @@ @Article{TFSFFKLB14
   pages = {1329-1353},
   url = {https://doi.org/10.1175/JPO-D-13-0215.1}
 }
-
-@Article{KH2010
-  author = "C. Konig Beatty and D.M. Holland",
-  title = "{Modeling landfast ice by adding tensile strength}",
-  journal = JPO,
-  year = "2010",
-  volume = {40},
-  pages = {185-198},
-  url = {https://doi.org/10.1175/2009JPO4105.1}
+@article{RCWODHNCB15,
+  author = "A.F. Roberts and A.P. Craig and W. Maslowski and R. Osinski and A.K. DuVivier and M. Hughes and B. Nijssen and J.J. Cassano and M. Brunke",
+  title = "{Simulating transient ice-ocean Ekman transport in the Regional Arctic System Model and Community Earth System Model}",
+  year = "2015",
+  journal = AG,
+  volume = {56},
+  number = {69},
+  pages = {211-228},
+  url = {https://doi.org/10.3189/2015AoG69A760}
 }
-
-@Article{Lemieux2016
-  author = "J.F. Lemieux and F.Dupont and P. Blain and F. Roy and G.C. Smith and G.M. Flato",
-  title = "{Improving the simulation of landfast ice by combining tensile strength and a parameterization for
-grounded ridges,}",
+@Article{LDBRSF16
+  author = "J.F. Lemieux and F. Dupont and P. Blain and F. Roy and G.C. Smith and G.M. Flato",
+  title = "{Improving the simulation of landfast ice by combining tensile strength and a parameterization for grounded ridges}",
   journal = JGRO,
   year = "2016",
   volume = {121},
-  pages = {},
+  pages = {7354-7368},
   url = {https://doi.org/10.1002/2016JC012006}
 }
-
-@article{Hunke2018,
-  author = {Hunke, Elizabeth and Roberts, Andrew and Allard, Richard and Lemieux, Jean-Fran{\c{c}}ois and Turner, Matthew and Craig, Tony and DuVivier, Alice and Bailey, David and Holland, Marika and Winton, Michael and Dupont, Frederic and Grumbine, Robert},
-  title = {{The CICE Consortium Sea Ice Modeling Suite}},
-  journal = {},
-  year = {In Prep.}
-}
-
-@article{Roberts2015,
-  author = {Roberts, Andrew F. and Craig, Anthony and Maslowski, Wieslaw and Osinski, Robert and Duvivier, Alice and Hughes, Mimi and Nijssen, Bart and Cassano, John J. and Brunke, Michael},
-  doi = {10.3189/2015AoG69A760},
-  journal = {Ann. Glaciol.},
-  number = {69},
-  pages = {211--228},
-  title = {{Simulating transient ice – ocean Ekman transport in the Regional Arctic System Model and Community Earth System Model}},
-  volume = {56},
-  year = {2015}
-}
-
-@article{Taylor2001,
-  author = {Taylor, Karl E},
-  journal = {J. Geophys. Res.},
-  number = {D7},
-  pages = {7183--7192},
-  title = {{Summarizing multiple aspects of model performance}},
-  volume = {106},
-  year = {2001}
-}
-
-@article{HiblerIII2006,
-  author = {Hibler, III, W. D. and Roberts, Andrew F. and Heil, Petra and Proshutinsky, A Y and Simmons, H L and Lovick, J},
-  doi = {10.3189/172756406781811178},
-  journal = {Ann. Glaciol.},
-  pages = {418--428},
-  title = {{Modeling M2 tidal variability in Arctic sea-ice drift and deformation}},
-  volume = {44},
-  year = {2006}
-}
-
-@article{Hibler2006,
-  author = {Hibler, W.D. and Roberts, A. and Heil, P. and Proshutinsky, A.Y. and Simmons, H.L. and Lovick, J.},
-  doi = {10.3189/172756406781811178},
-  journal = {Ann. Glaciol.},
-  title = {{Modeling M2 tidal variability in Arctic sea-ice drift and deformation}},
-  volume = {44},
-  year = {2006}
-}
-
-@article{Zwiers1995,
-  author = {Zwiers, Francis W. and von Storch, Hans},
-  doi = {10.1175/1520-0442(1995)008<0336:TSCIAI>2.0.CO;2},
-  journal = {J. Clim.},
-  number = {2},
-  pages = {336--351},
-  title = {{Taking serial correlation into account in tests of the mean}},
-  volume = {8},
-  year = {1995}
+@Article{NJHHMSTV16
+  author = "D. Notz and A. Jahn and E. Hunke and F. Massonnet and J. Stroeve and B. Tremblay and M. Vancoppenolle",
+  title = "{The CMIP6 Sea-Ice Model Intercomparison Project (SIMIP): understanding sea ice through climate-model simulations}",
+  journal = GMD,
+  year = "2016",
+  volume = {9},
+  pages = {3427-3446},
+  url = {https://doi.org/10.5194/gmd-9-3427-2016}
 }
-
-@book{VonStorch1999,
-  author = {von Storch, Hans and Zwiers, Francis W},
-  pages = {484},
-  publisher = {Cambridge University Press},
-  title = {{Statistical Analysis in Climate Research}},
-  year = {1999}
+@article{HRALTCDBHWDG18,
+  author = {E.C. Hunke and A. Roberts and R. Allard and J.F. Lemieux and M. Turner, and A.P. Craig and A.K. DuVivier and D. Bailey and M.M. Holland and M. Winton and F. Dupont and R. Grumbine},
+  title = "{The CICE Consortium Sea Ice Modeling Suite}",
+  journal = {In Prep.},
+  year = {2018 - In Prep.},
+  url = {https://doi.org}
 }
 
 @article{Roberts2018,
-  author = {Roberts, A. and Maslowski, W. and Hunke, E. and Osinski, R. and Cassano, J. and DuVivier, A. and Hughes, M. and Seefeldt, M. and Nijssen, B. and Hamman, J. and Hutchings, J. and Tsamados, M. and Feltham, D.},
-  journal = {Prep.},
-  title = {{Inter-comparison of isotropic and anisotropic sea-ice mechanics in a high-resolution fully coupled climate model}},
-  year = {2018}
+  author = "A. Roberts and W. Maslowski and E.C. Hunke and R. Osinski and J.J. Cassano and A.K. DuVivier and M. Hughes and M. Seefeldt and B. Nijssen and J. Hamman and J. Hutchings and M. Tsamados and D. Feltham",
+  title = "{Inter-comparison of isotropic and anisotropic sea-ice mechanics in a high-resolution fully coupled climate model}",
+  journal = {In Prep.},
+  year = {2018 - In Prep.},
+  url = {https://doi.org}
 }
-
 @article{Irving2015,
-  author = {Irving, Damien},
-  doi = {10.1175/BAMS-D-15-00010.1},
-  journal = {Bull. Am. Meteorol. Soc.},
-  number = {July},
-  pages = {151007152952002},
-  title = {{A minimum standard for publishing computational results in the weather and climate sciences}},
-  year = {2015}
-}
-
-@article{Lepparanta2012,
-  author = {Lepp{\"{a}}ranta, Matti and Oikkonen, Annu and Shirasawa, Kunio and Fukamachi, Yasushi},
-  doi = {10.1016/j.coldregions.2011.12.005},
-  journal = {Cold Reg. Sci. Technol.},
-  month = {jun},
-  pages = {83--91},
-  title = {{A treatise on frequency spectrum of drift ice velocity}},
-  volume = {76-77},
-  year = {2012}
+  author = "D. Irving",
+  title = "{A minimum standard for publishing computational results in the weather and climate sciences}",
+  year = "2015",
+  journal = BAMS,
+  number = {97},
+  pages = {1149-1158},
+  url = {https://doi.org/10.1175/BAMS-D-15-00010.1}
 }
-
-@book{Wilks2006,
-  author = {Wilks, Daniel S},
-  edition = {2nd},
-  pages = {627},
-  publisher = {Academic Press},
-  title = {{Statistical methods in the atmospheric sciences}},
-  year = {2006}
-}
-

doc/source/science_guide/sg_modelcomps.rst

@@ -1439,7 +1439,7 @@ where :math:`m` is the combined mass of ice and snow per unit area and
 :math:`\vec{\tau}_a` and :math:`\vec{\tau}_w` are wind and ocean
 stresses, respectively. The term :math:`\vec{\tau}_b` is a 
 seabed stress (also referred to as basal stress) that represents the grounding of pressure
-ridges in shallow water :cite:`Lemieux2016`. The strength of the ice is represented by the
+ridges in shallow water :cite:`LDBRSF16`. The strength of the ice is represented by the
 internal stress tensor :math:`\sigma_{ij}`, and the other two terms on
 the right hand side are stresses due to Coriolis effects and the sea
 surface slope. The parameterization for the wind and ice–ocean stress
@@ -1537,7 +1537,7 @@ pending further testing.
 Seabed stress
 ***************
 
-The parameterization for the seabed stress is described in :cite:`Lemieux2016`. The components of the basal seabed stress are 
+The parameterization for the seabed stress is described in :cite:`LDBRSF16`. The components of the basal seabed stress are 
 :math:`\tau_{bx}=C_bu` and :math:`\tau_{by}=C_bv`, where :math:`C_b` is a coefficient expressed as
 
 .. math::
@@ -1590,7 +1590,7 @@ is therefore simply equal to :math:`-\sigma_1/2`.
 *Elastic-Viscous-Plastic*
 
 In the EVP model the internal stress tensor is determined from a
-regularized version of the VP constitutive law. Following the approach of :cite:`KH2010` (see also :cite:`Lemieux2016`), the 
+regularized version of the VP constitutive law. Following the approach of :cite:`KH10` (see also :cite:`LDBRSF16`), the 
 elliptical yield curve can be modified such that the ice has isotropic tensile strength. 
 The tensile strength :math:`T_p` is expressed as a fraction of the ice strength :math:`P`, that is :math:`T_p=k_t P` 
 where :math:`k_t` should be set to a value between 0 and 1. The constitutive law is therefore 

doc/source/user_guide/ug_case_settings.rst

@@ -94,6 +94,7 @@ Table of namelist options
    :header: "variable", "options/format", "description", "recommended value"
    :widths: 15, 15, 30, 15 
 
+   "", "", "", ""
    "*setup_nml*", "", "", ""
    "", "", "*Time, Diagnostics*", ""
    "``days_per_year``", "``360`` or ``365``", "number of days in a model year", "365"
@@ -354,7 +355,7 @@ Table of namelist options
    "``trestore``", "integer", "sst restoring time scale (days)", ""
    "``restore_ice``", "true/false", "restore ice state along lateral boundaries", ""
    "", "", "", ""
-   "*icefields_tracer_nml*", "", "", ""
+   "*icefields_nml*", "", "", ""
    "", "", "*History Fields*", ""
    "``f_<var>``", "string", "frequency units for writing ``<var>`` to history", ""
    "", "``y``", "write history every ``histfreq_n`` years", ""