(part of the AQMEII-NA_N2O family of projects)

table of contents


Project for building and running version=5.0.1 of the CMAQ chemistry-transport model (aka "the model"). Requirements include:

  1. Source code is in the submodules CCTM, ICL, MECHS.
  2. BLDMAKE is also required for the CMAQ model builder.
  3. Über-configuration files are in project=CMAQ-build:



The code is currently setup to run (and has successfully run) on the EPA AMAD HPCC host=infinity. To run there (presuming that

  • not much has changed
  • your permissions are like mine
  • lots of other assumptions hold that probably don't :-)

you can skip the first step.

  1. Setup (with consistent compile/link settings!) the required libraries on your build machine, to which one must point with M3LIB. This will probably be your major challenge; fortunately, the fine folks on m3user@listserv.unc.edu are often helpful with that.
  2. Setup your build space. This step can be automated with build_CCTM_driver.sh.
    1. Create some root directory/folder for your build (e.g., /tmp/CMAQ) and move to it. This root folder will become your M3HOME, hence we will denote its path thusly.
    2. Into your ${M3HOME}, clone as peers (i.e., both first-level-subfolders of the root folder)
      1. this project=CCTM-build
      2. project=CMAQ-build
  3. Edit build properties.
    1. Edit your ${M3HOME}/CCTM-build/CCTM_utilities.sh so as to
      • properly set CCTM-wide configuration variables (e.g., APPL).
      • determine which of the following *config.cmaq* files to use.
    2. Edit your über-config files:
      • These files set your CMAQ first-order über-configuration variables (e.g., M3LIB). There are two:
      • It should only be necessary to edit one, depending on whether you want to build with bash (which you should) or csh (if you are tradition-bound). Unfortunately, presently, our build processes are a mixture of both: not all the bldit* scripts have been rewritten bash-style.
    3. Edit your ${M3HOME}/CMAQ-build/config.cmaq.sh or ${M3HOME}/CMAQ-build/config.cmaq (csh-based)

build CCTM

  1. Edit your CCTM builder ${M3HOME}/CCTM-build/build_CCTM.sh to appropriately set build-specific configuration variables for your platform and runtime specifications.
  2. Run your saved ${M3HOME}/CCTM-build/build_CCTM.sh to build your CCTM.

run CCTM

  1. Take a look at your ${M3HOME}/CCTM-build/outck.q: it doesn't do much, but you may need to edit it. (Until I make it go away!)
  2. Edit your CCTM runner ${M3HOME}/CCTM-build/run.cctm to appropriately set run-specific configuration variables for your platform and runtime specifications.
  3. Run your saved run.cctm (or drivers) to run your CCTM.

analyze output

If you want to compare your run's output with "golden" reference values (e.g., for the CMAQ benchmark), consider using code like bias_probe_driver_driver.sh to drive bias_probe_driver.sh to drive bias_probe.ncl to "probe" your "biases" (i.e., the differences between your actual and reference output).


I'm currently versioning using git branching, I currently branch the entire CMAQ-build project family when I do so, using repo_branch.sh.

CMAQ-5.0.1 benchmark

Analysands above were from benchmark run of build from branch=CMAQ-5.0.1_benchmark_runs_Nov_2013.


The initial run of AQMEII-NA_N2O_2008 used branch=AQMEII-NA_N2O_2008_0 (which is also master, at least for now).


  1. Move all these TODOs to issue tracker
  2. Make build fully bash-based. Probably requires changes to bldmake or bldit.cctm, since they expect csh (?)
  3. Implement run_CCTM.sh (very preliminary non-version saved here, just so I don't lose it) for both {CMAQ benchmark, "real" run}.
  4. bias_probe* issues:
    1. write analysis spreadsheets programmatically, add finer-grained stats (e.g., deciles instead of quartiles), add variation measures (e.g., σ)
    2. write the calculated relative bias, use that to plot (in R?) locations with large biases
    3. integrate bias_probe* into run_CCTM.sh
  5. Refactor away bldit.cctm: it should already be vestigial WRT envvar setting, so just do (in build_CCTM.sh) whatever bldit.cctm is doing that build_CCTM.sh is not already doing.
  6. Refactor away outck.q: it doesn't do much, so just do in run.cctm (and ultimately run_CCTM.sh--see above) whatever outck.q is doing that run.cctm is not already doing.