Skip to content

Commit aa5435e

Browse files
depricate use_u_for_wind, wind documentation
On advice from jla: error if a user has selected use_u_for_wind as there is a bug in Manhattan, where all ensemble members are set to the last ensemble member value in the rbf calculation #861 see #780 (comment) Documentation for mpas regristry changes needed for DART Regional wind updates namelist options in update_bc - not sure whey they do not use the same model_nml options, so not added to docs in this commit.
1 parent b34549b commit aa5435e

File tree

2 files changed

+94
-40
lines changed

2 files changed

+94
-40
lines changed

models/mpas_atm/model_mod.f90

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -426,6 +426,14 @@ subroutine static_init_model()
426426
read(iunit, nml = mpas_vars_nml, iostat = io)
427427
call check_namelist_read(iunit, io, 'mpas_vars_nml')
428428

429+
if (use_u_for_wind) then
430+
write(string1,*) 'use_u_for_wind=.true. is deprecated'
431+
write(string2,*) 'please contact the DART team if you are using this option'
432+
call error_handler(E_ERR,'static_init_model',string1,source, &
433+
text2=string2)
434+
endif
435+
436+
429437
call set_calendar_type( calendar )
430438
model_timestep = set_model_time_step()
431439
call get_time(model_timestep,ss,dd)
@@ -3257,6 +3265,9 @@ subroutine compute_u_with_rbf(state_handle, ens_size, loc, zonal, uval, ier)
32573265

32583266
integer :: e ! loop index
32593267

3268+
call error_handler(E_ERR, 'please contact the DART team if you are using compute_u_with_rbf', source)
3269+
3270+
32603271
ier = 0
32613272
uval = MISSING_R8
32623273

models/mpas_atm/readme.rst

Lines changed: 83 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -17,36 +17,86 @@ If you need to reproduce work with DART and MPAS v4 you will need to change the
1717
parameters ``cp``, ``cv`` and ``rvord`` to match MPAS v4.
1818

1919

20+
MPAS Grid
21+
---------
22+
2023
The mpas-atm model uses an unstructured Voronoi grid mesh,
2124
formally Spherical Centriodal Voronoi Tesselations (SCVTs). This allows for both
22-
quasi-uniform discretization of the sphere and local refinement. The MPAS/DART
25+
quasi-uniform discretization of the sphere and local refinement. The MPAS-DART
2326
interface was built on the SCVT-dual mesh and does not regrid to regular lat/lon
2427
grids. In the C-grid discretization, the normal component of velocity on cell
2528
edges is prognosed; zonal and meridional wind components are diagnosed on the
26-
cell centers. We provide several options to choose from in the assimilation of
27-
wind observations as shown below.
28-
29-
The grid terminology used in MPAS is as shown in the figure below:
29+
cell centers. The grid terminology used in MPAS is as shown in the figure below:
3030

3131
|MPAS_grid_structure|
3232

33-
The wind options during a DART assimilation are controlled by combinations of 4
34-
different namelist values. The values determine which fields the forward
35-
operator uses to compute expected observation values; how the horizontal
36-
interpolation is computed in that forward operator; and how the assimilation
37-
increments are applied to update the wind quantities in the state vector.
38-
Preliminary results based on real data assimilation experiments indicate that
39-
performance is better when the zonal and meridional winds are used as input to
40-
the forward operator that uses Barycentric interpolation, and when the
41-
prognostic *u* wind is updated by the incremental method described in the figure
42-
below. However there remain scientific questions about how best to handle the
43-
wind fields under different situations. Thus we have kept all implemented
44-
options available for use in experimental comparisons. See the figure below for
45-
a flow-chart representation of how the 4 namelist items interact:
46-
47-
|WindDA_options|
48-
49-
Cycling of MPAS/DART is run in a *restart* mode. As for all DART experiments,
33+
DART reads the static variables related to the grid structure
34+
from the MPAS_ATM NetCDF file (specified in ``init_template_filename``).
35+
The calculations to find the closest mesh cell to an observation location is performed in the
36+
cartesian coordinate to avoid the polar issues.
37+
38+
MPAS winds in DART
39+
------------------
40+
41+
The MPAS model uses the normal component of velocity on cell edges ``u`` as the prognostic variable
42+
for the wind field. DART uses diagnostics variables ``uReconstructZonal`` and ``uReconstructMeridional``
43+
in the state. Before building MPAS for use with DART, the MPAS Registry.xml must be
44+
updated to output ``uReconstructZonal`` and ``uReconstructMeridional`` (u,v) winds to the MPAS
45+
NetCDF restart file.
46+
47+
.. code-block:: fortran
48+
:emphasize-lines: 3, 4
49+
:caption: snippet from MPAS src/core_init_atmosphere/Registry.xml
50+
51+
packages="vertical_stage_out;met_stage_out"/>
52+
...
53+
<var name="u" packages="met_stage_out"/>
54+
<var name="uReconstructZonal" packages="met_stage_out"/>
55+
<var name="uReconstructMeridional" packages="met_stage_out"/>
56+
57+
58+
.. code-block:: fortran
59+
:emphasize-lines: 4, 5
60+
:caption: snippet from MPAS src/core_atmosphere/Registry.xml
61+
62+
<stream name="restart"
63+
...
64+
<var name="u"/>
65+
<var name="uReconstructZonal"/>
66+
<var name="uReconstructMeridional"/>
67+
68+
The DART updates to MPAS restart files is two step process because of the wind variables.
69+
First, filter is run to update ``uReconstructZonal``, and ``uReconstructZonal``. Then update_mpas_states
70+
(or udpdate_bc.f90 for regional MPAS) is run to update ``u`` from ``uReconstructZonal``, and
71+
``uReconstructZonal``.
72+
73+
The relevant namelist options are:
74+
75+
model_nml::update_u_from_reconstruct
76+
Must be set to ``.true.`` . u is updated from uReconstructZonal and uReconstructMeridional.
77+
78+
model_nml::use_increments_for_u_update
79+
- ``.false.`` ``u`` is updated from uReconstructZonal and uReconstructMeridional.
80+
- ``.true.`` ``u`` increments are calculated from the increments of ``uReconstructZonal`` and
81+
``uReconstructMeridional``, and u is updated from the increments.
82+
83+
.. Note ::
84+
The ``use_u_for_wind=.true.`` option shown in the flow chart below is deprecated.
85+
Please contact [email protected] if you are using ``use_u_for_wind=.true.`` as there is a bug
86+
`#861 <https://github.com/NCAR/DART/issues/861>`_ in versions
87+
of DART using this option since the Manhattan release.
88+
89+
.. figure:: ../../guide/images/MPAS_WindDA_options.png
90+
:alt: MPAS WindDA options
91+
:width: 100%
92+
93+
Options for wind data assimilation in MPAS-DART. use_u_for_wind=.true. is deprecated.
94+
95+
96+
Cycling MPAS-DART
97+
-----------------
98+
99+
Cycling of MPAS-DART is run in a *restart* mode. As for all DART experiments,
50100
the overall design for an experiment is this: the DART program ``filter`` will
51101
read the initial condition file, the observation sequence file, and the DART
52102
namelist to decide whether or not to advance the MPAS-ATM model. All of the
@@ -85,7 +135,7 @@ namelist.
85135
model_nml
86136
^^^^^^^^^
87137

