Merge pull request #32 from apcraig/e3smdocs1

Update documentation

columnphysics/icepack_mushy_physics.F90

@@ -141,6 +141,7 @@ subroutine conductivity_snow_array(ks)
   end subroutine conductivity_snow_array
 
 !=======================================================================
+!autodocument_start icepack_enthalpy_snow
 ! Enthalpy of snow from snow temperature
 
   function icepack_enthalpy_snow(zTsn) result(zqsn)
@@ -151,6 +152,8 @@ function icepack_enthalpy_snow(zTsn) result(zqsn)
     real(kind=dbl_kind) :: &
          zqsn ! snow layer enthalpy (J m-3)
 
+!autodocument_end
+
     character(len=*),parameter :: subname='(icepack_enthalpy_snow)'
 
     zqsn = -rhos * (-cp_ice * zTsn + Lfresh)
@@ -260,6 +263,7 @@ function liquidus_temperature_mush(Sbr) result(zTin)
   end function liquidus_temperature_mush
 
 !=======================================================================
+!autodocument_start icepack_enthalpy_mush
 ! Enthalpy of mush from mush temperature and bulk salinity
 
   function icepack_enthalpy_mush(zTin, zSin) result(zqin)
@@ -271,6 +275,8 @@ function icepack_enthalpy_mush(zTin, zSin) result(zqin)
     real(kind=dbl_kind) :: &
          zqin    ! ice layer enthalpy (J m-3)
 
+!autodocument_end
+
     real(kind=dbl_kind) :: &
          phi     ! ice liquid fraction
 

columnphysics/icepack_therm_shared.F90

@@ -278,7 +278,7 @@ function icepack_salinity_profile(zn) result(salinity)
       real(kind=dbl_kind) :: &
          salinity ! initial salinity profile
 
-!autodocument end
+!autodocument_end
 
       real (kind=dbl_kind), parameter :: &
          nsal    = 0.407_dbl_kind, &

columnphysics/icepack_warnings.F90

@@ -92,12 +92,16 @@ subroutine icepack_warnings_clear()
       end subroutine icepack_warnings_clear
 
 !=======================================================================
+!autodocument_start icepack_warnings_clear
+! return an array of all the current warning messages
 
       subroutine icepack_warnings_getall(warningsOut)
 
         character(len=char_len_long), dimension(:), allocatable, intent(out) :: &
              warningsOut
 
+!autodocument_end
+
         integer :: iWarning
         character(len=*),parameter :: subname='(icepack_warnings_getall)'
 

doc/source/icepack_index.rst

@@ -470,7 +470,7 @@ either Celsius or Kelvin units).  Deprecated parameters are listed at the end.
    "tmass", "total mass of ice and snow", "kg/m\ :math:`^2`"
    "Tmin", "minimum allowed internal temperature", "-100. C"
    "Tmltz", "melting temperature profile of ice", ""
-   "Tocnfrz", "temperature of constant freezing point parameterization", "-1.8 C"
+   "Tocnfrz", "temperature of constant freezing point parameterization", "C"
    "tr_aero", ":math:`\bullet` if true, use aerosol tracers", ""
    "tr_iso", ":math:`\bullet` if true, use water isotope tracers", ""
    "tr_bgc_[tracer]", ":math:`\bullet` if true, use biogeochemistry tracers", ""

doc/source/science_guide/sg_thermo.rst

@@ -21,7 +21,10 @@ horizontally uniform column with ice thickness
 :math:`h_{sn} = v_{sn}/a_{in}`. (Henceforth we omit the category
 index \ :math:`n`.) Each column is divided into :math:`N_i` ice layers
 of thickness :math:`\Delta h_i = h_i/N_i` and :math:`N_s` snow layers of
-thickness :math:`\Delta h_s = h_s/N_s`. The surface temperature (i.e.,
+thickness :math:`\Delta h_s = h_s/N_s`.   Minimum ice and snow thickness
+is specified by namelist parameters ``hi_min`` and ``hs_min``.
+
+The surface temperature (i.e.,
 the temperature of ice or snow at the interface with the atmosphere) is
 :math:`T_{sf}`, which cannot exceed :math:`0^{\circ}C`. The temperature at the
 midpoint of the snow layer is :math:`T_s`, and the midpoint ice layer
@@ -30,6 +33,13 @@ temperatures are :math:`T_{ik}`, where :math:`k` ranges from 1 to
 :math:`T_f`, the freezing temperature of the ocean mixed layer. All
 temperatures are in degrees Celsius unless stated otherwise.
 
+The ``tfrz_option`` namelist specifies the freezing temperature formulation.
+``minus1p8`` fixes the freezing temperature at -1.8C.  ``constant`` fixes
+the freeing point at whatever value is specified by the parameter ``Tocnfrz``.
+``linear_salt`` sets the freezing temperature based on salinity, 
+:math:`Tf = -depressT * sss`.  And ``mushy`` uses the mushy formulation for setting
+the freezing temperature.
+
 Each ice layer has an enthalpy :math:`q_{ik}`, defined as the negative
 of the energy required to melt a unit volume of ice and raise its
 temperature to :math:`0^{\circ}C`. Because of internal melting and freezing in brine
@@ -1679,7 +1689,8 @@ consistently (from a mushy physics point of view) to both enthalpy and
 bulk salinity, the resulting temperature may be changed to be greater
 than the limit allowed in the thermodynamics routines. If this situation
 is detected, the code corrects the enthalpy so the temperature is below
-the limiting value. Conservation of energy is ensured by placing the
+the limiting value. The limiting value, ``Tliquidus_max`` can be specified
+in namelist.  Conservation of energy is ensured by placing the
 excess energy in the ocean, and the code writes a warning (see :ref:`aborts`) 
 that this has
 occurred to the diagnostics file. This situation only occurs with the