QCEFF Table

[mjs2369]

Description:

This PR is a duplicate of #545 but with correctly revised git history.

The python script for converting from a YAML file to the table will be moved to a separate PR.

Previously the QCF code required an algorithm_info_mod specific to the model, which meant editing algorithm_info_mod.f90 to specify which distribution should be used for which quantity.

This code implements a QCF input table, which reads in the algorithm info choices (QCF options) at runtime and stores them in algorithm_info_mod module storage.

This replaces the former functionality of algorithm_info_mod if statements with the table information.

The observation, state, and inflation variables are read in from a single table. Each field keeps its own column, having 28 total in the table.

The full list of QCF input options and information of the structure of the table can be found in the documentation at DART/guide/qcf_table.rst

More info on the background of the issue can be read in the specification here: https://docs.google.com/document/d/1MnvEFfgj5SfFbnIahGHwjy1XJ5IWBvPS8NB1nrIjc8k/edit

Fixes issue

Fixes #503

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] Documentation update

Documentation changes needed?

• [x] My change requires a change to the documentation.
  • [x] I have updated the documentation accordingly.

While I have included new documentation on how to use the input table at DART/guide/qcf_table.rst , Jeff’s documentation at https://docs.dart.ucar.edu/en/quantile_methods/models/lorenz_96_tracer_advection/work/readme.html needs updated to reflect the difference in workflow for the tests listed, and in general the documentation for quantile methods should be highlighted and linked to on the main DART documentation page.

Tests

Compiled and ran filter with full debugging flags with Intel, CCE, gfortran Bitwise identical to quantile_methods, tested with Intel

Information on how to use the QCF input table with the quantile code is in the documentation at DART/guide/qcf_table.rst

build_everything now passes for all models:

RESULT: 0  models/null_model/work/ finished
RESULT: 1  models/POP/work/ finished
RESULT: 2  models/lorenz_63/work/ finished
RESULT: 3  models/9var/work/ finished
RESULT: 4  models/gitm/work/ finished
RESULT: 5  models/simple_advection/work/ finished
RESULT: 6  models/lorenz_96/work/ finished
RESULT: 7  models/ikeda/work/ finished
RESULT: 8  models/ROMS/work/ finished
RESULT: 9  models/lorenz_84/work/ finished
RESULT: 10 models/cam-fv/work/ finished
RESULT: 11  models/mpas_atm/work/ finished
RESULT: 12  models/forced_lorenz_96/work/ finished
RESULT: 13  models/wrf/work/ finished
RESULT: 14  models/cice/work/ finished
RESULT: 15  models/cm1/work/ finished
RESULT: 16  models/lorenz_04/work/ finished
RESULT: 17  models/bgrid_solo/work/ finished
RESULT: 18  models/noah/work/ finished
RESULT: 19  models/wrf_hydro/work/ finished
RESULT: 20  models/lorenz_96_2scale/work/ finished
RESULT: 21 observations/obs_converters/GOES/work/ failed
RESULT: 22  observations/obs_converters/tec/work/ finished
RESULT: 23  observations/obs_converters/GRACE/work/ finished
RESULT: 24  observations/obs_converters/CNOFS/work/ finished
RESULT: 25  observations/obs_converters/GPSPW/work/ finished
RESULT: 26  observations/obs_converters/SSEC/work/ finished
RESULT: 27  observations/obs_converters/text_GITM/work/ finished
RESULT: 28  observations/obs_converters/GTSPP/work/ finished
RESULT: 29 observations/obs_converters/gps/work/ failed
RESULT: 30  observations/obs_converters/GSI2DART/work/ finished
RESULT: 31  observations/obs_converters/SABER/work/ finished
RESULT: 32  observations/obs_converters/SIF/work/ finished
RESULT: 33  observations/obs_converters/WOD/work/ finished
RESULT: 34  observations/obs_converters/tpw/work/ finished
RESULT: 35  observations/obs_converters/ROMS/work/ finished
RESULT: 36  observations/obs_converters/COSMOS/work/ finished
RESULT: 37 observations/obs_converters/var/work/ failed
RESULT: 38  observations/obs_converters/tropical_cyclone/work/ finished
RESULT: 39  observations/obs_converters/CONAGUA/work/ finished
RESULT: 40  observations/obs_converters/Ameriflux/work/ finished
RESULT: 41  observations/obs_converters/CHAMP/work/ finished
RESULT: 42  observations/obs_converters/cice/work/ finished
RESULT: 43 observations/obs_converters/GMI/work/ failed
RESULT: 44  observations/obs_converters/DWL/work/ finished
RESULT: 45  observations/obs_converters/MIDAS/work/ finished
RESULT: 46  observations/obs_converters/USGS/work/ finished
RESULT: 47  observations/obs_converters/SST/work/ finished
RESULT: 48  observations/obs_converters/MPD/work/ finished
RESULT: 49  observations/obs_converters/even_sphere/work/ finished
RESULT: 50  observations/obs_converters/MODIS/work/ finished
RESULT: 51  observations/obs_converters/NCEP/prep_bufr/work/ finished
RESULT: 52  observations/obs_converters/NCEP/ascii_to_obs/work/ finished
RESULT: 53  observations/obs_converters/NCEP/netcdf/work/ finished
RESULT: 54  observations/obs_converters/gnd_gps_vtec/work/ finished
RESULT: 55  observations/obs_converters/SSUSI/work/ finished
RESULT: 56  observations/obs_converters/ok_mesonet/work/ finished
RESULT: 57  observations/obs_converters/snow/work/ finished
RESULT: 58  observations/obs_converters/text/work/ finished
RESULT: 59  observations/obs_converters/AURA/work/ finished
RESULT: 60  observations/obs_converters/radar/work/ finished
RESULT: 61  observations/obs_converters/MADIS/work/ finished
RESULT: 62 observations/obs_converters/quikscat/work/ failed
RESULT: 63 observations/obs_converters/AIRS/work/ failed
RESULT: 64  observations/obs_converters/AVISO/work/ finished

