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.2.2, “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:
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.cb05_soa.us12-nc <yourfile>
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.4.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.
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>
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.
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.
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.4.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:
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.4.2, “Use new inventory data”.
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.4.2, “Use new inventory data”.
Change the METSCEN value to your meteorology scenario name. This will affect the name of the input directory for the meteorology files (the
$METDAT
Change the SPC value to one of the supported speciation mechanisms (see Section 4.4.10.1, “Choosing from default mechanisms”) or to a new speciation mechanism (see Section 4.4.10.2, “Setup of new mechanism or changing an existing mechanism”).
Change the GRID and IOAPI_GRIDNAME_1 values to the grid names for naming files. See also Section 4.4.9, “Use a new modeling grid or change spatial inputs (anthropogenic and biogenic)”.
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.4.13.4, “Changing the dates, times, and duration of model-ready SMOKE emissions files”.
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.4.13.3, “Changing the episode” and Section 4.4.13.4, “Changing the dates, times, and duration of model-ready SMOKE emissions files”.
Change the YEAR value to the year of your base case inventory.
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 = |
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.2.4, “Script settings” documentation on FYEAR and CNTLCASE)
|
INVEN |
Base year inventory name, with version. Controls directory path of output inventory. INVOPD = |
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.2.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 matrix, 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.2.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.2.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.2.4, “Script settings”). 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.2.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.2.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).
|
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.
|