updated documentation to include namelist options for initial ice sta…

…te and fixed mixed layer properties

doc/source/icepack_index.rst

@@ -206,7 +206,9 @@ section :ref:`tabnamelist`.
    "H2_16O_ocn", "concentration of H2_16O isotope in ocean", "kg/kg"
    "H2_18O_ocn", "concentration of H2_18O isotope in ocean", "kg/kg"
    "HDO_ocn", "concentration of HDO isotope in ocean", "kg/kg"
+   "hbar_init_itd", ":math:`\bullet` initial modal ice thickness for itd-initialized grid cell", "3. m"
    "hfrazilmin", "minimum thickness of new frazil ice", "0.05 m"
+   "hi_init_slab", ":math:`\bullet` initial ice thickness for slab-initialized grid cell", "2. m"
    "hi_min", "minimum ice thickness for thinnest ice category", "m"
    "hi_ssl", "ice surface scattering layer thickness", "0.05 m"
    "hicen", "ice thickness in category n", "m"
@@ -215,6 +217,7 @@ section :ref:`tabnamelist`.
    "hin_max", "category thickness limits", "m"
    "history_format", "turns on netcdf history output if set to 'nc'", ""
    "hmix", "ocean mixed layer depth", "20. m"
+   "hmix_fixed", ":math:`\bullet` constant 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"
    "hp1", ":math:`\bullet` critical ice lid thickness for topo ponds (dEdd)", "0.01 m"
@@ -224,6 +227,8 @@ section :ref:`tabnamelist`.
    "hs0", ":math:`\bullet` snow depth at which transition to ice occurs (dEdd)", ""
    "hs1", ":math:`\bullet` snow depth of transition to pond ice", "0.03 m"
    "hs_ssl", "snow surface scattering layer thickness", "0.04 m"
+   "hsno_init_itd", ":math:`\bullet` initial snow depth for itd-initialized grid cell", "0.25 m"
+   "hsno_init_slab", ":math:`\bullet` initial snow depth for slab-initialized grid cell", "0. m"
    "Hstar", "determines mean thickness of ridged ice", "25. m"
    "**I**", "", ""
    "i0vis","fraction of penetrating visible solar radiation", "0.70"
@@ -364,7 +369,8 @@ section :ref:`tabnamelist`.
    "**Q**", "", ""
    "Qa", "specific humidity at 10 m", "kg/kg"
    "Qa_iso", "water isotope specific humidity at 10 m", "kg/kg"
-   "qdp", "deep ocean heat flux", "W/m\ :math:`^2`"
+   "qdp", "oceanic heat flux convergence", "W/m\ :math:`^2`"
+   "qdp_fixed", ":math:`\bullet` constant oceanic heat flux convergence", "0. W/m\ :math:`^2`"
    "qqqice", "for saturated specific humidity over ice", "1.16378\ :math:`\times`\ 10\ :math:`^7`\ kg/m\ :math:`^3`"
    "qqqocn", "for saturated specific humidity over ocean", "6.275724\ :math:`\times`\ 10\ :math:`^6`\ kg/m\ :math:`^3`"
    "Qref", "2m atmospheric reference specific humidity", "kg/kg"
@@ -433,7 +439,9 @@ section :ref:`tabnamelist`.
    "spval_dbl", "special value (double precision)", ":math:`10^{30}`", ""
    "ss_tltx(y)", "sea surface in the x(y) direction", "m/m"
    "sss", "sea surface salinity", "ppt"
+   "sss_fixed", ":math:`\bullet` constant mixed layer salinity", "34. ppt"
    "sst", "sea surface temperature", "C"
+   "sst_init", ":math:`\bullet` initial mixed layer temperature", "-1.8\ :math:`^\circ`\ C"
    "Sswabs", "shortwave radiation absorbed in snow layers", "W/m\ :math:`^2`"
    "stefan-boltzmann", "Stefan-Boltzmann constant", "5.67\ :math:`\times`\ 10\ :math:`^{-8}` W/m\ :math:`^2`\ K\ :math:`^4`"
    "stop_now", "if 1, end program execution", ""

doc/source/user_guide/ug_case_settings.rst

@@ -142,8 +142,12 @@ 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."
+   "``hbar_init_itd``", "real", "initial modal ice thickness for itd-initialized grid cell in m", "3.0"
+   "``hi_init_slab``", "real", "initial ice thickness for slab-initialized grid cell in m", "2.0"
    "``history_format``", "``cdf``", "history file output in netcdf format", "``none``"
    "","``none``","no history output",""
+   "``hsno_init_itd``", "real", "initial snow depth for itd-initialized grid cell in m", "0.25"
+   "``hsno_init_slab``", "real", "initial snow depth for slab-initialized grid cell in m", "0.0"
    "``ice_ic``", "``default``", "latitude and sst dependent initial condition", "``default``"
    "", "``none``", "no ice", ""
    "", "'path/file'", "restart file name", ""
