3.2. Directory structure

3.2.1. Example Assigns file
3.2.2. The basic SMOKE directories
3.2.3. Locations of input files
3.2.4. Locations of intermediate files for base and growth/control cases
3.2.5. Locations of model-ready output files for base and growth/control cases
3.2.6. Locations of reports

The SMOKE directory structure is the organization of UNIX directories and subdirectories (essentially the same as “folders” on Windows computers). These directories are defined and created using the SMOKE Assigns file. By “defined”, we mean that environment variables are set to the actual path name for each of the directories, and their relationships to one another are implicit in these definitions. As will be described in more detail in Chapter 4, How to Use SMOKE, you should create an Assigns file for each modeling case to organize your modeling runs. If created properly, the different Assigns files will cause the intermediate and output directories to be different for each case; this prevents overwriting files from one case with files from another. Some parts of the directory structure are shared by all modeling cases because they are usually the same (e.g., SMOKE support files), but the intermediate and output files are not assumed to be the same because they often differ between cases.

3.2.1. Example Assigns file

Before we can proceed with describing the scripts, we need to introduce the Assigns file. Detailed documentation on this file is provided in Section 4.2.2.2, “Assigns files”. For the purposes of the discussion here, we provide an example Assigns file to help clarify what it is. Because this file is quite lengthy, we have only included excerpts. In this subsection, the Assigns file is simply a set of setenv UNIX commands and calls to helper scripts.

The arrangement within the default Assigns file provided with SMOKE is:

  • Shell command (e.g., #!/bin/csh -fx for C shell)

  • Descriptive global comments

  • Settings for the naming roots

  • Settings for the episode dates and times

  • Settings for the directory structure and use of the set_dirs.scr helper script

  • Settings for SMOKE input and output files and calls to other helper scripts

The first settings section is used for naming roots. These settings allow users to set the inventory input and output identifiers, the base-case scenario names, and the grid and chemical mechanism names (see Chapter 4, How to Use SMOKE for more details). The following lines provide the naming roots used in the default Assigns file provided with SMOKE, ASSIGNS.nctox.cmaq.cb4pm25_wtox.us12-nc. This file and the helper scripts can be found in the $ASSIGNS directory, which we will define in Section 3.2.2, “The basic SMOKE directories”.

#
## I/O Naming roots
#
   setenv INVID     nctox        # Inventory input identifier
   setenv INVOP     nctox        # Base year inventory output name
   setenv INVEN     nctox        # Base year inventory name with version

   setenv ABASE     nctox        # Area base case output name
   setenv BBASE     nctox        # Biogenics base case output name
   setenv MBASE     nctox        # Mobile base case output name
   setenv PBASE     nctox        # Point base case output name

   setenv EBASE     nctox        # Output merged base case name

   setenv METSCEN      12km             # Met scenario name
   setenv GRID         us12-nc          # Gridding root for naming
   setenv IOAPI_GRIDNAME_1 US12NC_66X52 # Grid selected from GRIDDESC file
   setenv IOAPI_ISPH   19               # Specifies spheroid type associated with grid
   setenv SPC          cmaq.cb4p25_wtox # Speciation type

The next section of the file includes the settings for the episode:

## Mobile episode variables
   setenv EPI_STDATE 2001191     # Julian start date
   setenv EPI_STTIME  000000     # start time (HHMMSS)
   setenv EPI_RUNLEN 0480000     # run length (HHHMMSS)
   setenv EPI_NDAY   2           # number of full run days

## Per-period environment variables
   setenv G_STDATE  2001191      # Julian start date
   setenv G_STTIME   000000      # start time (HHMMSS)
   setenv G_TSTEP     10000      # time step  (HHMMSS)
   setenv G_RUNLEN   250000      # run length (HHMMSS)
   setenv ESDATE   20010710      # Start date of emis time-based files/dirs
   setenv MSDATE   20010710      # Start date of met time-based files
   setenv NDAYS           1      # Duration in days of each emissions file
   setenv MDAYS           1      # Duration in days of met time-based files
   setenv YEAR         2001      # Base year for year-specific files

As described in Chapter 4, How to Use SMOKE, these settings control both the way SMOKE runs (e.g., SMOKE uses EPI_STDATE, the start date of the episode, to decide what day to start the simulation) and the way SMOKE names files (e.g., ESDATE is used to help name time-dependent files).

The next section of the Assigns file is used to set the user-defined input and output directory paths. It uses a helper script called set_dirs.scr that applies the initial settings made by the Assigns file to set environment variables for the directories, as described in Section 3.2.2, “The basic SMOKE directories”. The set_dirs.scr script also verifies that all of the directories are there and that the permissions of the directories are group readable and writable.

## User-defined I/O directory settings
   setenv SMK_SUBSYS  $SMK_HOME/subsys              # SMOKE subsystem dir
   setenv SMKROOT     $SMK_SUBSYS/smoke             # System root dir
   setenv SMKDAT      $SMK_HOME/data                # Data root dir
   setenv ASSIGNS     $SMKROOT/assigns              # SMOKE assigns files

<omitted section>

## Set dependent directory names
#
source $ASSIGNS/set_dirs.scr

Now that we have provided a little background on Assigns files, we will spend the rest of this chapter describing the SMOKE directory structure. We will return to discussion of the Assigns file and scripts in Chapter 4, How to Use SMOKE. It is important to understand the directory structure information in the rest of this chapter before moving on to Chapter 4, How to Use SMOKE.