README - 20 March 2002 This README file accompanies the Meteorology-Chemistry Interface Processor (MCIP) Version 2 (MCIP2). MCIP2 is part of the U.S. Environmental Protection Agency's Community Multiscale Air Quality (CMAQ) modeling system. MCIP2 is an update to the existing release of MCIP. MCIP2 contains 89 Fortran 90 modules and routines, two Makefiles, and two scripts. MCIP Version 2 (MCIP2) contains the following new features: - Entirely re-engineered code to be dynamically allocatable in Fortran 90. That is, grid specifications and user options are run-time input rather than compile-time input. A single MCIP executable can be used for any MM5 data set regardless of domain size and resolution. Run-time options are communicated via a Fortran namelist that is set from the run script. - Supports both MM5 Version 2 and MM5 Version 3 formatted files. The user does not need to specify the format type. - Includes "pass-through" options for PBL and radiation variables. - Processes additional MM5 output fields from the Pleim-Xiu land-surface model. - Includes new option for Models-3 (Pleim) dry deposition routine. - Includes new 3-D output fields for ice and snow mixing ratios (QI and QS). - Includes new dry deposition velocity fields for atrazine (ATRA), atrazine product (ATRAP), and methanol (METHANOL). - Includes new 2-D output fields for soil moisture (SOIM1 and SOIM2), soil temperature (SOIT1 and SOIT2), and soil texture (SLTYP) when Pleim-Xiu land-surface model is run. - Ability to use multiple (e.g., restart) MM5 input files on the same execution of MCIP. - Ability to process MCIP at coarser time granularity than input MM5. For example, MCIP can generate hourly output if MM5 input is every 30 minutes or 15 minutes. - Ability to print input and output variables for a user-defined grid cell. - Makefiles replace "cfg" file, "m3bld", and "bldit" script to compile MCIP. - Fortran 90 modules replace ".EXT" files that are common to CMAQ system. - Significant cleanup and reorganization of the code has also occurred. MCIP2 can run on UNIX/Linux platforms and on Windows NT. MCIP2 has been tested on Sun, SGI, IBM, Linux, and Windows NT. The following is necessary to run MCIP2: - Fortran 90 compiler - Concurrent Versions System (CVS) software management tool - Network Common Data Form (NetCDF) libraries - Either Models-3 Input/Output (M3IO) or Input/Output Applications Programming Interface (I/O API) libraries See ftp://ftp.epa.gov/amd/stand_alone_models3/cmaq/CVS_NETCDF for information on acquiring and installing CVS and NetCDF. M3IO libraries are typically installed with the CMAQ system under the "tools" subdirectory at the top level of the CMAQ installation (e.g., environment variable M3HOME). I/O API libraries can be obtained from MCNC at http://www.emc.mcnc.org. This release of MCIP2 contains a single file, MCIP2.tar.gz. This compressed file contains a CVS-ready archive to install as "MCIP2" in the "models" subdirectory at the top level of the CMAQ installation (e.g., environment variable M3HOME). There are no binary files (executables, libraries, or sample data) in this file. The compressed tar file is 0.16 MB; the uncompressed tar file is 1.05 MB. To install MCIP2 on a UNIX/Linux system, do the following. (The commands will be similar but not identical for Windows NT.) - Change directory to the "models" subdirectory at the top level of the CMAQ installation. This directory may be accessible by the M3MODEL environment variable. - Download the MCIP2.tar.gz file to that directory. - Type "gunzip MCIP2.tar.gz" to uncompress the file. (On Windows NT, use "pkunzip"). - Type "tar xf MCIP2.tar" to create a new model, MCIP2. (The previous release of MCIP will remain unchanged.) MCIP2 will contain CVS control information, and a subdirectory "src" that has two further subdirectories, "mcip2" and "doc". The "mcip2" and "doc" directories contain the two CVS modules that you will extract. (On Windows NT, "pkunzip" will take care of this step.) - Move outside the M3MODEL path, and create a new directory where you want to extract and build MCIP2. Change to the new directory. - To extract the code from the new CVS archive, set the environment variable CVSROOT to the top of the MCIP2 installation: setenv CVSROOT $M3MODEL/MCIP2 (UNIX) set CVSROOT=:local:c:\%M3MODEL%\MCIP2 (Windows NT) - Extract the two MCIP2 modules from the CVS archive. "HEAD" will acquire the most current update to that module. This extraction from the CVS archive will put all of the files together in your new working directory. cvs export -r HEAD -d . mcip2 cvs export -r HEAD -d . doc - Modify the Makefile for your machine, library locations, and compile options. (Makefile.nt is for Windows NT.) If necessary, comment out the "default" options using "#" and uncomment the options for your machine. Add the paths and names of the NetCDF and M3IO (or I/O API) libraries in the locations they exist on your machines. You can substitute the explicit paths of the libraries for the environment variables in the Makefile. Note that Makefiles are sensitive to the use of tabs, so take special caution when editing the Makefile. - Compile MCIP2 by typing "make". (On Windows NT, use "nmake".) The executable will be "mcip.exe". - Modify the run script (run.mcip) to reflect the locations of your files, your user options, and your time period of interest. There are several comments in run.mcip to guide your selections. (The script run_mcip.bat is for Windows NT.) - Execute the MCIP2 script by typing "run.mcip >& mcip.log". (On Windows NT, "run_mcip > mcip.log".) This release of MCIP2 was developed by Tanya Otte (U.S. EPA Office of Research and Development). Additional contributions toward this release were provided by members of the U.S. EPA/ORD/National Exposure Research Laboratory Atmospheric Modeling Division CMAQ Development Team. A team of 30 volunteers representing various facets of the CMAQ user community participated in a three-phase beta-testing process for MCIP2. The beta testing team provided invaluable feedback that contributed to a more robust release of MCIP2.