CMAQ OGD Updates

Chapters 1-6 and 10 have been updated.

Liz: please update Chapters 7, 8, and 11. I started on Chapter 7 (I went through BCON); please take over and cover CALMAP to the end.

Zac: I will do chapters 9, 12, 13, and 14.

Please try to complete the content on these chapters by January 27

[lizadams]

Tasks for Chapter 4: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_ch04_science.md

• review and update the following statement:
  CMAQ is currently distributed with IC and BC profiles for the CB05, SAPRC-07T, and SAPRC-99 photochemical mechanisms and the CMAQ AERO6 aerosol module.
• Compare with Mechanisms tested and listed in Table 2.1 in our work plan document: https://documentation-cempd.vipapps.unc.edu/index.php/CMAQv5.2_Release_Workplan#Procedure
• Review and update PROCAN: Process-analysis preprocessor
• Review and update Lightning flash count preprocessor
• Review and update "The CMAS Center currently fully supports CMAQ on Linux systems using the Gnu, Portland Group, and Intel Fortran compilers. The CMAS Center no longer supports compiling and running CMAQ on other UNIX operating systems.

[lizadams]

Tasks for Chapter 7: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_ch07_programs_libraries.md

• Put links to the Release Notes where significant changes have been made to the programs
• Revise following section: The program LTNG_2D_DATA converts monthly lightning flash counts and ratios of cloud-to-cloud and cloud-to-ground flashes into an input file for CCTM (prior to CMAQv5.2).

Hold off on any changes to the LTNG_2D_DATA program section. This may be removed entirely in CMAQv5.2b.