Checklist for merging

• [x] Updated changelog entry
• [x] Documentation updated
• [x] Update conf.py

Checklist for release

• [ ] Merge into main
• [ ] Create release from the main branch with appropriate tag
• [ ] Delete feature-branch

Testing Datasets

• [ ] Dataset needed for testing available upon request
• [ ] Dataset download instructions included
• [x] No dataset needed

[hkershaw-brown]

note to reviewers, the documentation build for this pull request is here: https://dart-documentation--553.org.readthedocs.build/en/553/

[mjs2369]

https://dart-documentation--553.org.readthedocs.build/en/553/assimilation_code/modules/assimilation/assim_tools_mod.html#description-of-each-namelist-entry:~:text=%EF%83%81-,filter_kind,-type%3A%20integer

I think filter_kind needs removed from the description of namelist items on the assim_tools_mod documentation page. There is information about using Jon Potterjoy's Particle Filter there, though, that I'm not sure should be removed or where it should be moved to.

[mjs2369]

@hkershaw-brown I just retested this with all of the new code changes, and it is bitwise with quantile_methods for both the intel and gfortran compilers

This was tested for all lorenz_96_tracer_advection examples (tests A-D). Note that for tests B and C, I had to update the algorithm_info_mod code slightly as it was out-of-date and would not compile. You can see the types of changes made in this screenshot, fixing the bounds and using _DISTRIBUTION instead of _PRIOR:

This was also tested with the lorenz_96 model for sort_obs_inc = .true. AND .false (ensuring that the sorting code is actually running by using filter_kind=ENKF)

[hkershaw-brown]

This was tested for all lorenz_96_tracer_advection examples (tests A-D). Note that for tests B and C, I had to update the algorithm_info_mod code slightly as it was out-of-date and would not compile.

@mjs2369 great thanks Marlee, can you go ahead and commit the changes to all_eakf_algorithm_info_mod and state_eakf_tracer_bnrhf_algorithm_info_mod to the quantile_methods branch. You should be able to push to that branch now.

[hkershaw-brown]

@hkershaw-brown

Todo:

• [x] rename qcf_table qceff table

• [x] test lower case options in qcf-table

  • [x] need to_upper

• [x] test header version with column descriptions

• [x] QCEFF paper 1 & 2

• [x] test perfect_model_obs with non-default qty options. Perfect_model_obs is not logging the qceff table.

• [x] perfect_model_obs remove use_algorithm_info_mod

• [x] doc: remove/update namelist options that have been removed/deprecated/improved

  • [x] sort_obs_inc default .true. only applied to ENKF
  • [x] spread_restoration - can not use
  • [x] filter_kind -removed from namelist https://github.com/NCAR/DART/blob/5583e397f562be4bf65057a819e39e7948242713/assimilation_code/modules/assimilation/assim_tools_mod.f90#L1032

• [x] cam-fv input.nml remove new_qcf_input.nml (old version now!)

• [x] defaults probit_transform

• [x] defaults filter_kind (eakf), dist_type (normal_distribution)

• [x] Jeff's edits to index.hml

  • [x] still one funky sentence.

[hkershaw-brown]

todo:

check if (.not. module_initialized) call init_algorithm_info_mod(qcf_table_filename)

perfect_model_obs and filter call algorithm info mod, but only filter calls initalize with the qcf_table_filename. Is perfect_model_obs always using the default values for every qty?

[mjs2369]

@hkershaw-brown retested with all changes - bitwise identical with quantile_methods for all four lorenz_96_tracer_advection examples

I did one final review as well for both the code and docs and I think it is ready to merge!