Merge pull request #1180 from tlspero/v5.5_release

Updates for MCIPv5.5 Documentation
USEPA · Sep 25, 2024 · 7d289a7 · 7d289a7
2 parents c31983b + 8b848d1
commit 7d289a7
Show file tree

Hide file tree

Showing 5 changed files with 206 additions and 43 deletions.
diff --git a/PREP/mcip/docs/CHANGES b/PREP/mcip/docs/CHANGES
@@ -1,6 +1,43 @@
 CHANGES for MCIP
 
 
+MCIP Version 5.5 (19 September 2024)
+
+- Changed constraint on XORIG and YORIG for Lambert conformal projections
+  with user-specified runtime reference latitude. Original constraint of
+  500 meters introduced an error in calculating the location of the
+  lower-left corner (i.e., XORIG and YORIG) in domains with a horizontal
+  grid spacing that is not a multiple of 1 km. Now using a constraint of
+  5 meters to allow for "neater" XORIG and YORIG values across compilers.
+
+  Changed files:  PREP/mcip/src/setgriddefs.f90
+
+
+- Updated WRF option translation for the MCIP metadata for new physics
+  introduced between WRFv4.1 and WRFv4.6.
+
+  Changed files:  PREP/mcip/src/wrfemopts.f90
+
+
+- Removed redundant NF90_OPEN/NF90_CLOSE couplet to improve efficiency.
+
+  Changed files:  PREP/mcip/src/rdwrfem.f90
+
+
+- Updated version stamp.
+
+  Changed files:  PREP/mcip/src/mcipparm_mod.f90
+
+--------------------------------------------------------------------------------
+
+MCIP Version 5.4 (12 July 2022)
+
+- Updated version stamp.
+
+  Changed files:  PREP/mcip/src/mcipparm_mod.f90
+
+--------------------------------------------------------------------------------
+
 MCIP Version 5.3.3 (30 June 2021)
 
 - Removed reliance on reading F (Coriolis parameter) from WRF output for

diff --git a/PREP/mcip/docs/FAQ b/PREP/mcip/docs/FAQ
@@ -1,13 +1,103 @@
 Frequently Asked Questions for MCIP
 
+MCIP Version 5.5 (19 September 2024)
+
+What are the changes in this release?
+
+  There are only three changes in this release.
+
+  1. MCIP calculates XORIG and YORIG (projection parameters used by the CMAQ
+     system) from the projection information used by WRF. Because the math
+     calculations can get messy with real and double-precision trigonometry,
+     the solutions are inexact. Prior versions of MCIP used a constraint to
+     round the XORIG and YORIG to multiples of 500 meters. This constraint was
+     introduced several years ago, when most groups were using horizontal grid
+     spacings that were evenly divisible by 1 kilometer.
+
+     This release changes the constraint on XORIG and YORIG to now be in
+     multiples of 5 meters (rather than 500 meters). This change allows domains
+     with horizontal grid spacings like 1.333 km and 4.25 km to be handled
+     correctly. In addition, there is consistency in XORIG and YORIG values
+     across compilers and optimizations.
+
+  2. The WRF physics option tokens were updated for the MCIP metadata to
+     reflect new physics introduced between WRFv4.1 and WRFv4.6.
+
+  3. The routine that reads WRF data was updated to remove a redundant
+     NF90_OPEN/NF90_CLOSE couplet that slightly slowed the MCIP processing.
+
+
+Is there an MCIPv5.4.1?
+
+  No. There were no updates to MCIP in the release of CMAQv5.4.1. MCIP was
+  not updated and remained at MCIPv5.4 for both CMAQv5.4 and CMAQv5.4.1.
+
+
+Do I need to update from MCIPv5.3.3 or MCIPv5.4 to work with CMAQv5.5?
+
+  Not necessarily. If you are starting new runs with CMAQv5.5, and if you do
+  not have MCIP files, then it is recommended that you use MCIPv5.5. However,
+  if you have MCIP files processed already *AND* if you are *not* using a 
+  horizontal grid spacing that is not a multiple of 1 km (e.g., 1.333 km or
+  4.25 km), then you can probably use your older MCIP files.
+
+
+I already pointed out something that needs to be corrected in MCIP, but I
+do not see the update here. What is going on?
+
+  There are a few corrections to MCIP that did not get incorporated into this
+  release due to timelines and competing priorities. They are in the queue for
+  the next release. Thank you for your patience.
+
+
+MCIP crashed, and I don't understand my error. What should I do?
+
+  Clean up the directory with your MCIP executable and compiled object (.o)
+  files by using "make clean". Then recompile with the debug options turned
+  on, ensuring that you have the "traceback" or equivalent directive for
+  your compiler. Then rerun, and you should have a more meaningful error
+  message that may point you to the subroutine and specific line of code
+  that is causing your error.
+
+
+I think there is a bug in MCIP. How can I report it?
+
+  You can use the CMAS Center Forum to report bugs, get help from the
+  community, and communicate with developers. You can use the "MCIP"
+  category (upper-left corner on the Forum) for issues that are strictly
+  related to MCIP. Before opening a new thread on the Forum, please search
+  the Forum to see if the issue has already been raised and addressed. If
+  not, please open a new thread rather than amending an existing thread.
+  https://forum.cmascenter.org 
+
+
+Where can I get more information on the CMAQ system?
+
+  Please visit https://www.epa.gov/cmaq 
+
+
+Where can I get training on how to use the CMAQ system?
+
+  The CMAS Center provides periodic training on the use and utility of the
+  CMAQ system. Please visit https://www.cmascenter.org
+
+
+Do you take user suggestions?
+
+  Yes! Please submit them via the CMAS Center Forum
+  https://forum.cmascenter.org
+
+--------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
+
 MCIP Version 5.4 (12 September 2022)
 
 What are the changes in this release?
 
