bgrid_solo scripting and documentation update

CHANGELOG.rst

@@ -22,6 +22,13 @@ individual files.
 
 The changes are now listed with the most recent at the top.
 
+**July 11 2024 :: Bgrid documentation and scripting fix. Tag v11.5.1**
+
+- Updated Bgrid documentation and removed outdated scripts and files
+- Fixed obs_diag rank histogram documentation links
+- Improved inflation file documentation
+- GitHub action for running all quickbuilds in DART
+
 **May 16 2024 :: WRF v4. Tag v11.5.0**
 
 - WRF-DART and WRF-DART Tutorial updated to WRFv4. Note, not backwards compatible with WRFv3.9. 

assimilation_code/programs/obs_diag/threed_sphere/obs_diag.rst

@@ -1,3 +1,5 @@
+.. _obs-diag-threed-sphere:
+
 PROGRAM ``obs_diag`` (for observations that use the threed_sphere location module)
 ==================================================================================
 

conf.py

@@ -21,7 +21,7 @@
 author = 'Data Assimilation Research Section'
 
 # The full version, including alpha/beta/rc tags
-release = '11.5.0'
+release = '11.5.1'
 root_doc = 'index'
 
 # -- General configuration ---------------------------------------------------

models/bgrid_solo/readme.rst

@@ -27,10 +27,39 @@ model time step to maintain stability for larger model grids. The model state
 variables are the gridded surface pressure, temperature, and u and v wind
 components.
 
-The ``bgrid_solo`` directory has a ``work/workshop_setup.csh`` script that compiles 
-and runs an example. This example is intended to demonstrate that the same
-process used for a low-order model may be used for a much more 
-complex model and generates output for state-space or observation-space diagnostics. 
+In the ``DART/models/bgrid_solo/work`` directory, an example "perfect model" experiment
+can be run in which a bgrid_solo netcdf file is produced and then perturbed
+to get an ensemble. This example is intended to demonstrate that the same
+process used for a low-order model may be used for a much more complex model
+and generates output for state-space or observation-space diagnostics.
+
+The steps to run this example are as follows:
+
+1.  | ``./quickbuild.sh`` (or ``quickbuild.sh nompi`` if you are not building with mpi)
+    | Builds all DART executables and ``perfect_input.nc`` from the cdl file
+      ``perfect_input.cdl``
+
+2.  | ``./perfect_model_obs``
+    | Reads in an observation sequence file which has only observation definitions
+      (``obs_seq.in``) and generates synthetic observation values from a hindcast
+      model (``perfect_input.nc``). Results in output state vector file (``perfect_output.nc``)
+      and an output observation sequence file (``obs_seq.out``) to be assimilated by ``filter``
+
+3.  | ``cp perfect_output.nc filter_input.nc``
+    | Copies the output from the ``perfect_model_obs`` program to the input file for
+      the ``filter`` program
+
+4.  | In ``work/input.nml``, set ``perturb_from_single_instance = .true.`` in the
+      ``&filter_nml``
+    | This setting causes filter to perturb a single restart file to generate an
+      ensemble
+
+5.  | ``./filter``
+    | Runs the assimilation program, resulting in three main output files:
+    |    ``preassim.nc`` - the state of all ensemble members prior to the assimilation
+         (i.e. the forecast with any prior inflation applied)
+    |    ``analysis.nc`` - the state of all ensemble members after the assimilation
+    |    ``obs_seq.final`` - the ensemble members' estimate of the observations.
 
 Some examples of ways in which this model can be configured and modified to test
 DART assimilation capabilities are documented in Anderson et al. (2005). [3]_
@@ -42,21 +71,41 @@ interactive user input and create a text file that can be piped into program
 examples for users who are interested in designing their own custom obs_sequence
 files.
 
-Program ``column_rand`` creates an obs_sequence with randomly located columns of
-observations (essentially synthetic radiosondes) that observe surface pressure
-along with temperature and wind components at all model levels.
++ | Program ``column_rand`` creates an obs_sequence with randomly located columns of
+  | observations (essentially synthetic radiosondes) that observe surface pressure
+  | along with temperature and wind components at all model levels.
+
++ | Program ``id_set_def_stdin`` generates an obs_sequence file that observes every
+  | state variable with error variance of 10000 for surface pressure and 1.0 for
+  | temperature and wind components.
+
++ | Program ``ps_id_stdin`` generates an obs_sequence that observes every surface
+  | pressure variable for the default model size (30x60) with an error variance of 100.
+
++ | Program ``ps_rand_local`` generates a set of randomly located surface pressure
+  | observations with an interactively specified error variance. It also allows the
+  | observations to be confined to a rectangular subdomain.
+
+Diagnostics
+-----------
 
-Program ``id_set_def_stdin`` generates an obs_sequence file that observes every
-state variable with error variance of 10000 for surface pressure and 1.0 for
-temperature and wind components.
+The best method to determine the performance of an experiment in which you
+assimilate data from real-world sources is to compare the ensemble estimates of
+the observation to your real-world data. You can estimate the bias and error of
+the ensemble mean or gauge how many of the real-world observations are actually
+being assimilated. These diagnostics are known as observation-space diagnostics.
+DART provides the program ``obs_diag`` and MATLAB observation space diagnostics
+for you to use to quickly assess the performance of your experiment. 
 
