From b548bd761c2a36f7223cf055ac93612584f5f8c9 Mon Sep 17 00:00:00 2001 From: nancy Date: Fri, 26 Jan 2024 10:51:57 -0700 Subject: [PATCH 01/16] minor changes to support the wrf 3.9+ hybrid vertical coordinate test for the hybrid coordinate attribute, and if set, compute the vertical with the hybrid coordinate equation. this requires 2 additional arrays to be read, and written to the output files. this fix was originally contributed by anders jensen in 2019. --- models/wrf/model_mod.f90 | 72 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/models/wrf/model_mod.f90 b/models/wrf/model_mod.f90 index 8fc1592ca9..fc3e70ac87 100644 --- a/models/wrf/model_mod.f90 +++ b/models/wrf/model_mod.f90 @@ -284,6 +284,10 @@ module model_mod real (kind=r8), PARAMETER :: kappa = 2.0_r8/7.0_r8 ! gas_constant / cp real (kind=r8), PARAMETER :: ts0 = 300.0_r8 ! Base potential temperature for all levels. +! hybrid_opt 2 is a hybrid coordinate - terrain following at the +! surface, and straight pressure levels at the top. +integer, parameter :: VERT_HYBRID = 2 + !---- private data ---- ! Got rid of surf_var as global private variable for model_mod and just defined it locally @@ -309,7 +313,8 @@ module model_mod integer :: domain_size integer :: localization_coord - real(r8), dimension(:), pointer :: znu, dn, dnw, zs, znw + integer :: hybrid_opt + real(r8), dimension(:), pointer :: znu, dn, dnw, zs, znw, c1h, c2h real(r8), dimension(:,:), pointer :: mub, hgt real(r8), dimension(:,:), pointer :: latitude, latitude_u, latitude_v real(r8), dimension(:,:), pointer :: longitude, longitude_u, longitude_v @@ -4042,6 +4047,34 @@ subroutine nc_write_model_atts( ncid, id ) ''), & 'nc_write_model_atts','def_var DNW'//' units') +if (wrf%dom(dom_id)%hybrid_opt == VERT_HYBRID) then + call nc_check(nf90_def_var(ncid, name='C1H', xtype=nf90_real, & + dimids= btDimID, varid=C1HVarID), & + 'nc_write_model_atts','def_var C1H') + call nc_check(nf90_put_att(ncid, C1HVarID, 'long_name', & + 'dn values on full (w) levels'), & + 'nc_write_model_atts','def_var C1H'//' long_name') + call nc_check(nf90_put_att(ncid, C1HVarID, 'description', & + 'dn values on full (w) levels'), & + 'nc_write_model_atts','def_var C1H'//' description') + call nc_check(nf90_put_att(ncid, C1HVarID, 'units', & + ''), & + 'nc_write_model_atts','def_var C1H'//' units') + + call nc_check(nf90_def_var(ncid, name='C2H', xtype=nf90_real, & + dimids= btDimID, varid=C2HVarID), & + 'nc_write_model_atts','def_var C2H') + call nc_check(nf90_put_att(ncid, C2HVarID, 'long_name', & + 'dn values on full (w) levels'), & + 'nc_write_model_atts','def_var C2H'//' long_name') + call nc_check(nf90_put_att(ncid, C2HVarID, 'description', & + 'dn values on full (w) levels'), & + 'nc_write_model_atts','def_var C2H'//' description') + call nc_check(nf90_put_att(ncid, C2HVarID, 'units', & + ''), & + 'nc_write_model_atts','def_var C2H'//' units') +endif + ! ! float MUB(Time, south_north, west_east) ; ! MUB:FieldType = 104 ; @@ -4307,6 +4340,12 @@ subroutine nc_write_model_atts( ncid, id ) 'nc_write_model_atts','put_var znw') call nc_check(nf90_put_var(ncid, DNWVarID, wrf%dom(id)%dnw), & 'nc_write_model_atts','put_var dnw') +if (wrf%dom(id)%hybrid_opt == VERT_HYBRID) then + call nc_check(nf90_put_var(ncid, C1HVarID, wrf%dom(id)%c1h), & + 'nc_write_model_atts','put_var c1h') + call nc_check(nf90_put_var(ncid, C2HVarID, wrf%dom(id)%c2h), & + 'nc_write_model_atts','put_var c2h') +endif ! defining horizontal call nc_check(nf90_put_var(ncid, mubVarID, wrf%dom(id)%mub), & @@ -5276,7 +5315,12 @@ function model_rho_t_distrib(i,j,k,id,state_handle, ens_size) ! now calculate rho = - mu / dphi/deta -model_rho_t_distrib(:) = - (wrf%dom(id)%mub(i,j)+x_imu) / ph_e +if (wrf%dom(id)%hybrid_opt == VERT_HYBRID) then + model_rho_t_distrib(:) = - (wrf%dom(id)%c1h(k)*wrf%dom(id)%mub(i,j)+wrf%dom(id)%c2h(k) + & + wrf%dom(id)%c1h(k)*x_imu) / ph_e +else + model_rho_t_distrib(:) = - (wrf%dom(id)%mub(i,j)+x_imu) / ph_e +endif end function model_rho_t_distrib @@ -7044,6 +7088,7 @@ subroutine read_wrf_file_attributes(ncid,id) integer, intent(in) :: ncid, id logical, parameter :: debug = .false. +integer :: ret ! get meta data and static data we need @@ -7082,6 +7127,13 @@ subroutine read_wrf_file_attributes(ncid,id) 'static_init_model', 'get_att STAND_LON') if(debug) write(*,*) ' stdlon is ',stdlon + ! this attribute is not present in older wrf files, which means it is not + ! using a hybrid vertical coordinate. not having this attribute should + ! not cause an error. + ret = nf90_get_att(ncid, nf90_global, 'HYBRID_OPT', wrf%dom(id)%hybrid_opt) + if (ret /= NF90_NOERR) wrf%dom(id)%hybrid_opt = 0 + if(debug) write(*,*) 'hybrid_opt is ', wrf%dom(id)%hybrid_opt + RETURN end subroutine read_wrf_file_attributes @@ -7176,6 +7228,22 @@ subroutine read_wrf_static_data(ncid,id) 'read_wrf_static_data','get_var DNW') if(debug) write(*,*) ' dnw is ',wrf%dom(id)%dnw + if (wrf%dom(id)%hybrid_opt == VERT_HYBRID) then + allocate(wrf%dom(id)%c1h(1:wrf%dom(id)%bt)) + call nc_check( nf90_inq_varid(ncid, "C1H", var_id), & + 'read_wrf_static_data','inq_varid C1H') + call nc_check( nf90_get_var(ncid, var_id, wrf%dom(id)%c1h), & + 'read_wrf_static_data','get_var C1H') + if(debug) write(*,*) ' c1h is ',wrf%dom(id)%c1h + + allocate(wrf%dom(id)%c2h(1:wrf%dom(id)%bt)) + call nc_check( nf90_inq_varid(ncid, "C2H", var_id), & + 'read_wrf_static_data','inq_varid C2H') + call nc_check( nf90_get_var(ncid, var_id, wrf%dom(id)%c2h), & + 'read_wrf_static_data','get_var C2H') + if(debug) write(*,*) ' c2h is ',wrf%dom(id)%c2h + endif + allocate(wrf%dom(id)%zs(1:wrf%dom(id)%sls)) call nc_check( nf90_inq_varid(ncid, "ZS", var_id), & 'read_wrf_static_data','inq_varid ZS') From fab79afea66a54ce754bffdb8b45db4037115f51 Mon Sep 17 00:00:00 2001 From: nancy Date: Fri, 26 Jan 2024 11:09:25 -0700 Subject: [PATCH 02/16] add missing netcdf id vars and fix name of domain id in routine. --- models/wrf/model_mod.f90 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/models/wrf/model_mod.f90 b/models/wrf/model_mod.f90 index fc3e70ac87..cdef2f0454 100644 --- a/models/wrf/model_mod.f90 +++ b/models/wrf/model_mod.f90 @@ -3771,7 +3771,7 @@ subroutine nc_write_model_atts( ncid, id ) integer :: DNVarID, ZNUVarID, DNWVarID, phbVarID, & MubVarID, LonVarID, LatVarID, ilevVarID, XlandVarID, hgtVarID , LatuVarID, & - LatvVarID, LonuVarID, LonvVarID, ZNWVarID + LatvVarID, LonuVarID, LonvVarID, ZNWVarID, C1HVarID, C2HVarID integer :: TimeDimID @@ -4047,7 +4047,7 @@ subroutine nc_write_model_atts( ncid, id ) ''), & 'nc_write_model_atts','def_var DNW'//' units') -if (wrf%dom(dom_id)%hybrid_opt == VERT_HYBRID) then +if (wrf%dom(id)%hybrid_opt == VERT_HYBRID) then call nc_check(nf90_def_var(ncid, name='C1H', xtype=nf90_real, & dimids= btDimID, varid=C1HVarID), & 'nc_write_model_atts','def_var C1H') From 619f3e023863f9db5c9118bc8e07ec1b9d0063ce Mon Sep 17 00:00:00 2001 From: braczka Date: Mon, 4 Mar 2024 13:55:36 -0700 Subject: [PATCH 03/16] Simplify model_rho_t expression --- models/wrf/model_mod.f90 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/models/wrf/model_mod.f90 b/models/wrf/model_mod.f90 index cdef2f0454..e994cdae83 100644 --- a/models/wrf/model_mod.f90 +++ b/models/wrf/model_mod.f90 @@ -5316,8 +5316,7 @@ function model_rho_t_distrib(i,j,k,id,state_handle, ens_size) ! now calculate rho = - mu / dphi/deta if (wrf%dom(id)%hybrid_opt == VERT_HYBRID) then - model_rho_t_distrib(:) = - (wrf%dom(id)%c1h(k)*wrf%dom(id)%mub(i,j)+wrf%dom(id)%c2h(k) + & - wrf%dom(id)%c1h(k)*x_imu) / ph_e + model_rho_t_distrib(:) = - (wrf%dom(id)%c1h(k)*(wrf%dom(id)%mub(i,j)+x_imu) + wrf%dom(id)%c2h(k)) / ph_e else model_rho_t_distrib(:) = - (wrf%dom(id)%mub(i,j)+x_imu) / ph_e endif From 94a74346d486d1cf3d4a4193b4cfce6706d4c88b Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Tue, 12 Mar 2024 19:26:29 -0600 Subject: [PATCH 04/16] Basic updates to obs_impact_tool docs --- .../programs/obs_impact_tool/obs_impact_tool.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 5299da8916..13cbda8607 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -136,7 +136,20 @@ namelist. | debug | logical | If true print out debugging info. | +-----------------+--------------------+-----------------------------------------------------------------------------+ -| +| + +Filter Use +-------- +The following namelist options are required to use the obs_impact_tool code during the filter because ''obs_impact_tool'' is used to create the ''control_impact_runtime.txt'' file. + +:: + + &assim_tools_nml + adjust_obs_impact = .true. + obs_impact_filename = 'control_impact_runtime.txt' + / + +| Examples -------- From 3c8ef27312723a0c5cdcb07313d8787991905e6d Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Wed, 13 Mar 2024 10:58:30 -0600 Subject: [PATCH 05/16] Added table with namelist options to specify for filter and fixed typo. --- .../modules/assimilation/assim_tools_mod.rst | 2 +- .../obs_impact_tool/obs_impact_tool.rst | 19 ++++++++++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/assimilation_code/modules/assimilation/assim_tools_mod.rst b/assimilation_code/modules/assimilation/assim_tools_mod.rst index 502e2419de..f392f69f2a 100644 --- a/assimilation_code/modules/assimilation/assim_tools_mod.rst +++ b/assimilation_code/modules/assimilation/assim_tools_mod.rst @@ -289,7 +289,7 @@ Description of each namelist entry *type:* character(len=256) If adjust_obs_impact is true, the name of the file with the observation types and quantities and state quantities - that should have have an additional factor applied to the correlations during assimilation. + that should have an additional factor applied to the correlations during assimilation. ``allow_any_impact_values`` *type:* logical diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 13cbda8607..4563620340 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -140,7 +140,7 @@ namelist. Filter Use -------- -The following namelist options are required to use the obs_impact_tool code during the filter because ''obs_impact_tool'' is used to create the ''control_impact_runtime.txt'' file. +To use the ``obs_impact_tool`` code during the filter, the following namelist options are required because ``obs_impact_tool`` is used to create the ``control_impact_runtime.txt`` file as specified above. :: @@ -151,6 +151,23 @@ The following namelist options are required to use the obs_impact_tool code duri | +.. container:: + + +-------------------+--------------------+-----------------------------------------------------------------------------+ + | Item | Type | Description | + +===================+====================+=============================================================================+ + | adjust_obs_impact | logical | Name of an ascii text file which describes how the interaction of | + | | | observations to state vector values and observations to other observations | + | | | should be controlled. See the Overview section for details about the format | + | | | of the input file entries. | + +-------------------+--------------------+-----------------------------------------------------------------------------+ + |obs_impact_filename| character(len=512) | If adjust_obs_impact is true, the name of the file with the observation | + | | | types and quantities and state quantities that should have an additional | + | | | factor applied to the correlations during assimilation. | + +-------------------+--------------------+-----------------------------------------------------------------------------+ + +| + Examples -------- From 39c2207e0368189b69802d372385cf6dfb58ca6a Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Wed, 13 Mar 2024 13:05:58 -0600 Subject: [PATCH 06/16] Added building section to docs. --- .../programs/obs_impact_tool/obs_impact_tool.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 4563620340..4a4f1a7675 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -30,14 +30,6 @@ between 0 and 1 to be specified. This tool allows related collections of observation types and state vector quantities to be named and then express the relationship of the named groups to each other in a concise way. It can also define relationships by exceptions. -All the listed observation types and state vector quantities must be known by the system. -If they are not, look at the -&preprocess_nml :: input_items namelist which specifies which *obs_def_xxx_mod.f90* files -are included, which is where observation types are defined. -Quantities for different regimes (atmosphere, ocean, land, etc.) are defined in -``assimilation_code/modules/observations/xxx_quantities_mod.f90`` and explained in -:doc:`../../modules/observations/obs_kind_mod` - Format of the input file can be any combination of these types of sections: .. container:: @@ -168,6 +160,12 @@ To use the ``obs_impact_tool`` code during the filter, the following namelist op | +Building +-------- +In the quickbuild.sh script, add ``obs_impact_tool`` to the list of serial_programs. + +All the listed observation types and state vector quantities must be known by the system. If they are not, look at the &preprocess_nml :: input_items namelist which specifies which *obs_def_xxx_mod.f90* files are included, which is where observation types are defined. Quantities for different regimes (atmosphere, ocean, land, etc.) are defined in ``assimilation_code/modules/observations/xxx_quantities_mod.f90`` and explained in :doc:`../../modules/observations/obs_kind_mod` + Examples -------- From d32dd767cf9ea7bf13bf72dcce0bc4f5fc99fa50 Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Wed, 13 Mar 2024 18:20:27 -0400 Subject: [PATCH 07/16] Update obs_impact_tool.rst wording Co-authored-by: nancy collins --- assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 4a4f1a7675..4385d47e24 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -132,7 +132,7 @@ namelist. Filter Use -------- -To use the ``obs_impact_tool`` code during the filter, the following namelist options are required because ``obs_impact_tool`` is used to create the ``control_impact_runtime.txt`` file as specified above. +To use the output file from the ``obs_impact_tool`` during the run of filter, the following namelist options are required because ``obs_impact_tool`` is used to create the ``control_impact_runtime.txt`` file as specified above. :: From 452554a10af54bfea490ec85b67af3097e7292c1 Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Sun, 17 Mar 2024 17:16:22 -0600 Subject: [PATCH 08/16] Updates with specifics on how to use the code. --- .../obs_impact_tool/obs_impact_tool.rst | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 4385d47e24..360c1002b3 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -30,7 +30,13 @@ between 0 and 1 to be specified. This tool allows related collections of observation types and state vector quantities to be named and then express the relationship of the named groups to each other in a concise way. It can also define relationships by exceptions. -Format of the input file can be any combination of these types of sections: +Building +-------- +Begin by building ``obs_impact_tool`` by adding ``obs_impact_tool`` to the list of serial_programs in the quickbuild.sh script. + +All the listed observation types and state vector quantities must be known by the system. If they are not, look at the &preprocess_nml :: input_items namelist which specifies which *obs_def_xxx_mod.f90* files are included, which is where observation types are defined. Quantities for different regimes (atmosphere, ocean, land, etc.) are defined in ``assimilation_code/modules/observations/xxx_quantities_mod.f90`` and explained in :doc:`../../modules/observations/obs_kind_mod` + +Next, you should create an input file, ``cross_correlations.txt``, where you define the impacts of specific observations. The format of the input file can be any combination of these types of sections: .. container:: @@ -93,6 +99,10 @@ Format of the input file can be any combination of these types of sections: Namelist interface ``&obs_impact_tool_nml`` must be read from file ``input.nml``. +Then, you should run the ``obs_impact_tool`` with the input file ``cross_correlations.txt`` to create an output file ``control_impact_runtime.txt``. For specific formatting, refer to the details in the Namelist subsection. + +After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. Specific syntax is provided in the Filter Use subsection. + Namelist -------- @@ -160,16 +170,10 @@ To use the output file from the ``obs_impact_tool`` during the run of filter, th | -Building --------- -In the quickbuild.sh script, add ``obs_impact_tool`` to the list of serial_programs. - -All the listed observation types and state vector quantities must be known by the system. If they are not, look at the &preprocess_nml :: input_items namelist which specifies which *obs_def_xxx_mod.f90* files are included, which is where observation types are defined. Quantities for different regimes (atmosphere, ocean, land, etc.) are defined in ``assimilation_code/modules/observations/xxx_quantities_mod.f90`` and explained in :doc:`../../modules/observations/obs_kind_mod` - Examples -------- -To prevent chemistry species from impacting the meterological variables in the model state, and vice versa: +The following is an example of an input file to prevent chemistry species from impacting the meterological variables in the model state, and vice versa: .. container:: From a8330053a6d0d03ccd13ac8cd1600832d7b10854 Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Tue, 19 Mar 2024 11:00:23 -0600 Subject: [PATCH 09/16] Tighten up docs, remove filter use and last section --- .../obs_impact_tool/obs_impact_tool.rst | 62 +++---------------- 1 file changed, 10 insertions(+), 52 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 360c1002b3..96e66027ad 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -101,7 +101,15 @@ Namelist interface ``&obs_impact_tool_nml`` must be read from file ``input.nml`` Then, you should run the ``obs_impact_tool`` with the input file ``cross_correlations.txt`` to create an output file ``control_impact_runtime.txt``. For specific formatting, refer to the details in the Namelist subsection. -After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. Specific syntax is provided in the Filter Use subsection. +After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. +:: + + &assim_tools_nml + adjust_obs_impact = .true. + obs_impact_filename = 'control_impact_runtime.txt' + / + +| Namelist -------- @@ -140,36 +148,6 @@ namelist. | -Filter Use --------- -To use the output file from the ``obs_impact_tool`` during the run of filter, the following namelist options are required because ``obs_impact_tool`` is used to create the ``control_impact_runtime.txt`` file as specified above. - -:: - - &assim_tools_nml - adjust_obs_impact = .true. - obs_impact_filename = 'control_impact_runtime.txt' - / - -| - -.. container:: - - +-------------------+--------------------+-----------------------------------------------------------------------------+ - | Item | Type | Description | - +===================+====================+=============================================================================+ - | adjust_obs_impact | logical | Name of an ascii text file which describes how the interaction of | - | | | observations to state vector values and observations to other observations | - | | | should be controlled. See the Overview section for details about the format | - | | | of the input file entries. | - +-------------------+--------------------+-----------------------------------------------------------------------------+ - |obs_impact_filename| character(len=512) | If adjust_obs_impact is true, the name of the file with the observation | - | | | types and quantities and state quantities that should have an additional | - | | | factor applied to the correlations during assimilation. | - +-------------------+--------------------+-----------------------------------------------------------------------------+ - -| - Examples -------- @@ -190,24 +168,4 @@ The following is an example of an input file to prevent chemistry species from i IMPACT chem met 0.0 met chem 0.0 - END IMPACT - -Modules used ------------- - -:: - - types_mod - utilities_mod - parse_args_mod - -Files ------ - -- two text files, one input and one output. -- obs_impact_tool.nml - -References ----------- - -- none + END IMPACT \ No newline at end of file From c303bb098f3d8f86a82af4421740de457f5b3121 Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Tue, 19 Mar 2024 11:05:10 -0600 Subject: [PATCH 10/16] Tighten up overview --- .../obs_impact_tool/obs_impact_tool.rst | 28 ++++++++----------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 96e66027ad..4553243cf0 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -4,27 +4,23 @@ PROGRAM ``obs_impact_tool`` Overview -------- -The standard DART algorithms compute increments for an observation and then compute corresponding increments for each +Standard DART algorithms compute increments for an observation then compute corresponding increments for each model state variable due to that observation. To do this, DART computes a sample regression coefficient using the prior ensemble distributions of a state variable and the observation. The increments for each member of the observation are -multiplied by this regression coefficient and then added to the corresponding prior ensemble member for the state -variable. However, in many cases, it is appropriate to reduce the impact of an observation on a state variable; this is -called localization. The standard DART algorithms allow users to specify a localization that is a function of the +multiplied by this regression coefficient and added to the corresponding prior ensemble member for the state +variable. However, it may be appropriate to use localization, to reduce the impact of an observation on a state variable. +The standard DART algorithms allow users to specify a localization that is a function of the horizontal (and optionally vertical) distance between the observation and the state variable. The localization is a value between 0 and 1 and multiplies the regression coefficient when updating state ensemble members. +You may also want to do an additional localization that is a function of the type of observation and the state vector quantity. -Sometimes, it may be desirable to do an additional localization that is a function of the -type of observation and the -state vector quantity. This program allows users to construct a table that is read by -filter at run-time to localize the -impact of sets of observation types on sets of state vector quantities. Users can create -named sets of observation types -and sets of state vector quantities and specify a localization for the impact of the -specified observation types on the state vector quantities. - -An example would be to create a subset of observations of tracer concentration for a variety of tracers, and a subset of -dynamic state variable quantities like temperatures and wind components. It has been common to set this localization -value to 0 so that tracer observations have no impact on dynamic state quantities, however, the tool allows values +This program allows users to construct a table that is read by filter at run-time to localize the impact of sets of observation +types on sets of state vector quantities. Users can create named sets of observation types and sets of state vector quantities +and specify a localization for the impact of the specified observation types on the state vector quantities. + +An example would be to create a subset of observations of tracer concentration for a variety of tracers and a subset of +dynamic state variable quantities like temperatures and wind components. It is common to set this localization +value to 0 so that tracer observations have no impact on dynamic state quantities; however, the tool allows values between 0 and 1 to be specified. This tool allows related collections of observation types and state vector quantities to be named and then express the From 6f59ba61b14659da6351ec90ac67daa57f0fc97b Mon Sep 17 00:00:00 2001 From: Charlotte Merchant Date: Tue, 19 Mar 2024 11:10:40 -0600 Subject: [PATCH 11/16] Add anchors --- .../programs/obs_impact_tool/obs_impact_tool.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 4553243cf0..7f1eb16b09 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -95,9 +95,9 @@ Next, you should create an input file, ``cross_correlations.txt``, where you def Namelist interface ``&obs_impact_tool_nml`` must be read from file ``input.nml``. -Then, you should run the ``obs_impact_tool`` with the input file ``cross_correlations.txt`` to create an output file ``control_impact_runtime.txt``. For specific formatting, refer to the details in the Namelist subsection. +Then, you should run the ``obs_impact_tool`` with the input file ``cross_correlations.txt`` to create an output file ``control_impact_runtime.txt``. For specific formatting, refer to the details in the `Namelist`_ subsection. -After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. +After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. Descriptions of these fields are available at :doc:`../../modules/assimilation/assim_tools_mod`. :: &assim_tools_nml From 4f7b09467abc075ba9cd1ad272ce039eb204ff49 Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Mon, 8 Apr 2024 09:14:09 -0400 Subject: [PATCH 12/16] citation change NCAR to NSF NCAR --- CITATION.cff | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index 08550c7e99..3561dc2bf0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -5,5 +5,5 @@ version: "X.Y.Z" date-released: "2024-03-13" doi: "10.5065/D6WQ0202" authors: - - name: "UCAR/NCAR/CISL/DAReS" + - name: "UCAR/NSF NCAR/CISL/DAReS" city: "Boulder, Colorado" diff --git a/README.md b/README.md index 2cbcd209f6..7dc94b41c6 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ git clone https://github.com/NCAR/DART.git To cite DART, please use the following text: -> The Data Assimilation Research Testbed (Version X.Y.Z) [Software]. (2021). Boulder, Colorado: UCAR/NCAR/CISL/DAReS. +> The Data Assimilation Research Testbed (Version X.Y.Z) [Software]. (2021). Boulder, Colorado: UCAR/NSF NCAR/CISL/DAReS. > http://doi.org/10.5065/D6WQ0202 and update the DART version and year as appropriate. From 643d7d8f384e533be4215a7e9f6bbf348fd78367 Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Mon, 22 Apr 2024 14:08:59 -0400 Subject: [PATCH 13/16] ncar to nsf ncar adressing comment https://github.com/NCAR/DART/pull/663#issuecomment-2070350828 --- index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.rst b/index.rst index d0f3490564..a3dcbd6d5c 100644 --- a/index.rst +++ b/index.rst @@ -246,8 +246,8 @@ Citing DART Cite DART using the following text: - The Data Assimilation Research Testbed (Version X.Y.Z) [Software]. (2019). - Boulder, Colorado: UCAR/NCAR/CISL/DAReS. http://doi.org/10.5065/D6WQ0202 + The Data Assimilation Research Testbed (Version X.Y.Z) [Software]. (2024). + Boulder, Colorado: UCAR/NSF NCAR/CISL/DAReS. http://doi.org/10.5065/D6WQ0202 Update the DART version and year as appropriate. From f02e628f3678d634c9e6607dbc0fc463e52dea8d Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Mon, 22 Apr 2024 16:12:48 -0400 Subject: [PATCH 14/16] step by step instructions for obs_impact_tool following google documentation style guide(ish) --- .../modules/assimilation/assim_tools_mod.rst | 2 + .../obs_impact_tool/obs_impact_tool.rst | 122 +++++++++--------- 2 files changed, 60 insertions(+), 64 deletions(-) diff --git a/assimilation_code/modules/assimilation/assim_tools_mod.rst b/assimilation_code/modules/assimilation/assim_tools_mod.rst index f392f69f2a..daac0cac12 100644 --- a/assimilation_code/modules/assimilation/assim_tools_mod.rst +++ b/assimilation_code/modules/assimilation/assim_tools_mod.rst @@ -1,3 +1,5 @@ +.. _assim_tools: + MODULE assim_tools_mod ====================== diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index 7f1eb16b09..f081a4197e 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -4,41 +4,33 @@ PROGRAM ``obs_impact_tool`` Overview -------- -Standard DART algorithms compute increments for an observation then compute corresponding increments for each -model state variable due to that observation. To do this, DART computes a sample regression coefficient using the prior -ensemble distributions of a state variable and the observation. The increments for each member of the observation are -multiplied by this regression coefficient and added to the corresponding prior ensemble member for the state -variable. However, it may be appropriate to use localization, to reduce the impact of an observation on a state variable. -The standard DART algorithms allow users to specify a localization that is a function of the -horizontal (and optionally vertical) distance between the observation and the state variable. The localization is a -value between 0 and 1 and multiplies the regression coefficient when updating state ensemble members. -You may also want to do an additional localization that is a function of the type of observation and the state vector quantity. - -This program allows users to construct a table that is read by filter at run-time to localize the impact of sets of observation -types on sets of state vector quantities. Users can create named sets of observation types and sets of state vector quantities -and specify a localization for the impact of the specified observation types on the state vector quantities. - -An example would be to create a subset of observations of tracer concentration for a variety of tracers and a subset of -dynamic state variable quantities like temperatures and wind components. It is common to set this localization -value to 0 so that tracer observations have no impact on dynamic state quantities; however, the tool allows values -between 0 and 1 to be specified. - -This tool allows related collections of observation types and state vector quantities to be named and then express the -relationship of the named groups to each other in a concise way. It can also define relationships by exceptions. - -Building --------- -Begin by building ``obs_impact_tool`` by adding ``obs_impact_tool`` to the list of serial_programs in the quickbuild.sh script. +The standard DART algorithms work by calculating increments for an observation and then determining corresponding +increments for each variable in the state due to that observation. This is done by computing a sample regression +coefficient using the prior ensemble distributions of a state variable and the observation. The increments for each member +of the ensemble are multiplied by this coefficient and then added to the corresponding prior ensemble member for the variable. -All the listed observation types and state vector quantities must be known by the system. If they are not, look at the &preprocess_nml :: input_items namelist which specifies which *obs_def_xxx_mod.f90* files are included, which is where observation types are defined. Quantities for different regimes (atmosphere, ocean, land, etc.) are defined in ``assimilation_code/modules/observations/xxx_quantities_mod.f90`` and explained in :doc:`../../modules/observations/obs_kind_mod` +However, in many cases it is necessary to limit the influence of an observation on a variable; this is known as localization. +DART provides a way to specify a localization, known as cutoff, based on the horizontal and vertical distance between the observation +and the variable. -Next, you should create an input file, ``cross_correlations.txt``, where you define the impacts of specific observations. The format of the input file can be any combination of these types of sections: +In some situations, you may want additional localization based on the type of observation and the state quanity. +``obs_impact_tool`` allows users to create a table that filter reads during runtime to localize the impact of certain types of +observations on specific state vector quantities. Users can define sets of observation types and state vector quantities, and +specify localization for the impact of those observation types on the state vector quantities. -.. container:: +For example, you can create a subset of observations related to tracer concentration for various tracers, and a subset of +dynamic state variables like temperatures and wind components. Typically, it is common practice to set this localization value +to 0 to prevent tracer observations from affecting dynamic state quantities. However, ``obs_impact_tool`` allows you to specify values +between 0 and 1. - :: +#. Build ``obs_sequence_tool`` by adding ``obs_impact_tool`` to the list of serial_programs in the quickbuild.sh script for the model you are using. + Run ./quickbuild.sh to build all the DART programs. +#. Create an input file for ``obs_sequence_tool`` to define the impacts of observations. In the examples on this page, the input file + is called `cross_correlations.txt`. + The format of the input file can be any combination of the following types of sections: + .. code:: bash # hash mark starts a comment. @@ -93,22 +85,48 @@ Next, you should create an input file, ``cross_correlations.txt``, where you def groupname1 groupname1 0.0 END IMPACT -Namelist interface ``&obs_impact_tool_nml`` must be read from file ``input.nml``. + The following is an example of an input file to prevent chemistry species from impacting the meterological variables in the model state, and vice versa: -Then, you should run the ``obs_impact_tool`` with the input file ``cross_correlations.txt`` to create an output file ``control_impact_runtime.txt``. For specific formatting, refer to the details in the `Namelist`_ subsection. + .. code:: bash -After you have the output file to control the impact of observations on state vector items and other observation values, you can use this in your assimilation at filter run time by setting the ``obs_impact_filename`` field in ``assim_tools_nml`` to the name of your output file. Descriptions of these fields are available at :doc:`../../modules/assimilation/assim_tools_mod`. -:: + GROUP chem + QTY_CO QTY_NO QTY_C2H4 + END GROUP - &assim_tools_nml - adjust_obs_impact = .true. - obs_impact_filename = 'control_impact_runtime.txt' - / + GROUP met + ALLQTYS EXCEPT chem + END GROUP -| + IMPACT + chem met 0.0 + met chem 0.0 + END IMPACT -Namelist --------- + +#. Run ``obs_impact_tool`` using your `cross_correlations.txt` as input. ``obs_impact_tool`` will create an output file, + named `control_impact_runtime.txt` in this example. + + .. code:: text + + &obs_impact_tool_nml + input_filename = 'cross_correlations.txt' + output_filename = 'control_impact_runtime.txt' + / + + +#. Set the following namelist options in :ref:`&assim_tools_nml` to use `control_impact_runtime.txt` in filter. + Filter will apply your selected observation impacts during assimilation. + + .. code:: text + + &assim_tools_nml + adjust_obs_impact = .true. + obs_impact_filename = 'control_impact_runtime.txt' + / + + +obs_impact_tool Namelist +------------------------ This namelist is read from the file ``input.nml``. 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 @@ -141,27 +159,3 @@ namelist. +-----------------+--------------------+-----------------------------------------------------------------------------+ | debug | logical | If true print out debugging info. | +-----------------+--------------------+-----------------------------------------------------------------------------+ - -| - -Examples --------- - -The following is an example of an input file to prevent chemistry species from impacting the meterological variables in the model state, and vice versa: - -.. container:: - - :: - - GROUP chem - QTY_CO QTY_NO QTY_C2H4 - END GROUP - - GROUP met - ALLQTYS EXCEPT chem - END GROUP - - IMPACT - chem met 0.0 - met chem 0.0 - END IMPACT \ No newline at end of file From 1ba4106c18036416abf4a12e4e9f6838ac776cb5 Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Mon, 22 Apr 2024 16:17:18 -0400 Subject: [PATCH 15/16] change 'users' to you and clarify state variable --- .../programs/obs_impact_tool/obs_impact_tool.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst index f081a4197e..d84cd53f14 100644 --- a/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst +++ b/assimilation_code/programs/obs_impact_tool/obs_impact_tool.rst @@ -11,11 +11,11 @@ of the ensemble are multiplied by this coefficient and then added to the corresp However, in many cases it is necessary to limit the influence of an observation on a variable; this is known as localization. DART provides a way to specify a localization, known as cutoff, based on the horizontal and vertical distance between the observation -and the variable. +and the state variable. In some situations, you may want additional localization based on the type of observation and the state quanity. -``obs_impact_tool`` allows users to create a table that filter reads during runtime to localize the impact of certain types of -observations on specific state vector quantities. Users can define sets of observation types and state vector quantities, and +``obs_impact_tool`` allows you to create a table that filter reads during runtime to localize the impact of certain types of +observations on specific state vector quantities. You can define sets of observation types and state vector quantities, and specify localization for the impact of those observation types on the state vector quantities. For example, you can create a subset of observations related to tracer concentration for various tracers, and a subset of From 38cc779b8eac9d8c79d93c9627b94962469dda39 Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Tue, 23 Apr 2024 10:14:37 -0400 Subject: [PATCH 16/16] bump version and CHANGELOG for release Fixed formatting on v11.4.0 changelog --- CHANGELOG.rst | 12 +++++++++++- conf.py | 2 +- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 9fa8f5d357..43676cd8fc 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -22,22 +22,32 @@ individual files. The changes are now listed with the most recent at the top. +**April 23 2024 :: Bug-fix: WRF hybrid vertical coordinate. Tag v11.4.1** + +- DART now detects whether WRF is using Hybrid Vertical Coordinate (HVC) introduced in WRFv3.9 or terrain following (TF) system. + This fix is also compatible with pre WRFv3.9 versions which did not include explicit attribute information for vertical coordinate system. +- Improved obs_impact_tool documentation. + **March 27 2024 :: WRF-Hydro Developments; AIRS converter documentation update; Add citation.cff file. Tag v11.4.0** - WRF-Hydro: + - Added a new perfect model obs experimental capability to HydroDART - - Modified the Streamflow obs converter to allow for better diagnostics: allows DART to + - Modified the Streamflow obs converter to allow for better diagnostics: allows DART to compute obs space diagnostics on all gauges from the Routelink - Enhanced performance in the model_mod and noah_hydro_mod when running a full CONUS domain - Improved HydroDART Diagnostics with new capabilities (saves the hydrographs in a high-resolution pdf, handles hybrid DA components, separate plots for the hybrid statistics, allows the openloop to have different ens size and gauges than the DA runs) + - AIRS and AMSU-A observation converters: + - Updated the documentation to use up-to-date build suggestions for the HDFEOS library - Updated the AIRS converter code to be able to use version 7 of the AIRS data formats - Removed unused and non-functional code: AIRS/BUILD_HDF-EOS.sh, AIRS/L1_AMSUA_to_netcdf.f90, AIRS/shell_scripts/Build_HDF_to_netCDF.sh, AIRS/shell_scripts/Convert_HDF_to_netCDF.csh - Removed the unnecessary entries from obs_def_rttov_nml in the input.nml + - Added a citation.cff file to help users correctly cite DART software - creates a link to cite the repository on the landing page sidebar on GitHub. diff --git a/conf.py b/conf.py index bbdaa06a7d..6df8c544f0 100644 --- a/conf.py +++ b/conf.py @@ -21,7 +21,7 @@ author = 'Data Assimilation Research Section' # The full version, including alpha/beta/rc tags -release = '11.4.0' +release = '11.4.1' root_doc = 'index' # -- General configuration ---------------------------------------------------