CMAQv5.0 Readme file

README for CMAQv5.0 - 30 January 2012

Shawn Roselle

This README file outlines the steps necessary to build and run the CMAQ version 5.0 (CMAQv5.0) release. The build and run scripts that are included in the tar files are set up to compile and run on Linux (we tested with the Intel Fortran compiler (ifort) version 11.1.059). In case you want to run on another platform, the C-shell scripts are easy to modify for other Unix implementations.

The CMAQv5.0 release is available to the community accompanied by example scripts that invoke a specific configuration of the model. This configuration has been used by U.S. EPA in unit tests, system tests, and for model evaluation prior to the release of the model. There are other features and options within the CMAQ modeling system in this release, beyond this specific model configuration, that have not yet been fully tested, evaluated or documented, that are also available to users. As always, we are interested in feedback from the community on experiences using the CMAQ modeling system.

The distribution package consists of the following files:

• README.pdf - this readme text file

Text files describing updates and model options including:

• CMAQv50_release_notes.pdf
  • PMother_speciation.pdf
  • PM_emitted_species.pdf
  • Emissions_changes_for_CMAQv5.0.pdf
    • GSPRO_pm25_aero6_example.txt
    • GSREF_pm25_aero6_example.txt
  • POA_aging.pdf
  • ISORROPIA2_aqchem_notes.pdf
  • Dust_notes.pdf
  • Updates_to_SOA_yield_parameterization.pdf
  • Chemistry_Notes.pdf
  • LightningNO.pdf
  • Namelists.pdf
  • IOAPI_3.1.pdf
  • SMOKE.pdf
• CMAQv5.0.tar.gz - gzipped tar file containing CVS source code archives for models, tools, and libraries, and C-Shell scripts to build and execute the CMAQ model
• mcip_v4-0.tar.gz - - gzipped tar file for MCIPv4-0

NOTE: You must have CVS, IOAPIv3.1 and netCDF

The following outlines a sequence of steps you can follow to build and run the codes:

1) In a working directory, gunzip and untar the model distribution tar file, CMAQv5.0.tar.gz. This will produce the following subdirectories:

  CMAQv5.0/
           lib/
           models/
           scripts/

2) Edit the file CMAQv5.0/scripts/config.cmaq to set the environment variable for M3HOME, and to setup your computer system information, including compilers and conpiler flags. Environment variables M3MODEL and M3LIB are automatically set in the config.cmaq file.

  source CMAQv5.0/scripts/config.cmaq

3) cd to $M3HOME and gunzip and untar the data tar file, CMAQv5.0.DATA.tar.gz. This will produce the following subdirectories:

  data/
      bcon/   <<<<<<< empty, to be filled by the user
      cctm/   <<<<<<< empty, to be filled by the user
      crop/
      dust/
      emis/
      icon/   <<<<<<< empty, to be filled by the user
      jproc/  <<<<<<< empty
      lightning/
      mcip/
      ocean/
      procan/
      raw/
         phot/

4) Required external libraries.

Library directory: You will need to create the library directory, which depends on the system you are running on and the Fortran compiler you specified in the config.cmaq script. To do this, simply type:

  mkdir -p $M3LIB

netCDF: The scripts assume that netCDF resides in the $M3LIB path as $M3LIB/netcdf. If netCDF is installed elsewhere on your system, create a symbolic link in $M3LIB/netcdf to the existing netCDF.

Example:

  cd $M3LIB
  ln -s /share/linux86_64/wdx/lib/x86_64i/ifc/netcdf-3.6.2 netcdf

Ioapi: CMAQv5.0 requires IOAPI version 3.1, please download and install this library on your system following the instructions provided by the BAMS/IOAPI web site (http://www.baronams.com/products/ioapi).

The CMAQ scripts are setup for the IOAPI library to be installed in the following location:

  $M3LIB/ioapi_3.1

mpich: If you are running multiprocessor application, then the "mpich" library is required. The scripts are setup to link to the mpich libraries in the $M3LIB/mpich directory. Set a symbolic link to the mpich installed on your system.

Example:

  cd $M3LIB
  ln -s /share/linux86_64/wdx/lib/x86_64i/ifc/mpich mpich

5) Next create the stencil exchange library required for parallel processing (se_snl) and serial processing (sef90_noop):

  cd $M3HOME/scripts/stenex
  Execute (type) bldit.se
  Execute (type) bldit.se_noop

6) For parallel CCTM operation create the parallel I/O library (pario):

  cd $M3HOME/scripts/pario
  Execute (type) bldit.pario

7) Create bldmake, the tool required to build the executables for the CMAQ processors, model and tools.

  cd $M3HOME/scripts/build
  execute (type) bldit.bldmake

Note: Although bldmake is really a tool, we put it in with the "libraries."

8) Now create the model executables: ICON and BCON need to be compiled and run separately for profile data (coarse grid) and for nest data (fine grid); CCTM is compiled only once. If you are using the inline photolysis module in the CCTM, then you will not need to run JPROC.

Generally, you will need to get the MCIP4.0 code and run it to create met data from WRF for CCTM. MCIP4.0 can be downloaded from the same site as this distribution package. And of course, you will need "model-ready" emissions data - presumably from SMOKE. See the SMOKE.pdf readme file included with this package.

Start with ICON (cd to $M3HOME/scripts/icon). Invoke "bldit.icon". There will be a lot of text displayed to standard out (which you can capture of course, by redirecting to a file). The process should end with a ICON executable, which is invoked in the second script, "run.icon", producing output data files. These data files will be inserted into the path predefined in the run script ($M3DATA/icon). This will produce the first (profile) dataset for the first run of CCTM on the coarse domain. After CCTM finishes, you will need to generate a nest dataset for the fine domain.

Note: It's always a good idea to capture in a log file the text written to standard out when running these models. In each "run" script, near the top, is a suggested method (e.g. for ICON):

   run.icon >&! icon.log &

9) Check the ICON log file to ensure complete and correct execution. Then cd to $M3HOME/scripts/bcon and follow the same procedure; invoke "bldit.bcon", followed by "run.bcon >&! bcon.log &". This also produces the profile dataset for the a coarse domain run of CCTM. You can use data produced by the CCTM to generate a nested dataset for a finer scale domain.

10) Generate the CCTM executable: Change directory to $M3HOME/scripts/cctm and follow the same procedure, using "bldit.cctm" to generate the executable. The executable is invoked a the second script, "run.cctm". By default, the CCTM runscript is setup for parallel processing.

11) Following completion of the CCTM run, you should have a complete collection of datasets which you can compare with the distribution datasets in M3DATA_REF.tar.gz. Unless you modify the run scripts, the output data from all the models will reside in the following (automatically generated) paths:

   $M3DATA/
          bcon/
          cctm/
          icon/
          jproc/

12) Other details:

• You can check output ioapi file headers (and data) using the netCDF utility ncdump. This utility will be located in the same place as netcdf, mentioned in (4) above.
• The GRIDDESC file contains horizontal projection and grid domain definitions that are required input for many CMAQ models. The run script for CCTM contains the environment variables that point to the GRIDDESC file.
• The horizontal grid definition can be set to window from the met and emissions input files. However, the window must be a "proper subset" (i.e., a subset from the interior of the domain and not including boundaries). Note: The domains represented by the met and emissions data must be the same. Also note that you will need ICs/BCs files that match the window domain.
• Running CCTM for a windowed domain or a higher resolution nested domain from larger or coarser met and emissions datasets requires creating initial and boundary data for the target domain.