-  None. MCIPv5.4 has not been updated since the previous release (v5.3.3). Note 
-  that, beginning with version 5.3.3, the versioning of MCIP is aligned with the 
-  numbering used for CMAQ.  Therefore, the MCIP version numbering is updated with 
-  the release of CMAQv5.4.
+  None. MCIPv5.4 has not been updated since the previous release (v5.3.3). Note
+  that, beginning with version v5.3.3, the versioning of MCIP is aligned with
+  the numbering used for CMAQ. Therefore, the MCIP version numbering is
+  updated with the release of CMAQv5.4.
 
 --------------------------------------------------------------------------------
 --------------------------------------------------------------------------------

diff --git a/PREP/mcip/docs/ReleaseNotes b/PREP/mcip/docs/ReleaseNotes
@@ -1,35 +1,34 @@
 ********************************************************************************
-Announcing the release of MCIP Version 5.4 (12 September 2022)
+Announcing the release of MCIP Version 5.5 (19 September 2024)
 ********************************************************************************
 
-The MCIP code's version number is updated to version 5.4. With this release,
-no changes have been made to the MCIP code.  
+The MCIP code is updated to version 5.5.  This is a minor update to MCIP.
+These release notes and the CHANGES file reflect all changes that have been
+made to MCIP since MCIPv5.4 (the previous release).  Changes to MCIPv5.5
+were made by Tanya Spero (U.S. EPA).
 
-As implemented with the release of the previous version (v5.3.3), the version 
-numbering for MCIP is kept consistent with CMAQ to minimize confusion within the 
-user community. Therefore, MCIP's version is updated to v5.4 for consistency.  
-
-MCIPv5.4 accompanies CMAQv5.4.  If you are using CMAQv5.3+, you must
+MCIPv5.5 accompanies CMAQv5.5.  If you are using CMAQv5.3+, you must
 upgrade to use MCIPv5.0+.
 
-MCIPv5.4 requires I/O API version 3.1 or greater to support error-checking
+MCIPv5.5 requires I/O API version 3.1 or greater to support error-checking
 within the I/O API.
 
-MCIPv5.4 requires the netCDF F90 module (rather than the F77 include).
+MCIPv5.5 requires the netCDF F90 module (rather than the F77 include).
+
 
 MCIP can be cited with the following reference:
 
   Otte, T. L., and J. E. Pleim, 2010.  The Meteorology-Chemistry Interface
      Processor (MCIP) for the CMAQ modeling system: updates through
      MCIPv3.4.1.  Geoscientific Model Development, 3, 243-256.
 
-A DOI will also be available for CMAQv5.4 (which includes MCIPv5.4).
+A DOI will also be available for CMAQv5.5 (which includes MCIPv5.5).
 
 
 Background on MCIP and other useful information about the CMAQ system can be
 found online at http://www.epa.gov/cmaq.
 
-Inquiries related to potential bugs in MCIPv5.4 or questions related to
+Inquiries related to potential bugs in MCIPv5.5 for questions related to
 proper use of the code should be submitted to the MCIP Category in the
 Forum hosted by the CMAS Center:  https://forum.cmascenter.org/c/mcip.
 
