ch04_scripts.xml

<?xml version="1.0" encoding="UTF-8"?>

<chapter id="ch_scripts">

<title>How to Use SMOKE</title>

<section id="sect_scripts_introduction">

<title>Introduction</title>

<para>In this chapter, we provide information about using the UNIX scripts that come with SMOKE to run the test cases and adapting the scripts to run any case. There are several features of these scripts that specifically support SMOKE v1.5 and later, and using scripts developed for earlier versions of SMOKE will not work without adaptations. We provide a section in this document that explains what changes need to be made to users&rsquo; existing scripts to allow them to work with SMOKE. Alternatively, current users can adapt the new example scripts to their case. New users are advised to create their scripts based on the example scripts, following the instructions included in <xref linkend="sect_scripts_how_use_smoke" /> this chapter.</para>

<para>For all SMOKE users, a critical file to use and know about is the Assigns file. If you have followed the SMOKE installation instructions, then your Assigns file will be located in the directory: <filename class="directory"><envar>$SMK_HOME</envar>/subsys/smoke/assigns</filename> where the <envar>SMK_HOME</envar> directory is set in your <filename>.cshrc</filename> file in your home directory, during the SMOKE installation process.</para>

<para><emphasis role="bold">When using SMOKE, the first thing that you should do is go to the Assigns directory and invoke the Assigns file for the case that you will be working with. This step needs to be taken in every UNIX window from which you intend to run SMOKE.</emphasis></para>

<para>To invoke the Assigns file, use the following commands:</para>

<para><userinput><command>cd</command> <filename class="directory"><envar>$SMK_HOME</envar>/subsys/smoke/assigns</filename></userinput> <emphasis>(this changes to the correct directory)</emphasis></para>

<para><userinput><command>source</command> <filename>ASSIGNS.nctox.cmaq.cb05_soa.us12-nc</filename></userinput> <emphasis>(this invokes the default assigns file)</emphasis></para>

<para>Doing this will set a large number of environment variables that you will then have available for navigating the SMOKE directory structure. <xref linkend="tbl_scripts_variables_files" /> and <xref linkend="tbl_scripts_variables_time" /> in <xref linkend="sect_scripts_change_assigns" /> list those environment variables. The environment variables used to build some of the directory names are also set by the user in the Assigns file and described in that section.</para>

</section>

<section id="sect_dirs_example_data_files">

