4.5. How to use SMOKE

4.5.1. Change Assigns file to set scenario names, grid names, and other case-specific configuration information
4.5.2. Use new inventory data
4.5.3. Select which pollutants in the inventory are kept
4.5.4. Set fallback stack paramaters
4.5.5. Changing output and intermediate directory names
4.5.6. Change which programs are run
4.5.7. Set up country codes, state codes, or county codes
4.5.8. Set up list of known SCCs and ORIS IDs
4.5.9. Use a new modeling grid or change spatial inputs (anthropogenic and biogenic)
4.5.10. Use a different speciation mechanism or change speciation inputs
4.5.11. Use projection
4.5.12. Use MOBILE6 for on-road mobile sources
4.5.13. Change temporal processing
4.5.14. Use Elevpoint for selecting elevated and PinG sources
4.5.15. Use BEIS2
4.5.16. Use BEIS3
4.5.17. Change meteorology data
4.5.18. Model for CMAQ and MAQSIP
4.5.19. Model for UAM, REMSAD, and CAMX
4.5.20. Determine if a run worked correctly and troubleshoot
4.5.21. Change reports

This section builds on the previous section to describe how to use the SMOKE files, scripts, and programs to create emission inputs for your air quality model. The first part of setting up SMOKE for a case other than the test case that comes with SMOKE is to create an Assigns file and script files for your case. If you have not read through the earlier parts of this chapter, we recommend that you do so. There are some critical points that you need to understand about the Assigns file and scripts. In Section 4.1, “Introduction”, we have described that an Assigns file must always be used when starting to work with SMOKE and the UNIX commands to do that. In Section 4.3, “Script descriptions”, we have already described the purpose and use of the Assigns file and scripts, so please refer to that section for more information on these.

You may use this section as a step-by-step guide for all of the changes that you need to make to the scripts and files for running SMOKE. If you read it straight through and follow all of the steps that apply to your situation, then you will have set up SMOKE for your modeling case. If you are already familiar with SMOKE, you may also use this section as a reference for changing specific parts of the configuration to meet specific needs.

To create your own scripts and use your own data for the first time, you must take the following steps:

  1. Copy the example Assigns file to your own copy. The name of the Assigns file is not critical to the success of this step, but it is useful to name the file something that you will be able to identify easily for the modeling case for which it will be used.

    cp ASSIGNS.nctox.cmaq.cb4p25.us12-nc <yourfile>

  2. Modify the necessary features of the Assigns file for your case. For example, change the scenario names, episode dates, duration, grid name, or speciation name. Some of these changes require additional input files. See Section 4.5.1, “Change Assigns file to set scenario names, grid names, and other case-specific configuration information” for more details on the settings that you can change and the values to use for each.

  3. Invoke the Assigns file. This will create all of the input and output directories that you will need to set up your case:

    source <yourfile>

  4. Copy the appropriate nctox scripts to your own scripts, change the Assigns file listed in the script to the one that you created in the previous step.

  5. Using one or more of the subsections in this chapter, create your input files and change the options in the scripts. The subsections below explain what files and settings need to be changed and checked for many types of operations for configuring SMOKE.

You need not always start from the example Assigns file. Once you have your own case-specific Assigns files, you may use them as starting points for creating other files.

4.5.1. Change Assigns file to set scenario names, grid names, and other case-specific configuration information

This subsection provides an overview of all of the Assigns file settings that you may need to change. The remaining subsections in this chapter include more detail about the changes as associated with specific modeling needs. For example, Section 4.5.10, “Use a different speciation mechanism or change speciation inputs” explains how to change the Assigns file to set different chemical mechanisms as well as all of the files needed.

In the 5-step list provided in the previous section, note that the Assigns file must first be changed (step 2) and then invoked (step 3) to create the input and output directories for your case. Ideally, all of the settings in the list below would be done in step 2 before step 3 is performed. If this is not possible, however, you should at a minimum set the first five items on the list below before moving to step 3. These are the variables that affect the input and output directory names, so if they are set, then the directories that you need to use will for all other configuration steps will be set up for you.

The list below provides the typical settings that may need to be changed to be consistent with the case that you need. Each item in the list references a different section of this chapter and Table 4.1, “Variable in Assigns file for naming files and directories” or Table 4.2, “Variables in Assigns file for controlling time period and grid of processing” for more information. The variables in the Table 4.1, “Variable in Assigns file for naming files and directories” are used for naming files and directories. Table 4.2, “Variables in Assigns file for controlling time period and grid of processing” includes the settings for controlling the time period and grid of your SMOKE runs.