@@ -38,11 +37,47 @@ Users should consult the FAQ and other issues raised within the Forum
 before submitting new inquiries.
 
 
-The previous release of MCIP (v5.3.3) was tested with the following Fortran compilers 
-under both debug and optimized options (as shown in the Makefile):
 
-  Intel 19.0.5, netCDF 4.7.4, I/O API 3.2 (downloaded 11 October 2018)
+MCIPv5.5 was tested with the following Fortran compilers under both debug
+and optimized options (as shown in the Makefile):
+
+  Intel 21.4 with netCDF 4.9.2 and I/O API 3.2
+
+  Nvidia 22.11 with netCDF 4.9.2 and I/O API 3.2
+
+  GCC 8.5.0 with netCDF 4.9.2 and I/O API 3.2
+
+
+
+With MCIPv5.5, the following remain deprecated:
+  - Including "SOIM1", "SOIM2", "SOIT1", and "SOIT2" in METCRO2D.
+    Those fields are now in a separate file that includes all soil layers and
+    their associated depths (SOI_CRO).
+  - Including "LUFRAC_xx" in GRIDCRO2D.  Those fields are now in a separate
+    file that includes each fractional land use classification (LUFRAC_CRO).
+
+With MCIPv5.5, the following output variables in METCRO2D remain deprecated:
+     - 2-D cloud fraction (CFRAC)
+     - cloud top (CLDT)
+     - cloud bottom (CLDB)
+     - liquid water content (WBAR)
+They will be removed from METCRO2D in a forthcoming release of MCIP.
+
+
+Interactions with members of the CMAQ user community led to some of the changes
+that have been incorporated into MCIPv5.5.
+
+
+The following is a summary of the changes in MCIPv5.5:
+
+ 1.  Changed constraint on XORIG and YORIG for Lambert conformal projections
+     with user-specified runtime reference latitude. Original constraint of
+     500 meters introduced an error in calculating the location of the
+     lower-left corner (i.e., XORIG and YORIG) in domains with a horizontal
+     grid spacing that is not a multiple of 1 km. Now using a constraint of
+     5 meters to allow for "neater" XORIG and YORIG values across compilers.
 
-  PGI 19.10, netCDF 4.7.4, I/O API 3.2 (downloaded 28 August 2020)
+ 2.  Updated WRF option translation for the MCIP metadata for new physics
+     introduced between WRFv4.1 and WRFv4.6.
 
-  GCC 6.1.0, netCDF 4.6.3, I/O API 3.2 (downloaded 11 October 2018)
+ 3.  Removed a redundant NF90_OPEN/NF90_CLOSE couplet to improve efficiency.
diff --git a/PREP/mcip/src/Makefile b/PREP/mcip/src/Makefile
@@ -22,39 +22,39 @@
 MODEL = mcip.exe
 
 #...Portland Group Fortran
-#...also need to setenv LM_LICENSE_FILE from /usr/local/apps/pgi
-#FC     = /usr/local/apps/pgi/linux86-64/19.10/bin/pgf90
-#NETCDF = /usr/local/apps/netcdf-4.7.4/pgi-19.10
-#IOAPI_ROOT = /usr/local/apps/ioapi-3.2_20200828/pgi-19.10
+###FC     = /usr/local/apps/nvidia/Linux_x86_64/22.11/compilers/bin/nvfortran
+###NETCDF = /usr/local/apps/netcdf-4.9.2/nvhpc-22.11
+###IOAPI_ROOT = /usr/local/apps/ioapi-3.2/nvhpc-22.11
 ###FFLAGS = -g -O0 -Ktrap=unf -Ktrap=ovf -Ktrap=divz -Ktrap=inv -Ktrap=fp  \
-###         -Ktrap=inexact -pc 32 -Mbounds -Mchkfpstk -Mchkptr -Kieee     \
-###         -Minform,inform -Mfree -byteswapio -I$(NETCDF)/include \
+###         -Ktrap=inexact -pc 32 -Mbounds -Mchkptr -Kieee  \
+###         -Minform,inform -Mfree -byteswapio -I$(NETCDF)/include  \
 ###         -I$(IOAPI_ROOT)/Linux2_x86_64pg
