Add new capability for surface chemical DA

[liujake]

TYPE: new feature

KEYWORDS: Chemical DA, Surface Observations, 3DVar, GENBE_2.0

SOURCE: Wei Sun (NCAR/MMM, CAS), Jake Liu (NCAR/MMM), Dan Chen (IUM, Beijing)

DESCRIPTION OF CHANGES:

1. This PR adds the new capability for assimilating the surface chemical/aerosol observations (pm2.5, pm10, O3, NO2, SO2, CO) using 3DVar.

2. Several new namelist parameters are defined in registry.var_chem under wrfvarchem. The setting of chemicda_opt only works for MOSAIC scheme. The inflation factors of chemical background errors work for both aerosol schemes, but they are only tested under the MOSAIC scheme.

&wrfvarchem
chem_cv_options= 10/20: control variables are 4 gas + 15/32 GOCART/MOSAIC (4bin) aerosol variables

chemicda_opt=1/2/3/4/5 # assimilate pm2.5/pm10/pm2.5+pm10/co+o3+so2+no2/6-species

var_scaling12=36xmax_outer_iterations, # inflation factors of chemical background errors.

len_scaling12=36xmax_outer_iterations, # inflation factors of chemical background errors.

use_chemic_surfobs = .true., # read in ob_chemsfc.ascii
/

3. To compile 3DVar with chemical DA capability, set the environment variable "WRF_CHEM" as 1, then ./configure wrfda; compile all_wrfvar as usual. The executable remains da_wrfvar.exe.

4. The chemical background error file be.dat needs to be generated using GENBE_2.0 on https://github.com/wrf-model/GENBE_2.0.