The checklist of major Assigns settings to change is:

  1. Change the INVID, INVEN, and INVOP values to a new inventory name. The simplest approach is to set these three variables to the same name, but different names can be used. Examples of which files or directories are affected by these settings are provided in Table 4.1, “Variable in Assigns file for naming files and directories”. See also Section 4.5.2, “Use new inventory data”.

  2. Change the ABASE, BBASE, MBASE, PBASE, and EBASE values to a new scenario name. The simplest approach is to set these three variables to the same name, but different names can be used. Examples of which files or directories are affected by these settings are provided in Table 4.1, “Variable in Assigns file for naming files and directories”. See also Section 4.5.2, “Use new inventory data”.

  3. Change the METSCEN value to your meteorology scenario name. This will affect the name of the input directory for the meteorology files (the $METDAT directory, which can be a linked directory if you do not want to install your meteorology files under the SMOKE directory structure).

  4. Change the SPC value to one of the supported speciation mechanisms (see Section 4.5.10.1, “Choosing from default mechanisms”) or to a new speciation mechanism (see Section 4.5.10.2, “Setup of new mechanism or changing an existing mechanism”).

  5. Change the GRID and IOAPI_GRIDNAME_1 values to the grid names for naming files. See also Section 4.5.9, “Use a new modeling grid or change spatial inputs (anthropogenic and biogenic)”.

  6. Change the run period naming settings ESDATE and NDAYS (see Table 4.1, “Variable in Assigns file for naming files and directories”). See also Section 4.5.13.4, “Changing the dates, times, and duration of model-ready SMOKE emissions files”.

  7. Change the episode settings EPI_STDATE, EPI_STTIME, EPI_RUNLEN, and EPI_NDAY and the run period settings G_STDATE, G_STTIME, and G_RUNLEN. See Table 4.2, “Variables in Assigns file for controlling time period and grid of processing” and Section 4.5.13.3, “Changing the episode” and Section 4.5.13.4, “Changing the dates, times, and duration of model-ready SMOKE emissions files”.

  8. Change the YEAR value to the year of your base case inventory. In addition to being used in file names, this variable is used to automatically set the EF_YEAR variable in Table 4.2, “Variables in Assigns file for controlling time period and grid of processing”.

Table 4.1. Variable in Assigns file for naming files and directories

Environment Variable Description
INVID Inventory input directory identifier. Controls directory path of input inventory. INVDIR = $SMKDAT/inventory/$INVID
INVOP Base year inventory output name. Controls output file names for SMOKE intermediate inventory files and other output files from Smkinven and inventory-only reports from Smkreport. This variable is used to initialize the FYIOP variable, which is also used in the Assigns file and is equal to INVOP for base case modeling. FYIOP is reset by the set_case.scr helper script (see Section 4.3.4, “Script settings” documentation on FYEAR and CNTLCASE)
INVEN Base year inventory name, with version. Controls directory path of output inventory. INVOPD = $SMKDAT/inventory/$INVEN
ABASE Scenario identifier for area/non-point and nonroad mobile sources. Controls output file names and directories for outputs from SMOKE programs other than Smkinven (e.g., locations and file names of all matrices, hourly emissions, model-ready files). This variable is used to initialize the ASCEN variable, which is also used in the Assigns file and is equal to ABASE for base case modeling. ASCEN is reset by the set_case.scr helper script (see Section 4.3.4, “Script settings” documentation on FYEAR and CNTLCASE). Should be set to the same value as BBASE, MBASE, PBASE, and EBASE for the basic configuration.
BBASE Scenario identifier for biogenic sources that works the same way as ABASE, but affects the BSCEN variable.
MBASE Scenario identifier for on-road mobile sources that works the same way as ABASE, but affects the MSCEN variable.
PBASE Scenario identifier for on-road mobile sources that works the same way as ABASE, but affects the PSCEN variable.
EBASE Scenario identifier for merged emissions sources. Controls output file names and directories for outputs for final model-ready files. Sets the path for the STATIC, SCENARIO, and OUTPUT directories and file names for the merged outputs for multiple source categories from the Smkmerge program (e.g., the EGTS3D_L file).
METSCEN Meteorology scenario name. Sets the METDAT directory for the MCIP meteorology files and can be used to set the meteorology file names (not done in example nctox scripts). Also helps set names for meteorology-dependent SMOKE intermediate files for biogenics (Tmpbeis3 outputs B3GTS_S and B3GTS_L), on-road mobile (Temporal output MTMP), and point (Laypoint outputs PLAY and PLAY_EX).
GRID Grid name used for naming files that depend on the selected grid. User must coordinate GRID settings with IOAPI_GRIDNAME_1 setting Table 4.2, “Variables in Assigns file for controlling time period and grid of processing”. Dependent files include gridding and ungridding matrices, gridded land use and biogenic emissions, hourly mobile emissions, layer-fractions files, model-ready emissions, and some reports.
SPC Speciation profile name for selecting input files and naming output files and directories that depend on the chemical mechanism. This setting can be overridden by the SPC_OVERRIDE script setting (see Section 4.3.4, “Script settings”). The SPC setting sets input files GSPRO and GSREF; speciation matrix intermediate file names, and output directories OUTPUT, A_OUT, B_OUT, M_OUT, N_OUT, and P_OUT.
ESDATE Starting date for first modeled period in episode. Has format YYYYMMDD where YYYY is the 4-digit year, MM is the two-digit month (e.g., 07 for July), and DD is the two-digit day (e.g., 01 for the first). Users should coordinate this with the G_STDATE setting Table 4.2, “Variables in Assigns file for controlling time period and grid of processing”. The Assigns file resets this variable if the G_STDATE_ADVANCE variable is set by a calling script (see Section 4.3.4, “Script settings”).
MSDATE Meteorology file dates. This variable can be used to help name time-dependent meteorology files or directory names. In the example scripts for the nctox case, however, this variable is not used and the G_STDATE variable is used instead.
NDAYS Number of days in a modeling period. To break up a modeling episode into multiple modeling periods of one or more days, the user must set and coordinate this setting with the G_RUNLEN setting Table 4.2, “Variables in Assigns file for controlling time period and grid of processing”. NDAYS represents the number of days indicated in hours by the G_RUNLEN variable. NDAYS is used for naming hourly emissions files output from the Temporal program, biogenic outputs from Tmpbio, layer fractions files from Laypoint, and model-ready emissions files from Smkmerge.
YEAR Base case modeling year. This setting is used to set several things in coordination with the FYEAR and SMK_FUTURE_YN script settings (see Section 4.3.4, “Script settings”). For base case modeling, it sets the EF_YEAR setting that controls Emisfac. For growth modeling, it is used in the file name for the GCNTL input file, set by the growth/control example nctox scripts. This setting can be overridden by the YEAR_OVERRIDE setting, also described in Section 4.3.4, “Script settings”. Lastly, it is used to set the file name for the winter/summer designations file output from Metscan, called the BIOSEASON file.

