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
--------------------------------------