@@ -155,6 +159,7 @@ setup_nml
    "``restart_file``", "string", "output file prefix for restart dump", "'iced'"
    "``restart_format``", "``bin``", "restart file output in binary format", "``bin``"
    "","``cdf``","restart file output in netcdf format",""
+   "``sst_init``", "real", "initial ocean mixed layer temperature in C", "-1.8"
    "``use_leap_years``", "logical", "include leap days", "``.false.``"
    "``year_init``", "integer", "the initial year if not using restart", "0"
    "", "", "", ""
@@ -358,6 +363,7 @@ forcing_nml
    "``formdrag``", "logical", "calculate form drag", "``.false.``"
    "``fyear_init``", "integer", "first year of atmospheric forcing data", "1998"
    "``highfreq``", "logical", "high-frequency atmo coupling", "``.false.``"
+   "``hmix_fixed``", "real", "constant ocean mixed layer depth in m", "20.0"
    "``lateral_flux_type``", "``uniform_ice``", "flux ice with identical properties into the cell when closing (Icepack only)", ""
    "", "``none``", "advect open water into the cell when closing (Icepack only)", ""
    "``ice_data_file``", "string", "file containing ice opening, closing data", "' '"
@@ -376,9 +382,11 @@ forcing_nml
    "", "``mm_per_month``", "", ""
    "", "``mm_per_sec``", "(same as MKS units)", ""
    "", "``m_per_sec``", "", ""
+   "``qdp_fixed``", "real", "constant oceanic heat flux convergence W/m^2", "0.0"
    "``restore_ocn``", "logical", "restore sst to data", "``.false.``"
    "``saltflux_option``", "``constant``","salt flux is referenced to a constant salinity","``constant``"
    "","``prognostic``","use actual sea ice bulk salinity in flux"
+   "``sss_fixed``", "real", "constant ocean mixed layer salinity in ppt", "34.0"
    "``tfrz_option``","``constant``", "constant ocean freezing temperature (Tocnfrz)","``mushy``"
    "", "``linear_salt``", "linear function of salinity (ktherm=1)", ""
    "", "``minus1p8``", "constant ocean freezing temperature (:math:`-1.8^{\circ} C`)", ""

doc/source/user_guide/ug_implementation.rst

@@ -118,13 +118,28 @@ will be described in more detail in the :ref:`tabnamelist`.
 
 Two namelist variables control model initialization, ``ice_ic``
 and ``restart``.  Setting ``ice_ic`` = 'default' causes the model to run using
-initial values set in the code.  To start
+initial values set in the code and the namelist.  To start
 from a file **filename**, set 
 ``restart`` = .true. and ``ice_ic`` = **filename**.  When restarting using the Icepack
 driver, for simplicity the tracers are assumed to be set the same way (on/off) as in the
 run that created the restart file; i.e. that the restart file contains exactly the 
 information needed for the new run.  CICE is more flexible in this regard.
 
+When the model is not running from a restart file (i.e., ``ice_ic`` = 'default'
+and ``restart`` = .false.), there are namelist options that control the initial
+snow depth , ice thicknesses and mixed layer temperature (``sst_init``).
+For the slab-initialized grid cell (``nx`` = 2), the run starts with a single
+ice thickness category having 100% ice cover . ``hsno_init_slab`` and 
+``hi_init_slab`` define the initial snow depth and ice thickness for that
+ice thickness category. For the itd-initialized grid cell (``nx`` = 3), the ice
+thickness in each category is set to the midpoint of that category's ice
+thickness range (excluding the last category, which is set to 1 m thicker than
+the lower bound). The area fraction of each category is set according to a
+normalized, downward-facing parabolic function of ice thickness, where the 
+maximum of the parabola is ``hbar_init_itd`` and the area fraction of open 
+water is zero. All thickness categories are initialized with a snow depth of 
+``hsno_init_itd``.
+
 For stand-alone runs,
 routines in **icedrv\_forcing.F90** read and interpolate data from files.
 The namelist variables ``precalc_forc``, ``atm_data_type``, 
@@ -163,7 +178,14 @@ conventions were developed by the Year of Polar Prediction supersite
 Model Intercomparison Project (`Uttal et al., 2024 
 <https://doi.org/10.5194/gmd-17-5225-2024>`_) and a `python toolbox 
 <https://gitlab.com/mdf-makers/mdf-toolkit>`_ is available to build MDF 
-files from raw data.
+files from raw data. The ``ocn_MDF`` subroutine currently assumes that
+the oceanic heat flux convergence (``qdp``) is equal to the turbulent
+heat flux over the thermocline.
+
+If no ocean forcing is provided, namelist variables provide constant
+values of the ocean mixed layer salinity (``sss_fixed``), thickness 
+(``hmix_fixed``), and oceanic heat flux convergence (``qdp_fixed``). If
+forcing data is provided then these variables are ignored.
 
 .. _parameters: