reconcile with dev-access-esm1.6 - util- snmin threshold thru namelist (#552)

## Description

In ESM1.6 we have upgraded snmin(the threshold snow depth triggering
3-layer treatment) to a runtime configurable constant.

Merging ESM1.6 code we already have modifications to cable_common and
cable_runtime_opts. Strictly speaking, it shouldn't be necessary to make
any mods to offline at all.

However, with some very minor modifications (on top of those that are
already coming through the merge anyway), we can implement snmin as a
runtime configurable constant in offline as well.

put snmin=1.0 in cable.nml to reproduce main.

## Type of change

Enhancement following ESM1.6

## Checklist

- [x] The new content is accessible and located in the appropriate
section
- [x] I have checked that links are valid and point to the intended
content
- [x] I have checked my code/text and corrected any misspellings

## Testing

- [x] Are the changes bitwise-compatible with the main branch? If
working on an optional feature, are the results bitwise-compatible when
this feature is off? If yes, copy benchcab output showing successful
completion of the bitwise compatibility tests or equivalent results
below this line.

2025-03-03 16:40:25,871 - INFO - benchcab.benchcab.py:391 - 0 failed, 20
passed

<!-- readthedocs-preview cable start -->
----
📚 Documentation preview 📚:
https://cable--552.org.readthedocs.build/en/552/

<!-- readthedocs-preview cable end -->

---------

Co-authored-by: Claire Carouge <[email protected]>

Author: JhanSrbinovsky

documentation/docs/user_guide/inputs/cable_nml.md

@@ -1,14 +1,9 @@
 
 # Namelist file cable.nml #
 
-The namelist file for CABLE is cable.nml. For offline applications it
-should be located in the directory in which you are running CABLE. For
-ACCESS cases, cable.nml should be located in ~/CABLE-AUX/UM on the
-machine that CABLE is being executed on.
+The control namelist file for CABLE is cable.nml. 
 
-The cable.nml file includes some settings that are common across all CABLE
-applications and others that are required only for offline
-applications. The following are annotated examples of cable.nml:
+The cable.nml file includes some settings that are common across all CABLE applications and others that are required only for offline applications. Please refer to [the supported configurations][config_examples] for namelist examples.
 
 !!! Note
 
@@ -40,6 +35,7 @@ applications. The following are annotated examples of cable.nml:
 | spinup                           | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Spin up the model when .TRUE.                                                                           |
 | delsoilM                         | real               | any real number                                            | uninitialised                    | Allowed variation in soil moisture for spin up.                                                         |
 | delsoilT                         | real               | any real number                                            | uninitialised                    | Allowed variation in soil temperature for spin up.                                                      |
+| snmin                            | real               | any real number                                            | 1.0                              | Threshold/minimum snow depth triggering 3-layer snow model. \((m)\)                        |
 | output%restart                   | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Create a restart file when .TRUE..                                                                      |
 | output%met                       | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Output input meteorological data when .TRUE..                                                           |
 | output%flux                      | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Output convective, runoff, NEE when TRUE                                                                |
@@ -138,151 +134,7 @@ applications. The following are annotated examples of cable.nml:
 | cable_user%NtilesThruMetFile     | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Specify Ntiles through met file.                                                                        |
 | cable_user%l_ice_consistency     | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | If true, ensures consistency between soil and vegetation tiles with permanent ice. All tiles with permanent ice for soil will have ice for vegetation and vice-versa. All the parameters for these new ice tiles are updated to the ice parameters.                       |
 
-## For offline applications ##
-
-```fortran
-&cable
-   filename%met = '/projects/access/CABLE-AUX/offline/TumbaFluxnet.1.3_met.nc'
-   filename%out = 'out_cable.nc'
-   filename%log = 'log_cable.txt'
-   filename%restart_in  = ' '
-   filename%restart_out = './restart_out.nc'
-   filename%type    = '/projects/access/CABLE-AUX/offline/gridinfo_CSIRO_1x1.nc'
-   vegparmnew = .TRUE.  ! using new format when true
-   soilparmnew = .TRUE.  ! using new format when true
-   spinup = .TRUE.  ! do we spin up the model?
-   delsoilM = 0.001   ! allowed variation in soil moisture for spin up
-   delsoilT = 0.01    ! allowed variation in soil temperature for spin up
-   output%restart = .TRUE.  ! should a restart file be created?
-   output%met = .TRUE.  ! input met data
-   output%flux = .TRUE.  ! convective, runoff, NEE
-   output%soil = .TRUE.  ! soil states
-   output%snow = .TRUE.  ! snow states
-   output%radiation = .TRUE.  ! net rad, albedo
-   output%carbon    = .TRUE.  ! NEE, GPP, NPP, stores
-   output%veg       = .TRUE.  ! vegetation states
-   output%params    = .TRUE.  ! input parameters used to produce run
-   output%balances  = .TRUE.  ! energy and water balances
-   check%ranges     = 1  ! Range-checks on every timestep
-   check%exit = .TRUE.  ! Exit the program if range checks fail
-   check%energy_bal = .TRUE.  ! energy balance
-   check%mass_bal   = .TRUE.  ! water/mass balance
-   verbose = .TRUE. ! write details of every grid cell init and params to log?
-   leaps = .TRUE. ! calculate timing with leap years
-   logn = 88      ! log file number - declared in input module
-   fixedCO2 = 350.0   ! if not found in met file, in ppmv
-   spincasa      = .FALSE.     ! spin casa before running the model if TRUE, and should be set to FALSE if spincasainput = .TRUE.
-   l_casacnp     = .FALSE.  ! using casaCNP with CABLE
-   l_laiFeedbk   = .FALSE.  ! using prognostic LAI
-   l_vcmaxFeedbk = .FALSE.  ! using prognostic Vcmax
-   icycle = 0   ! BP pull it out from casadimension and put here; 0 for not using casaCNP, 1 for C, 2 for C+N, 3 for C+N+P
-   casafile%cnpipool='/projects/access/CABLE-AUX/core/biogeochem/poolcnpInTumbarumba.csv'  !
-   casafile%cnpbiome='/projects/access/CABLE-AUX/core/biogeochem/pftlookup_csiro_v16_17tiles.csv'  ! biome specific BGC parameters
-   casafile%cnpepool='poolcnpOut.csv'    ! end of run pool size
-   casafile%cnpmetout='casamet.nc'                ! output daily met forcing for spinning casacnp
-   casafile%cnpmetin=''          ! list of daily met files for spinning casacnp
-   casafile%phen='/projects/access/CABLE-AUX/core/biogeochem/modis_phenology_csiro.txt'        ! modis phenology
-   casafile%cnpflux='cnpfluxOut.csv'
-   ncciy = 0 ! 0 for not using gswp; 4-digit year input for year of gswp met
-   gswpfile%rainf = 'gswp/Rainf_gswp1987.nc'
-   gswpfile%snowf = 'gswp/Snowf_gswp1987.nc'
-   gswpfile%LWdown= 'gswp/LWdown_srb1987.nc'
-   gswpfile%SWdown= 'gswp/SWdown_srb1987.nc'
-   gswpfile%PSurf = 'gswp/PSurf_ecor1987.nc'
-   gswpfile%Qair  = 'gswp/Qair_cru1987.nc'
-   gswpfile%Tair  = 'gswp/Tair_cru1987.nc'
-   gswpfile%wind  = 'gswp/Wind_ncep1987.nc'
-   redistrb = .FALSE.  ! Turn on/off the hydraulic redistribution
-   wiltParam = 0.5
-   satuParam = 0.8
-   cable_user%FWSOIL_SWITCH = 'standard'        ! choices are: 'standard', 'non-linear extrapolation' or 'Lai and Ktaul 2000'
-   cable_user%DIAG_SOIL_RESP = 'ON '
-   cable_user%LEAF_RESPIRATION = 'ON '
-   cable_user%RUN_DIAG_LEVEL= 'BASIC'        ! choices are: 'BASIC', 'NONE'
-   cable_user%CONSISTENCY_CHECK= .TRUE.      ! TRUE outputs combined fluxes at each timestep for comparison to a control run
-   cable_user%CASA_DUMP_READ = .FALSE.      ! TRUE reads CASA forcing from netcdf format
-   cable_user%CASA_DUMP_WRITE = .FALSE.      ! TRUE outputs CASA forcing in netcdf format
-   cable_user%SSNOW_POTEV= 'HDM'      ! Humidity Deficit Method
-&end
-```
-
-## For ACCESS applications ##
-
-
-```fortran
-&cable
-!!
-!! cable namelist variables applicable to ACCESS/UM runs
-!! default parameter files are available in the following directory on raijin
-!! vegetation parameters in def_veg_params.txt or for vbeta=1 veg_params_vbeta1.txt
-!! vbeta=1 recommended but should be tested for your applications
-!
-  filename%veg     = '/projects/access/CABLE-AUX/core/biogeophys/veg_params_vbeta1.txt'
-!
-!! or checkout to your own area
-! filename%veg     = '~/CABLE-AUX/core/biogeophys/def_veg_params.txt' !relative to your home dir
-!!
-!! soil parameters in def_soil_params.txt. Not used except for isoil=9 (permanent ice) and
-!! rhosoil and css values (isoil=2 used for all non-ice tiles).
-!! Other soil parameters from spatially explicit ancillary files.
-!
-  filename%soil    = '/projects/access/CABLE-AUX/core/biogeophys/def_soil_params.txt'
-!
-! filename%soil    = '~/CABLE-AUX/core/biogeophys/def_soil_params.txt' !relative to your home dir
-!
-!! cable_user flags
-!
-  cable_user%CABLE_RUNTIME_COUPLED = .TRUE. ! controls whether snow initialised if
-                                            ! ktau_gl=1
-                                            ! must be set true for coupled run
-                                            ! use true for atmosphere only runs if
-                                            ! want to take snow from start dump
-                                            ! default is .false.
-  cable_user%FWSOIL_SWITCH = 'standard' ! Controls root water uptake function
-                                        ! choices are:
-                                        ! 'standard'
-                                        ! 'non-linear extrapolation'
-                                        ! 'Lai and Ktaul 2000' NB TYPO IS IN CODE (should be Katul)
-  cable_user%DIAG_SOIL_RESP = 'ON '  ! Controls soil respiration scheme when CASA-CNP not used
-                                     ! 'ON' uses scheme tuned with parameter veg%vegcf
-                                     ! 'OFF' uses scheme tuned with parameter veg%rs20
-  cable_user%LEAF_RESPIRATION = 'OFF' ! Controls what is output into the GPP stash variable
-                                      ! 'OFF' is true GPP (photosynthesis + leaf respiration)
-                                      ! 'ON' is only photosynthesis, canopy%fpn
-  cable_user%RUN_DIAG_LEVEL= 'BASIC'  ! Controls output from CABLE to standard out
-                                      ! choices are:
-                                      ! 'BASIC'
-                                      ! 'NONE'
-                                      ! 'zero' (in cable_explicit_driver - what does this do?)
-  cable_user%ssnow_POTEV = ''    ! Controls method used for soil evaporation
-                                 ! Choices are:
-                                 ! 'P-M' Penman_Monteith, otherwise defaults to
-                                 ! humidity deficit method
-!!--------------Test Switches--------------
-  cable_user%l_new_roughness_soil  = .FALSE.   ! for new soil roughness, E.Kowalczyk Mar14
-  cable_user%l_new_runoff_speed    = .FALSE.   ! for new increase in runoff speed, E.Kowalczyk Mar14
-  cable_user%l_new_reduce_soilevp  = .FALSE.   ! to reduce soil evaporation, E.Kowalczyk Mar14
-!!-----------------------------------------
-!
-  redistrb = .FALSE.  ! Turn on/off the hydraulic redistribution
-  wiltParam = 0.5     ! only used if hydraulic redistribution .true.
-  satuParam = 0.8     ! only used if hydraulic redistribution .true.
-!
-! CASA-CNP flags
-  l_casacnp = .true. ! redundant? actually controlled by icycle
-  icycle = 3 ! Controls whether CASA-CNP is run and for which species
-             ! Choices are:
-             ! 0 CASA-CNP not run
-             ! 1 Carbon only
-             ! 2 Carbon and nitrogen
-             ! 3 Carbon, nitrogen and phosphorus
-  l_laiFeedbk   = .TRUE.  ! using prognostic LAI
-  l_vcmaxFeedbk = .TRUE.  ! using prognostic Vcmax
-! filenames for CASA-CNP input files
-  casafile%cnpbiome='~/CABLE-AUX/core/biogeochem/pftlookup_csiro_v16_17tiles.csv' ! biome specific BGC parameters
-  casafile%phen='~/CABLE-AUX/core/biogeochem/modis_phenology_csiro.txt' ! phenology by latitude (modis derived)
-&end
-```
 
 <!-- markdown-link-check-disable-line --> [Walker]: https://doi.org/10.1002/ece3.1173
-[obsolete]: ../other_resources/obsolete_and_deprecated_features/obsolete_and_deprecated_features.md
+[obsolete]: ../other_resources/obsolete_and_deprecated_features/obsolete_and_deprecated_features.md
+[config_examples]: index.md#example-configurations

documentation/docs/user_guide/inputs/index.md

@@ -3,7 +3,6 @@
 CABLE can be used in many configurations, in part determined by the input files supplied to the code.
 Table 1 lists the various input files used in offline CABLE. A description of each file can be accessed through the left navigation bar.
 
-
 ## Table 1: CABLE input files for the offline case
 
 |   Input file         	 | Description |
@@ -16,4 +15,11 @@ Table 1 lists the various input files used in offline CABLE. A description of ea
 | Surface forcing        | information about the surface characteristics |
 | Restart                | information from a previous CABLE run to restart a simulation | 
 
+## Example configurations
+
+CABLE is used as a standalone model or in the ACCESS Earth System model. You can find example configurations for each of its applications at:
+
+- CABLE standalone: files under CABLE/src/offline
+- ACCESS-ESM1.5: ACCESS-NRI supported configurations at [access-esm1.5-configs repository][access-esm1.5-configs]
 
+[access-esm1.5-configs]: https://github.com/ACCESS-NRI/ACCESS-esm1.5-configs/

src/offline/cable.nml

@@ -54,6 +54,7 @@
    redistrb = .FALSE.  ! Turn on/off the hydraulic redistribution
    wiltParam = 0.5
    satuParam = 0.8
+   snmin = 1.0	
    cable_user%FWSOIL_SWITCH = 'standard'        ! choices are: 
                                                  ! 1. standard 
                                                  ! 2. non-linear extrapolation 

src/offline/cable_driver_common.F90

@@ -10,6 +10,7 @@ MODULE cable_driver_common_mod
     redistrb,                     &
     wiltParam,                    &
     satuParam,                    &
+    snmin,                        &
     cable_user,                   &
     gw_params,                    &
     cable_runtime
@@ -93,6 +94,7 @@ MODULE cable_driver_common_mod
     redistrb,       &
     wiltParam,      &
     satuParam,      &
+    snmin,          &
     cable_user,     & ! additional USER switches
     gw_params
 

src/util/cable_common.F90

@@ -26,6 +26,7 @@ MODULE cable_common_module
 USE cable_runtime_opts_mod ,ONLY : cable_user
 USE cable_runtime_opts_mod ,ONLY : satuparam
 USE cable_runtime_opts_mod ,ONLY : wiltparam
+USE cable_runtime_opts_mod ,ONLY : snmin
 
   IMPLICIT NONE
 
@@ -205,9 +206,6 @@ MODULE cable_common_module
   REAL, SAVE ::        &!should be able to change parameters!
        max_glacier_snowd=1100.0,&
        snow_ccnsw = 2.0, &
-                                !jh!an:clobber - effectively force single layer snow
-                                !snmin = 100.0,      & ! for 1-layer;
-       snmin = 1.,          & ! for 3-layer;
        max_ssdn = 750.0,    & !
        max_sconds = 2.51,   & !
        frozen_limit = 0.85    ! EAK Feb2011 (could be 0.95)

src/util/cable_runtime_opts_mod.F90

@@ -2,8 +2,11 @@ MODULE cable_runtime_opts_mod
 
 IMPLICIT NONE
 
-  ! hydraulic_redistribution parameters _soilsnow module
-REAL :: wiltParam = 0.0, satuParam = 0.0
+! hydraulic_redistribution parameters _soilsnow module
+REAL :: wiltParam = 0.0
+REAL :: satuParam = 0.0
+! depth at which to switch to 3 layer snow, default is ESM1.5 value
+REAL :: snmin = 1.0
 
 ! user switches turned on/off by the user thru namelists
 ! CABLE-2.0 user switches all in single namelist file cable.nml