<para>Many of the support files used in the test cases are based on the EPA&rsquo;s NEI modeling platform, available online at EPA&rsquo;s Emission Modeling Clearinghouse (<ulink url="http://www.epa.gov/ttn/chief/emch/index.html">http://www.epa.gov/ttn/chief/emch/</ulink>). </para>

<title>Test case descriptions</title>

<section id="sect_scripts_nctox_case">

<title>nctox case for area, nonroad, mobile, biogenic and point sources</title>

<para>The nctox case provides users with an example of using both criteria and toxics emissions inventories. The purposes of this case include:</para>

<itemizedlist>
<listitem>
<para>Providing a test case for SMOKE on users computers. It is not recommended for actual user's emissions modeling work.</para>
</listitem>
<listitem>
<para>Provide example scripts that users may adapt to their own cases</para>
</listitem>
</itemizedlist>

<para>This case has the following major features. It runs for July 10th and 11th, 2005 on a 12-km Lambert Conformal grid over North Carolina. The spatial extent of this case has been limited to provide a relatively fast test case, and the domain is a subdomain of EPA&rsquo;s 12-km national grid. The case includes toxics processing for stationary area, nonroad mobile, and point sources.</para>

<figure id="fig_scripts_nctox_domain">
<title>nctox domain</title>

<mediaobject>
<imageobject role="pdf">
<imagedata width="5in" fileref="images/scripts/nctox_domain_pdf.jpg" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/scripts/nctox_domain_html.jpg" />
</imageobject>
</mediaobject>
</figure>

<para>At this time, the case uses North Carolina records <emphasis>only</emphasis> from the following inventory data:</para>

<para><emphasis role="bold">stationary area sources:</emphasis> 2005 NEI for CO, NO<subscript>x</subscript>, VOC, SO<subscript>2</subscript>, NH<subscript>3</subscript>, PM<subscript>10</subscript>, and PM<subscript>2.5</subscript> from nonpt, averfire and alm sectors</para>

<para><emphasis role="bold">nonroad mobile sources:</emphasis> 2005 NEI for CO, NO<subscript>x</subscript>, VOC, SO<subscript>2</subscript>, NH<subscript>3</subscript>, PM<subscript>10</subscript>, and PM<subscript>2.5</subscript> from nonroad sector</para>

<para><emphasis role="bold">point sources:</emphasis> 2005 NEI for CO, NO<subscript>x</subscript>, VOC, SO<subscript>2</subscript>, NH<subscript>3</subscript>, PM<subscript>10</subscript>, and PM<subscript>2.5</subscript> from ptipm and ptnonipm sectors</para>

<para><emphasis role="bold">mobile sources:</emphasis> vehicle mileage traveled (VMT) and its average speed (SPEED), and vehicle average hotteling (HOTELLING) for onroad mobile sources, and vehicle population (VPOP) for offroad mobile sources</para>

<para><emphasis role="bold">biogenic sources:</emphasis> BELD3 data processed using BEIS3 (for entire grid, even those cells that are not in North Carolina)</para>

<para>For area, mobile, and point sources, this case uses toxics inventories for ozone modeling. The VOC model species for the current CB6 mechanism are based in part on the toxic inventory. SMOKE resolves the duplicate VOC mass caused by combining VOC emissions with toxic VOC emissions by subtracting the toxic VOC mass from the VOC mass and computing a NONHAPVOC emissions value. This is the <quote>integrate</quote> approach for VOC emissions, described in <xref linkend="sect_concepts_combine_toxics" />. The speciation profiles provided with this version of SMOKE include profiles that map the toxics VOC and NONHAPVOC pollutants to current CB6 species. Choices for speciation profiles in this version of SMOKE are listed in <xref linkend="sect_scripts_change_speciation" />.</para>

<para>In addition to the inventory data listed above, the parameters of the case are the following:</para>

<itemizedlist>
<listitem>
<para><emphasis role="bold">Episode:</emphasis> July 10th and 11th of 2005</para>
</listitem>
<listitem>
<para><emphasis role="bold">Output time zone:</emphasis> Greenwich Mean Time (zone 0)</para>
</listitem>
<listitem>
<para><emphasis role="bold">Projection:</emphasis> Lambert Conformal with Alpha=33, Beta=45, Gamma=-97, and center at (-97,40)</para>
</listitem>
<listitem>
<para><emphasis role="bold">Domain:</emphasis> Origin at (1128, -672) kilometers with 66 columns by 52 rows and 12-km square grid cells (shown in <xref linkend="fig_scripts_nctox_domain" />)</para>
</listitem>
<listitem>
<para><emphasis role="bold">Meteorology data:</emphasis> Daily (25-hour) 2005 meteorology files generated originally by EPA using MM5 and MCIP; the files have been reduced to the modeling domain and contain only the variables needed by SMOKE.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Chemical speciation data:</emphasis> Revised <envar>GSPRO</envar> and <envar>GSREF</envar> files to include toxic pollutants mapped to current-CB6 mechanism for both on-road and nonroad mobile source classification category (SCC) codes.</para>
</listitem>

</itemizedlist>

</section>

<section id="sect_scripts_script_descriptions">

<title>Script descriptions</title>

<section>

<title>Overview</title>

<para>Running SMOKE from scripts provides a flexible approach to running SMOKE. We recommend that new users start with the standard configuration of scripts and directories provided with the default installation. This configuration uses the directory structures described in <xref linkend="ch_dirs_files" /> and a separate run script for each source category, as we will get to soon. In <xref linkend="sect_scripts_how_use_smoke" />, we provide all of the information you need to know to adapt the test case configuration to your modeling case. If you ever want to move beyond using the default configuration, we do not describe how to do that in detail. In fact, we could not describe this, because there are an infinite number of ways to arrange the directories and scripting for SMOKE; however, we have provided some information about what do to in <xref linkend="sect_dirs_change_directory" />.</para>

<para>Running SMOKE using scripts involves many scripts working together. This can be confusing for new users, but we have made efforts to make using the scripts easier and more robust with this version of SMOKE.</para>

<para>All SMOKE scripts can be found in the <filename class="directory"><envar>$SMKROOT</envar>/scripts/run</filename> directory, or simply the <filename class="directory"><envar>$SCRIPTS</envar>/run</filename> directory (after having invoked the Assigns file).</para>

</section>

<section id="sect_scripts_assigns_files">

<title>Assigns files</title>

<para>The assigns files are located in <filename class="directory"><envar>$SMKROOT</envar>/assigns</filename>. The nctox case assigns file is called <filename>ASSIGNS.nctox.cmaq.cb05_soa.us12-nc</filename>. One Assigns file is provided for the nctox case, and you can create your own files by copying it to a new name and changing it. At least one Assigns file must come with each preconfigured run (such as the nctox case) for SMOKE.</para>

<para>The Assigns files are divided into three major sections. The first section contains environment variables for controlling the setup of a case, such as the dates being modeled, the name of the grid, and the name of the chemical mechanism. The second section lists all of the input files in SMOKE (by source category) and users can change these adapt the Assigns files to their cases by changing the input files. The third section calls helper scripts to create input and output directories and configure the compiler environment variables. It is wise to copy an existing Assigns files to new files and modify the new files, so that you do not lose the default configuration.</para>

<para>In addition, there are a number of helper scripts used by the Assigns files. Unless users are changing the way SMOKE behaves when running from scripts, it should not be necessary to change these scripts. Changing them could result in behavior different from what is documented in this chapter. The helper scripts and their purposes are:</para>

<itemizedlist>
<listitem>
<para><filename>check_settings.scr</filename>: Set all environment variables used in Assigns file to default values if they are not already defined by a calling script (e.g., when invoking the Assigns file from the UNIX prompt instead of a script).</para>
</listitem>
<listitem>
<para><filename>set_case.scr</filename>: Set the environment variables that control output file names (<envar>ABASE</envar>, <envar>BBASE</envar>, <envar>MBASE</envar>, <envar>PBASE</envar>, <envar>EBASE</envar>, <envar>ASCEN</envar>, <envar>BSCEN</envar>, <envar>MSCEN</envar>, <envar>PSCEN</envar>, and <envar>ESCEN</envar>). See also the <envar>SMK_FUTURE_YN</envar>, <envar>FYEAR</envar>, <envar>SMK_CONTROL_YN</envar>, and <envar>CNTLCASE</envar> script settings in <xref linkend="sect_scripts_script_settings" /></para>
</listitem>
<listitem>
<para><filename>set_dirs.scr</filename>: Set the SMOKE directory structure</para>
</listitem>
<listitem>
<para><filename>setmerge_files.scr</filename>: Set <command>Smkmerge</command> output file names, depending on run script settings</para>
</listitem>
<listitem>
<para><filename>smk_mkdir</filename>: Create input and output directories</para>
</listitem>
<listitem>
<para><filename>smk_rmfiles.scr</filename>: Remove SMOKE intermediate and output files</para>
</listitem>
<listitem>
<para><filename>sysflags</filename>: Set the compiler options needed for compiling SMOKE</para>
</listitem>
<listitem>
<para><filename>unset.scr</filename>: Unset environment variables that do not need to be defined after the Assigns file has been run</para>
</listitem>
</itemizedlist>

</section>
</section>

<section id="sect_scripts_example_scripts">

<title>Example script files and their purposes</title>

<para>The following files are currently provided with the SMOKE release. There are a number of helper scripts. The only one that users may want to change is the <filename>qa_run.scr</filename> script to add configurations for reporting. The helper scripts are:</para>

<itemizedlist>
<listitem>
<para><filename>cntl_run.csh</filename>: Runs the <command>Cntlmat</command> and <command>Grwinven</command> program. Sets the required <envar>GCNTL</envar> file name depending on script settings, as explained in <xref linkend="sect_scripts_use_projection" />.</para>
</listitem>

<listitem>
<para><filename>make_invdir.csh</filename>: Sets the <envar>INVNAME1</envar> and <envar>INVNAME2</envar> settings that <command>Smkinven</command> uses for creating the map-formatted inventory intermediate files.</para>
</listitem>
<listitem>
<para><filename>metcombine.csh</filename>: Runs the utility program <command>Metcombine</command> to combine the <filename>METCRO2D*</filename> and <filename>METCRO3D*</filename> files in the <filename class="directory"><envar>$METDAT</envar></filename> directory. This script creates files named <filename>METCOMBO*</filename> in the <filename class="directory"><envar>$METDAT</envar></filename> directory.</para>
</listitem>
<listitem>
<para><filename>movelog.csh</filename>: Deletes or renames the log files, depending on the <envar>AUTO_DELETE_LOG</envar> setting.</para>
</listitem>
<listitem>
<para><filename>qa_run.csh</filename>: Runs the <command>Smkreport</command> program</para>
</listitem>
<listitem>
<para><filename>smk_run.csh</filename>: Runs the following SMOKE programs: <command>Smkinven</command>, <command>Rawbio</command> (for both winter and summer runs), <command>Normbeis3</command>, <command>Spcmat</command>, <command>Grdmat</command>, <command>Metscan</command>, <command>Temporal</command>, <command>Tmpbio</command>, <command>Tmpbeis3</command>, <command>Smkmerge</command>, <command>Mrggrid</command>, and <command>Smk2emis</command>.</para>

<para>Creates <envar>PTMPLIST</envar> file for <command>Elevpoint</command> by assuming all files with the name pattern <filename>ptmp*<envar>$PSCEN</envar>*ncf</filename> in the <filename class="directory"><envar>$SMKDAT</envar>/run_<envar>$PSCEN</envar>/*</filename> directories should be included in the file.</para>

<para>Creates the <envar>METLIST</envar> and <envar>RADLIST</envar> files for <command>Tmpbio</command> by listing <envar>$MET_FILE1</envar> to <envar>METLIST</envar> and <envar>$MET_FILE2</envar> to <envar>RADLIST</envar>. <envar>MET_FILE1</envar> and <envar>MET_FILE2</envar> are set in the Assigns file.</para>

<para>Determines which speciation matrix is needed for <command>Smkmerge</command>, based on the requested units. If the <envar>MRG_GRDOUT_UNIT</envar> setting contains the string <quote>mole</quote> then the molar speciation matrix and molar gridded, hourly biogenic emissions are set to be used by <command>Smkmerge</command>.</para>

<para>Creates the <envar>FILELIST</envar> file for <command>Mrggrid</command> from the <envar>MRGFILES</envar> setting in the calling merge run script.</para>
</listitem>
</itemizedlist>

</section>

<section id="sect_scripts_script_settings">

<title>Script settings</title>

<para>The SMOKE scripts have many environment variables that users can set based on the program documentation in <xref linkend="ch_programs" />, as well as environment variables that control the scripts. The variables that control the behavior of the scripts are described in this section. The settings are listed in alphabetical order.</para>

<para><emphasis role="bold">Note that using upper case for the names of these settings in the scripts is required. Any values that are Y or N settings must also be upper case.</emphasis></para>

<para>For documentation on the <envar>A_SPC_OVERRIDE</envar>, <envar>N_SPC_OVERRIDE</envar>, <envar>B_SPC_OVERRIDE</envar>, <envar>M_SPC_OVERRIDE</envar>, and <envar>P_SPC_OVERRIDE</envar> settings, please refer to the <envar>SPC_OVERRIDE</envar> description.</para>

<itemizedlist>
<listitem>
<para><envar>AUTO_DELETE</envar>: [Y | N] When set to Y, will delete all SMOKE intermediate and output I/O API files automatically. It will not delete intermediate and output ASCII files or reports.</para>
</listitem>
<listitem>
<para><envar>AUTO_DELETE_LOG</envar>: [Y | N] When set to Y, SMOKE log files will be automatically deleted. Otherwise, the files will be automatically renamed by appending a number to the end. The first time the a log file needs to be overwritten, but <envar>AUTO_DELETE_LOG</envar> is N, the file will be renamed to a file name with an <quote>_1</quote> appended to the original name. If the same file needs to be moved on a subsequent rerun and the <quote>_1</quote> file is already there, then a <quote>_2</quote> file will be created.</para>
</listitem>
<listitem>
<para><envar>CNTLCASE</envar>: When this is defined to a name of the control case and the <envar>SMK_CONTROL_YN</envar> setting is Y, the following changes are made to the naming environment variables by the <filename><envar>$ASSIGNS</envar>/set_case.scr file</filename>:</para>

<programlisting>setenv ASCEN ${ASCEN}_${CNTLCASE}
setenv MSCEN ${MSCEN}_${CNTLCASE}
setenv PSCEN ${PSCEN}_${CNTLCASE}
setenv ESCEN ${ESCEN}_${CNTLCASE}
setenv FYIOP ${FYIOP}_${CNTLCASE}</programlisting>

<para>When the <envar>CNTLCASE</envar> name is set, regardless of the <envar>SMK_CONTROL_YN</envar> setting, the <filename><envar>$ASSIGNS</envar>/set_case.scr</filename> file also resets <envar>FYINV</envar> as follows:</para>

<programlisting>setenv FYINV ${FYINV}_${CNTLCASE}</programlisting>

<para>This setting is also used for automatic naming of the <envar>GCNTL</envar> file input to <command>Cntlmat</command>. See <xref linkend="sect_scripts_use_projection" />.</para>
</listitem>
<listitem>
<para><envar>DEBUG_EXE</envar>: Should be set to the name of the fortran debugger (e.g., dbx) to use when running with <envar>DEBUGMODE</envar> set to Y.</para>
</listitem>
<listitem>
<para><envar>DEBUGMODE</envar>: [Y | N] When set to Y, the scripts will try to invoke the debug versions of the SMOKE executables. These will only be available to be used if the debug versions of the executables have been created using the <command>Makeall debug</command> command in the <filename class="directory"><envar>$SCRIPTS</envar>/make</filename> directory.</para>
</listitem>
<listitem>
<para><envar>FYEAR</envar>: The 4-digit future year value is used for renaming files and directories when the <envar>SMK_FUTURE_YN</envar> setting is Y. When this is true, the following changes are made to the naming environment variables by the <filename><envar>$ASSIGNS</envar>/set_case.scr</filename> script:</para>

<programlisting>setenv ASCEN   ${ASCEN}-${fyr2}
setenv MSCEN   ${MSCEN}-${fyr2}
setenv PSCEN   ${PSCEN}-${fyr2}
setenv ESCEN   ${ESCEN}-${fyr2}
setenv FYIOP   ${INVOP}-${fyr2}
</programlisting>

<para>where <envar>${fyr2}</envar> is the last two digits of the <envar>FYEAR</envar> value. These 2 digits are inserted into the output file names for <command>Smkinven</command> output files when <envar>SMK_FUTURE_YN</envar> is set to Y.</para>

<para>In addition, when <envar>FYEAR</envar> is defined, the <filename><envar>$ASSIGNS</envar>/set_case.scr</filename> script makes the follows settings regardless of the value of <envar>SMK_FUTURE_YN</envar>.</para>

<programlisting>setenv FYINV ${FYINV}_${fyr2}
setenv BYFYR ${BYFYR}_${fyr2}</programlisting>

<para>This setting is also used for automatic naming of the <envar>GCNTL</envar> file input to <command>Cntlmat</command>. See <xref linkend="sect_scripts_use_projection" />.</para>
</listitem>
<listitem>
<para><envar>G_STDATE_ADVANCE</envar>: The value should be set to the number of days for 1 run of the <command>Temporal</command>, <command>Laypoint</command>, and <command>Smkmerge</command> programs. The example scripts have this set by the <envar>NDAYS</envar> environment variable in the Assigns file. When this value is set, the Assigns file will automatically increment the <envar>ESDATE</envar> and <envar>G_STDATE</envar> environment variables (that control SMOKE file names and time-dependent programs, respectively) to the next day. This feature is unable to cross from one year to the next.</para>
</listitem>
<listitem>
<para><envar>INVTABLE_OVERRIDE</envar>: Sets a file name for the <envar>INVTABLE</envar> file in the Assigns file that overrides whatever value is actually inside the Assigns file. The Assigns file invokes the override mechanism when this environment variable is defined, so to <emphasis>not</emphasis> use this scripting feature, the variable must <emphasis>not</emphasis> be defined. <emphasis role="bold">In other words, it is not acceptable to set this to a blank value.</emphasis></para>
</listitem>
<listitem>
<para><envar>MRG_GRDOUT_UNIT</envar>: While this setting is primarily a setting for the <command>Smkmerge</command> program, it is also used by the SMOKE scripts to determine whether <command>Smkmerge</command> should use mole-based or mass-based speciation matrices and biogenic model-ready files. When the variable is set with the first four letters to <quote>mole</quote>, for example moles/hr, mole/s, or moles/day, the <command>Smkmerge</command> program will be provided by the scripts the correct input files. The implementation of this feature currently means that units of <quote>gm mole</quote> will not work properly.</para>
</listitem>
<listitem>
<para><envar>NONROAD</envar>: [Y | N] When set to Y, the Assigns file will automatically rename all of the SMOKE area-source intermediate and output files using the <quote>n</quote> prefix on file names instead of the <quote>a</quote> prefix. For example, the <envar>ATMP</envar> file is set to <filename><envar>$SCENARIO</envar>/ntmp.ncf</filename> instead of <filename><envar>$SCENARIO</envar>/atmp.ncf</filename>. Also, the <envar>AREA</envar> file coming out of <command>Smkinven</command> changes to be a different name and use a different map-file directory.</para>
</listitem>
<listitem>
<para><envar>PROMPTFLAG</envar>: [Y | N] When set to Y, users will be prompted for all SMOKE file names. This option should not be set to Y for non-interactive processing. In fact, there is little need for this to ever be set to Y.</para>
</listitem>
<listitem>
<para><envar>QA_LABEL</envar>: Users can label their <command>Smkreport</command> log files and QA reports using this label. Typically, the QA report names are named using the <envar>$FYIOP</envar> variable or <envar>$ESCEN</envar> variable set in the <filename><envar>$ASSIGNS</envar>/set_case.scr</filename> script. When <envar>QA_LABEL</envar> is set to something, the log files and reports are labeled with <envar>$FYIOP</envar>.<envar>$QA_LABEL</envar> or <envar>$ESCEN</envar>.<envar>$QA_LABEL</envar>. This renaming is done in the <filename>qa_run.csh</filename> helper script in the <filename class="directory"><envar>$SCRIPTS</envar>/run</filename> directory.</para>
</listitem>
<listitem>
<para><envar>QA_TYPE</envar>: [none | all | part1 | part2 | part3 | part4 or custom]. This setting controls the <filename>qa_run.csh</filename> helper script and causes different reports to be written. The <envar>QA_TYPE</envar> settings will cause the script to use different <envar>REPCONFIG</envar> files for input to <command>Smkreport</command>, and the <envar>REPCONFIG</envar> files determine which reports are generated. <xref linkend="sect_scripts_change_reports" /> explains these default settings and how to change them to create the reports that you need.</para>
</listitem>
<listitem>
<para><envar>RUN_PART1</envar>, <envar>RUN_PART2</envar>, <envar>RUN_PART3</envar>, <envar>RUN_PART4</envar>: These settings should not have to be changed by most users. They are included for the convenience of those who want to more easily rearrange their SMOKE processing. Each source category has its own parts for processing as follows:</para>

<informaltable>
<tgroup cols="5">
<colspec colname="Variable" colwidth="1*" />
<colspec colname="Area" colwidth="1*" />
<colspec colname="Biogenic" colwidth="1*" />
<colspec colname="Mobile" colwidth="1*" />
<colspec colname="Point" colwidth="1*" />

<thead>
<row>
<entry colname="Area" align="center">Area</entry>
<entry align="center">Biogenic</entry>
<entry align="center">Mobile</entry>
<entry align="center">Point</entry>
</row>
</thead>

<tbody>
<row>
<entry><envar>RUN_PART1</envar></entry>
<entry><command>Smkinven</command>, <command>Spcmat</command>, <command>Grdmat</command>, <command>Cntlmat</command>, <command>Grwinven</command></entry>
<entry><command>Rawbio</command>, <command>Normbeis3</command>, <command>Metscan</command></entry>
<entry><command>Smkinven</command>, <command>Spcmat</command>, <command>Grdmat</command>, <command>Cntlmat</command>, <command>Grwinven</command></entry>
<entry><command>Smkinven</command>, <command>Spcmat</command>, <command>Grdmat</command>, <command>Cntlmat</command>, <command>Grwinven</command></entry>
</row>
<row>
<entry><envar>RUN_PART2</envar></entry>
<entry><command>Temporal</command></entry>
<entry><command>Tmpbio</command>, <command>Tmpbeis3</command></entry>
<entry><command>Temporal</command></entry>
<entry><command>Temporal</command></entry>
</row>
<row>
<entry><envar>RUN_PART3</envar></entry>
<entry colname="Point"><command>Elevpoint</command></entry>
</row>
<row>
<entry><envar>RUN_PART4</envar></entry>
<entry><command>Smkmerge</command>, <command>Mrggrid</command>, <command>Smk2emis</command></entry>
<entry><command>Mrggrid</command>, <command>Smk2emis</command></entry>
<entry><command>Movesmrg</command>, <command>Mrggrid</command>, <command>Smk2emis</command></entry>
<entry><command>Laypoint</command>, <command>Smkmerge</command>, <command>Mrggrid</command>, <command>Smk2emis</command></entry>
</row>
</tbody>

</tgroup>
</informaltable>
</listitem>

<listitem>
<para><envar>RUN_&lt;Program Name&gt;</envar>: [Y | N] The collection of <envar>RUN_&lt;Program Name&gt;</envar> variables control whether a program is going to be run during a given script run. These can be set to N if the program is not needed for some reason. How these settings should be set is described in <xref linkend="sect_scripts_change_programs" />.</para>
</listitem>

<comment>
<listitem>
<para><envar>SMK_CONTROL_YN</envar>: [Y | N] <remark>Missing text</remark><comment>be sure to mention <envar>FYIOP</envar></comment></para>
</listitem>
</comment>

<listitem>
<para><envar>SMK_FUTURE_YN</envar>: [Y | N] When set to Y, the file names and output directories are changed to use the <envar>FYEAR</envar> variable setting in the names. See the <envar>FYEAR</envar> documentation for more information on how the naming variables are set. This setting is needed only in scripts for processing future-year cases.</para>
</listitem>
<listitem>
<para><envar>SPC_OVERRIDE</envar>: Sets a value for the <envar>SPC</envar> variable in the Assigns file that overrides whatever value is actually inside the Assigns file. The Assigns file invokes the override mechanism when this environment variable is defined, so to not use this scripting feature, the variable must not be defined. <emphasis role="bold">In other words, it is not acceptable to set this to a blank value.</emphasis></para>

<para>In addition, the merge scripts that run the <command>Mrggrid</command> program can also use the <envar>A_SPC_OVERRIDE</envar>, <envar>N_SPC_OVERRIDE</envar>, <envar>B_SPC_OVERRIDE</envar>, <envar>M_SPC_OVERRIDE</envar>, and <envar>P_SPC_OVERRIDE</envar> settings. These settings override the <envar>SPC</envar> variable used <emphasis>only</emphasis> for the definition of the <envar>A_OUT</envar>, <envar>N_OUT</envar>, <envar>B_OUT</envar>, <envar>M_OUT</envar>, and <envar>P_OUT</envar> directories that contain the hourly, gridded, and speciated SMOKE output files. These settings can be used to pull multiple chemical mechanisms (such as toxics and non-toxics) into a single model-ready file. The user must determine which multiple mechanisms are appropriate to combine. It is acceptable to combine toxics-integrated and criteria-only current CB6 mechanisms, but inappropriate to combine CB6 and SARPRC mechanisms.</para>
</listitem>
<listitem>
<para><envar>SRCABBR</envar>: Sets the source category abbreviation name for use in naming log files. The typical settings are ar (area sources), nr (nonroad sources), mb (mobile sources), bg (biogenic sources), and pt (point sources).</para>
</listitem>
<listitem>
<para><envar>YEAR_OVERRIDE</envar>: Sets a value for the <envar>YEAR</envar> variable in the Assigns file that overrides whatever value is actually inside the Assigns file. The Assigns file invokes the override mechanism when this environment variable is defined, so to not use this scripting feature, the variable must not be defined. <emphasis role="bold">In other words, it is not acceptable to set this to a blank value.</emphasis></para>
</listitem>
</itemizedlist>

</section>

<section>

<title>SMOKE settings controlled through scripts</title>

<para>All SMOKE programs can be controlled by input environment variables, and the run scripts control these variables. The program documentation in <xref linkend="ch_utilities" />, <xref linkend="ch_programs" />, and <xref linkend="ch_quality_assurance" /> include the available environment variable settings for each program.</para>

<para>The example run scripts contain most of the major script settings needed for running SMOKE. The major exception to this is the <envar>UAM_*</envar> settings needed for <command>Smkmerge</command> and <command>Smk2emis</command>, when running for UAM-V and CAM<subscript>X</subscript>. These can be added to the scripts as needed.</para>

</section>
</section>

<section id="sect_scripts_run_example">
<title>Running the SMOKE test case</title>

<para>As mentioned in <xref linkend="sect_scripts_introduction" />, the first step in working with SMOKE is invoking the Assigns file. In this section, we will go beyond that first step to actually running the scripts for the nctox case. But first, we will review the essential steps for running SMOKE each and every time you start to work with the SMOKE system.</para>

<para>First, the <envar>SMK_HOME</envar> environment variable needs to be defined. In <xref linkend="sect_install_install" />, we explain that you can configure your UNIX system to set this automatically each time you log into your computer. If you have not done that, then you will need to set the <envar>SMK_HOME</envar> variable manually before invoking an Assigns file:</para>

<para><userinput><command>setenv</command> <envar>SMK_HOME</envar> <replaceable>&lt;directory in which you installed SMOKE&gt;</replaceable></userinput></para>

<para>Second, you must invoke the Assigns file for the case that you want to run. This will make available all of the environment variables that you can use to navigate through the SMOKE directory structure. There is a different Assigns file for each case, so we provide this instruction with the case-specific documentation below. Of course, when you develop an Assigns file for your case, you will use that instead.</para>

<para><emphasis role="bold">NOTE:</emphasis> All of the SMOKE scripts assume that you are running a variant of the C-shell (either <command>csh</command> or <command>tcsh</command>). The scripts will not work with other shells such as <command>bash</command>. If your shell is not <command>csh</command> or <command>tcsh</command>, you will need to change into an appropriate shell before running any SMOKE scripts.</para>

<para>To run the nctox test case, you must first source the Assigns file using the commands below:</para>

<para><userinput><command>cd</command> <filename class="directory"><envar>$SMK_HOME</envar>/subsys/smoke/assigns</filename></userinput> <emphasis>(change to the assigns directory)</emphasis></para>

<para><userinput><command>source</command> <filename>ASSIGNS.nctox.cmaq.cb05_soa.us12-nc</filename></userinput> <emphasis>(set up for the nctox case)</emphasis></para>

<para>Next, you&rsquo;ll run the base-year nctox scripts. These scripts process the stationary area, biogenic, nonroad mobile, and point emissions for the base year. The commands to run the scripts are below:</para>

<para><userinput><command>cd</command> <filename class="directory"><envar>$SCRIPTS</envar>/run</filename></userinput> <emphasis>(change to the run scripts directory)</emphasis></para>

<para><userinput><filename>smk_area_nctox.csh</filename></userinput> <emphasis>(invoke the stationary area run script)</emphasis></para>

<para><userinput><filename>smk_bg_nctox.csh</filename></userinput> <emphasis>(invoke the BEIS3 biogenic run script)</emphasis></para>

<para><userinput><filename>smk_nonroad_nctox.csh</filename></userinput> <emphasis>(invoke the nonroad mobile run script)</emphasis></para>

<para><userinput><filename>smk_point_nctox.csh</filename></userinput> <emphasis>(invoke the point run script)</emphasis></para>

<para><userinput><filename>smk_rateperdistance_nctox.csh</filename></userinput> <emphasis>(invoke the MOVES mobile sources on-roadway rate-per-distance (RPD) run script for all processes)</emphasis></para>
<para><userinput><filename>smk_ratepervehicle_nctox.csh</filename></userinput> <emphasis>(invoke the MOVES mobile sources off-network rate-per-vehicle (RPV) run script)</emphasis></para>
<para><userinput><filename>smk_rateperprofile_nctox.csh</filename></userinput> <emphasis>(invoke the MOVES mobile sources off-network rate-per-profile (RPP) run script)</emphasis></para>
<para><userinput><filename>smk_rateperhour_nctox.csh</filename></userinput> <emphasis>(invoke the MOVES mobile sources off-network rate-per-hour (RPH) run script)</emphasis></para>

<para><userinput><filename>smk_mrgall_nctox.csh</filename></userinput> <emphasis>(invoke the all-sources merge script)</emphasis></para>

<para>To verify that the nctox scripts have run correctly, go to the log file directory and look for errors by using:</para>
<para><userinput><command>cd</command> <filename class="directory"><envar>$LOGS</envar></filename></userinput> <emphasis>(change to the log file directory for the test case)</emphasis></para>
<programlisting>
grep ERROR *
</programlisting>

<para> If there are no errors, the next step is to run a QA script to be sure that the answers match.</para>
<para><userinput><command>cd</command> <filename class="directory"><envar>$SCRIPTS</envar>/install</filename></userinput> <emphasis>(change to the install directory)</emphasis></para>
<para><userinput><filename>check_smk_install</filename></userinput> <emphasis>(invoke the smoke install quality assurance script)</emphasis></para>
</section>

<section id="sect_scripts_how_use_smoke">

<title>How to use SMOKE</title>

<para>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 <xref linkend="sect_scripts_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 <xref linkend="sect_scripts_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.</para>

<para>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.</para>

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

<orderedlist>
<listitem>
<para>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.</para>

<para><userinput><command>cp</command> <filename>ASSIGNS.nctox.cmaq.cb05_soa.us12-nc</filename> <replaceable>&lt;yourfile&gt;</replaceable></userinput></para>
</listitem>

<listitem>
<para>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 <xref linkend="sect_scripts_change_assigns" /> for more details on the settings that you can change and the values to use for each.</para>
</listitem>

<listitem>
<para>Invoke the Assigns file. This will create all of the input and output directories that you will need to set up your case:</para>

<para><userinput><command>source</command> <replaceable>&lt;yourfile&gt;</replaceable></userinput></para>
</listitem>

<listitem>
<para>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.</para>
</listitem>

<listitem>
<para>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.</para>
</listitem>
</orderedlist>

<para>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.</para>

<section id="sect_scripts_change_assigns">

<title>Change Assigns file to set scenario names, grid names, and other case-specific configuration information</title>

<para>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, <xref linkend="sect_scripts_change_speciation" /> explains how to change the Assigns file to set different chemical mechanisms as well as all of the files needed.</para>

<para>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 <emphasis>at a minimum</emphasis> 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.</para>

<para>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 <xref linkend="tbl_scripts_variables_files" /> or <xref linkend="tbl_scripts_variables_time" /> for more information. The variables in the <xref linkend="tbl_scripts_variables_files" /> are used for naming files and directories. <xref linkend="tbl_scripts_variables_time" /> includes the settings for controlling the time period and grid of your SMOKE runs.</para>

<para>The checklist of major Assigns settings to change is:</para>

<orderedlist>
<listitem>
<para>Change the <envar>INVID</envar>, <envar>INVEN</envar>, and <envar>INVOP</envar> 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 <xref linkend="tbl_scripts_variables_files" />. See also <xref linkend="sect_scripts_use_new_inv" />.</para>
</listitem>

<listitem>
<para>Change the <envar>ABASE</envar>, <envar>BBASE</envar>, <envar>MBASE</envar>, <envar>PBASE</envar>, and <envar>EBASE</envar> 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 <xref linkend="tbl_scripts_variables_files" />. See also <xref linkend="sect_scripts_use_new_inv" />.</para>
</listitem>

<listitem>
<para>Change the <envar>METSCEN</envar> value to your meteorology scenario name. This will affect the name of the input directory for the meteorology files (the <filename class="directory"><envar>$METDAT</envar></filename> directory, which can be a linked directory if you do not want to install your meteorology files under the SMOKE directory structure).</para>
</listitem>

<listitem>
<para>Change the <envar>SPC</envar> value to one of the supported speciation mechanisms (see <xref linkend="sect_scripts_use_default_spc" />) or to a new speciation mechanism (see <xref linkend="sect_scripts_use_new_spc" />).</para>
</listitem>

<listitem>
<para>Change the <envar>GRID</envar> and <envar>IOAPI_GRIDNAME_1</envar> values to the grid names for naming files. See also <xref linkend="sect_scripts_use_grid" />.</para>
</listitem>

<listitem>
<para>Change the run period naming settings <envar>ESDATE</envar> and <envar>NDAYS</envar> (see <xref linkend="tbl_scripts_variables_files" />). See also <xref linkend="sect_scripts_duration_output" />.</para>
</listitem>

<listitem>
<para>Change the episode settings <envar>EPI_STDATE</envar>, <envar>EPI_STTIME</envar>, <envar>EPI_RUNLEN</envar>, and <envar>EPI_NDAY</envar> and the run period settings <envar>G_STDATE</envar>, <envar>G_STTIME</envar>, and <envar>G_RUNLEN</envar>. See <xref linkend="tbl_scripts_variables_time" /> and <xref linkend="sect_scripts_change_episode" /> and <xref linkend="sect_scripts_duration_output" />.</para>
</listitem>

<listitem>
<para>Change the <envar>YEAR</envar> value to the year of your base case inventory.</para>
</listitem>
</orderedlist>

<table id="tbl_scripts_variables_files">
<title>Variable in Assigns file for naming files and directories</title>

<tgroup cols="2">
<colspec colwidth="1*" />
<colspec colwidth="5*" />

<thead>
<row>
<entry align="center">Environment Variable</entry>
<entry align="center" valign="bottom">Description</entry>
</row>
</thead>

<tbody>
<row>
<entry><envar>INVID</envar></entry>
<entry>Inventory input directory identifier. Controls directory path of input inventory. <envar>INVDIR</envar> = <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar></filename></entry>
</row>
<row>
<entry><envar>INVOP</envar></entry>
<entry>Base year inventory output name. Controls output file names for SMOKE intermediate inventory files and other output files from <command>Smkinven</command> and inventory-only reports from <command>Smkreport</command>. This variable is used to initialize the <envar>FYIOP</envar> variable, which is also used in the Assigns file and is equal to <envar>INVOP</envar> for base case modeling. <envar>FYIOP</envar> is reset by the <filename>set_case.scr</filename> helper script (see <xref linkend="sect_scripts_script_settings" /> documentation on <envar>FYEAR</envar> and <envar>CNTLCASE</envar>)</entry>
</row>
<row>
<entry><envar>INVEN</envar></entry>
<entry>Base year inventory name, with version. Controls directory path of output inventory. <envar>INVOPD</envar> = <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVEN</envar></filename></entry>
</row>
<row>
<entry><envar>ABASE</envar></entry>
<entry>Scenario identifier for area/non-point and nonroad mobile sources. Controls output file names and directories for outputs from SMOKE programs other than <command>Smkinven</command> (e.g., locations and file names of all matrices, hourly emissions, model-ready files). This variable is used to initialize the <envar>ASCEN</envar> variable, which is also used in the Assigns file and is equal to <envar>ABASE</envar> for base case modeling. <envar>ASCEN</envar> is reset by the <filename>set_case.scr</filename> helper script (see <xref linkend="sect_scripts_script_settings" /> documentation on <envar>FYEAR</envar> and <envar>CNTLCASE</envar>). Should be set to the same value as <envar>BBASE</envar>, <envar>MBASE</envar>, <envar>PBASE</envar>, and <envar>EBASE</envar> for the basic configuration.</entry>
</row>
<row>
<entry><envar>BBASE</envar></entry>
<entry>Scenario identifier for biogenic sources that works the same way as <envar>ABASE</envar>, but affects the <envar>BSCEN</envar> variable.</entry>
</row>
<row>
<entry><envar>MBASE</envar></entry>
<entry>Scenario identifier for on-road mobile sources that works the same way as <envar>ABASE</envar>, but affects the <envar>MSCEN</envar> variable.</entry>
</row>
<row>
<entry><envar>PBASE</envar></entry>
<entry>Scenario identifier for on-road mobile sources that works the same way as <envar>ABASE</envar>, but affects the <envar>PSCEN</envar> variable.</entry>
</row>
<row>
<entry><envar>EBASE</envar></entry>
<entry>Scenario identifier for merged emissions sources. Controls output file names and directories for outputs for final model-ready files. Sets the path for the <envar>STATIC</envar>, <envar>SCENARIO</envar>, and <envar>OUTPUT</envar> directories and file names for the merged outputs for multiple source categories from the <command>Smkmerge</command> program (e.g., the <envar>EGTS3D_L</envar> file).</entry>
</row>
<row>
<entry><envar>METSCEN</envar></entry>
<entry>Meteorology scenario name. Sets the <envar>METDAT</envar> 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 (<command>Tmpbeis3</command> outputs <envar>B3GTS_S</envar> and <envar>B3GTS_L</envar>), on-road mobile (<command>Temporal</command> output <envar>MTMP</envar>), and point (<command>Laypoint</command> outputs <envar>PLAY</envar> and <envar>PLAY_EX</envar>).</entry>
</row>
<row>
<entry><envar>GRID</envar></entry>
<entry>Grid name used for naming files that depend on the selected grid. User must coordinate <envar>GRID</envar> settings with <envar>IOAPI_GRIDNAME_1</envar> setting <xref linkend="tbl_scripts_variables_time" />. Dependent files include gridding matrix, gridded land use and biogenic emissions, hourly mobile emissions, layer-fractions files, model-ready emissions, and some reports.</entry>
</row>
<row>
<entry><envar>SPC</envar></entry>
<entry>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 <envar>SPC_OVERRIDE</envar> script setting (see <xref linkend="sect_scripts_script_settings" />). The <envar>SPC</envar> setting sets input files <envar>GSPRO</envar> and <envar>GSREF</envar>; speciation matrix intermediate file names, and output directories <envar>OUTPUT</envar>, <envar>A_OUT</envar>, <envar>B_OUT</envar>, <envar>M_OUT</envar>, <envar>N_OUT</envar>, and <envar>P_OUT</envar>.</entry>
</row>
<row>
<entry><envar>ESDATE</envar></entry>
<entry>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 <envar>G_STDATE</envar> setting <xref linkend="tbl_scripts_variables_time" />. The Assigns file resets this variable if the <envar>G_STDATE_ADVANCE</envar> variable is set by a calling script (see <xref linkend="sect_scripts_script_settings" />).</entry>
</row>
<row>
<entry><envar>MSDATE</envar></entry>
<entry>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 <envar>G_STDATE</envar> variable is used instead.</entry>
</row>
<row>
<entry><envar>NDAYS</envar></entry>
<entry>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 <envar>G_RUNLEN</envar> setting <xref linkend="tbl_scripts_variables_time" />. <envar>NDAYS</envar> represents the number of days indicated in hours by the <envar>G_RUNLEN</envar> variable. <envar>NDAYS</envar> is used for naming hourly emissions files output from the <command>Temporal</command> program, biogenic outputs from <command>Tmpbio</command>, layer fractions files from <command>Laypoint</command>, and model-ready emissions files from <command>Smkmerge</command>.</entry>
</row>
<row>
<entry><envar>YEAR</envar></entry>
<entry>Base case modeling year. This setting is used to set several things in coordination with the <envar>FYEAR</envar> and <envar>SMK_FUTURE_YN</envar> script settings (see <xref linkend="sect_scripts_script_settings" />). For growth modeling, it is used in the file name for the <envar>GCNTL</envar> input file, set by the growth/control example nctox scripts. This setting can be overridden by the <envar>YEAR_OVERRIDE</envar> setting, also described in <xref linkend="sect_scripts_script_settings" />. Lastly, it is used to set the file name for the winter/summer designations file output from <command>Metscan</command>, called the <envar>BIOSEASON</envar> file.</entry>
</row>

</tbody>

</tgroup>
</table>

<table id="tbl_scripts_variables_time">
<title>Variables in Assigns file for controlling time period and grid of processing</title>

<tgroup cols="2">
<colspec colwidth="1*" />
<colspec colwidth="3*" />

<thead>
<row>
<entry align="center">Environment Variable</entry>
<entry align="center" valign="bottom">Description</entry>
</row>
</thead>

<tbody>
<row>
<entry><envar>G_STDATE</envar></entry>
<entry>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 <envar>ESDATE</envar> setting <xref linkend="tbl_scripts_variables_files" />. The Assigns file resets this variable if the <envar>G_STDATE_ADVANCE</envar> variable is set by a calling script (see <xref linkend="sect_scripts_script_settings" />). Controls operation of time-dependent programs <command>Temporal</command>, <command>Tmpbio</command>, <command>Laypoint</command>, and <command>Smkmerge</command>.</entry>
</row>
<row>
<entry><envar>G_STTIME</envar></entry>
<entry>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).</entry>
</row>
<row>
<entry><envar>G_RUNLEN</envar></entry>
<entry>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 <envar>NDAYS</envar> setting <xref linkend="tbl_scripts_variables_files" />. <envar>G_RUNLEN</envar> has format HHHHMMSS, where HHHH is a 4-digit duration in hours (leading zeros not required), MM and HH should be set as for <envar>G_STTIME</envar>. <envar>G_RUNLEN</envar> controls the duration modeled for each run of the <command>Temporal</command>, <command>Tmpbio</command>, <command>Laypoint</command>, and <command>Smkmerge</command> 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).</entry>
</row>
<row>
<entry><envar>G_TSTEP</envar></entry>
<entry>Time step. Has format HHMMSS with format the same as described for <envar>G_STTIME</envar>. The current version of SMOKE allows this setting to only be 10000, for hourly timesteps.</entry>
</row>
<row>
<entry><envar>EPI_STDATE</envar></entry>
<entry>Episode start date. Has the same format as <envar>G_STDATE</envar>. Does not change during the course of an episodic run. In the Assigns file, should be set the same as <envar>G_STDATE</envar>.</entry>
</row>
<row>
<entry><envar>EPI_STTIME</envar></entry>
<entry>Episode start time. Has the same format as <envar>G_STTIME</envar>. Does not change during the course of an episodic run. In the Assigns file, should be set the same as <envar>G_STTIME</envar>.</entry>
</row>
<row>
<entry><envar>EPI_RUNLEN</envar></entry>
<entry>Episode duration. Has the same format as <envar>G_RUNLEN</envar>. 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 <envar>G_RUNLEN</envar> minus one hour, is limited to at most one year, and for best results, should be a multiple of <envar>G_RUNLEN</envar> minus one hour. For example, if <envar>G_RUNLEN</envar> is 250000 (one day plus the required one additional hour), <envar>EPI_RUNLEN</envar> must be at least 240000 and at most 365 x 240000 = 87600000. This example would run an annual episode using 24-hour run periods.</entry>
</row>
<row>
<entry><envar>EPI_NDAY</envar></entry>
<entry>The number of days in the episode. Should be the value of <envar>EPI_RUNLEN</envar> 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 <envar>G_RUNLEN</envar>) during the episode (set by <envar>EPI_RUNLEN</envar>).</entry>
</row>
<row>
<entry><envar>IOAPI_GRIDNAME_1</envar></entry>
<entry>The selected grid. Controls which grid will be selected by the <command>Grdmat</command> program from the <envar>GRIDDESC</envar> file. Users should coordinate this setting with the <envar>GRID</envar> setting from <xref linkend="tbl_scripts_variables_files" />, which is used for naming files. This setting must match the grid names in the gridded land use and spatial surrogates files&rsquo; headers. </entry>
</row>

</tbody>

</tgroup>
</table>

</section>

<section id="sect_scripts_use_new_inv">

<title>Use new inventory data</title>

<para>This section describes what steps are necessary to take when using new inventory data for anthropogenic sources. For information on biogenic sources, see <xref linkend="sect_scripts_use_beis3" />. For more information about the details of each source category (e.g., what is the difference between using MOVES emission factors or precomputed on-road mobile emissions), see <xref linkend="sect_concepts_summary_source_processing" />.</para>

<para>Because this section is so spread out, we provide a small section guide here. This section includes the following subsections:</para>

<itemizedlist spacing="compact">
<listitem>Area/non-point inventories</listitem>
<listitem>Nonroad mobile inventories</listitem>
<listitem>On-road mobile inventories</listitem>
<listitem>Point inventories</listitem>
<listitem>Day-specific and hour-specific point and fire inventories</listitem>
<listitem>Future-year inventories</listitem>
<listitem>Pre-gridded inventories (for same output modeling domain or for converting to a different modeling domain (example: EDGAR/RCP/HTAP to CMAQ ready emissions file)</listitem>
<listitem>Using seasonal and annual data in the same run</listitem>
<listitem>Files and settings for all inventories</listitem>
</itemizedlist>

<section id="sect_scripts_area_invs">

<title>Area/non-point inventories</title>

<orderedlist>
<listitem>
<para>Determine the file format that you have (for preformatted data) or want to create (for new data).</para>

<orderedlist>
<listitem>
<para>Preformatted data considerations</para>

<itemizedlist>
<listitem>
<para>If you have preexisting data in SMOKE input format, then you will most likely want to use that format to input to SMOKE, unless you discover that you need a different format to take advantage of a SMOKE feature not available in a different format.</para>
</listitem>
<listitem>
	<para>If you have multiple files in a single format, then you can combine these into a single SMOKE run using a list file.</para> 
</listitem>
<listitem>
<para>If you have data in more than one format other than the case just mentioned, you must convert all files to the same format or process them separately in SMOKE, merging the hourly, gridded, speciated emissions files using <command>Mrggrid</command>.</para>
</listitem>
<listitem>
<para>If your area inventory includes nonroad mobile sources, you can process nonroad mobile sources with stationary area sources in most cases (see next bullet for exception).</para>
</listitem>
<listitem>
<para>If you want to combine nonroad mobile criteria and toxics inventories, you need to process nonroad mobile sources separately from area sources (see <xref linkend="sect_scripts_nonroad_invs" />).</para>
</listitem>
<listitem>
<para>Pregridded data from any source category can be input to SMOKE as an area source, but you must convert the data to an I/O API NetCDF file format first. See <xref linkend="sect_scripts_pregridded_invs_same" /> for more information.</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
</listitem>

<listitem>
<para>Collect or create inventories in correct formats.</para>

<para>Inventory files for area sources are usually named starting with <quote>arinv</quote>, because <envar>ARINV</envar> is the logical file name (environment variable) that <command>Smkinven</command> uses to read the file. The formats available for area/non-point sources are:</para>

<orderedlist>
<listitem>
<para>List format. The list format is simply an ASCII file that lists all of the files that you want SMOKE to import in a single run.</para>
</listitem>
<listitem>
	<para>List Grid format. The list grid format is simply an ASCII file that lists all of the global gridded inventory files that you want SMOKE to import in a single run. The List Grid format has four columns.
	Assigned SCC, Pollutant ID, Local Variable Name, Month of inventory and Full inventory fine directory path and filename.</para>
</listitem>
<listitem>
<para>ORL and FF10 formats. These formats are most appropriate for non-point toxics inventories, but also can be used for any inventory data.</para>
</listitem>
<listitem>
<para>Pregridded I/O API format. This format can only be used for pregridded data that has been converted to a time-independent, gridded I/O API file. The variables in the file are the pollutants. No SCCs or other source information can be provided with this format.</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Set and/or check the file headers that apply for your file format.</para>

<orderedlist>
<listitem>
<para>File format header: Make sure that the first line of the list file or individual files start with the #LIST (for list files only),#LIST GRID, #ORL, #FF10 (see <xref linkend="sect_input_inventory_format" />).</para>
</listitem>
<listitem>
<para>File type (#TYPE header): The type is important because it helps SMOKE determine the file format. Make sure that the header has been set according to the directions in <xref linkend="sect_input_inventory_header" />.</para>
</listitem>
<listitem>
	<para>Country (#COUNTRY header): Make sure that this head has been used and that the country name used in this header matches the name in the country section of the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> file (if USE_EXP_GEOCODE Y) file.</para>
</listitem>
<listitem>
<para>Inventory year (#YEAR). Make sure that the inventory year is accurately reflected in the header. This is the only way SMOKE knows what year the data is for. <comment>If the year is not the same for all of your inventory files and you want to make them the same, you will have to use the inventory growth, which is described in <xref linkend="sect_scripts_use_projection" />.</comment> If this year is not a base year but a future-year, make sure to follow the additional instructions in <xref linkend="sect_scripts_future_invs" />.</para>

</listitem>
<listitem>
<para>Description (#DESC header): Although this header is not required, it is good practice to take advantage of it and include as much information about the data as you have. There is no limit to the number of #DESC headers that can be included in the file.</para>
</listitem>
<listitem>
<para>Data header (#POLID or #DATA header): Make sure that this required header is included in the file. It should accurately reflect the data values provided on each line of the file. If there are data fields at the end of the file that you want to drop from being imported, you can leave them off of the #POLID or #DATA header to cause them to not be imported by <command>Smkinven</command> (see also the <envar>INVTABLE</envar> file for dropping emissions during import).</para>

<para>For ORL format, this header does not apply. The pollutants are designated by code number (i.e., CAS number) in the file format and therefore the header is not needed.</para>

</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Install inventory files in <filename class="directory"><envar>$ARDAT</envar></filename> directory.</para>

<para>This directory is <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/area</filename>.</para>
</listitem>

<listitem>
<para>Ensure the Assigns file has the <envar>ARINV</envar> variable set to the <envar>ARINV</envar> file name for your area-source inventory file.</para>
</listitem>

<listitem>
<para>Optionally, set up to assign point-source locations to area sources using the <envar>ARTOPNT</envar> file.</para>

<orderedlist>
<listitem>
<para>Put the <envar>ARTOPNT</envar> file in the <filename class="directory"><envar>$INVDIR</envar>/other</filename> directory.</para>
</listitem>
<listitem>
<para>Ensure the name of the <envar>ARTOPNT</envar> file is consistent with the <envar>ARTOPNT</envar> setting in the Assigns file.</para>
</listitem>
<listitem>
<para>Make sure that the <envar>ARTOPNT</envar> file data are consistent with the year of your inventory (e.g., use 1999 coordinates for a 1999 inventory), or that you can accept any discrepancies.</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>See also steps for all source categories in <xref linkend="sect_scripts_all_invs" />.</para>
</listitem>

</orderedlist>

</section>

<section id="sect_scripts_nonroad_invs">

<title>Nonroad mobile inventories</title>

<orderedlist>
<listitem>
<para>Determine the file format that you have (for preformatted data) or want to create (for new data).</para>

<orderedlist>
<listitem>

<itemizedlist>
<listitem>
<para>See <xref linkend="sect_scripts_area_invs" /> for issues relating to stationary area / non-point sources. These are the same issues as for nonroad mobile sources.</para>
</listitem>
<listitem>
<para>If you need to process nonroad mobile separately from stationary area/non-point sources because of recommendations in <xref linkend="sect_scripts_area_invs" />, you must separate the stationary area/non-point and nonroad mobile sources to two separate files if they are not already separated. There is no SMOKE utility to do this, but the UNIX <command>grep</command> command can be used to search for all SCCs in the nonroad mobile inventory; for example, all SCCs starting with <quote>22</quote>.</para>
</listitem>
</itemizedlist>

</listitem>

<listitem>
<para>New data considerations</para>

<itemizedlist>
<listitem>
<para>See <xref linkend="sect_scripts_area_invs" /> for issues relating to stationary area and non-point sources. These are the same issues as for nonroad mobile sources.</para>
</listitem>
<listitem>
<para>Decide whether area and nonroad mobile sources will be processed together, which may depend on whether the available inventory data include both area and nonroad mobile or whether they are already separate. One reason for separate processing is if you anticipate control strategies that affect only stationary area or only nonroad mobile sources, though it is not required that the processing be separate to apply such controls. A second reason for separate files if you are also using toxics inventories.</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

<para><emphasis>If processing nonroad mobile sources separately, continue with these steps. Otherwise, the steps for area/non-point sources listed in <xref linkend="sect_scripts_area_invs" /> will be sufficient.</emphasis></para>
</listitem>

<listitem>
<para>Collect or create inventories in correct formats.</para>

<para>Inventory files for nonroad sources are usually named starting with <quote>nrinv</quote>, because the Assigns file uses the <envar>NRINV</envar> environment variable to set the <envar>ARINV</envar> logical file name (environment variable) that <command>Smkinven</command> uses to read the file. The list of available formats for nonroad mobile sources is:</para>

<orderedlist>
<listitem>
<para>List format. The list format is simply an ASCII file that lists all of the files that you want SMOKE to import in a single run.</para>
</listitem>
<listitem>
<para>ORL format. This format is most appropriate for criteria and toxics inventories, but also can be used for any inventory data.</para>
</listitem>
<listitem>
<para>FF10 format. This format is most appropriate for criteria and toxics inventories, but also can be used for any inventory data.</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Set and/or check the file headers that apply for your file format.</para>

<orderedlist>
<listitem>
<para>File format header: Make sure that the first line of the list file or individual files start with the #LIST (for list files only),#LIST GRID, #ORL, #FF10.</para>
</listitem>
<listitem>
<para>For other headers, please refer to the documentation in step (3) of the area/non-point steps in <xref linkend="sect_scripts_area_invs" />.</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Install inventory files in <filename class="directory"><envar>$NRDAT</envar></filename> directory.</para>

<para>This directory is <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/nonroad</filename>.</para>
</listitem>

<listitem>
<para>Ensure the Assigns file has the <envar>NRINV</envar> variable set to the <envar>NRINV</envar> file name for your new nonroad-mobile-source inventory file.</para>
</listitem>

<listitem>
<para>Optionally, set up to assign point-source locations to nonroad mobile sources using the <envar>ARTOPNT</envar> file.</para>

<para>Please refer to the documentation in step (6) of the area/non-point steps in <xref linkend="sect_scripts_area_invs" />.</para>
</listitem>

<listitem>
<para>See also steps for all source categories in <xref linkend="sect_scripts_all_invs" />.</para>
</listitem>

</orderedlist>

</section>

<section>

<title>On-road mobile inventories</title>

<orderedlist>
<listitem>
<para>Determine the file format that you have (for preformatted data) or want to create (for new data).</para>

<orderedlist>

<itemizedlist>
<listitem>
<para>If using MOVES emission factors through SMOKE, create a VMT file in FF10 on-road mobile activity format (or use in combination with list format).</para>
</listitem>
<listitem>
<para>If using both VMT and emissions, you <emphasis>must</emphasis> use a list-format to import the two separate inventories together. <comment>Also, it is important to make sure that the same sources appear in both inventories. This can be done outside of SMOKE before importing the inventory, or with <command>Smkreport</command>, after importing the inventories. After import, both VMT and emissions should appear in a report by source.</comment></para>
</listitem>
<listitem>
<para>If using both criteria and toxics data and wish to have the full functionality of SMOKE for both inventories, you must use a list file to list both inventory files (criteria and toxics) for SMOKE to combine.</para>
</listitem>

<comment>
<listitem>
<para><remark>It is possible to use the ORL format for criteria inventories, but you will not be able to integrate your VOC emissions in this case (<xref linkend="sect_concepts_combine_toxics" /> explains VOC integration).</remark></para>
</listitem>
</comment>

</itemizedlist>

</orderedlist>

</listitem>

<listitem>
<para>Collect or create inventories in correct formats.</para>

<para>Inventory files for on-road mobile sources are usually named starting with <quote>mbinv</quote>, because <command>Smkinven</command> uses the <envar>MBINV</envar> logical file name (environment variable) to read the file. The list of available formats for on-road mobile sources is:</para>

<orderedlist>
<listitem>
<para>List format. The list format is simply an ASCII file that lists all of the files that you want SMOKE to import in a single run.</para>
</listitem>
<listitem>
<para>ORL and FF10 format. These formats are most appropriate for toxics inventories, but also can be used for any inventory data.</para>
</listitem>

</orderedlist>

</listitem>

<listitem>
<para>Set and/or check the file headers that apply for your file format.</para>

<orderedlist>
<listitem>
<para>Please refer to the documentation in step (3) of the area/non-point steps in <xref linkend="sect_scripts_area_invs" />.</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Install inventory files in <filename class="directory"><envar>$MBDAT</envar></filename> directory.</para>

<para>This directory is <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/mobile</filename></para>
</listitem>

<listitem>
<para>Install other mobile-specific files in inventory directories.</para>

<para>The following mobile-specific files must also be installed in the <envar>MBDAT</envar> directory. These files can usually be copied from the example files provided with the SMOKE installation. The formats and additional discussion about the contents of these files can be found in <xref linkend="sect_input_source_mobile" />. These files are:</para>

<itemizedlist>
<listitem>
<para><envar>MCXREF</envar> (MOVES usage only)</para>
</listitem>
<listitem>
<para><envar>MFMREF</envar> (MOVES usage only)</para>
</listitem>
<listitem>
<para><envar>MEPROC</envar> (MOVES usage only)</para>
</listitem>
</itemizedlist>

<para>For all inputs needed for MOVES usage only, refer to <xref linkend="sect_scripts_use_moves" />.</para>

</listitem>

<listitem>
<para>See also steps for all source categories in <xref linkend="sect_scripts_all_invs" />.</para>
</listitem>

</orderedlist>

</section>

<section>

<title>Point/fires inventories</title>

<orderedlist>
<listitem>
<para>Determine the file format that you have (for preformatted data) or want to create (for new data).</para>

<orderedlist>
<listitem>
<para>Preformatted data considerations</para>

<itemizedlist>
<listitem>
<para>If you have preexisting data in SMOKE input format, then you will most likely want to use that format to input to SMOKE, unless you discover that you need a different format to take advantage of a SMOKE feature not available in a different format.</para>
</listitem>
<listitem>
<para>Pregridded data must be input as an area source.</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>New data considerations</para>

<itemizedlist>

<comment>
<listitem>
<para><remark>It is possible to use the SMOKE toxics format for criteria inventories, but you will not be able to integrate your VOC emissions in this case (<xref linkend="sect_concepts_combine_toxics" /> explains VOC integration).</remark></para>
</listitem>
</comment>

<listitem>
<para>Hour-specific or day-specific data (including precomputed plume-rise data) are covered in <xref linkend="sect_scripts_hour_day_invs" />.</para>
</listitem>

<listitem>
<para>For wildfires and prescribed fires emission modeling without precomputed plume rise, you could use <envar>ORL FIRE</envar> format for both criteria and toxics inventory together. Using a master (annual) inventory file (<envar>PTINV</envar>) for fires described in <xref linkend="sect_input_ptinv_fire"/>, SMOKE requires day-specific inventory file(s) (<envar>PTDAY</envar>) described in <xref linkend="sect_input_ptday_fireemis"/> to provide both criteria and toxics inventories for those matched sources. See more infomation about how-to-do at <xref linkend="sect_ptfire_emis_cmaq"/>.</para>
</listitem>

</itemizedlist>

</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Collect or create inventories in correct formats.</para>

<orderedlist>
<listitem>
<para>List format. The list format is simply an ASCII file that lists all of the files that you want SMOKE to import in a single run.</para>
</listitem>
<listitem>
<para>ORL format. This format is most appropriate for point toxics inventories, but also can be used for any inventory data.</para>
</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Set and/or check the file headers that apply for your file format.</para>

<para>Please refer to the documentation in step (3) of the area/non-point steps in <xref linkend="sect_scripts_area_invs" />.</para>
</listitem>

<listitem>
<para>Install inventory files in <filename class="directory"><envar>$PTDAT</envar></filename> directory.</para>

<para>This directory is <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/point</filename></para>
</listitem>

<listitem>
<para>Ensure the Assigns file has the <envar>PTINV</envar> variable set to the <envar>PTINV</envar> file name for your point-source inventory file.</para>
</listitem>

<comment>
<listitem>
<para><envar>VELOC_RECALC</envar> <remark>Missing text - see <xref linkend="sect_programs_smkinven" /></remark></para>
</listitem>
</comment>

<listitem>
<para>For hour-specific and day-specific data, including fire data, see <xref linkend="sect_scripts_hour_day_invs" />.</para>
</listitem>

<listitem>
<para>See also steps for all source categories in <xref linkend="sect_scripts_all_invs" />.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_hour_day_invs">

<title>Day-specific and hour-specific point and fire inventories</title>

<para>Point sources in SMOKE can include day-specific or hour-specific data. This can include fire emissions and plume rise data. The following steps must be performed to use day-specific and/or hour-specific data in SMOKE.</para>

<orderedlist>
<listitem>
<para>Determine the files that need to be created and their formats</para>

<orderedlist>
<listitem>
<para>For day-specific emissions data, create the list file <envar>PTDAY</envar> and one or more files with day-specific emissions in the format provided in <xref linkend="sect_input_ptday" />. The format requires that a list file be used to point to the actual data files, even if a single data file with emissions data is used.</para>
</listitem>
<listitem>
<para>For day-specific emissions data, the daily total should ideally be based on the same time zone as is being modeled by SMOKE. SMOKE needs to use the same output time zone (set with the <envar>OUTZONE</envar> setting) as is used in the meteorology data that will be input to the air quality model. For example, if the time zone being modeled by SMOKE were GMT, then ideally the daily total emissions would be from 0 GMT to 23 GMT for each day.</para>
</listitem>
<listitem>
<para>For hour-specific emissions data that is <emphasis>not</emphasis> CEM data, create the list file <envar>PTHOUR</envar> and one or more files with hour-specific emissions in the format provided in <xref linkend="sect_input_pthour" />. The format requires that a list file be used to point to the actual data files, even if a single data file with emissions data is used.</para>
</listitem>
<listitem>
	<para>If using CEM data, the data files for 1995 through 2000 are available with SMOKE. A list file <envar>PTHOUR</envar> must be created to list the one or more CEM data files that will be input. To speed processing, the DATERANGE setting can be used in the list file <envar>PTHOUR</envar> to cause SMOKE to skip the dates in the CEM files that are not needed.  Detail information is described in <xref linkend="sect_concepts_hour_specific_cem" /></para>
</listitem>
<listitem>
<para>If using hourly precomputed plume rise (e.g., for fire data), the <envar>PTHOUR</envar> file should be created as described above for emissions data, but specific variable names must be provided<comment>, as described in the file format documentation in <xref linkend="sect_input_pthour" /></comment>. The allowable data includes the fraction of the plume in layer 1, the plume bottom height, and the plume top height.</para>
</listitem>
<listitem>
<para>If using daily fire inventories without precomputed plume rise, the <envar>PTDAY</envar> file should be created as described above for emissions data and specific variables ( size of acres burned, fuel loading, and duration of fire ) must be provided for plume rise calculation and re-normalization of temporal profiles, as described in the file format documentation in <xref linkend="sect_input_ptinv_fire" /> and <xref linkend="sect_input_ptday_fireemis" />.</para>
</listitem>
<listitem>
<para>If using hourly stack exit temperature, velocity, or flow rates, the <envar>PTHOUR</envar> file should be created as described above for emissions data, but specific variable names must be provided, as described in the file format documentation in <xref linkend="sect_input_pthour" />.</para>
</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Install inventory files in <filename class="directory"><envar>$PTDAT</envar></filename> directory.</para>

<para>This directory is <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/point</filename></para>
</listitem>

<listitem>
<para>Ensure the Assigns file has the <envar>PTHOUR</envar> and <envar>PTDAY</envar> variables set to the <envar>PTHOUR</envar> and <envar>PTDAY</envar> file names for your inventory files.</para>
</listitem>

<listitem>
<para>Ensure script settings will use the day-specific and hour-specific data.</para>

<orderedlist>
<listitem>
<para>For day-specific data import and usage, set <envar>DAY_SPECIFIC_YN</envar> setting to Y.</para>
</listitem>
<listitem>
<para>For hour-specific data import and usage, set <envar>HOUR_SPECIFIC_YN</envar> setting to Y. This applies to using either hourly emissions or hourly-precomputed plume rise.</para>
</listitem>
</orderedlist>

</listitem>
<listitem>
<para>If using hourly data, make sure the <envar>OUTZONE</envar> setting is consistent with what will be used for other SMOKE processing steps.</para>

<para>The example SMOKE scripts make it difficult to not use the same <envar>OUTZONE</envar> setting for all processing steps. Nevertheless, the user is responsible for ensuring that the same setting is used for all SMOKE processing steps, including import of hourly inventories. The <envar>OUTZONE</envar> setting will affect the hourly inventory import because the hourly emissions will be adjusted by <command>Smkinven</command> from the local time zones in the <envar>PTHOUR</envar> input files to the output time zone set by <envar>OUTZONE</envar> to create the <envar>PHOUR</envar> intermediate file.</para>
</listitem>

<listitem>
<para>If using precomputed plume rise, ensure script settings will cause SMOKE to use the plume rise data.</para>

<orderedlist>
<listitem>
<para>Set <envar>HOUR_PLUMEDATA_YN</envar> setting to Y.</para>
</listitem>
<listitem>
<para>For UAM and CAM<subscript>X</subscript> modeling, set:</para>

<itemizedlist>
<listitem>
<para><envar>RUN_LAYPOINT</envar> setting to Y (this program is not usually needed for these models)</para>
</listitem>
<listitem>
<para><envar>EXPLICIT_PLUMES_YN</envar> setting to Y</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>
</listitem>

<listitem>
<para>For fires emission modeling with internal plume rise calculation, SMOKE compute the plume rise data with internally computed heat flux from fuel loading and burned area. See detail at <xref linkend="sect_ptfire_emis_cmaq"/></para>
</listitem>

<listitem>
<para>If providing future-year hour-specific data, ensure that the dates used in the file are consistent with the <emphasis>base year</emphasis> dates. The dates must match the dates of the meteorology data that will be used by the air quality model.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_future_invs">

<title>Future-year inventories</title>

<para>For future-year modeling, you can choose to input future-year inventories to SMOKE. This is a different approach from importing a base-year inventory and using SMOKE growth to create a future-year inventory. The future-year inventory could be created outside of SMOKE and would need to be in one of the SMOKE input formats available for the source categories of interest.</para>

<para>A future-year inventory could also be created by SMOKE, since the <command>Grwinven</command> program can output emissions in ORL format. In this section, we do not cover importing base year inventories and using SMOKE to grow them to a future year; that topic is covered in <xref linkend="sect_scripts_use_projection" />. Following the instructions in that section, it is feasible to create a future-year inventory in SMOKE raw input format and use it as we describe in this section.</para>

<orderedlist>
<listitem>
<para>Set the #YEAR setting in the inventory input files to the future inventory year.</para>
</listitem>
<listitem>
<para>Set the <envar>SMK_BASEYR_OVERRIDE</envar> setting in the run script to the value of the base year.</para>

<para>Ordinarily, this setting would simply be set to zero, which indicates that it is not to be used and the inventory year is the same as the base year. In this case, the base year cannot be set by the inventory year, so this setting provides the actual year to use. The base year is most often the same year as the year of meteorology data you are using to model your episode. When this setting is defined by a script, <command>Smkinven</command> will set the base year with that setting and set the future year as the year of the inventory data.</para>
</listitem>
<listitem>
<para>Set the <envar>YEAR</envar> setting in the Assigns file to the base year.</para>
</listitem>
<listitem>
<para>Set the <envar>FYEAR</envar> setting in the run scripts to the future year.</para>
</listitem>
<listitem>
<para>Set the <envar>SMK_FUTURE_YN</envar> setting in the run scripts to Y.</para>
</listitem>
</orderedlist>

<para>See <xref linkend="sect_scripts_script_settings" /> for more information about how this setting affects the output directory structure and file names.</para>

</section>

<section id="sect_scripts_pregridded">
	        <title>Pre-gridded inventories</title>
		        <para>Smoke has two ways of processing the pregridded inventory data.  If the inventory data is in native netCDF format then see <xref linkend="sect_scripts_pregridded_invs_same" />.  If the inventory is in IO-API/netCDF format then see <xref linkend="sect_scripts_pregridded_invs_different" /> </para>

<section id="sect_scripts_pregridded_invs_same">

<title>Pre-gridded inventories from the same modeling domain as an area source without source characterization or attributes</title>

<para>SMOKE has a limited capability to import pre-gridded data from the same modeling domain. It can import the data if it is time-independent and if the grid cell and pollutant names are the only attributes needed to identify the emissions. If SCC or other attributes are available, SMOKE cannot use these directly; though in the case of SCCs, each SCC could conceivably be tediously input as a separate dataset and modeled as a separate inventory.</para>

<para>If any source category is available as pre-gridded data, the following steps must be taken.</para>

<orderedlist>
<listitem>
<para>Plan to import the data as an area source.</para>

<para>Only SMOKE area-source processing can use pre-gridded data, no matter that actual source category of origin for the data. Essentially, once emissions data no longer has attributes such as SCCs, stack information for point sources, or country/state/county codes, it all appears to be the same type of data to SMOKE and can be processed as an area source.</para>

<para>This is not to say that all pre-gridded inventories can be processed correctly by SMOKE. For example, if a pre-gridded point source inventory including stack identifiers and stack parameters were provided with grid cell numbers instead of lat/lon coordinates, this could not be appropriately processed by SMOKE area processing as pre-gridded data.</para>

<para>If any SMOKE processing steps such as chemical speciation or temporal allocation need to be done based on SCC, this is not possible. Only a single default profile for speciation or temporal allocation can be applied to each pre-gridded inventory.</para>
</listitem>
<listitem>
<para>Convert data to I/O API format.</para>

<para>Users must convert the pre-gridded data to I/O API format. The format is like the <envar>AG</envar> file that can be output from <command>Smkmerge</command>. This format has each pollutant stored as a variable and is time independent. Some sort of ASCII-to-I/O API converter must be created and used to perform this step. At this time, there is no general-purpose tool to make such a conversion released with the SMOKE system.</para>
</listitem>
<listitem>
<para>Set the <envar>IMPORT_GRDIOAPI_YN</envar> setting to Y.</para>

<para>This setting will cause <command>Smkinven</command> to expect the I/O API gridded input and will request the <envar>AG</envar> logical file name instead of the <envar>ARINV</envar> file.</para>
</listitem>
<listitem>
<para>Ensure that the <envar>AG</envar> logical file name is set by the Assigns file or by the run script.</para>

<para>This logical file name must be set to the I/O API-formatted pre-gridded inventory file.</para>
</listitem>
</orderedlist>

</section>
<section id="sect_scripts_pregridded_invs_different">

<title>Pre-gridded inventories processing for converting between different modeling domains with source characterization and attributes</title>
<para>SMOKE will regrid the data from the native NetCDF-formatted pregridded inventory data (e.g. lat-lon for global inventories) to the CMAQ modeling grid, and apply a unique source ID to each grid cell to allow SMOKE to perform chemical speciation, temporal allocation from annual to hourly timesteps, and elevated source selection and vertical allocation. The pre-gridded inventory files each contain data for a different sector, the sector and pollutant contained in each pre-gridded inventory file is specified in the ARINV file using the #LIST GRID format.</para>
<para>To process pre-gridded data from different modeling domains, the following steps must be taken.</para>
<orderedlist>
<listitem>
<para> Set the <envar>IMPORT_GRDNETCDF_YN</envar> to Y to read the native netCDF annual inventory files.</para>
</listitem>
<listitem>
<para>Grdmat is used to convert the data from the input data grid (e.g. lat-lon for EDGAR/RCP/HTAP) to the output modeling grid. Set the <envar>IOAPI_GRIDNAME_1</envar> to specify the output grid.</para>
</listitem>
<listitem>
<para>SMOKE reads each grid cell in the gridded inventory file as a unique source that will have a unique source ID.  The lower left corner of inventory grid will be source 1, cell (2,1) will be source 2, cell (3,1) source 3, etc</para>
</listitem>
<listitem>
<para> For each gridded inventory file, a Geographical Code Mask Input file (GRIDMASK) is provided by UNC for EDGAR inventory files that assigns a GEOGRID_LEVEL2 value to each grid cell.</para>
</listitem>
<listitem>
<para> The ARINV file is used to read in a list of gridded inventory files and to specify the SCC associated with each gridded inventory file</para>
</listitem>
<listitem>
<para> Set the <envar>NETCDF_POL_UNIT</envar> to kg m-2 -s</para>
</listitem>
<listitem>
<para> Set the <envar>NETCDF_INV_YEAR</envar> to the year of the inventory (e.g. 2010)</para>
</listitem>
<listitem>
<para> To apply control factors to adjust emissions by GEOCODE_LEVEL and SCC use the CONTROL packet in the GCNTL file </para>
</listitem>
<listitem>                                                                                                                             
	<para> To apply vertical profiles to gridded inventory data using the SMOKE Utility Program Layalloc. The EDGAR inventory includes fixed vertical profiles by sector that define the percentages of emissions by altitude band. Layalloc will create 3-d output files for the gridded emissions sectors that emit above the surface layer (e.g. energy and industrial sources).  </para>
</listitem>  
</orderedlist>

</section>
</section>

<section id="sect_scripts_all_invs">

<title>Files and settings for all inventories</title>

<para>For importing all inventories, the following steps should be taken to review settings and change them as appropriate for your specific modeling case.</para>

<para>Assigns file settings:</para>

<orderedlist>
<listitem>
<para>Change the Assigns files inventory settings.</para>

<para>Following the settings in <xref linkend="sect_scripts_change_assigns" />, you should have created a new Assigns file for your case and set the <envar>INVID</envar>, <envar>INVEN</envar>, and <envar>INVOP</envar> settings described in <xref linkend="tbl_scripts_variables_files" />. Since the inventory input directories depend on the <envar>INVID</envar> setting, you should make sure that the value set for <envar>INVID</envar> is consistent with the location of the inventory files. For example, the <envar>ARINV</envar> files should be installed in <filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVID</envar>/area</filename>. Make sure that <envar>$INVID</envar> label in the paths for the files installed in prior subsections is the same as the <envar>$INVID</envar> label in the Assigns file that is included in the Assigns file you will use.</para>
</listitem>
<listitem>
<para>Set the <envar>ABASE</envar>, <envar>MBASE</envar>, <envar>PBASE</envar>, and <envar>EBASE</envar> settings described in <xref linkend="tbl_scripts_variables_files" />. This is usually done for a new inventory, and can also be done for new scenarios with an existing inventory.</para>
</listitem>
</orderedlist>

<para>Script settings:</para>

<orderedlist continuation="continues">
<listitem>
<para>Double check that the correct Assigns file (e.g., the one with the correct <envar>$INVID</envar> setting) is used by the run scripts for your case.</para>
</listitem>
<listitem>
<para>Set the <envar>RAW_DUP_CHECK</envar> setting to Y if you want <command>Smkinven</command> to give an error if any duplicate entries are found in the inventory. See <xref linkend="sect_programs_smkinven" /> for more information.</para>
</listitem>
<listitem>
<para>Set the <envar>SMKINVEN_FORMULA</envar> setting to compute one or more pollutant values from teh values of other pollutants.</para>

<para>This is most commonly used to compute coarse particulates (PMC) from PM<subscript>10</subscript> and PM<subscript>2.5</subscript> using the setting <quote>PMC = PM10 - PM2_5</quote>.</para>
</listitem>
<listitem>
<para>Set the <envar>WEST_HSPHERE</envar> setting to reset any positive longitude values that are intended for the Western hemisphere to a negative value.</para>
</listitem>
<listitem>
<para>Set the <envar>WKDAY_NORMALIZE</envar> setting to account for the desired weekday normalization approach to be used for hourly emissions. See <xref linkend="sect_programs_smkinven" /> for more information.</para>
</listitem>
<listitem>
<para>Set the <envar>SMK_PROCESS_HAPS</envar> to read the <envar>NHAPEXCLUDE</envar> file.</para>

<para>This setting is only relevant when importing both criteria and toxic inventories. In this case, if there are VOCs in both inventories and the <envar>INVTABLE</envar> has indicate which toxics are VOCs, <command>Smkinven</command> will attempt to integrate VOC emissions for all sources from the criteria and toxics inventories. The <envar>NHAPEXCLUDE</envar> file provides a list of SCCs for which <command>Smkinven</command> should not integrate the inventories and should instead drop the toxic VOC emissions to prevent double counting. Toxic emissions of explicit model species are never dropped, however. More information is available in <xref linkend="sect_concepts_combine_toxics" />.</para>
</listitem>
<listitem>
<para>Set the <envar>SMK_ARTOPNT_YN</envar> setting to Y when <command>Smkinven</command> should use the <envar>ARTOPNT</envar> file to assign point source locations to area-source emissions.</para>
</listitem>
<listitem>
<para>Set the <envar>FILL_ANNUAL</envar> setting to Y to fill annual emissions values with average-day values, when average-day values are available but annual values are not.</para>

<para>See <xref linkend="sect_scripts_average_day_invs" /> for more information on why one might want to use this option.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_average_day_invs">

<title>Using average-day and annual data in the same run</title>

<para>The ORL and FF10 formats provide fields for both annual and average-day emissions values. SMOKE will import both values when either of these formats are used and store all emissions in the SMOKE intermediate inventory files. To configure the <command>Temporal</command> allocation step, you have the option of using the <envar>SMK_AVEDAY_YN</envar> setting to select using either the annual or average-day data when both are available. This option and its typical usage will be explained with the <command>Temporal</command> settings.</para>

<para>This section describes what to do when both annual data and average-day data need to be used in the same SMOKE run. This can occur when part of an inventory has been provided using annual inventories only (the average-day values are missing or incorrect) and a different part with average-day inventories only (the annual values are missing). This is only a problem when you want to run all of the sources in a single run; so, if nonroad and stationary area sources are provided with the two different temporal resolutions, these can just be run with separate SMOKE runs. If two parts of the stationary area source inventory are provided with two different temporal resolutions, then this section can help to setup the modeling correctly.</para>

<para>Two approaches are available in SMOKE to resolve this situation. In the first approach, one can set SMOKE to run using the average-day data, and in the second approach, set to use the annual data. These lists describe these two approaches:</para>

<para>Run all sources using <quote>annual</quote> data</para>

<orderedlist>
<listitem>
<para>Set the <envar>FILL_ANNUAL</envar> setting to Y. This will cause the missing annual data to be filled in with the available average-day data by multiplying the number of days in the year, accounting for leap years.</para>
</listitem>
<listitem>
<para>Ensure that the monthly temporal profile assignments made by the <envar>ATREF</envar>, <envar>MTREF</envar>, or <envar>PTREF</envar> files assign uniform monthly profiles to any all sources that have the annual numbers filled in with seasonal values.</para>
</listitem>
<listitem>
<para>During temporal processing, set <envar>SMK_AVEDAY_YN</envar> to N. This will ensure that both the annual values that were available in the inventory and the annual values that were computed will be used by the <command>Temporal</command> program. Since the monthly temporal profiles for the filled-in annual emissions have been set to uniform, the average-day values will be calculated from the filled-in annual values.</para>
</listitem>
</orderedlist>

<para>Run all sources using average-day data</para>

<orderedlist>
<listitem>
<para>Set the <envar>FILL_ANNUAL</envar> setting to N. By default, <command>Smkinven</command> computes an average-day value when none is provided by dividing the annual value by the number of days in the year, accounting for leap years.</para>
</listitem>
<listitem>
<para>During temporal processing, set <envar>SMK_AVEDAY_YN</envar> to Y. This will ensure that both the average-day values that were available in the inventory and the average-day values that were computed will be used by the <command>Temporal</command> program.</para>
</listitem>
<listitem>
<para>Note that no monthly profiles are applied to average-day emissions, so if monthly variation is needed, it will need to be calculated outside of SMOKE. In this case, it might be easier to run all sources as annual, as described above.</para>
</listitem>
</orderedlist>

</section>

</section>

<section>

<title>Select which pollutants in the inventory are kept</title>

<para>Users have the option of deciding at run time which inventory pollutants will be kept from an inventory provided in ORL format.  The <envar>INVTABLE</envar> file lists all possible criteria and toxic pollutants. While the example files are fairly comprehensive, it is possible users may need to add pollutants to this file using the <envar>INVTABLE</envar> file format description. Additionally, users can change which pollutants are kept for further processing in SMOKE. This is done by setting the Keep column of the file to Y for all pollutants that SMOKE should keep, all pollutants in these files must have the Keep column set to Y.</para> 
<para>Both the run time and intermediate file sizes can be reduced by keeping only the pollutants that you need to include for modeling purposes. In the bulleted list below, we provide several examples of why a user might want to change which pollutants are kept.</para>

<itemizedlist>
<listitem>
<para>You want to model additional toxics not set up in the example configuration (e.g., atrazine, dioxin).</para>
</listitem>
<listitem>
<para>You want to import ROG emissions instead of VOC emissions from a criteria inventory.</para>
</listitem>
<listitem>
<para>You want to import only mercury for CMAQ modeling and drop all other toxic pollutants.</para>
</listitem>
<listitem>
<para>You want to add a tracer to the inventory and need SMOKE to output the tracer emissions to the model-ready file.</para>
</listitem>
</itemizedlist>

</section>

<section>

<title>Set fallback stack paramaters</title>

<para>The <command>Smkinven</command> program allows you to fill in stack parameters for sources that do not have any. The details of how this is done are described in <xref linkend="sect_concepts_check_stack_params" />.  To change the defaults, the <envar>PSTK</envar> input file to <command>Smkinven</command> must be edited to use different stack parameters and/or include different state/county and SCC codes.</para>

<para>To discover what if any default stack parameters are being used for your SMOKE processing, review the <command>Smkinven</command> log file, which will contain warnings about all stack parameters that were filled in and changed from the inventory values.</para>

</section>

<section>

<title>Changing output and intermediate directory names</title>

<para>As described in <xref linkend="ch_dirs_files" /> and also <xref linkend="tbl_scripts_variables_files" />, the output and intermediate directory names are based on user-defined environment variables. The following list provides a checklist for all of the possible changes that you might make and where to find more information on how changes would affect your output and intermediate directories. Make sure that the scripts that you are using to run SMOKE use the same Assigns file in which you are making the changes described in this list.</para>

<orderedlist>
<listitem>
<para>Set the <envar>INVEN</envar> setting in the Assigns file to the label to use in the output inventory path (<filename class="directory"><envar>$SMKDAT</envar>/inventory/<envar>$INVEN</envar></filename>).</para>
</listitem>
<listitem>
<para>Decide whether you want to use the same setting or different settings for <envar>ABASE</envar>, <envar>MBASE</envar>, <envar>PBASE</envar>, and <envar>EBASE</envar> in the Assigns file.</para>

<para>If these are the same, the directory structure will be the <quote>basic</quote> configuration, and if these are different, the structure will be the <quote>advanced</quote> configuration; both configurations are described in <xref linkend="ch_dirs_files" />.</para>

<orderedlist>
<listitem>
<para>Set the <envar>ABASE</envar> setting to change the paths for stationary area and nonroad mobile source intermediate and output files.</para>
</listitem>
<listitem>
<para>Set the <envar>MBASE</envar> setting to change the paths for on-road mobile source intermediate and output files.</para>
</listitem>
<listitem>
<para>Set the <envar>PBASE</envar> setting to change the paths for point source intermediate and output files.</para>
</listitem>
<listitem>
<para>Set the <envar>EBASE</envar> setting to change the path for the final merged model-ready emissions from all source categories. This will also set the output path for QA reports of anthropogenic sources. See <xref linkend="ch_dirs_files" /> for specifics.</para>
</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Set the <envar>BBASE</envar> setting in the Assigns file to select using BELD3 or BELD4 data. See <xref linkend="sect_scripts_use_beis3" />.</para>
</listitem>
<listitem>
<para>Set the <envar>SPC</envar> setting in the Assigns file to change the output paths for all source categories.</para>

<para>As described in <xref linkend="ch_dirs_files" />, the <envar>OUTPUT</envar> directory is based in part on this <envar>SPC</envar> setting. This setting must be coordinated with the selection of the chemical speciation mechanism (see <xref linkend="sect_scripts_change_speciation" />).</para>
</listitem>
<listitem>
<para>For future year modeling, the output paths will be changed automatically.</para>

<para>As described in <xref linkend="ch_dirs_files" />, the <envar>FYEAR</envar>, <envar>CNTLCASE</envar>, <envar>SMK_FUTURE_YN</envar>, and <envar>SMK_CONTROL_YN</envar> script settings can have an impact on the output directory paths. When either <envar>SMK_FUTURE_YN</envar> or <envar>SMK_CONTROL_YN</envar> are set to Y, the output path will be changed as described in <xref linkend="ch_dirs_files" /> for the growth and control case configuration.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_change_programs">

<title>Change which programs are run</title>

<para>The example SMOKE scripts each have several <envar>RUN_&lt;Program&gt;</envar> settings, where the program names fill in the <envar>&lt;Program&gt;</envar> placeholder. For example, the <envar>RUN_&lt;Program&gt;</envar> setting that controls the <command>Smkinven</command> program is <envar>RUN_SMKINVEN</envar>. In the scripts, each <envar>RUN_&lt;Program&gt;</envar> setting can be set to either Y for <quote>yes</quote> and N for <quote>no</quote>. When a <envar>RUN_&lt;Program&gt;</envar> setting is set to Y, the script will try to run the program associated with the <envar>RUN_&lt;Program&gt;</envar> setting. For example, when <envar>RUN_SMKINVEN</envar> is set to Y in the script, running the script will cause the <command>Smkinven</command> program to run.</para>

<para><xref linkend="tbl_scripts_run_programs" /> is the full list of <envar>RUN_&lt;Program&gt;</envar> settings available and the situations in which each needs to be run.</para>

<table id="tbl_scripts_run_programs">
<title>List of <envar>RUN_&lt;Program&gt;</envar> settings and situations to set to Y</title>

<tgroup cols="2">
<colspec colwidth="1*" />
<colspec colwidth="4*" />

<thead>
<row>
<entry align="center">Setting</entry>
<entry align="center">Reasons to set to Y to run program</entry>
</row>
</thead>

<tbody>
<row>
<entry><envar>RUN_SMKINVEN</envar></entry>
<entry>Import raw inventory data and create SMOKE intermediate inventory file for area, nonroad mobile, on-road mobile, or point sources</entry>
</row>
<row>
<entry><envar>RUN_SPCMAT</envar></entry>
<entry>Compute speciation factors and create speciation matrix for area, nonroad mobile, on-road mobile, point sources.</entry>
</row>
<row>
<entry><envar>RUN_GRDMAT</envar></entry>
<entry>Compute gridding factors and create gridding matrix for area, nonroad mobile, on-road mobile, or point sources.</entry>
</row>
<row>
<entry><envar>RUN_CNTLMAT</envar></entry>
<entry>Compute growth factors and create growth matrix for area, nonroad mobile, on-road mobile, or point sources. Compute control factors and create multiplicative control and/or reactivity control matrices for area, nonroad mobile, on-road mobile, or point sources.</entry>
</row>
<row>
<entry><envar>RUN_GRWINVEN</envar></entry>
<entry>Calculate grown and/or controlled inventory and create SMOKE intermediate inventory files for area, nonroad mobile, on-road mobile, or point sources. Required when using SMOKE to create future-year inventories.</entry>
</row>
<row>
<entry><envar>RUN_TEMPORAL</envar></entry>
<entry>Calculate hourly emissions and create intermediate hourly emissions file for area, nonroad mobile, on-road mobile, or point sources.</entry>
</row>
<row>
<entry><envar>RUN_ELEVPOINT</envar></entry>
<entry>Select elevated and PinG point sources.</entry>
</row>
<row>
<entry><envar>RUN_LAYPOINT</envar></entry>
<entry>Calculate plume rise for CMAQ for any point sources. Calculate plume rise for UAM or CAM<subscript>X</subscript> for explicit plume-rise sources (i.e., those sources with precomputed plume rise).</entry>
</row>
<row>
<entry><envar>RUN_MOVESMRG</envar></entry>
<entry>Create 3-d model-ready emissions by merging MOVES RPD, RPP and RPV Look-up tables with Spcmat and Grdmat for mobile sources.</entry>
</row>
<row>
<entry><envar>RUN_SMKMERGE</envar></entry>
<entry>Create 3-d model-ready emissions for point sources or all source categories together for CMAQ. Create 2-d gridded, hourly, speciated emissions for area sources, nonroad mobile sources, on-road mobile sources, point sources, and/or all sources combined in I/O API format. Convert units of biogenic outputs from <command>Tmpbio</command> from moles/hr to moles/s for CMAQ. Create ASCII elevated point source file for UAM or CAM<subscript>X</subscript>.</entry>
</row>
<row>
<entry><envar>RUN_SMK2EMIS</envar></entry>
<entry>Convert 2-d merged I/O API file with all low-level emissions from <command>Smkmerge</command> to binary input format for UAM or CAM<subscript>X</subscript>.</entry>
</row>
<row>
<entry><envar>RUN_SMKREPORT</envar></entry>
<entry>Create default and/or custom reports of processed emissions.</entry>
</row>
<row>
<entry><envar>RUN_NORMBEIS3</envar></entry>
<entry>Import gridded BELD3 landuse for use in creating BEIS3 emissions.</entry>
</row>
<row>
<entry><envar>RUN_TMPBEIS3</envar></entry>
<entry>Calculate BEIS3 emissions in gridded, hourly, speciated I/O API format.</entry>
</row>

</tbody>

</tgroup>
</table>

</section>

<section>

<title>Set up country codes, state codes, or county codes</title>

<para>By default, SMOKE is setup to use the country, state, and county codes based on a U.S. view. The codes assume a 3-tier system of codes as described in <xref linkend="sect_concepts_costcy_codes" />. The three tiers allow specification of regions as follows:</para>

<itemizedlist>
<listitem>
<para>One digit for country code</para>
</listitem>
<listitem>
<para>Two digits for state codes</para>
</listitem>
<listitem>
<para>Three digits for county codes</para>
</listitem>
</itemizedlist>

<para>All codes provided in the emission inventories must be integers and must match entries in the <envar>COSTCY</envar> or <link linkend="sect_input_geocode"><envar>GEOCODE_LEVEL4</envar></link> (if USE_EXP_GEOCODE Y) file, which is the master list of country, state, county and tribal codes in any given SMOKE installation. The format for the COSTCY file can be found in <xref linkend="ch_input_files" />. By default, the codes are shared by all scenarios installed in the same SMOKE system (using different <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> (if USE_EXP_GEOCODE Y) files requires changing the Assigns file to not share the same <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> (if USE_EXP_GEOCODE Y) file among all cases).</para>

<para>The codes in the inventory must match the codes in this file. SMOKE assigns time zones, daylight saving time exemptions, state names, and county names using this file. Therefore, if one of the counties in the inventory does not match a valid country, state, and county code in the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> file (if USE_EXP_GEOCODE Y), it can cause errors in the modeling.</para>

<para>The following list provides the steps that users should take to ensure that the file will work for their modeling case:</para>

<orderedlist>
<listitem>
	<para>Check whether the countries with data in the inventory are included in the /COUNTRY/ section of the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> (if USE_EXP_GEOCODE Y) file.</para>
</listitem>
<listitem>
<para>Change country codes and names if necessary within the limitation of 10 countries per file. If the country codes change, the country-specific SMOKE temporal profile assignments made by <envar>ATREF</envar>, <envar>MTREF</envar>, and <envar>PTREF</envar> may no longer be valid.</para>
</listitem>
<listitem>
	<para>Check whether the states with data in the inventory are included in the /STATE/ section of the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> file (if USE_EXP_GEOCODE Y) file.</para>
</listitem>
<listitem>
<para>Change or add state codes and names if necessary to ensure all states are listed for all countries.</para>
</listitem>
<listitem>
	<para>Check whether the counties with data in the inventory are included in the /COUNTY/ section of the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> file (if USE_EXP_GEOCODE Y) file and that all counties have assigned time zones.</para>

	<para><command>Smkinven</command> will perform this function for you if needed and will list in the <command>Smkinven</command> log file all counties that are not included in the <envar>COSTCY</envar> or <envar>GEOCODE_LEVEL[1-4]</envar> file (if USE_EXP_GEOCODE Y) file or that do not have time zones assigned. If county codes have changed for merged or separated counties (e.g., Miami/Dade county in Florida).</para>
</listitem>
<listitem>
<para>Change or add county codes and names if necessary to ensure all counties are included in the inventory for all states and countries and that time zones have been assigned to each.</para>
</listitem>
</orderedlist>

</section>

<section>

<title>Set up list of known SCCs and ORIS IDs</title>

<para>The descriptions of the SCCs and ORIS IDs in SMOKE can be updated easily by modifying or adding to the files that contain these codes. The SCC descriptions are used in <command>Smkreport</command> output reports, and the ORIS ID descriptions are used in <command>Smkinven</command> reports when using CEM data. Updating the files descriptions or valid codes is simply a matter of editing the ASCII files that contain these codes. The logical file name for the SCC description file is <envar>SCCDESC</envar>, and that for the ORIS ID description is <envar>ORISDESC</envar>. Example <envar>SCCDESC</envar> and <envar>ORISDESC</envar> files are in the <filename class="directory"><envar>$GE_DAT</envar></filename> directory and described in <xref linkend="sect_dirs_example_data_files" />.</para>

</section>

<section id="sect_scripts_use_grid">

<title>Use a new modeling grid or change spatial inputs (anthropogenic and biogenic)</title>

<para>Using a new modeling grid and/or changing the spatial inputs requires a number of changes to the Assigns file, scripts, and input files. In this section, we first describe how to set up for a different modeling grid and then how to install new inputs for that grid or change the spatial inputs for the existing grid.</para>

<section>

<title>Set up for a different modeling grid</title>

<para>The following steps are needed to set up for a different modeling grid.</para>

<orderedlist>
<listitem>
<para>Insert or find the grid parameters in the <envar>GRIDDESC</envar> file</para>

<para>The <envar>GRIDDESC</envar> file contains many grid descriptions and grid projections. Each grid description is defined by a 16-character (or less) name. <xref linkend="ch_input_files" /> contains the file format. If the grid you want is already in the file, note its name.</para>

<para>If the grid you want is not in the file, use the format in <xref linkend="ch_input_files" /> to insert or modify a grid description for the new grid. The grid cells must align with the cells of the cross-grid meteorology data files that will be used for modeling biogenic emissions and possibly for point and on-road mobile sources.</para>
</listitem>
<listitem>
<para>Change the <envar>GRID</envar> variable in the Assigns file to a new grid name</para>

<para>As described in Section <xref linkend="sect_scripts_change_assigns" />, change the <envar>GRID</envar> environment variable to a name that will be used to name output and intermediate files. This name should be coordinated with the selection made in step 3. Since the <envar>GRID</envar> variable is used in naming files, it is helpful to use a name that is easily distinguished from other grid names that you might use, but not so long as to add a lot of characters to the name of each file that includes the <envar>GRID</envar> variable in its name. Usually a name of 4 or 5 characters is sufficient.</para>

<para>Changing the <envar>GRID</envar> setting is a good reason to create a new Assigns file. To do this, you can copy an existing Assigns file as described in <xref linkend="sect_scripts_how_use_smoke" />.</para>
</listitem>
<listitem>
<para>Change  the <envar>IOAPI_GRIDNAME_1</envar> variable in the Assigns file to the name of the grid entered or found in step 1.</para>

<para>As noted in step 2, the name selected should have some relationship to the <envar>GRID</envar> environment variable. For example, if the <envar>IOAPI_GRIDNAME_1</envar> setting is <quote>US36_120X90</quote>, the <envar>GRID</envar> setting might be <quote>us36</quote>.</para>
</listitem>
<listitem>
<para>Update the run scripts to use the Assigns file for the new grid.</para>
</listitem>
<listitem>
<para>Follow the remaining steps in the next subsection.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_install_spatial_inputs">

<title>Installing or changing spatial input files</title>

<para>The following steps are needed to install or change the spatial input files.</para>

<orderedlist>
<listitem>
<para>Update or install the grid description in the <envar>GRIDDESC</envar> file, if not done previously (see step 1 in the previous subsection).</para>
</listitem>
<listitem>
<para>Create and install the spatial surrogates file and surrogate description file <envar>SRGDESC</envar></para>

<para>The Area and Mobile spatial surrogates files located in <envar>SRGPRO_PATH</envar> and the <envar>BGPRO</envar> are one of the most difficult inputs to create for SMOKE. The gridded data in the files must match the definition in the <envar>GRIDDESC</envar> and <envar>SRGDESC</envar> files for the grid selected using the <envar>IOAPI_GRIDNAME_1</envar> variable.</para>

<para>The best approach to creating this file is to obtain it from someone else who has created surrogates for your domain. For example, EPA has developed various spatial surrogates and available at EPA&rsquo;s Emission Modeling Clearinghouse (<ulink url="http://www.epa.gov/ttn/chief/emch/index.html">http://www.epa.gov/ttn/chief/emch/</ulink>). Of course, using a national file has its limitations if your domain happens to be far away from the center of the U.S. since the map projection for the surrogates is more distorted further away from the center of the projection. However, for most users, this distortion will be a small price to pay for having readily available spatial surrogates.</para>

<para>The second best approach to creating this file is to use the MIMS Spatial Allocator (MSA). This tool can create SMOKE-ready surrogates using GIS shape files, which are provided with the tool for multiple surrogates. Please refer to the <ulink url="http://www.cmascenter.org">CMAS web site</ulink> for more information.</para>

<para>A third approach to creating this file it to perform the same calculations done by the MSA using a GIS like ArcInfo. The calculations being done by the MSA are provided on the MSA website and could be implemented in a GIS, though this would probably be much too difficult an option for most users.</para>

<para>The surrogate file does not need to have the same outer boundaries as your modeling grid, but the grid cells do need to align with the grid cells of the surrogate file. This means that the projection of the surrogates must be the same as the projection as the modeling grid and the cell sizes must also match. SMOKE will produce an error if there is an inconsistency. If the grid represented by the surrogates file is larger than the modeling grid and the cells align, SMOKE will automatically extract the grid cells for the modeling domain from the larger grid provided by the surrogates.</para>

<para>In addition to the surrogate file, it is important to create a surrogate description file (<envar>SRGDESC</envar>). This is simply a file that lists the surrogate codes and their descriptions. Since the surrogate file itself does not currently have descriptive text that indicate what the surrogate codes mean, the surrogate description file is the only way users have of knowing to what data the codes in the surrogate file refer.</para>

<para>The same surrogate file can be used for Area and Mobile.  This is accomplished by using the same physical file name in the <envar>SRGDESC</envar>.  Please see <xref linkend="ch_input_files" /> for more information on these files. The <envar>BGPRO</envar> file must include the <quote>county area</quote> spatial surrogate, and is used for estimating county-total emissions from gridded emissions.</para>

<para>The Area and Mobile spatial surrogate file(s) should be installed as a sub-directory in the <filename class="directory"><envar>$GE_DAT</envar></filename> directory.  This sub-directory is assigned to <envar>SRGPRO_PATH</envar>.  The surrogate description file should be stored in <filename class="directory"><envar>$GE_DAT</envar></filename> as well. It is useful to include the name of the <envar>GRID</envar> in the name of the sub-directory <envar>SRGPRO_PATH</envar> for you may in the future be modeling different grids and therefore needing different surrogate files. The Biogenic surrogate file <envar>BGPRO</envar> should be located in <filename class="directory"><envar>$GE_DAT</envar></filename>.</para>
</listitem>
<listitem>
<para>Create and install the spatial cross-reference file</para>

<para>An example spatial cross-reference file (<envar>AGREF</envar> and <envar>MGREF</envar>) is provided with SMOKE that can be used for most inventories as long as the spatial surrogate codes in the new surrogate file match the codes in the example surrogate file, which are provided in the <envar>SRGDESC</envar> file described in <xref linkend="ch_dirs_files" />. If the codes match then the only concern will be whether the surrogate assignments are acceptable. By default, the same file is used for both the <envar>AGREF</envar> and <envar>MGREF</envar> files, which is accomplished by using the same physical file name in the Assigns file for both logical file names. The files can be the same file or two different files, at the discretion of the user - usually one file is more convenient unless different default settings (SCC=0) are needed, or unless the data all already available as two separate files.</para>

<para>When <command>Smkinven</command> imports an area, non-road mobile, or on-road mobile inventory, a list of SCCs is created (logical file name <envar>ASCC</envar>, <envar>NSCC</envar>, or <envar>MSCC</envar>). After importing the data but before running spatial allocation, it is wise to examine the list of SCCs included in this file and compare it with the list in the example spatial cross-reference files. This comparison can be accomplished manually or using the <command>Smkreport</command> program with a report that includes the surrogate codes assigned to each SCC (see <xref linkend="ch_quality_assurance" />). The <command>Smkreport</command> results will list all of the surrogate assignments by SCC and the emissions associated with each, with which users may evaluate if any SCCs were included in the inventory but not in the example SMOKE file. The example spatial cross-reference files (<envar>AGREF</envar> and <envar>MGREF</envar>) can be updated with any new assignments or to include SCCs that are in the user&rsquo;s inventory but not in the example files.</para>

<para>If a new surrogates file uses surrogate codes that are different from the example codes, then new spatial surrogate cross-reference files need to be created. These can be created by copying and editing the existing files to replace the example surrogate codes with the new codes. For example, the current code for population is 100. If the new code for population is 400, then all of the <quote>100</quote> surrogate codes in the file would need to be replaced with <quote>400</quote>s. These replacements must be made carefully because the example file also uses <quote>400</quote> for the rural land area surrogate, so if global search and replace is performed, one must be careful to change what one intends to change. It is much easier to simply use the codes that are already in use in any new surrogates file, or modify the surrogate file to use those codes.</para>

<para>The spatial cross-reference file(s) should be installed in the <filename class="directory"><envar>$GE_DAT</envar></filename> directory, since the file is likely to be shared by many SMOKE runs and source categories. It is useful to name the file(s) to include the <envar>GRID</envar> environment variable for easier identification as association with the surrogate file(s) with which it works.</para>
</listitem>
<listitem>
<para>Create and install the biogenic gridded land use data</para>

<para>You must create a gridded biogenic land use data (<envar>BELD4</envar> for BEIS3.60 or <envar>BELD3_A</envar>, <envar>BELD3_B</envar>, and <envar>BELD3_TOT</envar> for BEIS3.14) to use for your grid. The MSA described in step 2 is able to create these files using the BELD3 or BELD4 database. Please refer to step 2 for the web address of this tool. The outputs of the MSA can be used for BEIS3 modeling directory.</para>

<para>The gridded land use data in the file must match the definition in the <envar>GRIDDESC</envar> file for the grid selected using the <envar>IOAPI_GRIDNAME_1</envar> variable. As with the spatial surrogates, the grid can be larger than the modeling grid, but it the cells must overlay exactly with the grid cells of the actual modeling grid, which includes the grid projection and cell sizes.</para>

<para>The gridded biogenic land use file(s) should be installed in the <filename class="directory"><envar>$BGDAT</envar></filename> directory for BEIS3 modeling.</para>
</listitem>
<listitem>
<para>Create and install the meteorology files.</para>

<para>Meteorology files are a necessary input to the air quality model; therefore, the same meteorology files that will be used for the air quality modeling can be used for input to SMOKE. The MCIP program (a CMAQ preprocessor) can be used to convert the files from MM5 output format to the I/O API input format for SMOKE and CMAQ. Other user-created programs can be used as well as long as the variable names and file arrangements are consistent with what SMOKE expects. <xref linkend="ch_input_files" /> explains the details on the meteorology files that SMOKE expects and the variables that must be included in these files.</para>

<para>The meteorology files must be consistent with the grid selected. Like the surrogate file, the meteorology grid can be larger than the SMOKE modeling grid, but the grid cells must align. This includes the cell sizes being the same and the projection being the same. If this is the case, the SMOKE programs that use the meteorology files (<command>Met4moves</command>, <command>Temporal</command>, <command>Laypoint</command>, <command>Tmpbio</command>, and <command>Tmpbeis3</command>) will extract the meteorology data from the region of the files that intersects with the modeling grid.</para>
</listitem>
<listitem>
<para>Optionally create the <envar>BIOSEASON</envar> file</para>

<para>If you are modeling biogenic emissions with SMOKE for an episode and grid that covers both winter and summer seasons, then the best modeling approach is to create a <envar>BIOSEASON</envar> file from the meteorology data for input to <command>Tmpbio</command> or <command>Tmpbeis3</command>. This file indicates which grid cells and days are during <quote>winter</quote> and which are during <quote>summer</quote>, to allow <command>Tmpbio</command> or <command>Tmpbeis3</command> to apply the winter or summer emission factor for the correct cells and days. Summer is defined for biogenic modeling in the Northern Hemisphere as the period after the last freeze and before the first freeze in each grid cell. This file may not apply to some episodes or regions which do not experience freezing temperatures, and in those cases, users may run <command>Tmpbio</command> or <command>Tmpbeis3</command> without this file.</para>
</listitem>
<listitem>
<para>Set the fallback surrogate in the run scripts for area/non-point, nonroad mobile, and on-road mobile sources.</para>

<para>All scripts for source categories that use spatial surrogates have a <command>Grdmat</command> setting <envar>SMK_DEFAULT_SRGID</envar> that is used to set a fallback surrogate code. The fallback surrogate code is explained in <xref linkend="ch_programs" /> with the <command>Grdmat</command> program. It prevents emissions from being zeroed out when there is no surrogate of the assigned type for a source. The fallback surrogate should therefore be a surrogate that is never zero for a county, such as population. Only one fallback surrogate can be set for all sources in a given run. The <envar>SMK_DEFAULT_SRGID</envar> setting should be reset if the surrogate codes change (e.g., the default setting of 8 is not population) or if you want to change the fallback surrogate to a different one.</para>
</listitem>
<listitem>
<para>Update Assigns file to use all new files.</para>

<para>Update the Assigns file that you are using for this case to include all new files that you have created in this step:</para>

<itemizedlist>
<listitem>
<para><envar>BGPRO</envar></para>
</listitem>
<listitem>
<para><envar>AGREF</envar>, <envar>MGREF</envar></para>
</listitem>
<listitem>
<para><envar>SRGDESC</envar></para>
</listitem>
<listitem>
<para><envar>SRGPRO_PATH</envar></para>
</listitem>
<listitem>
<para><envar>BGUSE</envar></para>
</listitem>
<listitem>
<para><envar>BELD3_A</envar>, <envar>BELD3_B</envar>, <envar>BELD3_TOT</envar></para>
</listitem>
<listitem>
<para><envar>BIOSEASON</envar></para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Check that the inventory files cover the region of the grid.</para>

<para>When using a new grid, it is important to use an inventory that covers the states and counties included in your domain. There are two ways of checking that this is the case. First, obtain a map of your modeling domain prior to creating your inventory and note the states that are included wholly or in part in the domain. Before modeling, create, adapt, or amend your inventory to ensure that the inventories from each of those states are included.</para>

<para>The second way that you can check that you are using data for all regions of the domain is to run the data through SMOKE and look at the resulting gridded emissions in PAVE. Using PAVE, reset the scale of the plot to a very small maximum value (e.g., 0.001). All areas of the domain with emissions should show up red. If any areas show up gray, then there are missing values that could be because the inventory is not complete.</para>
</listitem>
</orderedlist>

</section>

</section>

<section id="sect_scripts_change_speciation">

<title>Use a different speciation mechanism or change speciation inputs</title>

<para>A common change to the SMOKE configuration is to select a speciation approach for an air quality model and chemical mechanism. In <xref linkend="ch_scripts" />, we noted that many speciation files are available for download from EPA. In this section, we describe how to use the <envar>SPC</envar> value in the Assigns file to select these.</para>

<section id="sect_scripts_use_default_spc">

<title>Choosing from default mechanisms</title>

<para>SMOKE provides several chemical mechanisms that one can select for modeling. In the default SMOKE configuration, only a few small changes are necessary to the Assigns file and script to use a different chemical mechanism.</para>

<orderedlist>
<listitem>
<para>Set the <envar>SPC</envar> setting in the Assigns file.</para>

<para>The <envar>SPC</envar> setting in the Assigns file controls which chemical mechanism is used by the scripts and SMOKE programs. Depending on what source categories you are modeling, the air quality model that you are using, and the chemical mechanism for that air quality model. See the default data files described in <xref linkend="ch_scripts" /> for the actual file names that will be used for each source category. Where different files are needed for different source categories, the Assigns file will automatically detect this and set the <envar>GSPRO</envar> and <envar>GSREF</envar> files accordingly.</para>

</listitem>

<listitem>
<para>Determine whether VOC-to-TOG or ROG-to-TOG is needed and set script accordingly.</para>

<para>If your inventory contains the pollutant VOC or ROG and you are modeling for CMAQ, UAM, or CAM<subscript>X</subscript>, then you will need to use SMOKE&rsquo;s <envar>GSCNV</envar> file to convert the VOC or ROG mass to TOG mass.</para>

<para>The SMOKE <command>Spcmat</command> program will use the <envar>GSCNV</envar> file if the <envar>POLLUTANT_CONVERSION</envar> setting in the script is Y. This is the default configuration for the CMAQ run scripts.</para>

<para>If your inventory contains TOG, then the <envar>POLLUTANT_CONVERSION</envar> setting in the run script should be set to N.</para>
</listitem>

<listitem>
<para>Ensure that the inventory pollutants that need speciation match the inventory pollutants in the speciation profiles and cross-reference files.</para>

<para>All of the pollutants in your inventory that you wish to include in the outputs must have valid profiles in the <envar>GSPRO</envar> and <envar>GSREF</envar> files. If the pollutant is left out of the <envar>GSREF</envar> file, the pollutant will be dropped from modeling (in some cases, this is desirable, but a warning will be generated by <command>Spcmat</command>). For each pollutant in your inventory check that:</para>

<orderedlist>
<listitem>
<para>The pollutant has one or more entries in the <envar>GSREF</envar> file. In some cases, you may have to add entries. For example, not all <envar>GSREF</envar> files have <quote>ROG</quote> entries, but these can easily be added simply by copying the VOC assignments and changing the VOC label to ROG.</para>
</listitem>
<listitem>
<para>For CMAQ, UAM, and CAM<subscript>X</subscript> and the pollutant is VOC or ROG, check that the TOG profiles are in the <envar>GSPRO</envar> file.</para>
</listitem>
<listitem>
<para>For all models and all other pollutants, check that the profiles are included in the <envar>GSPRO</envar> file.</para>
</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Ensure that the correct Assigns file is used in your run scripts.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_use_new_spc">

<title>Setup of new mechanism or changing an existing mechanism</title>

<orderedlist>
<listitem>
<para>Create and install the <envar>GSPRO</envar> file.</para>

<para>If only a few changes will be made to a <envar>GSPRO</envar> file, you can simply copy an existing <envar>GSPRO</envar> file to a new file. If more extensive changes are needed to create a new mechanism, currently, there is no utility for creating a <envar>GSPRO</envar> file in SMOKE. <comment>There is a system in development that will be available in early 2004.</comment> For now, users must use the file format in <xref linkend="ch_input_files" /> and a high degree of expertise to develop new <envar>GSPRO</envar> files.</para>

<para>Install the <envar>GSPRO</envar> file in the <filename class="directory"><envar>$GE_DAT</envar></filename> directory. For the default <envar>GSPRO</envar> file for that chemical mechanism (i.e., the one that applies to the most source categories), name the file <filename>gspro.<envar>$SPC</envar>.txt</filename>. If your speciation profile is specific to a certain source category, name the <envar>GSPRO</envar> file as follows:</para>

<itemizedlist>
<listitem>
<para>area/non-road mobile: <filename>gspro.<envar>$SPC</envar>.a.txt</filename></para>
</listitem>
<listitem>
<para>on-road mobile: <filename>gspro.<envar>$SPC</envar>.m.txt</filename></para>
</listitem>
<listitem>
<para>point: <filename>gspro.<envar>$SPC</envar>.p.txt</filename></para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Create and install the <envar>GSREF</envar> file.</para>

<para>You may be able to simply copy a <envar>GSREF</envar> file to a new name, depending on whether the profile codes are different for your new mechanism. In many cases, the same profile codes are used (e.g., from the SPECIATE database), but the profiles themselves are all that have changed.</para>

<para>If you need to create a new <envar>GSREF</envar> from scratch, you will need to ensure that all of the SCCs and all of the pollutants in the inventory have profile assignments. Any pollutant in the inventory that is not included in the <envar>GSREF</envar> file will be dropped from modeling. Any SCC that is not included will be assigned the default profile, which is the profile assigned to SCC = 0.</para>

<para>Name the <envar>GSREF</envar> file using a similar approach as for the <envar>GSPRO</envar> file, but use the <quote>gsref</quote> prefix instead of the <quote>gspro</quote> prefix. Therefore, the default file for that chemical mechanism (the one that applies to the most source categories) should be named <filename>gsref.<envar>$SPC</envar>.txt</filename>. Any source-category-specific files should use the names as follows:</para>

<itemizedlist>
<listitem>
<para>area/non-road mobile: <filename>gsref.<envar>$SPC</envar>.a.txt</filename></para>
</listitem>
<listitem>
<para>on-road mobile: <filename>gsref.<envar>$SPC</envar>.m.txt</filename></para>
</listitem>
<listitem>
<para>point: <filename>gsref.<envar>$SPC</envar>.p.txt</filename></para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Create the pollutant-to-pollutant conversion file, if necessary.</para>

<para>If the speciation profiles change or new profiles are added for VOC speciation, a <envar>GSCNV</envar> file must be created accordingly. This can be accomplished by copying and editing the example <envar>GSCNV</envar> file or creating a new <envar>GSCNV</envar> file from scratch. This requires a high degree of expertise and must be closely coordinated with creating the <envar>GSPRO</envar> file.</para>
</listitem>
<listitem>
<para>Edit the <envar>INVTABLE</envar> file.</para>

<para>Particularly for toxics modeling, changes to the <envar>GSPRO</envar> file must be coordinated with changes to the <envar>INVTABLE</envar> file in the following ways:</para>

<itemizedlist>
<listitem>
<para>If the definition of NONHAPVOC changes, the <envar>INVTABLE</envar> definition of NONHAPVOC must change as well.</para>
</listitem>
<listitem>
<para>If there are new explicit model species, these must be identified in the <envar>INVTABLE</envar> file.</para>
</listitem>
<listitem>
<para>If there are new model species that are not part of the chemical mechanism, these must be identified in the <envar>INVTABLE</envar> file.</para>
</listitem>
<listitem>
<para>If there are new pollutants, these must be included in the <envar>INVTABLE</envar> file (as well as the raw inventories, of course).</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Coordinate with MOVES inputs.</para>

<para>When processing using on-road mobile emissions and SMOKE running MOVES, users need to create the <envar>MEPROC</envar> file that contains a list of MOVES pollutants by emissions processes created by MOVES. This SMOKE input need to be coordinated so that the pollutants expected by the chemical mechanism are all created by SMOKE/MOVES. This requires that the <envar>MEPROC</envar> file have all pollutant/process combinations for the required pollutants and that the MOVES inputs are configured to generate emissions for those pollutants. The <envar>MEPROC</envar> file is documented in <xref linkend="sect_input_meproc_moves" />. The MOVES inputs are documented in the MOVES manual, and the limitations placed on these files by SMOKE are documented in <xref linkend="sect_scripts_use_moves" />.</para>
</listitem>

<listitem>
<para>Edit the Assigns file and scripts</para>

<para>Make sure to change the <envar>SPC</envar> variable in your Assigns file to the one for your new chemical mechanism. Also make sure that your run scripts use the Assigns file with the correct <envar>SPC</envar> setting.</para>
</listitem>
</orderedlist>

</section>

<section>

<title>Changing speciation assignments</title>

<para>Speciation assignments can be changed so that different speciation profiles are used for certain SCCs and pollutants or to add SCCs and pollutants. You will need to ensure that all of the SCCs and all of the pollutants in the inventory have profile assignments. Any pollutant in the inventory that is not included in the <envar>GSREF</envar> file will be dropped from modeling. Any SCC that is not included will be assigned the default profile, which is the profile assigned to SCC = 0.</para>

<orderedlist>
<listitem>
<para>Adding entries to an existing cross-reference file.</para>

<para>Edit an existing cross-reference file or copy it to a new file for editing. Insert the new speciation assignments based on the format of the file, described in <xref linkend="ch_input_files" />.</para>
</listitem>

<listitem>
<para>Create new speciation cross-reference file(s) for your case.</para>

<para>Copy the speciation cross-reference (<envar>GSREF</envar>) file for the chemical mechanism that you are using (or a chemical mechanism that is most similar to the one you have created). Edit the speciation profile assignments using the file format, described in <xref linkend="ch_input_files" />. The naming convention for the new file must be consistent with the convention described in the previous subsection.</para>
</listitem>

<listitem>
<para>Change the pollutant-to-pollutant conversion file.</para>

<para>If different SCCs get different profiles, then the <envar>GSCNV</envar> file must be changed as well. The VOC-to-TOG factor in the <envar>GSCNV</envar> depends on the profile that has been assigned to an SCC. So, the factor must be consistent with the profile assigned. Calculating the VOC-to-TOG factor requires some expertise, and this is outside the scope of this manual. However, if you change an SCC to use an existing profile, you can determine the correct VOC-to-TOG factor by first finding another SCC that uses that profile and then setting the VOC-to-TOG factor to be the same as the one for that other SCC.</para>
</listitem>

<listitem>
<para>If any new files are created, ensure that the Assigns file uses all new files.</para>

<para>Make sure that the <envar>SPC</envar> setting in the Assigns is correct and that the Assigns file will set the <envar>GSPRO</envar>, <envar>GSREF</envar>, and <envar>GSCNV</envar> files so that any new files will be used by the programs.</para>
</listitem>
</orderedlist>

</section>

<section>

<title>Changing the definition of NONHAPVOC or NONHAPTOG</title>

<para>The definition of NONHAPVOC and NONHAPTOG simply must be consistent between the <envar>GSPRO</envar> file and the <envar>INVTABLE</envar> file. This change applies only to chemical mechanisms that use VOC model species and can therefore benefit from the integration of toxics and criteria VOC. This includes all models that SMOKE supports.</para>

<orderedlist>
<listitem>
<para>Edit the <envar>INVTABLE</envar> file.</para>

<para>You can add pollutants and change their NONHAPVOC status using the <envar>INVTABLE</envar> file format provided in <xref linkend="ch_input_files" />.</para>
</listitem>

<listitem>
<para>Create new speciation profiles.</para>

<para>The speciation profiles must use the same definition of NONHAPVOC or NONHAPTOG. The header of the file must be updated to reflect the new definitions. The profiles for NONHAPVOC and NONHAPTOG must also be updated to be consistent. Finally, all other TOG profiles must be updated to be consistent with the definition.</para>
</listitem>

<listitem>
<para>Coordinate with MOVES inputs.</para>

<para>When processing using on-road mobile emissions and SMOKE running MOVES, users need to create the <envar>MEPROC</envar> file that contains a list of MOVES pollutants by emissions processes created by MOVES. This SMOKE input need to be coordinated so that the pollutants expected by the chemical mechanism are all created by SMOKE/MOVES. This requires that the <envar>MEPROC</envar> file have all pollutant/process combinations for the required pollutants and that the MOVES inputs are configured to generate emissions for those pollutants. The <envar>MEPROC</envar> file is documented in <xref linkend="sect_input_meproc_moves" />. The MOVES inputs are documented in the MOVES manual, and the limitations placed on these files by SMOKE are documented in <xref linkend="sect_scripts_use_moves" />.</para>
</listitem>
</orderedlist>

</section>

</section>

<section id="sect_scripts_use_projection">

<title>Setup projection and control scenarios</title>

<section>

<title>Setup for using growth only</title>

<para>The SMOKE growth capability is needed when the inventory year and the modeling year are different. For example, if your base-year inventory is for 2002 and you must evaluate a control strategy in 2010, then you will need to use the SMOKE growth capability.</para>

<orderedlist>
<listitem>
<para>Create and install growth packet files</para>

<para>The /PROJECTION/ packet handles the growth from the base year to a future year. This packet is part of the <envar>GCNTL</envar> file described in <xref linkend="ch_input_files" />. A packet for each source category that requires growth should be created and saved in a file with the correct name, as described next. Users must ensure that all of the SCCs in the inventory that require growth are included in this packet. Any source that does not match an entry in this file will have a factor of 1 assigned to indicate no change from the base to the future year.</para>

<para>In the default configuration of SMOKE, a <envar>GCNTL</envar> file must be created that includes the /PROJECTION/ packet to use SMOKE growth. This file must follow the naming convention <filename>gcntl.<envar>$YEAR</envar>_<envar>$FYEAR</envar>.txt</filename>, where <envar>YEAR</envar> is set in the Assigns file and <envar>FYEAR</envar> is set in the script as per <xref linkend="sect_scripts_script_settings" />.</para>

<para>The file should be installed in the inventory input directory for the source category to which it applies:</para>

<itemizedlist>
<listitem>
<para>Non-point (stationary area) files: <filename class="directory"><envar>$ARDAT</envar></filename> directory</para>
</listitem>
<listitem>
<para>Nonroad mobile files: <filename class="directory"><envar>$NRDAT</envar></filename> directory</para>
</listitem>
<listitem>
<para>On-road mobile files: <filename class="directory"><envar>$MBDAT</envar></filename> directory</para>
</listitem>
<listitem>
<para>Point files: <filename class="directory"><envar>$PTDAT</envar></filename> directory</para>
</listitem>
</itemizedlist>

<para>Please note that these instructions apply to on-road mobile sources in the following ways:</para>

<itemizedlist>
<listitem>
<para>Growth of on-road mobile VMT</para>
</listitem>
<listitem>
<para>Growth of on-road mobile precomputed emissions</para>
</listitem>
</itemizedlist>

<para>Creating on-road mobile emission factors is accomplished by changing the <envar>FYEAR</envar> setting and using the <envar>SMK_FUTURE_YN</envar> set to Y. This is described also in <xref linkend="sect_scripts_use_moves" /> on running SMOKE with MOVES.</para>
</listitem>

<listitem>
<para>Create scripts with correct settings for your particular needs</para>

<para>To create the scripts with the correct settings, the best starting place is one of the SMOKE example future-year scripts, introduced in <xref linkend="sect_scripts_example_scripts" />. These scripts are already setup to run for growth only. To help you understand what the scripts are doing, we have described in the list below the key elements of the script:</para>

<itemizedlist>
<listitem>
<para>Uses the base-year Assigns file for the case we are running. The script settings (such as <envar>FYEAR</envar> and <envar>SMK_FUTURE_YN</envar>) will adjust what the Assigns file does.</para>
</listitem>
<listitem>
<para><envar>FYEAR</envar> defined and <envar>SMK_FUTURE_YN</envar> not defined initially (default is N).</para>
</listitem>
<listitem>
<para>Run <command>Cntlmat</command> to create growth matrices only (these scripts do not create control matrices, although that is not normally what users will do in real cases). This program reads the <envar>GCNTL</envar> file and creates a growth matrix.</para>
</listitem>
<listitem>
<para>Run <command>Grwinven</command> to grow base year inventory to future year (no controls).</para>
</listitem>
<listitem>
<para>Reset <envar>SMK_FUTURE_YN</envar> to Y (note: placeholder for resetting <envar>SMK_CONTROL_YN</envar> is included, but is not set to Y in example script).</para>
</listitem>
<listitem>
<para>Source the Assigns file, which will change output directories and file names now that <envar>SMK_FUTURE_YN</envar> is set to Y. Note that <envar>RUN_PART1</envar> is temporarily reset to N in the example script to prevent Assigns file from deleting SMOKE intermediate files.</para>
</listitem>
<listitem>
<para>Run <command>Temporal</command> and <command>Smkmerge</command>. The <command>Temporal</command> program will use the grown emissions to create hourly grown emissions. <command>Smkmerge</command> will use these in addition to the base-year gridding matrix and speciation matrix to create future-year model-ready emissions. The base year matrices can be used because they are identical to the future-year ones when SMOKE is used to apply growth.</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section>

<title>Setup for using controls only</title>

<para>Using controls only in the SMOKE scripts is needed when you import a grown inventory that does not include any or all of the controls that you wish to apply to the inventory. This is what we have assumed in these instructions. We assume that in this case, the growth of the inventory was performed outside of SMOKE, and SMOKE has read in an inventory for the year defined by the <envar>FYEAR</envar> script setting. This inventory must be imported in a different script that is similar to the base-year script, but follows the instructions for importing future-year inventories in <xref linkend="sect_scripts_future_invs" />.</para>

<orderedlist>
<listitem>
<para>Determine which control packets you need</para>

<para>Please refer to the <command>Cntlmat</command> section of <xref linkend="ch_programs" /> for a description of what each of the control packets can do and how they interact.</para>

<para>The available packets are:</para>

<itemizedlist>
<listitem>
<para>/MACT/ packet</para>
</listitem>
<listitem>
<para>/CONTROL/ packet</para>
</listitem>
<listitem>
<para>/EMS_CONTROL/ packet</para>
</listitem>
<listitem>
<para>/CTG/ packet</para>
</listitem>
<listitem>
<para>/ALLOWABLE/ packet</para>
</listitem>
<listitem>
<para>/REACTIVITY/ packet</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Create and install control packets file</para>

<para>The control packets just listed handle the application of controls for a certain future year. These controls can represent the existing controls that must be applied by emission sources so that they will be in compliance with the law. The controls can also represent additional controls that you want to evaluate to see their impact on modeled air quality. <xref linkend="ch_input_files" /> explains these packets and their formats.</para>

<para>You should create a separate control file for each source category that contains all of the control packets that apply to that source category. Any inventory source and pollutant that does not receive a control is assigned a factor of 1 to indicate no change between the base case and the control case.</para>

<para>In the default configuration of SMOKE, a <envar>GCNTL</envar> file must be created that includes the only control packets. This file must follow the naming convention <filename>gcntl.<envar>$CNTLCASE</envar>.txt</filename>, where <envar>CNTLCASE</envar> is set in the script as per Section <xref linkend="sect_scripts_script_settings" />.</para>
</listitem>
<listitem>
<para>Create scripts with correct settings for your particular needs</para>

<para>To create the scripts with the correct settings, the best starting place is one of the SMOKE example future-year scripts, introduced in <xref linkend="sect_scripts_example_scripts" />. The script must be changed, however, in the following ways to implement control-only. There are two ways to run controls in SMOKE. The first is to apply multiplicative controls using <command>Grwinven</command> and reactivity controls (if needed) with <command>Smkmerge</command>. The second is the apply both multiplicative and reactivity controls using <command>Smkmerge</command>. The following settings must be used for each case:</para>

<itemizedlist>
<listitem>
<para>Apply multiplicative controls with <command>Grwinven</command> and reactivity control (if any) with <command>Smkmerge</command></para>

<itemizedlist>
<listitem>
<para>Uses the base-year Assigns file for the case we are running. The script settings (such as <envar>FYEAR</envar>, <envar>CNTLCASE</envar>, and <envar>SMK_CONTROL_YN</envar>) will adjust what the Assigns file does.</para>
</listitem>
<listitem>
<para>Set <envar>FYEAR</envar> = the imported future-year inventory</para>
</listitem>
<listitem>
<para>Set <envar>SMK_FUTURE_YN</envar> = Y on the line after <envar>FYEAR</envar>. Remove this setting from later in the script (around line 120).</para>
</listitem>
<listitem>
<para>Set <envar>RUN_CNTLMAT</envar> = Y to run <command>Cntlmat</command> to create control matrices only</para>
</listitem>
<listitem>
<para>Set <envar>RUN_GRWINVEN</envar> = Y to run <command>Grwinven</command> to import the control matrices</para>
</listitem>
<listitem>
<para>Set <envar>RUN_TEMORAL</envar> = Y to run <command>Temporal</command> on controlled inventory</para>
</listitem>
<listitem>
<para>Set <envar>RUN_SMKMERGE</envar> = Y to run <command>Smkmerge</command> on controlled inventory</para>
</listitem>
<listitem>
<para>Set options for <command>Cntlmat</command>, <command>Grwinven</command>, <command>Temporal</command>, and <command>Smkmerge</command> (see <xref linkend="ch_programs" />).</para>
</listitem>
<listitem>
<para>Set <envar>SMK_NUM_CTLMAT</envar> to 1</para>

<para>For area or nonroad mobile, set <envar>ACMAT01</envar> to <envar>$ACMAT</envar></para>

<para>For on-road mobile, set <envar>MCMAT01</envar> to <envar>$MCMAT</envar></para>

<para>For point, set <envar>PCMAT01</envar> to <envar>$PCMAT</envar></para>

<para>These settings assume that you are using only one multiplicative control matrix. <command>Grwinven</command> can actually import multiple control matrices from different cases. To use more than one control matrix, set <envar>SMK_NUM_CTLMAT</envar> to the number of control matrices and set <envar>ACMAT02</envar>, <envar>ACMAT03</envar>, etc to the names of the additional control matrices.</para>
</listitem>
<listitem>
<para>Set <envar>CNTLCASE</envar> to the control strategy name that you want for the control case.</para>
</listitem>
<listitem>
<para>At line 120 of file, reset <envar>SMK_CONTROL_YN</envar> to Y</para>
</listitem>
<listitem>
<para>To run <command>Smkmerge</command> for reactivity controls, add the <envar>MRG_CTLMAT_REAC</envar> option to the <command>Smkmerge</command> options and set to <quote>A</quote>, <quote>M</quote>, <quote>P</quote> or some combination of those letters to indicate whether you want it to use the reactivity matrix for area (including nonroad), on-road mobile, or point sources.</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Apply both multiplicative and reactivity controls with <command>Smkmerge</command></para>

<itemizedlist>
<listitem>
<para>Uses the base-year Assigns file for the case we are running. The script settings (such as <envar>FYEAR</envar>, <envar>CNTLCASE</envar>, and <envar>SMK_CONTROL_YN</envar>) will adjust what the Assigns file does.</para>
</listitem>
<listitem>
<para>Set <envar>FYEAR</envar> = the imported future-year inventory</para>
</listitem>
<listitem>
<para>Set <envar>SMK_FUTURE_YN</envar> = Y on the line after <envar>FYEAR</envar>. Remove this setting from later in the script (around line 120).</para>
</listitem>
<listitem>
<para>Set <envar>RUN_CNTLMAT</envar> = Y to run <command>Cntlmat</command> to create control matrices only</para>
</listitem>
<listitem>
<para>Set <envar>RUN_GRWINVEN</envar> = N to run <command>Grwinven</command> to import the control matrices</para>
</listitem>
<listitem>
<para>Set <envar>RUN_TEMORAL</envar> = N</para>
</listitem>
<listitem>
<para>Set <envar>RUN_SMKMERGE</envar> = Y to run <command>Smkmerge</command> on controlled inventory</para>
</listitem>
<listitem>
<para>Set options for <command>Cntlmat</command> and <command>Smkmerge</command> (see <xref linkend="ch_programs" />).</para>
</listitem>
<listitem>
<para>Set <envar>CNTLCASE</envar> to the control strategy name that you want for the control case.</para>
</listitem>
<listitem>
<para>At line 120 of file, reset <envar>SMK_CONTROL_YN</envar> to N</para>
</listitem>
<listitem>
<para>To run <command>Smkmerge</command> for multiplicative controls, add the <envar>MRG_CTLMAT_MULT</envar> setting to <command>Smkmerge</command> options and set to <quote>A</quote>, <quote>M</quote>, <quote>P</quote> or some combination of those letters to indicate whether you want it to use the multiplicative control matrix for area (including nonroad), on-road mobile, or point sources.</para>
</listitem>
<listitem>
<para>To run <command>Smkmerge</command> for reactivity controls, add the <envar>MRG_CTLMAT_REAC</envar> setting to the <command>Smkmerge</command> options and set to <quote>A</quote>, <quote>M</quote>, <quote>P</quote> or some combination of those letters to indicate whether you want it to use the reactivity control matrix for area (including nonroad), on-road mobile, or point sources.</para>
</listitem>
</itemizedlist>

</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section>

<title>Setup for both growth and controls</title>

<para>Follow the instructions that apply for both of the previous two subsections. The differences between this case and the previous two cases are as follows:</para>

<itemizedlist>
<listitem>
<para>Name the <envar>GCNTL</envar> input file differently. It should be named: <filename>gcntl.<envar>$YEAR</envar>_<envar>$FYEAR</envar>_<envar>$CNTLCASE</envar>.txt</filename></para>
</listitem>
<listitem>
<para>The <command>Grwinven</command> program must be used at least to grow the inventory, so you must</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_GRWINVEN</envar> to Y.</para>
</listitem>
<listitem>
<para>Set <envar>SMK_NUM_CTLMAT</envar> to at least 1. It should be set to the total number of growth and control matrices to be applied by the <command>Grwinven</command> program.</para>
</listitem>
<listitem>
<para>The <envar>ACMAT01</envar>, <envar>ACMAT02</envar>, etc file names should be set to be consistent with the matrices being applied and the source categories (e.g., <envar>ACMAT01</envar> should be <envar>$APMAT</envar> or <envar>$ACMAT</envar>, but not <envar>$PCMAT</envar>, since that would be inconsistent between source categories).</para>
</listitem>
</itemizedlist>

</listitem>
</itemizedlist>

</section>

</section>

<section id="sect_scripts_use_moves">

<title>Use MOVES for on-road mobile sources</title>

<para>Extra files are needed for input to SMOKE when running with MOVES. These files are:</para>

<itemizedlist>
<listitem>
<para><envar>MEPROC</envar>: Mobile emission processes</para>
</listitem>
<listitem>
<para><envar>MCXREF</envar>: Mobile representative county cross-reference file</para>
</listitem>
<listitem>
<para><envar>MFMREF</envar>: Mobile fuel month file</para>
</listitem>
<listitem>
<para><envar>MRCLIST</envar>: List of MOVES Lookup Tables for <command>Movesmrg</command></para>
</listitem>
<listitem>
<para><envar>RUNCTL</envar>: Runcontrol file</para>
</listitem>
</itemizedlist>

<para>The <envar>MEPROC</envar>, <envar>MCXREF</envar>, and <envar>MFMREF</envar> files are installed in the <filename class="directory"><envar>$MBDAT</envar></filename> directory for the default SMOKE configuration.</para>

<para>The subsections below describe how adjusting these files will allow you to perform a variety of changes to the on-road mobile processing.</para>

<section>

<title>Coordinating with other input files</title>

<para>The <envar>MEPROC</envar> file must be coordinated with the <envar>INVTABLE</envar>, <envar>GSPRO</envar>, and <envar>GSREF</envar>. The <envar>MCXREF</envar> and <envar>MFMREF</envar> must be coordinated with the inventory. The following list indicates all of the things that you must check for when creating any of these files.</para>

<itemizedlist>
<listitem>
<para>The <envar>MEPROC</envar> file must have all of the pollutants (e.g., CO, NOX, and so on) as an input file to <command>Movesmrg</command>.</para>
</listitem>

<listitem>
<para>If a pollutant that you want to model is not in the <envar>MEPROC</envar> file, it will not be modeled by SMOKE correctly. All pollutants that you wish to include in the outputs must be in the <envar>MEPROC</envar> file.</para>
</listitem>
<listitem>
<para>All pollutants in the <envar>MEPROC</envar> file must also be in the <envar>INVTABLE</envar> file with Keep = Y, including the <envar>INVTABLE</envar> limitation that the file pollutant names are limited to 11 characters for on-road mobile pollutants.</para>
</listitem>
<listitem>
<para>All pollutants in the <envar>MEPROC</envar> file must be available in SMOKE-ready MOVES lookup tables.</para>
</listitem>
<listitem>
<para>All process-pollutant combinations in the <envar>MEPROC</envar> file must also be included in the <envar>GSREF</envar> file. The format for the <quote>pollutant</quote> entry in the <envar>GSREF</envar> is &lt;emission process&gt;__&lt;pollutant&gt;. Note that the joiner between &lt;emission process&gt; and &lt;pollutant&gt; is a double underscore. <emphasis role="bold">A single underscore will prevent the processing from working properly.</emphasis> For example, running exhaust carbon monoxide must be included as EXR__CO.</para>
</listitem>
<listitem>
<para>When integrating toxics HAPs and criteria TOG and using MOVES, the NONHAPTOG definition in the <envar>INVTABLE</envar> file and <envar>GSPRO</envar> files must be consistent.</para>
</listitem>
<listitem>
<para>The <envar>MCXREF</envar> file should assign representative counties for all counties for which you provide VMT data in the inventory.</para>
</listitem>
</itemizedlist>

</section>

<section>

<title>Changing representative counties</title>

<para>Representative counties have previously been explained in <xref linkend="sect_concepts_reference_counties_moves" />. The <envar>MCXREF</envar> file assigns representative counties for each county in your domain. To change the representative counties, this file should be edited to assign different representative counties to each county in the inventory. After editing this file, you must make sure that no counties in the inventory have been left out of the file.</para>

</section>
<section>

<title>Changing fuel month for representative counties</title>

<para>Reference fuel month have previously been explained in <xref linkend="sect_concepts_moves_reference_fuel_month" />. The <envar>MFMREF</envar> file assigns fuel month for each representative county in your domain. To change the fuel month, this file should be edited to assign a different fuel month to each representative county in the inventory. User must meet the criteria to share the same fuel month between representative counties.</para>
</section>

</section>
<section>

<title>Change temporal processing</title>

<para>Changing the temporal aspect of SMOKE processing is one of the critical changes that users must make. One of the most basic changes that you can make to SMOKE is the time period for which SMOKE will be run. In this section, we will explain how to make the following changes to your SMOKE processing:</para>

<itemizedlist>
<listitem>
<para><xref linkend="sect_scripts_temporal_xref" /></para>
</listitem>
<listitem>
<para><xref linkend="sect_scripts_normalize_weekly" /></para>
</listitem>
<listitem>
<para><xref linkend="sect_scripts_change_episode" /></para>
</listitem>
<listitem>
<para><xref linkend="sect_scripts_duration_output" /></para>
</listitem>
<listitem>
<para><xref linkend="sect_scripts_non_seq_dates" /></para>
</listitem>

<!--
<listitem>
<para><xref linkend="sect_scripts_use_average_day" /></para>
</listitem>
-->

<!--
<listitem>
<para><xref linkend="sect_scripts_change_outzone" /></para>
</listitem>
-->

<!--
<listitem>
<para><xref linkend="sect_scripts_mwss_approach" /></para>
</listitem>
-->

<listitem>
<para><xref linkend="sect_scripts_change_holidays" /></para>
</listitem>
<listitem>
<para><xref linkend="sect_scripts_uniform_profiles" /></para>
</listitem>
</itemizedlist>

<section id="sect_scripts_temporal_xref">

<title>Changing temporal cross-reference and profiles</title>

<para>To change the temporal cross-reference and profiles the following steps must be taken.</para>

<orderedlist>
<listitem>
<para>Determine which days of the week will have distinct diurnal profiles.</para>

<para>SMOKE provides the capability for optionally assigning different diurnal profiles for different days of the week. The file format for the <envar>ATPRO</envar>, <envar>MTPRO</envar>, and <envar>PTPRO</envar> file explains the different sections of the file that you can use to assign these different profiles. Before you add temporal profiles, you must decide which approach you will use for the new profiles:</para>

<itemizedlist>
<listitem>
<para>Different diurnal profiles for weekdays and weekends (using the /DIURNAL WEEKDAY/ and /DIURNAL WEEKEND/ packets).</para>
</listitem>
<listitem>
<para>Different diurnal profiles for each day of the week (using the /DIURNAL &lt;DAYNAME&gt;/ packets, where &lt;DAYNAME&gt; = the day of the week (MONDAY, TUESDAY, etc.).</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Ensure that different diurnal profiles for different days of the week will match across the days.</para>

<para>When setting up new diurnal temporal profiles, it is important is ensure that the same temporal profile codes are used across the packets for the diurnal profiles because as source can only be assigned a single code for all of its diurnal profiles. For example, if a source were to use diurnal profile code 50, that code must be included in all of the diurnal packets and all instances of code 50 must be for that source. In other words, it is not possible to assign code 50 on Mondays and code 60 on Tuesdays.</para>
</listitem>
<listitem>
<para>Edit the <envar>ATPRO</envar>, <envar>MTPRO</envar>, or <envar>PTPRO</envar> file to include new diurnal, weekly, or monthly profiles.</para>

<para>The file format for the <envar>ATPRO</envar>, <envar>MTPRO</envar>, and <envar>PTPRO</envar> files is in <xref linkend="ch_input_files" />. To add new diurnal profiles, you must edit these files in a text editor and the new profiles added. It is possible to use the same file instead of three separate files; in this case, just configure the Assigns file to use the same file name for all three logical file names. This has been done in the default configuration.</para>
</listitem>
<listitem>
<para>Edit the <envar>ATREF</envar>, <envar>MTREF</envar>, or <envar>PTREF</envar> file to add entries or change assignments.</para>

<para>The file format for the <envar>ATREF</envar>, <envar>MTREF</envar>, and <envar>PTREF</envar> files is in <xref linkend="ch_input_files" />. To add or change temporal profile assignments, you must edit these files in a text editor and select the source characteristics that will be associated with a diurnal, weekly, and monthly profile. The example file uses primarily SCCs to assign temporal profiles, but the file format supports other fields to make more specific assignments by county, pollutant, link ID, plant ID, or other point-source characteristics.</para>
</listitem>
<listitem>
<para>Ensure <envar>ATREF</envar>, <envar>MTREF</envar>, and <envar>PTREF</envar> have entries for all sources in the inventory.</para>

<para>Once you have edited the file, you will need to check that all sources are being assigned profiles or that the default temporal profile is acceptable for sources that do not have more specific assignments. The easiest way to check that the files are acceptable to you is to run it through the <command>Temporal</command> program using the <envar>REPORT_DEFAULTS</envar> option set to Y. With this option, the <command>Temporal</command> log file will report all sources that have received the default temporal profile. You can review the log file to determine if this default is acceptable to you. Additionally, you can run <command>Smkreport</command> (after <command>Temporal</command> has been run) with the following instructions in the <envar>REPCONFIG</envar> input file to get a report with the temporal profile codes that <command>Temporal</command> assigned to each source. The instructions are:</para>

<itemizedlist spacing="compact">
<listitem>BY DIUCODE</listitem>
<listitem>BY WEKCODE</listitem>
<listitem>BY MONCODE</listitem>
<listitem>BY SOURCE</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section id="sect_scripts_normalize_weekly">

<title>Setting normalization of weekly profiles</title>

<para>To set normalization of weekly profiles, the following steps must be taken.</para>

<orderedlist>
<listitem>
<para>Determine whether you are using an annual or average-day inventory.</para>

<para>You are using an annual inventory if you have <envar>SMK_AVEDAY_YN</envar> is set to N in your run scripts.</para>

<para>You are using an average-day inventory if you have <envar>SMK_AVE_DAY_YN</envar> set to Y in your run scripts.</para>
</listitem>
<listitem>
<para>If using an annual inventory, use weekly normalization.</para>

<para>To do this, make sure the <envar>WKDAY_NORMALIZE</envar> setting is set to N in your run script when you run <command>Smkinven</command>.</para>
</listitem>
<listitem>
<para>If using an average-day inventory, determine whether it is an average weekday or not, and set the weekly normalization accordingly.</para>

<para>If your average-day inventory is an average that excludes weekend emissions, then you need weekday normalization of your weekly profiles. To do this, make sure the <envar>WKDAY_NORMALIZE</envar> setting is set to Y in your run script when you run <command>Smkinven</command>.</para>

<para>If the values of your average-day inventory include weekend emissions, then you do not need weekday normalization and the <envar>WKDAY_NORMALIZE</envar> setting in your run scripts should be set to N when you run <command>Smkinven</command>.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_change_episode">

<title>Changing the episode</title>

<para>The episode definition is the period for which you will generate SMOKE outputs. To change the episode dates, the following steps must be taken. In addition, the episode dates must be consistent with the run length settings, described in the next subsection.</para>

<orderedlist>
<listitem>
<para>Choose an episode within a single calendar year.</para>
</listitem>
<listitem>
<para>Set the <envar>EPI_STDATE</envar> to the Julian start date of your episode.</para>

<para>In general, this setting is the same as the <envar>G_STDATE</envar> setting in the Assigns file. As will be described in the next subsection, <envar>G_STDATE</envar> changes with each modeling period within the episode (e.g., modeling with 5-day periods), but the <envar>EPI_STDATE</envar> setting is the same for the entire SMOKE run.</para>

<para>The <envar>EPI_STDATE</envar> setting is also generally consistent with the base model year set by the <envar>YEAR</envar> environment variable, which in turn is consistent with the year of data in the input inventory files.</para>
</listitem>
<listitem>
<para>Set the <envar>EPI_STTIME</envar> to the start time that you wish to use for each model-ready emissions file created in your SMOKE run. This value is usually 0.</para>
</listitem>
<listitem>
<para>Set the <envar>EPI_RUNLEN</envar> to the number of hours in the episode.</para>

<para>Do not add an hour to this duration as with the <envar>G_RUNLEN</envar> setting described in the next subsection. The format for this setting allows up to four hours in the format (i.e., HHHHMMSS).</para>
</listitem>
<listitem>
<para>Set the <envar>EPI_NDAY</envar> to the number of days of the episode.</para>

<para>The minimum value is 1 and the maximum value is 365 (366 for leap years).</para>
</listitem>
<listitem>
<para>Ensure that all time dependent input data are available for the run period.</para>

<para>The critical time-dependent data that you must ensure are available for the episode duration are:</para>

<itemizedlist>
<listitem>
<para>Meteorology data (see <xref linkend="sect_scripts_change_meteorology" />)</para>
</listitem>
<listitem>
<para>Day- and hour-specific point source data (including any precomputed plume rise data)</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section id="sect_scripts_duration_output">

<title>Changing the dates, times, and duration of model-ready SMOKE emissions files</title>

<para>The run length is the time period for which each program that uses temporal process will be run. Sometimes these periods are called the <quote>chunks</quote> of processing, as in the episode is being processed in <quote>chunks</quote>. This period will determine the length of all of the hourly SMOKE intermediate files including <envar>ATMP</envar>, <envar>MTMP</envar>, <envar>PTMP</envar>, <envar>PLAY</envar>, and all model-ready outputs from <command>Smkmerge</command>. To change the run length, the following steps must be taken.</para>

<orderedlist>
<listitem>
<para>Set the <envar>G_STDATE</envar> setting the same as your <envar>EPI_STDATE</envar>.</para>

<para>The <envar>G_STDATE</envar> setting in the Assigns file is the starting date of the first SMOKE model-ready emissions file. The <envar>G_STDATE_ADVANCE</envar> script variable is set in the scripts so that the scripts will automatically reset the <envar>G_STDATE</envar> variable as need to run SMOKE for each period in the episode. The length of those periods is set by the <envar>G_RUNLEN</envar> variable and the number of periods is <envar>EPI_RUNLEN</envar> divided by <envar>G_RUNLEN</envar>.</para>
</listitem>
<listitem>
<para>Set the <envar>G_STTIME</envar> setting the same as the EPI_STTIME. This value is the start time that you wish to use for each model-ready emissions file created in your SMOKE run. This value is usually 0.</para>

<para>Generally, the start time must also be consistent with the start time of the other inputs to the air quality model, such as the meteorology data. For example, if the meteorology data start at 12 Greenwich Mean Time (GMT) and the air quality model will also start at that time, then the emissions files will also need to start at 12 GMT. This can be achieved by setting <envar>G_STTIME</envar> and <envar>EPI_STTIME</envar> to 120000 (HHMMSS format).</para>
</listitem>
<listitem>
<para>Set the <envar>G_TSTEP</envar> setting to 10000 for 1 hour (HHMMSS format). In version 2 of SMOKE and earlier, this is the only setting that is supported by the code.</para>
</listitem>
<listitem>
<para>Set the <envar>G_RUNLEN</envar> to the period run length for each model-ready SMOKE emissions file.</para>

<para>The run length can be set to as many hours as your air quality model can support for a single input file, as long as your files do not surpass a 2 GB file size limit, which are be imposed by 32-bit UNIX operating systems and by the NetCDF library on which SMOKE is based. Generally, the air quality models can accept files for as long as the user wishes to provide, so the limit is therefore the file sizes, which can be determined by trial and error. The conservative approach is to create emissions files for 1 day at a time.</para>

<para>The air quality models require an extra hour of emissions data for each file. Therefore the number of hours for the <envar>G_RUNLEN</envar> setting is computed as:</para>

<para>(number of days per file) x 24 + 1</para>

<para>The <envar>G_RUNLEN</envar> setting must be in format of HHHHMMSS where HHHH is a four-digit number of hours, MM is the minutes (must be 00), and SS is the seconds (must also be 00).</para>
</listitem>
<listitem>
<para>Set the <envar>ESDATE</envar> setting to the first date of your episode in YYYYMMDD format.</para>

<para>Recall that the <envar>ESDATE</envar> setting is for naming files. In the Assigns file, the value of this setting should be the starting date for the first emissions file to be created by the SMOKE run. The default SMOKE script configuration will automatically update <envar>ESDATE</envar> for subsequent run periods.</para>
</listitem>
<listitem>
<para>Set the <envar>NDAYS</envar> setting to the number of days represented by <envar>G_RUNLEN</envar>.</para>

<para>For example, if <envar>G_RUNLEN</envar> is 490000 (2 days x 24 + 1 = 49 hours), then <envar>NDAYS</envar> should be 2.</para>
</listitem>
</orderedlist>

</section>


<section id="sect_scripts_non_seq_dates">

<title>Setting non-sequential processing dates</title>

<para>The <envar>PROCDATES</envar> option is specifically designed for use on daily and/or hourly inventory data with <command>Temporal</command>.  <envar>PROCDATES</envar> is not yet incorporated within other SMOKE core programs, such as <command>Grdmat</command>,<command>Smkmerge</command> or <command>Smkreport</command>.  For creating model-ready outputs and QA reports, the users need to be sure that the episode dates (<envar>EPI_STDATE</envar> and <envar>G_STDATE</envar>) in the assigns file are listed in <envar>PROCDATES</envar></para>

<para>If <envar>PROCDATES</envar> is not assigned, the defaults are <envar>G_STDATE</envar>, <envar>G_STTIME</envar> and <envar>G_RUNLEN</envar>.</para>

<para>The following steps must be taken to set non-sequential processing dates.</para>

<para>Area/Non-road/Point Sources</para>

<orderedlist>

<listitem>
<para>Determine whether you need to use <envar>PROCDATES</envar>.</para>
</listitem>

<listitem>
<para>If you are using <envar>PROCDATES</envar>, you need to set the environment variable by uncommenting <envar>PROCDATES</envar> in the assigns file.</para>
</listitem>

<listitem>
<para>Set the environment variable <envar>PROCDATES</envar> to the file procdates.txt located in <envar>GE_DAT</envar>. (i.e. setenv <envar>PROCDATES</envar> <envar>$GE_DAT</envar>/procdates.txt.</para>
</listitem>

</orderedlist>

<para>Mobile Source</para>

<para><command>Temporal</command> is responsible to convert annual/monthly  to hourly <envar>VMT</envar>. <command>Movesmrg</command> is responsible for combining hourly emissions factors calculated by <envar>MOVES</envar> with hourly <envar>VMT</envar> data to generate hourly on-road mobile emissions. </para>

<orderedlist>

<listitem>
<para>Determine whether you need to use <envar>PROCDATES</envar>.</para>
</listitem>

<listitem>
<para>If you are using <envar>PROCDATES</envar>, you need to set the environment variable by uncommenting <envar>PROCDATES</envar> in the assigns file.</para>
</listitem>

<listitem>
<para>Set the environment variable <envar>PROCDATES</envar> to the file procdates.txt located in <envar>GE_DAT</envar>. (i.e. setenv <envar>PROCDATES</envar> <envar>$GE_DAT</envar>/procdates.txt.</para>
</listitem>

</orderedlist>

<para>NOTE: Since the <command>Temporal</command> dynamically create names for the output files, two new environment variables <envar>[A|M|P]TMPNAME</envar> and <envar>[A|M|P]TSUPNAME</envar> are used to set the directory and file prefix for naming the output files <envar>[A|M|P]TMP</envar> and <envar>[A|M|P]TSUP</envar>. The files are named using the starting date of each time period.For example, if <envar>ATMPNAME</envar> is set to /data/ntmp.nctox., then the <envar>ATMP</envar> file for a given time period will be put in the data directory and named ntmp.nctox.start date.ncf.</para>

</section>


<!--
<section id="sect_scripts_use_average_day">

<title>Using average-day emissions values</title>

<para>The IDA and ORL formats provide fields for both annual and average-day emissions. The EMS formats assume that the emissions will be provided as average-day values, and some of the steps in the following list do not apply to EMS-95 format, as noted. To use average-day emission values, the following steps must be taken.</para>

<remark>Missing text - see <xref linkend="sect_scripts_average_day_invs" /></remark>

</section>
-->

<!--
<section id="sect_scripts_change_outzone">

<title>Changing the output time zone</title>

<para>The output time zone for SMOKE is inherent in its hourly outputs, such that hours 0 through 23 in the I/O API NetCDF SMOKE files must be in some time zone. This time zone much match the time zone of the meteorology files; hence, the time zone that you need is generally the same time zone as the hours of your meteorology data to use in your air quality model. To change the output time zone, the following steps must be taken.</para>

<remark>Missing text - see <xref linkend="sect_concepts_time_zones" /></remark>

</section>
-->

<!--
<section id="sect_scripts_mwss_approach">

<title>Monday, weekday, Saturday, Sunday approach</title>

<para>The default approach for running SMOKE (provided with the default SMOKE run scripts) is to model every day of the episode as if it were a unique day. In reality, in many cases, the same emissions will be calculated for certain days within a month. As we will explain, you can reconfigure your emissions processing to use a Monday, weekday, Saturday, Sunday (MWDSS) approach, which can save a great deal of processing time. In this subsection, we explain how to determine whether you can use such an approach for some or all of your source categories, and how to reconfigure the default scripts to use the approach. The following steps must be taken if you would like to use this approach.</para>

<remark>Missing text - see <xref linkend="sect_concepts_mwss_processing" /></remark>

</section>
-->

<section id="sect_scripts_change_holidays">

<title>Changing holiday dates</title>

<para>As previously explain in <xref linkend="sect_concepts_holiday_processing" />, SMOKE can model holidays as special days. The holidays that are relevant are those holidays for which anthropogenic activities are significantly altered, since its those activities that determine the appropriate weight to give the emissions on each day of the week and the diurnal temporal patterns for those days. For example, the nearly all workers in the U.S. have a holiday from their employment on Thanksgiving day, and the patterns of industrial and motor-vehicle activities are substantially altered resulting in different emissions patterns on those days. The Valentines Day holiday, however, does not affect such patterns because employers do not allow workers a day off on that day.</para>

<para>The <envar>HOLIDAYS</envar> file controls which days SMOKE will treat as holidays and which day of the week SMOKE will emulate for that day. The file must be created for each year, since some holiday dates are different each year. Although the format of the file suggests that the holidays can be modeled differently for different counties in the inventory, this is not the case - the format is provided for a future update to SMOKE, which has not yet been implemented.</para>

<para>To change the holiday dates that are modeled by SMOKE, all that is required is changing the <envar>HOLIDAYS</envar> file to include the year and holidays in which you are interested, and select a day of the week to use for modeling that holiday. If you do not wish SMOKE to treat a holiday any differently, then it should be removed from the file. If you wish no days to be modeled as holidays, we recommend including at least one date in the file, and assigning its actual day of the week, to prevent SMOKE from getting confused.</para>

</section>

<section id="sect_scripts_uniform_profiles">

<title>Use uniform temporal profiles for all sources</title>

<para>SMOKE includes a little-used option to allow SMOKE to ignore all temporal profile information from the temporal cross-reference and temporal profiles. In this case, the emissions will be constant for all hours of all days, except for a slight variation from month to month to account for the different number of days in each month. This option still requires the temporal cross-reference and temporal profile input files, but they are ignored. To use this capability in SMOKE, set the <envar>UNIFORM_TPROF_YN</envar> setting in the run script to Y.</para>

</section>

</section>

<section id="sect_scripts_use_elevpoint">

<title>Use <command>Elevpoint</command> for selecting elevated and PinG sources</title>

<para>The <command>Elevpoint</command> program can select elevated and/or PinG sources as needed for some air quality models and configurations. You must use the <command>Elevpoint</command> program in the following cases:</para>

<itemizedlist>
<listitem>
<para>You are running UAM or CAM<subscript>X</subscript> including elevated point sources and/or PinG sources.</para>
</listitem>
<listitem>
<para>You are running CMAQ and want to select specific elevated sources or want to model with the PinG capability.</para>
</listitem>
</itemizedlist>

<para>The following steps must be taken to use <command>Elevpoint</command>:</para>

<orderedlist>
<listitem>
<para>Create a <envar>PELVCONFIG</envar> file.</para>

<para>The PELVCONFIG file is the <command>Elevpoint</command> input file that controls what sources will be selected as elevated and/or PinG. <xref linkend="ch_input_files" /> explains the file format for this file and how to use this format. A example <envar>PELVCONFIG</envar> file provided with SMOKE (in the nctox case <filename class="directory"><envar>PTDAT</envar></filename> directory) contains additional instructions on setting up this file.</para>
</listitem>
<listitem>
<para>Update Assigns file to use the correct name of the <envar>PELVCONFIG</envar> file.</para>
</listitem>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to Y in point source run script.</para>
</listitem>
<listitem>
<para>If using PinG sources, set <envar>SMK_PING_METHOD</envar> to 1 in point source run script (otherwise, set to 0).</para>
</listitem>
<listitem>
<para>If selecting specific elevated sources, set <envar>SMK_ELEV_METHOD</envar> to 1 in point source run script (otherwise, set to 0).</para>
</listitem>
<listitem>
<para>See model-specific settings in <xref linkend="sect_scripts_model_cmaq" /> and <xref linkend="sect_scripts_model_uam" />.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_use_beis3">

<title>Use BEIS3</title>

<para>The steps you need to take to use BEIS3 for your modeling case are:</para>

<orderedlist>
<listitem>
<para>Ensure that the land use file has been created and properly installed</para>

<para>See <xref linkend="sect_scripts_install_spatial_inputs" />, step 4) for more information on creating and installing the land use data.</para>
</listitem>
<listitem>
<para>Ensure that the meteorology data are correct</para>

<para>See <xref linkend="sect_scripts_install_spatial_inputs" />, step 5) and <xref linkend="sect_scripts_change_meteorology" /> for more information on creating and installing the meteorology data.</para>
</listitem>
<listitem>
<para>Ensure that BEIS3 emission factors are in place.</para>

<para>The <envar>B3FAC</envar> file is installed by SMOKE and does not need to be changed, so it is very unlikely that this file will not be in its <filename class="directory"><envar>GE_DAT</envar></filename> location. The example Assigns file sets the logical file names for this file, which should not be changed.</para>
</listitem>
<listitem>
<para>Setup your BEIS3 run script</para>

<para>To set up your BEIS3 run, copy the example BEIS3 run script listed in <xref linkend="sect_scripts_example_scripts" /> and reset the script settings. The settings that you may need to reset are as follows (see <xref linkend="ch_programs" /> for all program options):</para>

<itemizedlist>
<listitem>
<para><envar>RUN_METSCAN</envar>: Set to Y if you need to use the <envar>BIOSEASON</envar> file (see <xref linkend="sect_scripts_install_spatial_inputs" />, step 6).</para>
</listitem>
<listitem>
<para><command>Normbeis3</command> options</para>
</listitem>
<listitem>
<para><command>Tmpbeis3</command> options</para>
</listitem>
<listitem>
<para><command>Smkmerge</command> options - this program is used to create state/county totals and/or to change units for CMAQ from moles/hr (output by <command>Tmpbeis3</command>) to moles/s. Depending on the purpose for running <command>Smkmerge</command> in your script, adjust the <command>Smkmerge</command> options accordingly. Please note that you cannot create gridded outputs in moles/s and state/county totals in tons/day in a single run.</para>

<para>If creating state/county totals, make sure the <envar>AREA_SURROGATE_NUM</envar> setting is set to the cell-area surrogate number in your <envar>BGPRO</envar> file.</para>
</listitem>
<listitem>
<para><envar>SPC_OVERRIDE</envar>: May be needed in some cases (see <xref linkend="sect_scripts_script_settings" />)</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section id="sect_scripts_change_meteorology">

<title>Change meteorology data</title>

<para>To change the meteorology data, you must take the following steps:</para>

<orderedlist>
<listitem>
<para>Determine what format your air quality model will accept for meteorology data and convert data to I/O API format if needed.</para>

<para>If you are modeling with CMAQ, then the data will be in the I/O API format created by MCIP or MCPL that SMOKE can accept. If you are modeling with UAM or CAM<subscript>X</subscript>, then you must check to see which meteorology format the model accepts. Some versions of these models can use the same I/O API format as for CMAQ, but some cannot.</para>

<para>If your meteorology data are not in the correct format, then you will need to convert the data. There is currently no utility provided with SMOKE to convert the meteorology format needed by some versions of UAM and CAM<subscript>X</subscript> to SMOKE input format.</para>
</listitem>
<listitem>
<para>Ensure required variables are included in meteorology data</para>

</listitem>
<listitem>
<para>Ensure meteorology data cover the correct time period</para>

</listitem>
<listitem>
<para>Ensure meteorology data are on the correct grid</para>

<para>As described in <xref linkend="sect_scripts_install_spatial_inputs" /> step 5, check that the meteorology grid and modeling grid are consistent.</para>
</listitem>
<listitem>
<para>Install meteorology data</para>

<para>The meteorology data should be installed in the <filename class="directory"><envar>$METDAT</envar></filename> directory, as explained in <xref linkend="ch_dirs_files" />. The names of the files are up to you.</para>
</listitem>
<listitem>
<para>Ensure that the meteorology data names match with the names in the Assigns file</para>

<para>Edit the Assigns file and look for the <envar>$METDAT</envar> variable. Ensure that it is consistent with the actual location of the meteorology files. Also check the settings for <envar>GRID_CRO_2D</envar>, <envar>GRID_CRO_3D</envar>, <envar>MET_CRO_2D</envar>, <envar>MET_CRO_3D</envar>, and <envar>MET_DOT_3D</envar> and make sure that the naming scheme for these files is consistent with your file names.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_ptfire_emis_cmaq">

<title>Plume Rise Calculation for Fires</title>

<para>Starting with SMOKE version 2.3, SMOKE can compute hourly plume rise from an intenally computed heat flux using area burned and fuel loading data. This approach allows SMOKE to compute hourly heat flux based upon daily area burned, fuel loading, material burned and a constant default heat content (8000 BTU/lb) (Equation 1). The daily heat flux and emissions are temporally allocated to hourly values based upon the duration of the fire (begining and ending hours). However, if there is a precomputed heat flux available as a daily inventory, <command>Smkinven</command> will not internally compute the heat flux and drop the begin and end hours of fire.</para>

<orderedlist>
<listitem>
<para>Heat Flux (BTU/hr) = [ Area Burned (acre/day) x Fuel Loading (tons/acre) x Heat Content (BTU/lb) x (2000lb/ton) ] /  Duration of fire (hr/day) </para>
</listitem>
</orderedlist>

<para>Detail information on how the fire emissions are calculated can be found on the proceeding presented by <ulink url="https://www3.epa.gov/ttnchie1/conference/ei14/session12/pouliot.pdf">Pouliot et al., (2005)</ulink>.</para>

<para>The SMOKE plume rise requires two ORL formatted files for wildfire/prescribed fires. The master #ORL FIRE file (<xref linkend="sect_input_ptinv_fire" />) contains the fire characteristics including country/state/county code, fire idenfication code, geographic coordinate, fire name, heat content, material burned and NFDRS code.  The day-specific #ORL FIREEMIS file (<quote><xref linkend="sect_input_ptday_fireemis" /></quote>) includes daily pollutant emissions, area burned, fuel loading, optional heat flux, and fire begining and ending time. Starting with SMOKE version 3.7, <command>Smkinven</command> can process these master and daily fire inventories with precomputed heat flux using current point FF10 formats, #FF10_POINT file (<quote><xref linkend="sect_input_ptinv_ff10" /></quote>) and #FF10_DAILY_FF10 file (<quote><xref linkend="sect_input_ptday_ff10" /></quote>)</para>

<para>Regardless whether the heat flux for wildfires is precomputed or internally computed, the fire-specific plume rise algorithm converts the heat flux to a bouyancy flux for use in the plume rise calculation. See more detail at <xref linkend="sect_programs_laypoint_plume_rise_fires"/></para>


<para>NOTE: SMOKE requires that the fire inventory pollutant names are copied to the Chemical Abstracts Service (CAS) number column in the inventory table (<envar>INVTABLE</envar>) file  (See <xref linkend="sect_input_invtable" />).</para> 
<orderedlist>
<listitem>
<para> To compute plume rise for fires using SMOKE, following these steps. Add the fire inventory variables to the <envar>INVTABLE</envar> file:</para>
<programlisting><envar>HFLUX           HFLUX                    Y     1 N N N N   0 tons/yr</envar>
<envar>HEATCONTENT     HEATCONTENT              Y     1 N N N N   0 tons/yr</envar>
<envar>FUEL_LOAD       FUEL_LOAD                Y     1 N N N N   0 tons/yr</envar>
<envar>ACRESBURNED     ACRESBURNED              Y     1 N N N N   0 tons/yr</envar>
<envar>BEGHOUR         BEGHOUR                  Y     1 N N N N   0 tons/yr</envar>
<envar>ENDHOUR         ENDHOUR                  Y     1 N N N N   0 tons/yr</envar></programlisting>
</listitem>

<listitem>
<para>Run <command>Smkinven</command> with these settings,</para>
<itemizedlist>
<listitem>
<para>Set <envar>RUN_SMKINVEN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>IMPORT_AVEINV_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>CHECK_STACKS_YN</envar> to N</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>Do not run <command>Elevpoint</command>,</para>
<itemizedlist>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ELEV_METHOD</envar> to 0</para>
</listitem>
<listitem>
<para>Set <envar>SMK_PING_METHOD</envar> to 0</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>Run <command>Laypoint</command> with these settings, </para>
<itemizedlist>
<listitem>
<para>Set <envar>RUN_LAYPOINT</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>FIRE_PLUME_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>HOURLY_FIRE_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>SMK_SPECELEV_YN</envar> to N</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>Run <command>Smkmerge</command> with theses settings,</para>
<itemizedlist>
<listitem>
<para>Set <envar>RUN_SMKMERGE</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ASCIIELEV_YN</envar> to N</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>Set these multiple program control settings.</para>
<itemizedlist>
<listitem>
<para>Set <envar>DAY_SPECIFIC_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>EXPLICIT_PLUMES_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_PING_METHOD</envar> to 0</para>
</listitem>
<listitem>
<para>Set <envar>QA_TYPE</envar> to part2</para>
</listitem>
</itemizedlist>
</listitem>

</orderedlist>

</section>

<section id="sect_in-line_model_cmaq">

<title>In-line Plume Rise Calculation in CMAQ model (as of version 4.7)</title>

<para>Staring with version 2.5, SMOKE supports the calculation of plume rise for point sources in CMAQ known as an in-line plume rise calculation. SMOKE is used to select the point sources to reduce the CMAQ plume rise treatment. In this section, we give a basic outline of how to run SMOKE to output emissions for the in-line plume rise processing in CMAQ. To prepare emissions for the CMAQ in-line plume rise calculation follow these steps:</para>

<orderedlist>
<listitem>
<para> For fires, the following two lines need to be added to the <envar>GSPRO</envar> file (See <xref linkend="sect_input_gspro" />):</para>

<para><envar>"0000";"HFLUX";"HFLUX";1;1;1</envar></para>
<para><envar>"0000";"ACRESBURNED";"ACRESBURNED";1;1;1</envar></para>

</listitem>
<listitem>
<para>Set these variables in the SMOKE run scripts.</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_LAYPOINT</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ELEV_METHOD</envar> to 2 (See <xref linkend="sect_programs_elevpoint_envar" />)</para>
</listitem>
<listitem>
<para>Set <envar>SMK_PING_METHOD</envar> to 0</para>
</listitem>
<listitem>
<para>Set <envar>MRG_LAYERS_YN</envar> to N</para>
</listitem>
</itemizedlist>

</listitem>

<listitem>
<para><command>Elevpoint</command> to select the sources to receive the CMAQ in-line plume rise treatment. Create a <envar>PELVCONFIG</envar> file to group sources with nearly identical stack parameters to reduce the total number of plume rise calculations performed by the CMAQ in-line plume rise module. Non-fire sources with an analytical plume rise height greater than 38 meters are typically selected for in-line plume rise processing. The <envar>PELVCONFIG</envar> file used for CMAQ in-line processing of non-fire sources should be similar to the following example:</para>

<para>SMK_SOURCE  P</para>
<para>/SPECIFY ELEV GROUP/</para>
<para>HT +/- 0.001 AND DM +/- 0.001 AND TK +/- 0.001 AND VE +/- 0.001</para>
<para>/END/</para>
<para> </para>
<para>/SPECIFY ELEV/</para>
<para>RISE >= 38</para>
<para>/END/</para>

<para>For point source fires, such as the EPA ptfire sector, the following is an example of a <envar>PELVCONFIG</envar> file:</para>
<para>SMK_SOURCE  P</para>
<para>/SPECIFY ELEV GROUP/</para>
<para>HT+/- 1.0</para>
<para>/END/</para>
<para> </para>
<para>/SPECIFY ELEV/</para>
<para>PM2_5 > 0</para>
<para>/END/</para>

</listitem>
</orderedlist>

</section>

<section id="sect_scripts_model_cmaq">

<title>Model for CMAQ</title>

<para>In this section, we attempt to give a basic outline of the considerations for script reconfiguration needed for SMOKE output for the CMAQ model. All models require <command>Smkmerge</command> to be configured for outputting gridded data, with speciation, and with hourly emissions. The following configurations are needed when modeling for CMAQ.</para>

<orderedlist>
<listitem>
<para>Make sure the chemical speciation is set for one of the CMAQ chemical mechanism.</para>

<para>This check involves the <envar>SPC</envar> setting, explained in <xref linkend="sect_scripts_change_speciation" />.</para>
</listitem>
<listitem>
<para>Set the basic settings for CMAQ.</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_LAYPOINT</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>REP_LAYER_MAX</envar> to the number of the layer you expect should be the maximum plume rise layer (the layer that includes 2000 meters).</para>
</listitem>
<listitem>
<para>Set <envar>MRG_TEMPORAL_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_SPCMAT_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_LAYERS_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_GRDOUT_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ASCIIELEV_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_EMLAYS</envar> to the number of layers you need for your emissions files (usually up to the layer that includes 2000 meters, unless you are using explicit plume rise, in which case the layer that includes the maximum plume height of the precomputed plume top).</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Set the correct output units in the runs scripts.</para>

<para>CMAQ expects output units of moles/s. For biogenic processing, this requires the <command>Smkmerge</command> program to be run to convert the moles/hr units output by <command>Tmpbio</command> or <command>Tmpbeis3</command> to moles/s.</para>

<para>Set the <envar>MRG_GRDOUT_UNIT</envar> setting in the run script to either moles/s (for CMAQ). For biogenics processing, make sure <envar>RUN_SMKMERGE</envar> is set to Y.</para>
</listitem>

<listitem>
<para>Configure approach for plume rise for standard point sources, including optional PinG sources for CMAQ.</para>

<para>The point-source run script should have the following settings in each of the following situations.</para>

<orderedlist>
<listitem>
<para>Calculate plume rise for all point sources.</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>HOUR_PLUMEDATA_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_SPECELEV_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>EXPLICIT_PLUMES_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_PING_METHOD</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_SPECELEV_YN</envar> to N</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Select specific elevated sources for CMAQ and calculate plume rise only for those.</para>

<para>Use the same settings as in part (a) above, except:</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to Y (See <xref linkend="sect_scripts_use_elevpoint" /> for more information about running <command>Elevpoint</command> to select elevated sources)</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ELEV_METHOD</envar> to 1</para>
</listitem>
<listitem>
<para>Set <envar>SMK_SPECELEV_YN</envar> to Y</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Select PinG sources for CMAQ.</para>

<para>Use the same settings in part (a) above, except:</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to Y (See <xref linkend="sect_scripts_use_elevpoint" /> for more information about running <command>Elevpoint</command> to select PinG sources)</para>
</listitem>
<listitem>
<para>Set <envar>SMK_PING_METHOD</envar> to 1</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</listitem>
<listitem>
<para>Configure approach for plume rise for explicit plume rise sources.</para>

<para>Explicit plume rise sources (i.e., sources for which plume rise has been computed outside of SMOKE) require additional precomputed plume rise information, previously described for inventory data import in <xref linkend="sect_scripts_hour_day_invs" />. In addition to these data for CMAQ modeling, the following settings must be made in the run scripts. These settings are in addition to the other configurations you need for the other point sources described above. <remark>If the only point sources in your inventory are explicit plume rise sources, then use the settings described in steps 3 and 5a above.</remark></para>

<itemizedlist>
<listitem>
<para>Set <envar>HOUR_PLUMEDATA_YN</envar> to Y</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section id="sect_scripts_model_uam">

<title>Model for UAM and CAM<subscript>X</subscript></title>

<orderedlist>
<listitem>
<para>Make sure the chemical speciation is set for one of the UAM or CAM<subscript>X</subscript> chemical mechanisms.</para>

<para>This check involves the <envar>SPC</envar> setting, explained in <xref linkend="sect_scripts_change_speciation" />. Please note that the files and setup needed for CAM<subscript>X</subscript>-PM are not available in SMOKE v2.1.</para>
</listitem>
<listitem>
<para>Set the basic settings for UAM and CAM<subscript>X</subscript></para>

<para>In these settings, we will configure the system to select elevated point sources using the <command>Elevpoint</command> program, but not PinG sources.</para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_LAYPOINT</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>RUN_ELEVPOINT</envar> to Y (See <xref linkend="sect_scripts_use_elevpoint" /> for more information about running <command>Elevpoint</command> to select elevated sources)</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ELEV_METHOD</envar> to 1</para>
</listitem>
<listitem>
<para>Set <envar>MRG_TEMPORAL_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_SPCMAT_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_LAYERS_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>MRG_GRDOUT_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>SMK_ASCIIELEV_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>MRG_GRDOUT_UNIT</envar> to moles/hr</para>
</listitem>
<listitem>
<para>Set <envar>EXPLICIT_PLUMES_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>HOUR_PLUMEDATA_YN</envar> to N</para>
</listitem>
<listitem>
<para>Set <envar>SMK_SPECELEV_YN</envar> to Y</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Optionally configure for PinG sources.</para>

<para>In addition to different instructions in the <envar>REPCONFIG</envar> file, the point-source run script should have the following settings in each of the following situations.</para>

<itemizedlist>
<listitem>
<para>Set SMK_PING_METHOD to 1</para>
</listitem>
</itemizedlist>

</listitem>
<listitem>
<para>Configure approach for plume rise for explicit plume rise sources.</para>

<para>Explicit plume rise sources (i.e., sources for which plume rise has been computed outside of SMOKE) require additional precomputed plume rise information, previously described for inventory data import in <xref linkend="sect_scripts_hour_day_invs" />. In addition to these data for UAM and CAM<subscript>X</subscript> modeling, the following settings must be made in the run scripts. These settings are in addition to the other configurations you need for the other point sources described above. <remark>If the only point sources in your inventory are explicit plume rise sources, then use the settings described in steps 2 and 3 above.</remark></para>

<itemizedlist>
<listitem>
<para>Set <envar>RUN_LAYPOINT</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>EXPLICIT_PLUMES_YN</envar> to Y</para>
</listitem>
<listitem>
<para>Set <envar>HOUR_PLUMEDATA_YN</envar> to Y</para>
</listitem>
</itemizedlist>

</listitem>
</orderedlist>

</section>

<section>

<title>Determine if a run worked correctly and troubleshoot</title>

<para>Determining if your run worked correctly and troubleshooting are described in detail in <xref linkend="ch_quality_assurance" />. We refer the reader to that chapter for explanations of how to perform these steps.</para>

<orderedlist>
<listitem>
<para>Resolve all errors and warnings in all log files.</para>

<comment><para><xref linkend="ch_errors" /> includes possible errors and warnings generated by the SMOKE programs and provides guidance on how to handle them.</para></comment>
</listitem>
<listitem>
<para>Compare SMOKE output emissions to inventory total emissions at each stage of SMOKE processing to ensure emissions have not been erroneously lost or added.</para>
</listitem>
<listitem>
<para>Review and analyze SMOKE reports that indicate the speciation profiles, temporal profiles, and spatial surrogate codes assigned to each SCC in the inventory.</para>
</listitem>
<listitem>
<para>Examine your inventory for interregional inconsistencies.</para>
</listitem>
<listitem>
<para>Visually examine your model-ready emissions to search for possible errors.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_change_reports">

<title>Change reports</title>

<para>SMOKE provides the <command>Smkreport</command> tool as a very flexible tool to generate reports on your inventory and emissions modeling case. This program is documented in detail in <xref linkend="ch_quality_assurance" />. Here, we provide the information that you need to reconfigure your scripts to use different reporting. The <envar>QA_TYPE</envar> and <envar>QA_LABEL</envar> environment variables introduced in <xref linkend="sect_scripts_script_settings" /> are clarified here.</para>

<orderedlist>
<listitem>
<para>Customize the names of the output report files and <command>Smkreport</command> log files.</para>

<para>The example SMOKE run scripts will name the log files and report output files with preset names. If you set the <envar>QA_LABEL</envar> setting, the reports and log file names will then include the value of that setting. For example, if the default report name were <filename>a.state.nei99.rpt</filename> and <envar>QA_LABEL</envar> were set to <quote>run1</quote>, the new report name would be <filename>a.state.nei99.run1.rpt</filename>. The <quote>run1</quote> in <envar>QA_LABEL</envar> is inserted before the final <quote>rpt</quote> extension.</para>
</listitem>
<listitem>
<para>Select from one of the default settings for <envar>QA_TYPE</envar></para>

<para>The default <envar>QA_TYPE</envar> settings allow users to run <command>Smkreport</command> with the default <envar>REPCONFIG</envar> files. These files are located in the <filename class="directory"><envar>$OTHER</envar></filename> directory, documented in <xref linkend="ch_dirs_files" />. Each source category has its own valid <envar>QA_TYPE</envar> settings, and each of these settings causes certain reports to be created. <xref linkend="tbl_scripts_qa_type" /> indicates which <envar>QA_TYPE</envar> setting can be used in which case, and the <envar>REPCONFIG</envar> files that will be used.</para>

<table id="tbl_scripts_qa_type">
<title><envar>QA_TYPE</envar> settings with associated source categories and default <envar>REPCONFIG</envar> files</title>

<tgroup cols="3">
<colspec colwidth="1*" />
<colspec colwidth="1*" />
<colspec colwidth="3*" />

<thead>
<row>
<entry align="center"><envar>QA_TYPE</envar></entry>
<entry align="center">Source Categories</entry>
<entry align="center"><envar>REPCONFIG</envar> file from <filename class="directory"><envar>$SMKDAT</envar>/inventory/nctox/other</filename></entry>
</row>
</thead>

<tbody>
<row>
<entry>part1 (<envar>RUN_PART1</envar> must be set to Y)</entry>
<entry>
<simplelist>
<member>area</member>
<member>nonroad</member>
<member>mobile</member>
<member>point</member>
</simplelist>
</entry>
<entry>
<simplelist>
<member><filename>repconfig.ar.inv.txt</filename></member>
<member><filename>repconfig.nr.inv.txt</filename></member>
<member><filename>repconfig.mb.inv.txt</filename></member>
<member><filename>repconfig.pt.inv.txt</filename></member>
</simplelist>
</entry>
</row>
<row>
<entry>part2 (<envar>RUN_PART2</envar> must be set to Y)</entry>
<entry>
<simplelist>
<member>area</member>
<member>nonroad</member>
<member>mobile</member>
<member>point</member>
</simplelist>
</entry>
<entry>
<simplelist>
<member><filename>repconfig.ar.temporal.txt</filename></member>
<member><filename>repconfig.nr.temporal.txt</filename></member>
<member><filename>repconfig.mb.temporal.txt</filename></member>
<member><filename>repconfig.pt.temporal.txt</filename></member>
</simplelist>
</entry>
</row>
<row>
<entry>part3 (<envar>RUN_PART3</envar> must be set to Y)</entry>
<entry>point</entry>
<entry><filename>repconfig.pt.elev.txt</filename></entry>
</row>
<row>
<entry>part4 (<envar>RUN_PART4</envar> must be set to Y)</entry>
<entry>point</entry>
<entry><filename>repconfig.pt.lfrac.txt</filename></entry>
</row>
<row>
<entry>all</entry>
<entry>
<simplelist>
<member>area</member>
<member>nonroad</member>
<member>mobile</member>
<member>point</member>
</simplelist>
</entry>
<entry>All of the above reports will be generated, provided that the <envar>RUN_PART(1-4)</envar> settings are set as listed in column 1 of this table.</entry>
</row>
<row>
<entry>custom</entry>
<entry>
<simplelist>
<member>area</member>
<member>nonroad</member>
<member>mobile</member>
<member>point</member>
</simplelist>
</entry>
<entry>See step (3) below.</entry>
</row>
</tbody>
</tgroup>
</table>

<para>The helper script <filename>qa_run.csh</filename> is responsible for selecting the correct <envar>REPCONFIG</envar> file based on the <envar>QA_TYPE</envar> setting, and these settings need not be changed. If users wish to implement a different configuration, the <quote>custom</quote> value of <envar>QA_TYPE</envar> should be able to meet those needs without any changes to <filename>qa_run.csh</filename>. Copying the <envar>REPCONFIG</envar> files from the example files to your case and changing them changes the default reports that are generated by SMOKE for your case.</para>

<para>Users can examine these <envar>REPCONFIG</envar> files along with the documentation in <xref linkend="ch_quality_assurance" /> to determine the reports that will be generated by each. These reports are also generated during the SMOKE installation and test case run, and can provide examples for understanding which reports will be written.</para>
</listitem>

<listitem>
<para>Using the <quote>custom</quote> setting</para>

<para>If <envar>QA_TYPE</envar> is set to <quote>custom</quote>, then the <filename>qa_run.csh</filename> script expects that users will set the correct <envar>REPORT*</envar> environment variables in the main body of their run script. The <envar>REPORT*</envar> environment variables are typically used as the logical file names for <command>Smkreport</command>, those environment variables used are themselves configurable in the <envar>REPCONFIG</envar> file. The physical file names can also be set in the <envar>REPCONFIG</envar> file directly, instead of relying on the scripts to contain environment variable settings. These options are explained in greater detail in <xref linkend="ch_quality_assurance" />.</para>
</listitem>
</orderedlist>

</section>

<section id="sect_scripts_source_apportionment">

<title>Generating CMAQ-ready Source Apportionment Input Data Files</title>

<para>Source apportionment in SMOKE consists of grouping sources by characteristics (i.e. FIPS code, SCC, and point source information) and then tagging the emissions from those groupings for further analysis in the air quality model. The SMOKE programs <command>Movesmrg</command> and <command>Smkmerge</command> can optionally output the emissions in special files used for later source apportionment processing.</para>

<para>The following steps outline the process for creating the source apportionment output files:</para>

<orderedlist>
<listitem>
<para>Define source groups using the <envar>SOURCE_GROUPS</envar> file</para>

<para>The format for the <envar>SOURCE_GROUPS</envar> file is described in <xref linkend="sect_input_smkmerge_groups" />. When assigning sources to groups, SMOKE will match each source to the most specific line in the <envar>SOURCE_GROUPS</envar> file. The hierarchy of assignment priority is listed below.</para>

<orderedlist spacing="compact">
<listitem>
<para>Country/state/county code, SCC, plant ID, point ID [point sources only]</para>
</listitem>
<listitem>
<para>Country/state/county code, SCC, plant ID [point sources only]</para>
</listitem>
<listitem>
<para>Country/state/county code, plant ID, point ID [point sources only]</para>
</listitem>
<listitem>
<para>Country/state/county code, plant ID [point sources only]</para>
</listitem>
<listitem>
<para>Country/state/county code, SCC [non-biogenic sources only]</para>
</listitem>
<listitem>
<para>Country/state code, SCC [non-biogenic sources only]</para>
</listitem>
<listitem>
<para>SCC [non-biogenic sources only]</para>
</listitem>
<listitem>
<para>Country/state/county code</para>
</listitem>
<listitem>
<para>Country/state code</para>
</listitem>
<listitem>
<para>Default group (country/state/county code = 0, SCC = 0)</para>
</listitem>
</orderedlist>

</listitem>

<listitem>
<para>Define locations for the output files <envar>SRCGROUPS_OUT</envar> (source group information), <envar>SGINLNTS_L</envar> (emissions data), and <envar>SRCGRP_REPORT</envar> (source group report file)</para>
</listitem>

<listitem>
<para>For point source processing, use in-line plume rise calculation</para>

<para>Review <xref linkend="sect_in-line_model_cmaq" /> for instructions on configuring <command>Elevpoint</command> and <command>Laypoint</command> for in-line emissions processing.</para>
</listitem>

<listitem>
<para>After completing other SMOKE processing, run <command>Movesmrg</command> (on-road mobile emissions using MOVES lookup tables) or <command>Smkmerge</command> with <envar>SMK_SRCGROUP_OUTPUT_YN</envar> set to Y</para>

<para>When processing emissions using source apportionment, you can only run <command>Smkmerge</command> for a single source category (i.e. A, B, M, or P). For point source processing, <command>Smkmerge</command> cannot merge layers (<envar>MRG_LAYERS_YN</envar> must be N) and in-line emissions must be output (<envar>SMK_ELEV_METHOD</envar> must be 2). <command>Movesmrg</command> and <command>Smkmerge</command> will create both the source apportionment data files and the model-ready output files in a single run. For biogenics, if you are running <command>Smkmerge</command> for reporting purposes (i.e. to create state and county totals), make sure to set the units correctly for the source apportionment output data, typically the same as the model-ready output units.</para>
</listitem>

<listitem>
<para>Review source grouping assignments</para>

<para>After running <command>Movesmrg</command> or <command>Smkmerge</command>, the <envar>SRCGRP_REPORT</envar> file will list each source in the inventory and the group it was assigned to. You can review this report to verify that the sources were grouped as desired.</para>
</listitem>

</orderedlist>

</section>

<section id="sect_scripts_aermod">

<title>Generating AERMOD-ready Input Data Files [SMOKE4AERMOD)</title>

<para>As of SMOKE v4.5, The <ulink url="https://github.com/CEMPD/SMOKE/tree/master/scripts/aermod">SMOKE4AERMOD</ulink> postprocessing scripts have been developed for SMOKE to generate the SMOKE-compatible inventory-based AERMOD-ready input data files for AERMOD modeling run in chi/q mode as a part of <ulink url="https://www.epa.gov/national-air-toxics-assessment/nata-overview">U.S. EPA National Air Toxics Assessment (NATA)</ulink> studies support. The NATA is an EPA&rsquo;s screening tool of ongoing review of air toxics in the United States for states, local and tribal agencies. NATA's results will help these agencies identify which pollutatns, emission sources and places they may wish to study further to better understand any possible risks to public health air toxics.</para>
<para>These postprocessing scripts creates <quote>helper</quote> files for several inventory sectors listed below.</para> 

<orderedlist>
<listitem><para>Nonpoint Sources : nonpt</para></listitem>
<listitem><para>Nonpoint Oil and Gas Sources : np_oilgas</para></listitem>
<listitem><para>Point Energy Generating Unit Sources : ptegu</para></listitem>
<listitem><para>Point Non-Integrated Planning Model Sources : ptnonipm</para></listitem>
<listitem><para>Point Airports Sources : ptairport</para></listitem>
<listitem><para>Nonroad Mobile Sources : nonroad</para></listitem>
<listitem><para>Onroad Mobile Sources : Onroad</para></listitem>
<listitem><para>Residential Wood Combustion Sources : RWC</para></listitem>
<listitem><para>Commercial Marine Vessel Sources : CMV</para></listitem>
</orderedlist>
</section>



</section>

</chapter>