LIST OF MODIFIED FILES:
A Registry/Registry.wrfchemvar
M Registry/registry.var_chem
M compile
M external/RSL_LITE/gen_comms.c
M frame/module_domain.F
M frame/module_driver_constants.F
M share/mediation_integrate.F
M share/output_wrf.F
M tools/gen_allocs.c
M var/build/da.make
M var/build/depend.txt
A var/da/da_chem_sfc/da_ao_stats_chem_sfc.inc
A var/da/da_chem_sfc/da_calculate_grady_chem_sfc.inc
A var/da/da_chem_sfc/da_check_max_iv_chem_sfc.inc
A var/da/da_chem_sfc/da_chem_sfc.f90
A var/da/da_chem_sfc/da_get_innov_vector_chem_sfc.inc
A var/da/da_chem_sfc/da_jo_and_grady_chem_sfc.inc
A var/da/da_chem_sfc/da_jo_chem_sfc.inc
A var/da/da_chem_sfc/da_oi_stats_chem_sfc.inc
A var/da/da_chem_sfc/da_print_stats_chem_sfc.inc
A var/da/da_chem_sfc/da_residual_chem_sfc.inc
A var/da/da_chem_sfc/da_transform_xtoy_chem_sfc.inc
A var/da/da_chem_sfc/da_transform_xtoy_chem_sfc_adj.inc
M var/da/da_control/da_control.f90
A var/da/da_define_structures/da_allocate_observations_chem_sfc.inc
A var/da/da_define_structures/da_allocate_y_chem_sfc.inc
M var/da/da_define_structures/da_deallocate_background_errors.inc
A var/da/da_define_structures/da_deallocate_y_chem_sfc.inc
M var/da/da_define_structures/da_define_structures.f90
A var/da/da_define_structures/da_zero_xchem_type.inc
M var/da/da_main/da_solve.inc
M var/da/da_main/da_solve_init.inc
M var/da/da_main/da_update_firstguess.inc
M var/da/da_main/da_wrfvar_init2.inc
M var/da/da_main/da_wrfvar_top.f90
M var/da/da_minimisation/da_amat_mul.inc
M var/da/da_minimisation/da_calculate_gradj.inc
M var/da/da_minimisation/da_calculate_grady.inc
M var/da/da_minimisation/da_calculate_j.inc
M var/da/da_minimisation/da_calculate_residual.inc
M var/da/da_minimisation/da_dot_cv.inc
M var/da/da_minimisation/da_get_innov_vector.inc
M var/da/da_minimisation/da_get_var_diagnostics.inc
M var/da/da_minimisation/da_jo_and_grady.inc
M var/da/da_minimisation/da_minimisation.f90
M var/da/da_minimisation/da_minimise_cg.inc
M var/da/da_minimisation/da_minimise_lz.inc
M var/da/da_minimisation/da_sensitivity.inc
M var/da/da_minimisation/da_transform_vtoy.inc
M var/da/da_minimisation/da_transform_vtoy_adj.inc
M var/da/da_minimisation/da_write_diagnostics.inc
A var/da/da_obs/da_fill_obs_structures_chem_sfc.inc
M var/da/da_obs/da_obs.f90
M var/da/da_obs/da_transform_xtoy.inc
M var/da/da_obs/da_transform_xtoy_adj.inc
A var/da/da_obs_io/da_final_write_obs_chem_sfc.inc
A var/da/da_obs_io/da_final_write_obs_gas_sfc.inc
M var/da/da_obs_io/da_obs_io.f90
A var/da/da_obs_io/da_read_obs_chem_sfc.inc
M var/da/da_obs_io/da_read_omb_tmp.inc
A var/da/da_obs_io/da_scan_obs_chem_sfc.inc
A var/da/da_obs_io/da_write_obs_chem_sfc.inc
M var/da/da_par_util/da_cv_to_vv.inc
M var/da/da_par_util/da_par_util.f90
M var/da/da_par_util/da_vv_to_cv.inc
M var/da/da_setup_structures/da_rescale_background_errors.inc
M var/da/da_setup_structures/da_scale_background_errors.inc
M var/da/da_setup_structures/da_setup_background_errors.inc
M var/da/da_setup_structures/da_setup_be_regional.inc
M var/da/da_setup_structures/da_setup_cv.inc
M var/da/da_setup_structures/da_setup_firstguess.inc
M var/da/da_setup_structures/da_setup_firstguess_wrf.inc
M var/da/da_setup_structures/da_setup_obs_structures.inc
A var/da/da_setup_structures/da_setup_obs_structures_chem_sfc.inc
M var/da/da_setup_structures/da_setup_structures.f90
M var/da/da_statistics/da_analysis_stats.inc
M var/da/da_statistics/da_statistics.f90
M var/da/da_test/da_check.inc
A var/da/da_test/da_check_cvtovv_adjoint_chem.inc
M var/da/da_test/da_check_gradient.inc
A var/da/da_test/da_check_vchemtox_adjoint.inc
A var/da/da_test/da_check_vtox_adjoint_chem.inc
M var/da/da_test/da_test.f90
M var/da/da_transfer_model/da_transfer_model.f90
A var/da/da_transfer_model/da_transfer_wrftoxb_chem.inc
M var/da/da_transfer_model/da_transfer_xatoanalysis.inc
M var/da/da_transfer_model/da_transfer_xatowrf.inc
A var/da/da_vtox_transforms/da_transform_vchemtox.inc
A var/da/da_vtox_transforms/da_transform_vchemtox_adj.inc
M var/da/da_vtox_transforms/da_transform_vtovv.inc
M var/da/da_vtox_transforms/da_transform_vtovv_adj.inc
M var/da/da_vtox_transforms/da_transform_vtox.inc
M var/da/da_vtox_transforms/da_transform_vtox_adj.inc
M var/da/da_vtox_transforms/da_vtox_transforms.f90

TESTS CONDUCTED:

1. WRFDA regression tests passed.
2. New chemical DA is tested with 6 types of surface obs and 4-bin MOSAIC aerosol scheme.

RELEASE NOTE: Add new capability for assimilating surface pm2.5, pm10, O3, CO, NO2, SO2 using 3DVar.
Sun, W., Liu, Z., Chen, D., Zhao, P., and Chen, M., 2020: Development and application of the WRFDA-Chem three-dimensional variational (3DVAR) system: aiming to improve air quality forecasting and diagnose model deficiencies, Atmos. Chem. Phys., 20, 9311-9329.

[liujake]

@davegill This PR should have no impact on model side, but you may like to take some quick look at a few files outside ~var/.
M compile
M external/RSL_LITE/gen_comms.c
M frame/module_domain.F
M frame/module_driver_constants.F
M share/mediation_integrate.F
M share/output_wrf.F
M tools/gen_allocs.c

[liujake]

@davegill Looks like jenkins autotest will be invoked every time when PR message is edited. This seems to be unnecessary. Is this the behavior by design?

[davegill]

@liujake
Jake,
A full regression test should not be undertaken for each unimportant change (modify the name of the PR, change a PR commit message, add a label, etc). There may be about 1 minute where github is checking with the various associated testing pieces, but it should come back fairly quickly for these types of unimportant modifications.