88-
.. code-block:: fortran
138+
.. code-block:: text
89139
90140
&model_nml
91141
init_template_filename = 'mpas_init.nc',
@@ -104,7 +154,6 @@ model_nml
104154
outside_grid_level_tolerance = -1.0,
105155
write_grid_to_diag_files = .false.,
106156
no_normalization_of_scale_heights = .true.
107-
108157
/
109158
110159
+---------------------------------------+---------------------------------------+-----------------------------------------+
@@ -171,6 +220,10 @@ model_nml
171220
| | | [default]. In that case, triangular |
172221
| | | meshes are used for the barycentric |
173222
| | | (e.g., area-weighted) interpolation. |
223+
| | | |
224+
| | | ``.true.`` is deprecated. Please contact|
225+
| | | [email protected] if you are using |
226+
| | | ``use_u_for_wind=.true.`` |
174227
| | | If ``.true.``, wind vectors at an |
175228
| | | arbitrary (e.g., observation) point |
176229
| | | are reconstructed from the normal |
@@ -264,8 +317,6 @@ model_nml
264317
+---------------------------------------+---------------------------------------+-----------------------------------------+
265318

266319

267-
268-
269320
mpas_vars_nml
270321
^^^^^^^^^^^^^
271322

@@ -298,21 +349,14 @@ When writing back to MPAS NetCDF files, out-of-range values are adjusted to be i
298349
Note the adjustment is done only when writing to MPAS NetCDF files, not during assimilation.
299350
DART files, mean, sd, and inflation files are not adjusted.
300351

301-
Note that changing values at the edges of the distribution means it is no longer completely Gaussian.
302-
In practice this technique has worked effectively, but if the assimilation is continually trying to
303-
move the values outside the permitted range the results may be of poor quality.
304-
Examine the diagnostics for these fields carefully when using bounds to restrict their values.
305-
You may want to consider using the :ref:`QCEFF<qceff>` filter when working with bounded quantities.
306-
352+
.. Note::
307353

308-
Grid Information
309-
----------------
354+
Changing values at the edges of the distribution means the distribution is no longer completely Gaussian.
355+
In practice this technique has worked effectively, but if the assimilation is continually trying to
356+
move the values outside the permitted range the results may be of poor quality.
357+
Examine the diagnostics for these fields carefully when using bounds to restrict their values.
358+
You may want to consider using the :ref:`QCEFF<qceff>` filter when working with bounded quantities.
310359

311-
As the forward operators use the unstructured grid meshes in MPAS-ATM, the
312-
DART/MPAS interface needs to read static variables related to the grid structure
313-
from the MPAS ATM netCDF file (specified in ``init_template_filename``).
314-
The calculations to find the closest mesh cell to an observation location is performed in the
315-
cartesian coordinate to avoid the polar issues.
316360

317361
References
318362
----------
@@ -322,4 +366,3 @@ http://mpas-dev.github.io.
322366

323367
.. |MPAS_grid_structure| image:: ../../guide/images/MPAS_grid_structure.png
324368

325-
.. |WindDA_options| image:: ../../guide/images/MPAS_WindDA_options.png

0 commit comments

Comments
 (0)