Fix RTD, minor updates to documentation (#437)

* - Add .readthedocs.yaml to fix readthedocs - Minor update to icepack_mushy_physics inline documentation - Update Icepack interfaces documentation, add icepack_mushy public interfaces - Remove trailing blank spaces in source code * Add cpp CCSMCOUPLED to trigger CESMCOUPLED cpp in icepack_kinds. icepack_kinds is used by all files in columnphysics, so should be comprehensive.
CICE-Consortium · May 22, 2023 · 6703bc5 · 6703bc5
1 parent e6727c1
commit 6703bc5
Show file tree

Hide file tree

Showing 10 changed files with 193 additions and 98 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.7"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: doc/source/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: doc/requirements.txt
diff --git a/columnphysics/icepack_kinds.F90 b/columnphysics/icepack_kinds.F90
@@ -1,3 +1,6 @@
+#ifdef CCSMCOUPLED
+#define CESMCOUPLED
+#endif
 !=======================================================================
 
 ! Defines variable precision for all common data types

diff --git a/columnphysics/icepack_mechred.F90 b/columnphysics/icepack_mechred.F90
@@ -1910,7 +1910,7 @@ subroutine icepack_step_ridge (dt,           ndtd,         &
       end subroutine icepack_step_ridge
 
 !=======================================================================
-      
+
       end module icepack_mechred
 
 !=======================================================================
diff --git a/columnphysics/icepack_mushy_physics.F90 b/columnphysics/icepack_mushy_physics.F90
@@ -68,11 +68,10 @@ module icepack_mushy_physics
 !=======================================================================
 ! Physical Quantities
 !=======================================================================
+! Detemine the conductivity of the mush from enthalpy and salinity
 
   subroutine conductivity_mush_array(nilyr, zqin, zSin, km)
 
-    ! detemine the conductivity of the mush from enthalpy and salinity
-
     integer (kind=int_kind), intent(in) :: &
          nilyr   ! number of ice layers
 
@@ -101,17 +100,19 @@ subroutine conductivity_mush_array(nilyr, zqin, zSin, km)
   end subroutine conductivity_mush_array
 
 !=======================================================================
+!autodocument_start icepack_mushy_density_brine
+! Compute density of brine from brine salinity
 
   function icepack_mushy_density_brine(Sbr) result(rho)
 
-    ! density of brine from brine salinity
-
     real(kind=dbl_kind), intent(in) :: &
          Sbr ! brine salinity (ppt)
 
     real(kind=dbl_kind) :: &
          rho ! brine density (kg m-3)
 
+!autodocument_end
+
     real(kind=dbl_kind), parameter :: &
          a = 1000.3_dbl_kind    , & ! zeroth empirical coefficient
          b = 0.78237_dbl_kind   , & ! linear empirical coefficient
@@ -126,11 +127,10 @@ end function icepack_mushy_density_brine
 !=======================================================================
 ! Snow
 !=======================================================================
+! Heat conductivity of the snow
 
   subroutine conductivity_snow_array(ks)
 
-    ! heat conductivity of the snow
-
     real(kind=dbl_kind), dimension(:), intent(out) :: &
          ks ! snow layer conductivity (W m-1 K-1)
 
@@ -141,11 +141,10 @@ subroutine conductivity_snow_array(ks)
   end subroutine conductivity_snow_array
 
 !=======================================================================
+! Enthalpy of snow from snow temperature
 
   function enthalpy_snow(zTsn) result(zqsn)
 
-    ! enthalpy of snow from snow temperature
-
     real(kind=dbl_kind), intent(in) :: &
          zTsn ! snow layer temperature (C)
 
@@ -159,11 +158,10 @@ function enthalpy_snow(zTsn) result(zqsn)
   end function enthalpy_snow
 
 !=======================================================================
+! Temperature of snow from the snow enthalpy
 
   function temperature_snow(zqsn) result(zTsn)
 
-    ! temperature of snow from the snow enthalpy
-
     real(kind=dbl_kind), intent(in) :: &
          zqsn ! snow layer enthalpy (J m-3)
 
@@ -182,12 +180,11 @@ end function temperature_snow
 !=======================================================================
 ! Mushy Layer Formulation - Assur (1958) liquidus
 !=======================================================================
+! Liquidus relation: equilibrium brine salinity as function of temperature
+! based on empirical data from Assur (1958)
 
   function liquidus_brine_salinity_mush(zTin) result(Sbr)
 
-    ! liquidus relation: equilibrium brine salinity as function of temperature
-    ! based on empirical data from Assur (1958)
-
     real(kind=dbl_kind), intent(in) :: &
          zTin         ! ice layer temperature (C)
 
@@ -223,12 +220,11 @@ function liquidus_brine_salinity_mush(zTin) result(Sbr)
   end function liquidus_brine_salinity_mush
 
 !=======================================================================
+! Liquidus relation: equilibrium temperature as function of brine salinity
+! based on empirical data from Assur (1958)
 
   function liquidus_temperature_mush(Sbr) result(zTin)
 
-    ! liquidus relation: equilibrium temperature as function of brine salinity
-    ! based on empirical data from Assur (1958)
-
     real(kind=dbl_kind), intent(in) :: &
          Sbr    ! ice brine salinity (ppt)
 
@@ -264,11 +260,10 @@ function liquidus_temperature_mush(Sbr) result(zTin)
   end function liquidus_temperature_mush
 
 !=======================================================================
+! Enthalpy of mush from mush temperature and bulk salinity
 
   function enthalpy_mush(zTin, zSin) result(zqin)
 
-    ! enthalpy of mush from mush temperature and bulk salinity
-
     real(kind=dbl_kind), intent(in) :: &
          zTin, & ! ice layer temperature (C)
          zSin    ! ice layer bulk salinity (ppt)
@@ -289,11 +284,10 @@ function enthalpy_mush(zTin, zSin) result(zqin)
   end function enthalpy_mush
 
 !=======================================================================
+! Enthalpy of mush from mush temperature and liquid fraction
 
   function enthalpy_mush_liquid_fraction(zTin, phi) result(zqin)
 
-    ! enthalpy of mush from mush temperature and bulk salinity
-
     real(kind=dbl_kind), intent(in) :: &
          zTin, & ! ice layer temperature (C)
          phi     ! liquid fraction
@@ -309,12 +303,11 @@ function enthalpy_mush_liquid_fraction(zTin, phi) result(zqin)
   end function enthalpy_mush_liquid_fraction
 
 !=======================================================================
+! Enthalpy of melting of mush from bulk salinity
+! Energy needed to fully melt mush (T < 0)
 
   function enthalpy_of_melting(zSin) result(qm)
 
-    ! enthalpy of melting of mush
-    ! energy needed to fully melt mush (T < 0)
-
     real(kind=dbl_kind), intent(in) :: &
          zSin ! ice layer bulk salinity (ppt)
 
@@ -328,11 +321,10 @@ function enthalpy_of_melting(zSin) result(qm)
   end function enthalpy_of_melting
 
 !=======================================================================
+! Enthalpy of brine (fully liquid) from temperature
 
   function enthalpy_brine(zTin) result(qbr)
 
-    ! enthalpy of brine (fully liquid)
-
     real(kind=dbl_kind), intent(in) :: &
          zTin ! ice layer temperature (C)
 
@@ -346,18 +338,20 @@ function enthalpy_brine(zTin) result(qbr)
   end function enthalpy_brine
 
 !=======================================================================
+!autodocument_start icepack_mushy_temperature_mush
+! Temperature of mush from mush enthalpy and bulk salinity
 
   function icepack_mushy_temperature_mush(zqin, zSin) result(zTin)
 
-    ! temperature of mush from mush enthalpy
-
     real(kind=dbl_kind), intent(in) :: &
          zqin   , & ! ice enthalpy (J m-3)
          zSin       ! ice layer bulk salinity (ppt)
 
     real(kind=dbl_kind) :: &
          zTin       ! ice layer temperature (C)
 
+!autodocument_end
+
     real(kind=dbl_kind) :: &
          qb     , & ! liquidus break enthalpy
          q0     , & ! fully melted enthalpy
@@ -454,11 +448,10 @@ function icepack_mushy_temperature_mush(zqin, zSin) result(zTin)
   end function icepack_mushy_temperature_mush
 
 !=======================================================================
+! Temperature of mush from mush enthalpy and liquid fraction
 
   function temperature_mush_liquid_fraction(zqin, phi) result(zTin)
 
-    ! temperature of mush from mush enthalpy
-
     real(kind=dbl_kind), intent(in) :: &
          zqin   , & ! ice enthalpy (J m-3)
          phi        ! liquid fraction
@@ -474,11 +467,10 @@ function temperature_mush_liquid_fraction(zqin, phi) result(zTin)
   end function temperature_mush_liquid_fraction
 
 !=======================================================================
+! Mush heat conductivity from mush temperature and bulk salinity
 
   function heat_conductivity(zTin, zSin) result(km)
 
-    ! msuh heat conductivity from mush temperature and bulk salinity
-
     real(kind=dbl_kind), intent(in) :: &
          zTin              , & ! ice layer temperature (C)
          zSin                  ! ice layer bulk salinity (ppt)
@@ -497,18 +489,22 @@ function heat_conductivity(zTin, zSin) result(km)
 
   end function heat_conductivity
 
-  !=======================================================================
+!=======================================================================
+!autodocument_start icepack_mushy_liquid_fraction
+! Liquid fraction of mush from mush temperature and bulk salinity
 
   function icepack_mushy_liquid_fraction(zTin, zSin) result(phi)
 
-    ! liquid fraction of mush from mush temperature and bulk salinity
-
     real(kind=dbl_kind), intent(in) :: &
          zTin, & ! ice layer temperature (C)
          zSin    ! ice layer bulk salinity (ppt)
 
     real(kind=dbl_kind) :: &
-         phi , & ! liquid fraction
+         phi     ! liquid fraction
+
+!autodocument_end
+
+    real(kind=dbl_kind) :: &
          Sbr     ! brine salinity (ppt)
 
     character(len=*),parameter :: subname='(icepack_mushy_liquid_fraction)'
@@ -521,5 +517,3 @@ end function icepack_mushy_liquid_fraction
 !=======================================================================
 
 end module icepack_mushy_physics
-
-
diff --git a/columnphysics/icepack_therm_itd.F90 b/columnphysics/icepack_therm_itd.F90
@@ -915,7 +915,7 @@ subroutine lateral_melt (dt,         ncat,       &
       real (kind=dbl_kind), intent(in) :: &
          rside   , & ! fraction of ice that melts laterally
          wlat        ! lateral melt rate (m/s)
-         
+
       real (kind=dbl_kind), intent(inout) :: &
          fside       ! lateral heat flux (W/m^2)
 
@@ -982,7 +982,7 @@ subroutine lateral_melt (dt,         ncat,       &
          f_flx         !
 
       real (kind=dbl_kind) :: &
-         sicen,        & 
+         sicen,        &
          etot,         & ! column energy per itd cat, for FSD code
          elapsed_t,    & ! FSD subcycling
          subdt           ! FSD timestep (s)
@@ -1064,8 +1064,8 @@ subroutine lateral_melt (dt,         ncat,       &
             do k = 1, nilyr
                etot = etot + trcrn(nt_qice+k-1,n) * vicen(n)/real(nilyr,kind=dbl_kind)
             enddo                  ! nilyr
-               
-            ! lateral heat flux, fside < 0        
+
+            ! lateral heat flux, fside < 0
             fside = fside + rsiden(n)*etot/dt
 
          enddo ! ncat
@@ -1245,7 +1245,7 @@ subroutine lateral_melt (dt,         ncat,       &
       if (tr_fsd) then
 
          trcrn(nt_fsd:nt_fsd+nfsd-1,:) =  afsdn
-         
+
          call icepack_cleanup_fsd (ncat, nfsd, trcrn(nt_fsd:nt_fsd+nfsd-1,:) )
          if (icepack_warnings_aborted(subname)) return
 

diff --git a/configuration/driver/icedrv_RunMod.F90 b/configuration/driver/icedrv_RunMod.F90
@@ -177,7 +177,7 @@ subroutine ice_step
       if (tr_fsd .and. wave_spec) call step_dyn_wave(dt)
 
       do k = 1, ndtd
-         
+
          ! horizontal advection of ice or open water into the single column
          call step_lateral_flux_scm(dt_dyn)
 

diff --git a/configuration/driver/icedrv_init.F90 b/configuration/driver/icedrv_init.F90
@@ -278,7 +278,7 @@ subroutine input_data
       ocn_data_type   = 'default' ! source of ocean forcing data
       ocn_data_file   = ' '       ! ocean forcing data file
       ice_data_file   = ' '       ! ice forcing data file (opening, closing)
-      lateral_flux_type   = 'uniform_ice' ! if 'uniform_ice' assume closing 
+      lateral_flux_type   = 'uniform_ice' ! if 'uniform_ice' assume closing
                                            ! fluxes in uniform ice
       bgc_data_format = 'bin'     ! file format ('bin'=binary or 'nc'=netcdf)
       bgc_data_type   = 'default' ! source of BGC forcing data