-#FFLAGS = -O4 -fastsse -pc 32 -Mfree -byteswapio -I$(NETCDF)/include \
-#         -I$(IOAPI_ROOT)/Linux2_x86_64pg
-#LIBS   = -L$(IOAPI_ROOT)/Linux2_x86_64pg -lioapi \
-#	 -L$(NETCDF)/lib -lnetcdff -lnetcdf
+###FFLAGS = -O4 -fastsse -pc 32 -Mfree -byteswapio -I$(NETCDF)/include \
+###         -I$(IOAPI_ROOT)/Linux2_x86_64pg
+###LIBS   = -L$(IOAPI_ROOT)/Linux2_x86_64pg -lioapi \
+###	 -L$(NETCDF)/lib -lnetcdff -lnetcdf
 
 #...gfortran
-#FC	= gfortran
-#NETCDF = /usr/local/apps/netcdf-4.6.3/gcc-6.1.0
-#IOAPI_ROOT = /usr/local/apps/ioapi-3.2_20181011/gcc-6.1.0
-#FFLAGS	= -O3 -I$(NETCDF)/include -I$(IOAPI_ROOT)/Linux2_x86_64
+###FC	= gfortran
+###NETCDF = /usr/local/apps/netcdf-4.9.2/gcc-8.5
+###IOAPI_ROOT = /usr/local/apps/ioapi-3.2/gcc-8.5
+###FFLAGS	= -O3 -I$(NETCDF)/include -I$(IOAPI_ROOT)/Linux2_x86_64
 ###FFLAGS	= -g -O0  \
 ###          -ffpe-trap='invalid','zero','overflow','underflow'  \
 ###          -I$(NETCDF)/include -I$(IOAPI_ROOT)/Linux2_x86_64
-#LIBS    = -L$(IOAPI_ROOT)/Linux2_x86_64 -lioapi  \
-#          -L$(NETCDF)/lib -lnetcdff -lnetcdf
+###LIBS    = -L$(IOAPI_ROOT)/Linux2_x86_64 -lioapi  \
+###          -L$(NETCDF)/lib -lnetcdff -lnetcdf
 
 #...Intel Fortran
 FC      = ifort
-NETCDF = /usr/local/apps/netcdf-4.7.3/intel-19.0
-IOAPI_ROOT = /usr/local/apps/ioapi-3.2_20181011/intel-19.0
+NETCDF = /usr/local/apps/netcdf-4.9.2/intel-21.4
+IOAPI_ROOT = /usr/local/apps/ioapi-3.2/intel-21.4
 ###FFLAGS  = -g -O0 -check all -C -traceback -FR -I$(NETCDF)/include  \
 ###          -I$(IOAPI_ROOT)/Linux2_x86_64ifort
-FFLAGS  = -O3 -traceback -FR -I$(NETCDF)/include -I$(IOAPI_ROOT)/Linux2_x86_64ifort
+FFLAGS  = -O3 -traceback -FR -I$(NETCDF)/include  \
+	  -I$(IOAPI_ROOT)/Linux2_x86_64ifort
 LIBS    = -L$(IOAPI_ROOT)/lib -lioapi \
-          -L$(NETCDF)/lib -lnetcdff -lnetcdf
+	  -L$(NETCDF)/lib -lnetcdff -lnetcdf
 
 DEFS   = 
 

diff --git a/PREP/mcip/src/mcipparm_mod.f90 b/PREP/mcip/src/mcipparm_mod.f90
@@ -148,6 +148,7 @@ MODULE mcipparm
 !                        with CMAQ. Therefore, the versioning skips from 
 !                        MCIPv5.1 to MCIPv5.3.3. (T. Spero)
 !           12 Jul 2022  Updated version stamp. (M. Mallard)
+!           19 Sep 2024  Updated version stamp. (T. Spero)
 !-------------------------------------------------------------------------------
 
   USE m3utilio, ONLY: mxdesc3
@@ -316,7 +317,7 @@ MODULE mcipparm
 
   CHARACTER(LEN=80)                 :: fdesc      ( mxdesc3 )
   CHARACTER(LEN=16),  PARAMETER     :: progname   = 'MCIP'
-  CHARACTER(LEN=10),  PARAMETER     :: vdate      = '07/12/2022'
-  CHARACTER(LEN=8),   PARAMETER     :: ver        = 'V5.4'
+  CHARACTER(LEN=10),  PARAMETER     :: vdate      = '09/19/2024'
+  CHARACTER(LEN=8),   PARAMETER     :: ver        = 'V5.5'
 
 END MODULE mcipparm