Merge pull request #528 from NCAR/fix-doc-index

readthedocs build fix #526
mpas constants #251

.readthedocs.yaml

@@ -8,3 +8,6 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+
+sphinx:
+  configuration: conf.py

CHANGELOG.rst

@@ -22,6 +22,12 @@ individual files.
 
 The changes are now listed with the most recent at the top.
 
+**August 8 2023 :: MPAS-ATM constants and readthedocs fix. Tag v10.8.2**
+
+- MPAS-ATM constants updated to MPAS v5+
+- readthedocs build info updated.
+
+
 **July 27 2023 :: Bug-fixes for MOM6 and WRF. Tag v10.8.1**
 
 - bug-fixes:

assimilation_code/modules/assimilation/filter_mod.rst

@@ -13,7 +13,7 @@ parameter configuration that are driven from its namelist. See the namelist sect
 of assimilation steps to be done is controlled by the input observation sequence and by the time-stepping capabilities
 of the model being used in the assimilation.
 
-See :doc:`../../../README` for more documentation, including a discussion of the
+See :ref:`Welcome page` for more documentation, including a discussion of the
 capabilities of the assimilation system, a diagram of the entire execution cycle, the options and features.
 
 Namelist

assimilation_code/programs/filter/filter.rst

@@ -23,7 +23,7 @@ This overview includes these subsections:
 -  Description of Inflation Options
 -  Detailed Program Flow
 
-See :doc:`../../../README` for more documentation, including a discussion of the
+See :ref:`Welcome page` for more documentation, including a discussion of the
 capabilities of the assimilation system, a diagram of the entire execution cycle, the options and features.
 
 Program flow

conf.py

@@ -21,8 +21,8 @@
 author = 'Data Assimilation Research Section'
 
 # The full version, including alpha/beta/rc tags
-release = '10.8.1'
-master_doc = 'README'
+release = '10.8.2'
+root_doc = 'index'
 
 # -- General configuration ---------------------------------------------------
 

guide/downloading-dart.rst

@@ -3,7 +3,7 @@ Downloading DART
 
 The DART source code is distributed on the GitHub repository
 `NCAR/DART <https://github.com/NCAR/DART>`_ with the documentation
-served through :doc:`readthedocs<../README>`.
+served through :ref:`readthedocs <Welcome page>`.
 
 Go to https://github.com/NCAR/DART and clone the repository or get the
 ZIP file according to your preference. See the `github help page on

README.rst → index.rst

@@ -1,3 +1,5 @@
+.. _Welcome page:
+
 Welcome to the Data Assimilation Research Testbed
 =================================================
 

models/CESM/doc/setup_guidelines.rst

@@ -5,7 +5,7 @@ CESM+DART setup overview
 ------------------------
 
 If you found your way to this file without reading more basic DART help files, 
-please read those first. :doc:`Getting Started <../../../README>` is a good place to find pointers to those files. 
+please read those first. :ref:`Getting Started <Welcome page>` is a good place to find pointers to those files. 
 Then see :doc:`CESM<../readme>` for an overview of DART's interfaces to CESM.
 Finally, see the ../../{your_cesm_component(s)}/readme.html documentation about
 the code-level interfaces and namelist values for various CESM component models.

models/clm/tutorial/README.rst

@@ -31,7 +31,7 @@ for CLM-specific assistance.
 
 If you are new to DART, we recommend that you become familiar
 by first working through the :doc:`../../../theory/readme` and then
-understanding the :doc:`DART getting started <../../../README>` documentation.
+understanding the :ref:`DART getting started <Welcome page>` documentation.
 
 This CLM5-DART tutorial is based on a simple example in which we 
 describe how to:
@@ -53,8 +53,8 @@ observations that are assimilated, updated model state variables, assimilation t
 assimilation frequency, and the model and observation grid resolution.
 
 We encourage users to complete the tutorial and then modify CLM-DART to pursue their own
-research questions.  We have comprehensive and searchable :doc:`documentation
-<../../../README>`, with trained and experienced
+research questions.  We have comprehensive and searchable :ref:`documentation
+<Welcome page>`, with trained and experienced
 staff that can help troubleshoot issues (dart@ucar.edu).
 
 

models/mpas_atm/model_mod.f90

@@ -210,10 +210,10 @@ module model_mod
 
 ! Real (physical) constants as defined exactly in MPAS.
 ! redefined here for consistency with the model.
-real(r8), parameter :: rgas = 287.0_r8
-real(r8), parameter :: rv = 461.6_r8
-real(r8), parameter :: cp = 1003.0_r8
-real(r8), parameter :: cv = 716.0_r8
+real(r8), parameter :: rgas = 287.0_r8  ! Constant: Gas constant for dry air [J kg-1 K-1]
+real(r8), parameter :: rv = 461.6_r8    ! Constant: Gas constant for water vapor [J kg-1 K-1]
+real(r8), parameter :: cp = 7.0_r8*rgas/2.0_r8 ! = 1004.5 Constant: Specific heat of dry air at constant pressure [J kg-1 K-1] 
+real(r8), parameter :: cv = cp - rgas          ! = 717.5  Constant: Specific heat of dry air at constant volume [J kg-1 K-1]
 real(r8), parameter :: p0 = 100000.0_r8
 real(r8), parameter :: rcv = rgas/(cp-rgas)
 real(r8), parameter :: rvord = rv/rgas    
@@ -7380,7 +7380,7 @@ function theta_to_tk (ens_size, theta, rho, qv, istatus)
 
 integer,                       intent(in)  :: ens_size
 real(r8), dimension(ens_size), intent(in)  :: theta    ! potential temperature [K]
-real(r8), dimension(ens_size), intent(in)  :: rho      ! dry density
+real(r8), dimension(ens_size), intent(in)  :: rho      ! dry air density [kg/m3]
 real(r8), dimension(ens_size), intent(in)  :: qv       ! water vapor mixing ratio [kg/kg]
 integer,  dimension(ens_size), intent(inout) :: istatus
 real(r8), dimension(ens_size) :: theta_to_tk          ! sensible temperature [K]
@@ -7408,7 +7408,7 @@ function theta_to_tk (ens_size, theta, rho, qv, istatus)
 endif
 where (istatus == 0)
 
-   theta_m = (1.0_r8 + 1.61_r8 * qv_nonzero)*theta
+   theta_m = (1.0_r8 + rvord * qv_nonzero)*theta
 
    where (theta_m > 0.0_r8 .and. rho > 0.0_r8)  ! Check if all the input are positive
 
@@ -7441,7 +7441,7 @@ subroutine compute_full_pressure(ens_size, theta, rho, qv, pressure, tk, istatus
 
 integer,  intent(in)  :: ens_size
 real(r8), dimension(ens_size), intent(in)  :: theta    ! potential temperature [K]
-real(r8), dimension(ens_size), intent(in)  :: rho      ! dry density
+real(r8), dimension(ens_size), intent(in)  :: rho      ! dry air density [kg/m3]
 real(r8), dimension(ens_size), intent(in)  :: qv       ! water vapor mixing ratio [kg/kg]
 real(r8), dimension(ens_size), intent(out) :: pressure ! full pressure [Pa]
 real(r8), dimension(ens_size), intent(out) :: tk       ! return sensible temperature to caller
@@ -7457,7 +7457,7 @@ subroutine compute_full_pressure(ens_size, theta, rho, qv, pressure, tk, istatus
 tk = theta_to_tk(ens_size, theta, rho, qv_nonzero, istatus)
 
 where (istatus == 0)       ! We only take non-missing tk here
-   pressure = rho * rgas * tk * (1.0_r8 + 1.61_r8 * qv_nonzero)
+   pressure = rho * rgas * tk * (1.0_r8 + rvord * qv_nonzero)
 end where
 
 if ( debug > 1 ) then

models/mpas_atm/readme.rst

@@ -7,7 +7,15 @@ Overview
 This document describes the DART interface module for the atmospheric component 
 of the Model for Prediction Across Scales
 `MPAS <https://ncar.ucar.edu/what-we-offer/models/model-prediction-across-scales-mpas>`__ 
