PROGRAM `clm_to_dart`

Overview

clm_to_dart is used to replace indeterminate values in the CLM restart file with the _FillValue value specified by the variable attribute. This is necessary to ensure that all ensemble members have the proper _FillValue applied to any variable that may be part of the DART state. Only CLM restart files have variables that require this treatment.

clm_to_dart reads every variable in the input file and determines if the variable has snow layers by looking for a levtot or levsno dimension in the variable. The SNLSNO variable is used to detemine which layers are unused. However, when there is only a trace of snow, SNLSNO may indicate there are no snow layers in use and yet still have some valid values in the snow layer closest to the ground. This situation is confirmed by checking for non-zero values of snowcover fraction (frac_sno) as it seems to be a conservative predictor of the presence of snow. Therefore, in general, the indeterminate value for unused snow layer is preserved during the assimilation step, unless there is a trace of snow in which case it may be adjusted.

See the Discussion of Indeterminate Values section for an example.

Usage

The issue arises because all CLM columns have a fixed number of snow layers but only some of the layers may actually contain snow. CLM internally tracks the number of active snow layers in the SNLSNO variable and the indeterminate values in the unused snow layers are of no consequence. To prevent these indeterminate values from being operated on by filter, DART requires these indeterminate values to be replaced by the DART MISSING_R8 code, which is done automatically if the variable has a _FillValue.

clm_to_dart overwrites the input file. Consequently, the intended use is to copy the CLM restart file and feed the copy into clm_to_dart. This strategy allows the copies to be read into DART and updated with the posterior values. The companion PROGRAM dart_to_clm uses the _FillValue values as a mask to only update the original CLM restart file with valid posterior values. Where the DART posterior file has _FillValue values, the original CLM values are left unchanged.

The SNLSNO variable is required. Any file that does not have SNLSNO will be unchanged and the program will report the error and terminate. This is why only CLM restart files need the treatment. CLM history files do not have SNLSNO.

It is a useful exercise to dump the CLM restart file and the output of clm_to_dart and compare the results (for select variables). You have to use your own (low-resolution!) restart file.

cp T_SOISNO clm5_tag34.clm2.r.0003-01-01-00000.nc clm_restart.nc
ncdump -f F -v T_SOISNO clm_restart.nc > T_SOISNO_org.txt
./clm_to_dart
ncdump -f F -v T_SOISNO clm_restart.nc > T_SOISNO_new.txt
diff T_SOISNO_org.txt T_SOISNO_new.txt

Namelist

Namelists start with an ampersand ‘&’ and terminate with a slash ‘/’. Character strings that contain a ‘/’ must be enclosed in quotes to prevent them from prematurely terminating the namelist. These are the defaults:

&clm_to_dart_nml
  clm_restart_file  = 'clm_restart.nc'
  verbose           = 0
 /

Item	Type	Description
clm_restart_file	character(len=256)	Path name of the CLM restart file to be overwritten.
verbose	integer	Flag to control how much run-time output is created. 0 is very little output. 1 reports which variables are being updated. 2 reports all 2d variables with columns as one dimension. 3 reports all variables and columns which contain indeterminate values Warning, 3 can generate a lot of output.

Modules used

assimilation_code/modules/utilities/netcdf_utilities_mod.f90
assimilation_code/modules/utilities/null_mpi_utilities_mod.f90
assimilation_code/modules/utilities/time_manager_mod.f90
assimilation_code/modules/utilities/types_mod.f90
assimilation_code/modules/utilities/utilities_mod.f90

Files

clm_restart_file, specified by namelist;
namelistfile; input.nml

Discussion of Indeterminate Values

To explore the most robust way to replace the indeterminate values with the DART-required _FillValue, a low-resolution run (10 deg x 15 deg) was performed using the f10_f10_musgs tag on the release-clm5.0.34 branch. The clm_to_dart_nml verbosity was set to 3 and the clm_to_dart run-time output was captured and is summarized below. The output has been pruned to improve clarity and the column headers have been added. Only the output for the T_SOISNO variable is shown as it clearly illustrates the situation.

