Add a table of physical constants to the user guide (#326)

# CABLE ## Description Added a table of physical constants and a table of mathematical constants to the user guide. Additional tables of constants can be added following the same pattern. Fixed missing/incorrect units in code and documentation. **It might be a good time at this stage to decide on the numerical value to use for the ice density: 910 from cable_soilparm.nml OR 921 from cable_phys_constants_mod.F90 ?** Interestingly another well known code uses 917. - [X] New or updated documentation  ---- 📚 Documentation preview 📚: https://cable--326.org.readthedocs.build/en/326/
CABLE-LSM · Aug 9, 2024 · 8b93b3b · 8b93b3b
2 parents 32ad6b7 + 1239fec
commit 8b93b3b
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 20 deletions.
diff --git a/documentation/docs/user_guide/constants/index.md b/documentation/docs/user_guide/constants/index.md
@@ -0,0 +1,11 @@
+# CABLE constants
+
+Table 1 lists the various types of constants used in CABLE. A list of the numerical values of each type can be accessed through the left navigation bar.
+
+
+## Table 1: Various constants used in CABLE 
+
+|   CABLE constants   	 |
+|------------------------|
+| Physical constants   	 |
+| Mathematical constants |
diff --git a/documentation/docs/user_guide/constants/mathematical_constants.md b/documentation/docs/user_guide/constants/mathematical_constants.md
@@ -0,0 +1,5 @@
+## Table 1: CABLE mathematical constants
+
+| Name	                | Value            |
+|-----------------------|------------------|
+|  pi                   | 3.1415927        |
diff --git a/documentation/docs/user_guide/constants/physical_constants.md b/documentation/docs/user_guide/constants/physical_constants.md
@@ -0,0 +1,23 @@
+## Table 1: CABLE physical constants
+
+| Name	                | Value            | Units                                               | Description                                         |
+|-----------------------|------------------|-----------------------------------------------------|--------------------------------------------------   |
+|  tfrz                 | 273.16      	   | \( K \)	       				     	 |   Temperature corresponding to \( 0^{\circ}C \)     |
+|  sboltz               | 5.67E-8     	   | \( W \cdot m^{-2} \cdot K^{-4} \)                   |   Stefan-Boltzmann constant   	               |
+|  emsoil               | 1.0         	   | \(  -  \)           			      	 |   Soil emissivity                  	               |
+|  emleaf               | 1.0         	   | \(  -  \) 					      	 |   Leaf emissivity                  	               |
+|  capp                 | 1004.64     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)                  |   Air specific heat                        	       |
+|  hl  	                | 2.5014E6    	   | \( J \cdot kg^{-1} \) 				 |   Latent heat of vaporization	               |
+|  hlf 	                | 0.334E6     	   | \( J \cdot kg^{-1} \)              	      	 |   Latent heat of fusion                             |
+|  hls 	                | 2.8350E6    	   | \( J \cdot kg^{-1} \) 			         |   Latent heat of Sublimation                        |
+|  dheat                | 21.5E-6     	   | \( cm^{2} \cdot s^{-1} \) 			      	 |   Molecular diffusivity for heat                    |
+|  grav                 | 9.8086      	   | \( m \cdot s^{-2} \) 			      	 |   Gravity acceleration                              |                             
+|  rgas                 | 8.3143      	   | \(J \cdot mol^{-1} \cdot K^{-1} \)                  |   Universal gas const 	                       |
+|  rmair                | 0.02897     	   | \( kg \cdot mol^{-1} \) 			      	 |   Molecular weight of dry air                       |
+|  rmh2o                | 0.018016    	   | \( kg \cdot mol^{-1} \) 			      	 |   Molecular weight of water                         |
+|  cgsnow               | 2090.0      	   | \( J \cdot kg^{-1} \cdot K^{-1} \)                	 |   Specific heat for snow	                       |           
+|  csice                | 2.100E3     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)		      	 |   Specific heat for ice	                       |
+|  cswat                | 4.218E3     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)		      	 |   Specific heat for water at \( 0^{\circ}C \)       |
+|  density_liq          | 1000.0      	   | \( kg \cdot m^{-3} \) 			      	 |   Density of liquid water                           |
+|  density_ice          | 921.0       	   | \( kg \cdot m^{-3} \) 			      	 |   Density of ice                                    |                
+        
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
@@ -86,6 +86,10 @@ nav:
       - Restart: user_guide/inputs/restart.md
     - Output files:
       - user_guide/outputs/index.md
+    - CABLE constants:
+      - user_guide/constants/index.md
+      - Physical constants: user_guide/constants/physical_constants.md 
+      - Mathematical constants: user_guide/constants/mathematical_constants.md
     - Other resources:
       - Existing configurations: user_guide/other_resources/configurations/config.md
       - Obsolete and deprecated features: user_guide/other_resources/obsolete_and_deprecated_features/obsolete_and_deprecated_features.md