-(or briefly, MPAS-ATM) global model, which uses an unstructured Voronoi grid mesh,
+(or briefly, MPAS-ATM) global model.
+
+The DART interface has constants set to match MPAS v5.0 onwards as defined in 
+`MPAS-Model/src/framework/mpas_constants.F <https://github.com/MPAS-Dev/MPAS-Model/blob/master/src/framework/mpas_constants.F>`__.
+If you need to reproduce work with DART and MPAS v4 you will need to change the model_mod.f90 
+parameters ``cp``, ``cv`` and ``rvord`` to match MPAS v4. 
+
+
+The mpas-atm model uses an unstructured Voronoi grid mesh,
 formally Spherical Centriodal Voronoi Tesselations (SCVTs). This allows for both
 quasi-uniform discretization of the sphere and local refinement. The MPAS/DART
 interface was built on the SCVT-dual mesh and does not regrid to regular lat/lon

models/wrf/tutorial/README.rst

@@ -27,7 +27,7 @@ forum for WRF-specific assistance.
 
 If you are new to DART, we recommend that you become familiar with DART
 by working through the :doc:`../../../theory/readme` and then
-understanding the :doc:`DART getting started <../../../README>` documentation.
+understanding the :ref:`DART getting started <Welcome page>` documentation.
 
 before attempting the WRF/DART tutorial as you will find many helpful
 resources for learning the base DART configuration.
@@ -109,7 +109,7 @@ needed to perform an experiment.
 Build the DART executables.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have not already, see :doc:`Getting Started <../../../README>` to
+If you have not already, see :ref:`Getting Started <Welcome page>` to
 download the DART software package. Set an environment variable
 *DART_DIR* to point to your base DART directory. How to do this will
 depend on which shell you are using.
@@ -135,7 +135,7 @@ might need for an experiment with that model.
 
 1. It is assumed you have successfully configured the
    ``$DART_DIR/build_templates/mkmf.template`` file for your system. If
-   not, you will need to do so now. See the :doc:`Getting Started <../../../README>`
+   not, you will need to do so now. See :ref:`Getting Started <Welcome page>`
    for more detail, if necessary.
 
 2. [OPTIONAL] Modify the DART code to use 32bit reals. Most WRF/DART
@@ -576,7 +576,7 @@ want to run with the example observations, you can skip to Step
 4.
 
 However, observation processing is critical to the success of running
-DART and was covered in :doc:`getting started <../../../README>`. In
+DART and was covered in :ref:`Getting Started <Welcome page>`. In
 brief, to add your own observations to WRF/DART you will need to
 understand the relationship between observation definitions and
 observation sequences, observation types and observation quantities, and