Table 4.2. Variables in Assigns file for controlling time period and grid of processing

Environment Variable Description
G_STDATE Julian starting date of first modeled period in episode. Has format YYYYDDD where YYYY is a 4-digit year and DDD is a 3-digit Julian date (e.g., 001 for the first day of the year). Users should coordinate this with the ESDATE setting Table 4.1, “Variable in Assigns file for naming files and directories”. The Assigns file resets this variable if the G_STDATE_ADVANCE variable is set by a calling script (see Section 4.3.4, “Script settings”). Controls operation of time-dependent programs Temporal, Tmpbio, Laypoint, and Smkmerge.
G_STTIME Start time of each period in the episode. Has format HHMMSS where HH is a 2-digit hour (leading zero not required), MM is a 2-digit minute (set to 00 for SMOKE), and SS is a 2-digit second (set to 00 for SMOKE).
G_RUNLEN Duration of each run period in episode. To break up a modeling episode into multiple modeling periods of one or more days, the user must set and coordinate this setting with the NDAYS setting Table 4.1, “Variable in Assigns file for naming files and directories”. G_RUNLEN has format HHHHMMSS, where HHHH is a 4-digit duration in hours (leading zeros not required), MM and HH should be set as for G_STTIME. G_RUNLEN controls the duration modeled for each run of the Temporal, Tmpbio, Laypoint, and Smkmerge programs. Must be set one hour greater than the number of days times 24 (e.g., a two-day period length is 2 x 24 + 1 = 49).
G_TSTEP Time step. Has format HHMMSS with format the same as described for G_STTIME. The current version of SMOKE allows this setting to only be 10000, for hourly timesteps.
EPI_STDATE Episode start date. Has the same format as G_STDATE. Does not change during the course of an episodic run. In the Assigns file, should be set the same as G_STDATE.
EPI_STTIME Episode start time. Has the same format as G_STTIME. Does not change during the course of an episodic run. In the Assigns file, should be set the same as G_STTIME.
EPI_RUNLEN Episode duration. Has the same format as G_RUNLEN. Does not change during the course of an episodic run. In the Assigns file, should be set for the entire duration of the modeling episode, which must be greater than or equal to G_RUNLEN minus one hour, is limited to at most one year, and for best results, should be a multiple of G_RUNLEN minus one hour. For example, if G_RUNLEN is 250000 (one day plus the required one additional hour), EPI_RUNLEN must be at least 240000 and at most 365 x 240000 = 87600000. This example would run an annual episode using 24-hour run periods.
EPI_NDAY The number of days in the episode. Should be the value of EPI_RUNLEN divided by 240000. This settings controls for how many days to use the automatic looping in the example scripts, which loops over all of the periods (set by G_RUNLEN) during the episode (set by EPI_RUNLEN).
EF_YEAR The emission factor year. Controls the year for which emission factors are generated by MOBILE6 via the Emisfac program. This is set automatically by the Assigns file based on the YEAR setting (see Table 4.1, “Variable in Assigns file for naming files and directories”).
IOAPI_GRIDNAME_1 The selected grid. Controls which grid will be selected by the Grdmat program from the GRIDDESC file. Users should coordinate this setting with the GRID setting from Table 4.1, “Variable in Assigns file for naming files and directories”, which is used for naming files. This setting must match the grid names in the gridded land use and spatial surrogates files’ headers.