• should I take out references to saprc99_ae6_aq mechanism (as it is not available in CMAQv5.2)
• put in link to this mechanism table: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/Release_Notes/CMAQv5.2_Mechanisms.md
• change $M3HOME to $CMAQ_HOME
• IOAPI_ISPH: [default: 19] - change this default setting to 20
• update description of CALMAP files (??)
• update list of mechanisms listed in this section: CMAQ is distributed with ASCII vertical profiles representing clean continental BCs for North America for the following chemical mechanisms: cb05_ae6_aq, saprc07t_ae6_aq, saprc99_ae6_aq, and racm2_aq6_aq.
• need the BCON and other preprocessor run scripts to review and update the environment variable settings
• add internal links between each program, is JPROC to the section in Chapter 7 where this program is discussed.
• where is the PROCAN build script? (don't see it in the distribution) (removed)
  Remove all references to PROCAN. It's no longer part of the CMAQ distribution.
• where is the PROCAN run script? "" (removed from documentation)
  See above
• section on building STENEX needs to be revised, is the src code for STENEX compiled by the bldit.cctm or is there a separate STENEX build and run script -(where is it located in the distribution?) (removed)
  Remove all references to STENEX and PARIO as needing to be built. They are compiled automatically in the CCTM build.

These are the available BLDIT scripts in the POST and PREP directories:
POST/appendwrf/scripts/bldit.appendwrf
POST/appendwrf/scripts_sol/bldit.appendwrf
POST/bldoverlay/scripts/bldit.bldoverlay
POST/bldoverlay/scripts_sol/bldit.bldoverlay
POST/block_extract/scripts_sol/bldit.block_extract
POST/combine/scripts/bldit.combine
POST/combine/scripts_sol/bldit.combine
POST/combine/scripts_v51/bldit.combine
POST/hr2day/scripts/bldit.hr2day
POST/hr2day/scripts_sol/bldit.hr2day
POST/sitecmp_dailyo3/scripts/bldit.sitecmp_dailyo3
POST/sitecmp_dailyo3/scripts_sol/bldit.sitecmp_dailyo3
POST/sitecmp/scripts/bldit.sitecmp
POST/sitecmp/scripts_sol/bldit.sitecmp
POST/writesite/scripts/bldit.writesite
POST/writesite/scripts_sol/bldit.writesite
PREP/bcon/scripts/bldit.bcon
PREP/icon/scripts/bldit.icon
PREP/jproc/scripts/bldit.jproc

• review above bldit scripts and see if they are all described somewhere in the OGD

[lizadams]

• need a way to link to a section within a Chapter in the OGD
  (tried using the following syntax from within Chapter 7 to link to a table in Chapter 5 and it worked!)
  [Chapter 5](CMAQ_OGD_ch05_sys_req.md#Table5-3)
  Next need to see if the same thing works with header sections
  Chaper 9 has a header with the following title: Grids and coordinate systems
  The way to reference that section of the document in Chapter 8, I used the following:
  [Grids and coordinate systems](CMAQ_OGD_ch09_grid_defn.md#grids-and-coordinate-systems)

[lizadams]

Tasks for Chapter 8: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_ch08_input_files.md

• add link to CMAQv5 release notes
• removed / or escape symbol (holdover from wiki) from the filenames to make them easier to read
• changed
  <span id=Table6-1></span> to <a id=Table6-1></a>
  so that references to the table would work
• search for the work Section in the markdown document and then replace with appropriate link within a chapter @CMASCenter - I still need to complete this.
• review OMI file: OMI_1979_to_2015.dat (https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/Release_Notes/In-Line_Photolysis_Updates_to_the_OMI_data_file.md)
  note - release notes indicate that newer data have increased (daily) temporal resolution (the temporal resolution in the OGD is listed as annual.
  I am not sure what the yeardate convention is for this file, but it changes as described in the release notes in 2009. Values before 2009.953 have -1 as a missing data, values after that yeardate do not have -1 as missing data but use previous days value. Note, there are 17 different longitude values for each yeardate in the file at 80 degree North Latitude. (longitude values: 80, 70, 60, 50, 40, 30, 20, 10, 0, -10,... -80)
  grep by year reveals 2010 had 6205 records (6205/17) = 365 days ( all days of year)
  grep by year reveals 2006 had 816 records (816/17) = 48 days (4 days per month)
  yeardate latitude 180.0Z 157.5W 135.0W 112.5W 090.0W 067.5W 045.0W 022.5W 000.0Z 022.5E 045.0E 067.5E 090.0E 112.5E 135.0E 157.5E 180.0Z
  2009.953 -80 327 316 292 264 244 256 261 310 322 317 272 265 283 304 319 322
  2009.9658 80.0 350 351 352 355 355 355 347 348 347 344 343 343 343 344 346 348 350
  Note, the release notes and the OGD do not specify the source of the data, but this link has an image of OMI data and also indicates that OMI data is missing for 1995, which is also true for the dataset provided here: http://earthobservatory.nasa.gov/Features/WorldOfChange/ozone.php
• edit Lightning NOx emissions section to match Release Note: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/Release_Notes/Lightning_NOx.md
  Need to review and document format of the new input file
• review changes to input files and environment variables mentioned here: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/Release_Notes/PM_Diagnostic_Files.md
  We don't appear to have the outck_bidi.q file in our testing area, and also not all of the environment variables and/or file names are being used in our run script.
  Checked FILES3_CTM.EXT and it has the following logical names defined: (this differs from the names listed in the Release Notes..
  CTM_APMDIAG_1
  CTM_AVIS_1

1. GRID_CRO_3D (need an example to document what is in this file- not available in the benchmark case)
2. OCEAN_1 (description says CCTM is compiled with AERO5 or AERO6, it will expect the OCEAN_1) - doesn't it always expect the ocean file?)

Note: the following are output files. There isn't a table of Output files, just a listing of them.

1. MET_BDY_2D - need to add content
2. CTM_DRY_DEP_1 - add content
3. CTM_WET_DEP_1 "
4. CTM_MGEM_1 "
   note LTNGOUT isn't in the FILES3_CTM.EXT file.
   Figures in Chapter 8 were missing from the OGD: https://www.airqualitymodeling.org/index.php/CMAQ_version_5.0_(February_2010_release)_OGD#CMAQ_FILES

• Need to re-create the figures:

1. Figure 8-1. Illustration of CMAQ boundary condition file
2. Figure 8-2. Graphical example of a CMAQ gridded boundary conditions file
3. Figure 8-3. Graphical example of a CMAQ gridded initial conditions file

• compare files listed in ./src/ICL/fixed/filenames/FILES_CTM.EXT with list of filenames in table 8.1 (this table should probably be split into multiple tables (one for each program)
• Review format of CSQY file. Table 8-7. CSQY format description doesn't match what is in the CSQY file now. There are additional vlaues, ie. NPHOTAB, NTEMP, and
  to make this easier, we could do the format of the table.
• provided a link under Table 8-7 to an example CSQY file in the github repository. https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/src/MECHS/cb05e51_ae6_aq/CSQY_DATA_cb05e51_ae6_aq
• don't seem to have access to an example TOMS file - mentioned as input to JPROC
• don't seem to have access to InTerFile from mcip run script: set InTerFile = $InTerDir/geo_em_d01.nc
• don't seem to have access to InSatfiles
• Need to review entire DUST_LU_2 section.
• replaced outdated links to SMOKE User Manual and to Spatial Allocator User Manual.
• changed to using relative links so that when code is pushed to EPA, the links will point to their repository 1cb7e38

[lizadams]

Tasks for Chapter 4: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_ch04_science.md

• reviewing modules - are all of the directories under CMAQ_v5.2Beta/CCTM/src considered a module?

[lizadams]

Tasks for Release Notes: https://github.com/CMASCenter/EPA-CMAQ/tree/5.2Beta/CCTM/docs/Release_Notes

• links to the Relevant Pull Requests for each Release Note are broken. For example the Pull Request on the AH3OPJ_IEPOX_update.md points to the following: https://github.com/usepa/cmaq_dev/pull/105 - which doesn't seem to exist (or only exists on the EPA internal github site).
  Above the pull request it does say "internal reference" so this may be enough of an explanation. cmaq_dev maybe the internal EPA archive? We'll need to check with them to see what these pull request are

• (remove this section)

[lizadams]

Tasks for Chapter 11:

• add code block using

code section....

• review Coding Guidelines
• find and update link to Section 9.xxx
• replace Code Example VDIFF from CMAQ v4.7 with the following: CCTM/src/vdiff/acm2/vdiffproc.F
  (illustrates a science process class-driver Fortran 90 subroutine)
  is this the best example to use?
• run.cctm script provided in the distribution needs to have it's header fixed. It currently contains:
  # ====================== CCTMv5.1 Run Script ======================

needs be changed to
# ====================== CCTMv5.2 Run Script ======================

• @CMASCenter - there is a reference to the github CMASCenter site in this section. This leads to a question of whether EPA wants to have folks submitting pull requests directly to them, or if they want the community to first issue a pull request to us, and have us go thru testing the submitted code and then after it passes a set of checks/or QA procedures, for us to submit the request to EPA

[lizadams]

• Do we have or need contents for this chapter: (CMAQ_OGD_ch14_input.md) Information on how to develop the meteorology and emissions for CMAQ

[lizadams]

Tasks for Chapter 2: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_ch02_overview.md

• Lightning Data Preprocessor (LTNG_2D_DATA)
  is this still supported or is it being replaced by the inline lightning process??

It is being replaced but I haven't seen with what. Let's leave in this content for now and we can replace/remove later.

[lizadams]

Tasks for Quickstart guide: https://github.com/CMASCenter/EPA-CMAQ/blob/5.2Beta/CCTM/docs/User_Manual/CMAQ_OGD_quick_start.md

• we reference the CMASCenter github site, rather than EPA's when telling folks to clone the code: git clone -b 5.2Beta https://github.com/CMASCenter/EPA-CMAQ.git
  @CMASCenter This relates to the same question for Chapter 11, does EPA want folks to clone the code from the CMASCenter, or from their Site. Do they want folks to submit pull requests directly to them? Will the CMASCenter staff be helping to QA and/or test community submitted pull requests, or will this be handled primarily by EPA?