diff --git a/src/params/cable_phys_constants_mod.F90 b/src/params/cable_phys_constants_mod.F90
@@ -21,27 +21,27 @@ MODULE cable_phys_constants_mod
 
 PUBLIC
 
-REAL, PARAMETER :: tfrz   = 273.16        ! Temp (K) corresp. to 0 C           
-REAL, PARAMETER :: sboltz = 5.67e-8       ! Stefan-Boltz. const (W/m2/K4)      
-REAL, PARAMETER :: emsoil = 1.0           ! soil emissivity                    
-REAL, PARAMETER :: emleaf = 1.0           ! leaf emissivity                    
-REAL, PARAMETER :: capp   = 1004.64       ! air spec. heat (J/kg/K)            
-REAL, PARAMETER :: hl = 2.5014e6          ! latent heat of vaporization (J/kg) 
+REAL, PARAMETER :: tfrz   = 273.16        ! Temp (K) corresp. to 0 C
+REAL, PARAMETER :: sboltz = 5.67e-8       ! Stefan-Boltz. const (W/m2/K4)
+REAL, PARAMETER :: emsoil = 1.0           ! soil emissivity
+REAL, PARAMETER :: emleaf = 1.0           ! leaf emissivity
+REAL, PARAMETER :: capp   = 1004.64       ! air spec. heat (J/kg/K)
+REAL, PARAMETER :: hl     = 2.5014e6      ! latent heat of vaporization (J/kg)
 !Below are constants used in CABLE model which are not as yet used in JAC-6.2
-REAL, PARAMETER :: hlf = 0.334e6          ! latent heat of fusion (J/kg)              
-REAL, PARAMETER :: hls = 2.8350e6         ! latent heat of sublimation (J/kg)         
-REAL, PARAMETER :: dheat  = 21.5e-6       ! molecular diffusivity for heat (cm2/s)    
-REAL, PARAMETER :: grav   = 9.8086        ! gravity acceleration (m/s2)               
-REAL, PARAMETER :: rgas   = 8.3143        ! universal gas const (J/mol/K)             
-REAL, PARAMETER :: rmair  = 0.02897       ! molecular wt: dry air (kg/mol)            
-REAL, PARAMETER :: rmh2o  = 0.018016      ! molecular wt: water (kg/mol)              
-REAL, PARAMETER :: cgsnow = 2090.0        ! specific heat for snow (J/kg/K)           
-REAL, PARAMETER :: cs_rho_ice = 1.9257e6  ! heat capacity * density ice               
-REAL, PARAMETER :: cs_rho_wat = 4.218e6   ! heat capacity * density  water            
-REAL, PARAMETER :: csice = 2.100e3        ! specific heat for ice (J/kg/K)            
-REAL, PARAMETER :: cswat = 4.218e3        ! specific heat for water at 0°C (J/kg/K)   
-REAL, PARAMETER :: density_liq = 1000.0   ! density of liquid water                   
-REAL, PARAMETER :: density_ice = 917.0    ! density of ice                            
+REAL, PARAMETER :: hlf    = 0.334e6       ! latent heat of fusion (J/kg)
+REAL, PARAMETER :: hls    = 2.8350e6      ! latent heat of sublimation (J/kg)
+REAL, PARAMETER :: dheat  = 21.5e-6       ! molecular diffusivity for heat (cm2/s)
+REAL, PARAMETER :: grav   = 9.8086        ! gravity acceleration (m/s2)
+REAL, PARAMETER :: rgas   = 8.3143        ! universal gas const (J/mol/K)
+REAL, PARAMETER :: rmair  = 0.02897       ! molecular wt: dry air (kg/mol)
+REAL, PARAMETER :: rmh2o  = 0.018016      ! molecular wt: water (kg/mol)
+REAL, PARAMETER :: cgsnow = 2090.0        ! specific heat for snow (J/kg/K)
+REAL, PARAMETER :: cs_rho_ice = 1.9341e6  ! heat capacity * density ice
+REAL, PARAMETER :: cs_rho_wat = 4.218e6   ! heat capacity * density  water
+REAL, PARAMETER :: csice = 2.100e3        ! specific heat for ice (J/kg/K)
+REAL, PARAMETER :: cswat = 4.218e3        ! specific heat for water at 0°C (J/kg/K)
+REAL, PARAMETER :: density_liq = 1000.0   ! density of liquid water
+REAL, PARAMETER :: density_ice = 921.0    ! density of ice                              
 
 ! Teten coefficients
 REAL, PARAMETER :: tetena = 6.106         ! Magnus Tetans (Murray 1967)