-Program ``ps_id_stdin`` generates an obs_sequence that observes every surface
-pressure variable for the default model size (30x60) with an error variance of
-100.
+``obs_diag`` reads the ``obs_seq.final`` files and calculates several quantities,
+such as the root-mean-squared error, bias, and spread, for an arbitrary number of
+regions and levels. ``obs_diag`` outputs a netCDF file called ``obs_diag_output.nc``,
+which can then be used in the DART MATLAB routines located in
+``DART/diagnostics/matlab/``.
 
-Program ``ps_rand_local`` generates a set of randomly located surface pressure
-observations with an interactively specified error variance. It also allows the
-observations to be confined to a rectangular subdomain.
+For more detail on obs_diag and the MATLAB diagnostics, see 
+:ref:`PROGRAM obs_diag for the threed_sphere location module <obs-diag-threed-sphere>` 
+and :ref:`MATLAB observation space diagnostics <configMatlab>`.
 
 Namelist
 --------
@@ -138,19 +187,19 @@ The following values are specified in ``model_nml``.
 +======================+====================+===========================================+
 | current_time(4)      | integer            | Specifies the initial time of the Bgrid   |
 |                      |                    | model internal clock. The four integer    | 
-|                      |                    | values are the day, hour, minutes, and    |
-|                      |                    | seconds. The default version of the Bgrid |
+|                      |                    | values are the day, hour, minute, and     |
+|                      |                    | second. The default version of the Bgrid  |
 |                      |                    | model has neither a diurnal or seasonal   |
 |                      |                    | cycle, so these can all be set to 0, the  |
 |                      |                    | default value.                            |
 +----------------------+--------------------+-------------------------------------------+
 | override             | logical            | If true, then the initial model date is   |
 |                      |                    | taken from namelist entry current_time,   |
-|                      |                    | even if an atmos_model.res file is found  |
-|                      |                    | in directory INPUT. For most DART         |
-|                      |                    | applications, atmospheric restart values  |
-|                      |                    | are coming from DART files and no INPUT   |
-|                      |                    | directory is used.                        |
+|                      |                    | even if an ``atmos_model.res`` file       |
+|                      |                    | is found in the directory ``INPUT``.      |
+|                      |                    | For most DART applications, atmospheric   |
+|                      |                    | restart values come from DART files and   |
+|                      |                    | no INPUT directory is used.               |
 +----------------------+--------------------+-------------------------------------------+
 | dt_atmos             | integer            | Model timestep in seconds.                |
 +----------------------+--------------------+-------------------------------------------+
@@ -168,12 +217,12 @@ The following values are specified in ``model_nml``.
 |                      |                    | model advance changes the time by         |
 |                      |                    | dt_bias. However, internally the bgrid    |
 |                      |                    | model is moving things forward by         |
-|                      |                    | dt_atmos. By running perfect_model_obs    |
+|                      |                    | dt_atmos. By running ``perfect_model_obs``|
 |                      |                    | with one time step for the internal bgrid |
-|                      |                    | clock (for instance dt_atmos = 3600,      |
-|                      |                    | dt_bias = 3600), and filter with another  |
-|                      |                    | (dt_atmos = 3000, and dt_bias = 3600)     |
-|                      |                    | model error is simulated.                 |
+|                      |                    | clock (for instance ``dt_atmos = 3600``,  |
+|                      |                    | ``dt_bias = 3600``), and ``filter`` with  |
+|                      |                    | another (``dt_atmos = 3000``, ``dt_bias = |
+|                      |                    | 3600``), model error is simulated.        |
 +----------------------+--------------------+-------------------------------------------+
 | state_variables(:,2) | character(len=129) | Strings that identify the bgrid_solo      |
 |                      |                    | variables that should be part of the DART |
@@ -184,19 +233,19 @@ The following values are specified in ``model_nml``.
 | template_file        | character(len=256) | This is the name of the file that         |
 |                      |                    | specifies the resolution of the variables |
 |                      |                    | DART uses to create the DART state        |
-|                      |                    | vector. If *template_file = "null"* the   |
-|                      |                    | *&bgrid_cold_start_nml* namelist          |
+|                      |                    | vector. If ``template_file = "null"`` the |
+|                      |                    | ``&bgrid_cold_start_nml`` namelist        |
 |                      |                    | variables are used to specify the         |
 |                      |                    | resolution. The actual input filenames    |
-|                      |                    | for *filter* and *perfect_model_obs* come |
-|                      |                    | from their respective namelists.          |
+|                      |                    | for ``filter`` and ``perfect_model_obs``  |
+|                      |                    | come from their respective namelists.     |
 |                      |                    | The resolutions in the file specified in  |
-|                      |                    | *template_file* must match the            |
+|                      |                    | ``template_file`` must match the          |
 |                      |                    | resolutions of the variables in the input |
 |                      |                    | filenames. To start an experiment with a  |
-|                      |                    | new model resolution, set template_file   |
-|                      |                    | to "null" and set the resolutions in      |
-|                      |                    | bgrid_cold_start_nml.                     | 
+|                      |                    | new model resolution, set ``template_file=|
+|                      |                    | "null"`` and set the resolutions in       |
+|                      |                    | in the ``&bgrid_cold_start_nml``.         | 
 +----------------------+--------------------+-------------------------------------------+
 
 The following values are specified in ``bgrid_cold_start_nml``.