The frac_sno variable (snow cover fraction) is used to determine when there is a reliable trace amount of snow and the original values in the snow layer closest to the ground are left alone. This was determined to be a more useful indicator than H2OSNO, as demonstrated in the example below. Please note that if the frac_sno > 0 this indicates a trace of snow exists for that column/layer, and the indeterminate value for T_SOISNO is left alone. On the other hand, if frac_sno < 0 this indicates that particular column/layer is truly empty, and the indeterminate value will be overwritten with the _FillValue attribute value, such that DART will not adjust it.

Note

The program clm_to_dart identifies indeterminate values for any variable that contains snow layers. These variables are identified if they have dimensions such as column, levtot or levsno. These include variables related to water mass (e.g. H2OSOI_ICE, H2OSOI_LIQ), thickness (e.g. DZSNO, ZSNO, ZISNO) and other snow layer characteristics that influence albedo (e.g. Snw_rds, Mss_bcpho, Mss_dst1).

In the example below, the execution of clm_to_dart will overwrite the indeterminate values within the clm restart file with the _FillValue attribute value to prevent DART from performing an update to that value.

--------------------------------------
Starting ... at YYYY MM DD HH MM SS =
                2021  6 14 16 57  4
Program clm_to_dart
--------------------------------------

 set_nml_output Echo NML values to log file only
minval of SNLSNO is          -10
There are          520  variables in the file.
 inquire variable number          204 varname T_SOISNO dimensions are levtot column
 clm_to_dart  variable #          204  is "T_SOISNO" - replacing indeterminate values

VARIABLE  LEVEL  COLUMN   VALUE               H2OSNO                    frac_sno                  SNOW_DEPTH
T_SOISNO  12        488   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        503   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        522   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        523   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        524   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        525   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        526   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        527   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        528   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        533   273.04618842687802  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        538   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        574   272.77291836570703  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        601   271.54492290326198  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        603   271.54645412989498  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        607   271.57732177585501  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        628   272.98586559496499  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        762   272.45467200034398  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        763   271.34254388393202  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12        769   271.34932534583101  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2386   273.04040468859000  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2479   273.14991153505002  1.3694861766505699       0.11795998521670301        4.6284512959401197E-002
T_SOISNO  12       2760   273.08583001204897  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2761   273.04455346669300  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2762   272.91332916458902  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2763   273.12159885062198  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2768   272.89811384494902  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2769   273.04499957659402  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       2885   273.14979133425902  6.6918688785517395E-007   6.6918687813277700E-008  0.63344272495211695
T_SOISNO  12       2887   273.14964165253900  2.2492550993511499E-020   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2889   272.53294466428503  1.5189620271589999E-020   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2891   273.14945332076400  5.4222364686270699E-020   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2893   273.14980341715801  1.4201683058442200E-020   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2895   273.14999999999998  3.5526247972183701E-020   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2896   273.14999404812397  9.6873949694950192E-006   9.6873931487717592E-007  0.20872425049864601
T_SOISNO  12       2899   273.14970403389998  6.0580004576503196E-022   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2901   273.14957578176399  1.0670595573239900E-021   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2903   273.14947638500303  1.1110267474343600E-021   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2905   273.14935524945503  2.5542577505086200E-022   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2907   273.14958719516397  1.9081446552101299E-022   0.0000000000000000        0.0000000000000000
T_SOISNO  12       2997   273.14999999999998  0.53787417421960904       1.2912522851932499E-002   2.1771531678050301E-003
T_SOISNO  12       3146   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       3329   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       3409   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       3410   273.14999999999998  0.0000000000000000        0.0000000000000000        0.0000000000000000
T_SOISNO  12       3411   273.14999999999998  1.0623461506454501E-002   1.0618761027172401E-003  0.10534145620281500
T_SOISNO  12       3412   273.14999999999998  1.0717589342154700E-002   1.0712805155617101E-003  0.10527378255254000
T_SOISNO  12       3413   273.14999999999998  1.1963762509646500E-002   1.1957631326947600E-003  0.11023440903539100

--------------------------------------
Finished ... at YYYY MM DD HH MM SS =
                2021  6 14 16 57  4
Program clm_to_dart
--------------------------------------

References

none, but https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.html is very relevant.

PROGRAM clm_to_dart