The third section of the REPCONFIG file is called the Create-report section. It is responsible for providing instructions to Smkreport for generating the reports. The /CREATE REPORT/ packet is used in this section. This packet uses the following types of instructions
(listed in alphabetical order):
By using these instructions (some of which have a number of different options), many different types of outputs can be achieved by Smkreport. The ordering of the instructions in the packet is not important, with one exception: if multiple titles are used, they will be printed to the report in the order in which they appear in the packet. The remainder of this subsection provides descriptions of each of these instructions.
The ARRANGE instruction controls the arrangement of variables and files for a single report. This instruction sets how many variables are included in a report or a section of a report, and can set the number of sections that a report will have. It also permits a database format that includes an emissions data value for each record in the report.
If no ARRANGE instruction is provided for a report, Smkreport will attempt to write all of the variables requested in the report to the same file and section. If too many variables are requested in the report, this could cause Smkreport to abort with an error. In general, if you have more than 20 variables that will be written to a given report, you should consider using the ARRANGE instruction.
The syntax of the ARRANGE instruction is:
ARRANGE <option>
with the following valid options:
MULTIFILE [number of variables]: Writes the report into multiple output files. This is different from the Smkreport capability of creating multiple reports: the instruction applies to a single report and indicates that the report should
be output as multiple files. The file names in this case are created automatically by Smkreport based on the file name set by the associated NEWFILE instruction (explained in Section 7.3.8, “The /NEWFILE/ packet”), by appending a “_1”, “_2”, “_3”, and so forth to the file name that would otherwise be output by Smkreport. For example, if the output report setting REPORT1 is defined as /outdir/test/report1.myfile.txt, but that report requires two files, then the actual files that would be written would be /outdir/test/report1.myfile.txt_1 and /outdir/test/report1.myfile.txt_2.
The number of variables option controls the number of variables written to each file of the report. For example, if the report will include 100 variables and the number of variables is set to 15, then Smkreport will create a report using seven separate files, six that include 15 variables (taking care of the first 90 variables) and a seventh file that has the remaining 10 variables. Smkreport allows a maximum of 30 variables per file using the MULTIFILE instruction.
ONEFILE [number of variables]: Writes the report into a single output file with multiple sections. Like the MULTIFILE option, this is different from the Smkreport capability of creating multiple reports: the instruction applies to a single report, but permits multiple sections of the report to be written to the same file.
The number of variables option controls the number of variables written to each section of the report. The number of sections is set automatically by dividing the number of data variables selected for the report by the number of variables.
DATABASE: Writes the report one variable at a time, with only one data variable on each row of the report. The attributes of the row are repeated for all variables, and all entries are written for one variable before the next variable is written. For example, if a report BY SCC10 is requested for the variables NOX and SO2, the report will list all SCCs with the NOX emissions as a data variable, followed by all SCCs again with SO2 emissions. Without the DATABASE instruction, the NOX and SO2 values would be written to the same line of the report and the SCC codes would be written only once.
The ASCIIELEV instruction causes Smkreport to use the elevated ASCII emissions file (ELEVTS_L or ELEVTS_S) written by Smkmerge as the sole source for emissions information in the report. This option can be used only for point sources (SMK_SOURCE is
set to P). When this option is included in a REPCONFIG file, all other reports in the REPCONFIG file must also include the ASCIIELEV instruction, or Smkreport will produce an error.
Using this instruction, Smkreport will use the emissions in the ELEVTS_S or ELEVTS_L file as the sole source of emissions and inventory information. These files include information about the states, counties,
plants, stacks, stack parameters, hour, cell number, and speciated emissions. Therefore, only certain instructions may be
used with the ASCIIELEV instruction, or else a warning will be printed to the log file and the unusable instruction will be
ignored. The following subset of /CREATE REPORT/ instructions can be used with the ASCIIELEV instruction:
The following instructions are implied by the ASCIIELEV instruction:
MRG_GRDOUT_UNIT setting, described below)
The BY instruction controls what columns in addition to data columns will be printed in the output report. Multiple BY commands may appear in the same /CREATE REPORT/ packet, but not all combinations make sense. The BY instructions tell the program the basis on which to sum the emissions or activity values. The syntax of the BY instruction is:
BY <option>
with the following valid options:
CELL: Records are printed by cell. This option requires the GRIDDING instruction, so Smkreport automatically adds the GRIDDING instruction when the BY CELL instruction is used (even if it is not actually in the REPCONFIG file).
COUNTRY [NAME]: Records are printed by country total. This option invokes use of the COSTCY file. NAME can be appended to the option to additionally output the country name instead of only the country number.
COUNTY [NAME]: Records are printed by county total. This option invokes use of the COSTCY file. NAME can be appended to the option to additionally output the county name instead of only the county number.
DOMCODE: Records are printed by Day of Month profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
ELEVSTAT [STACKGROUP]: Records include the status of sources as elevated (E), plume-in-grid (P), and low-level (L). All elevated
statuses could appear in the same report, depending on the inventory and elevated source selection criteria. STACKGROUP can be appended to the option to additionally output stack group number from PELV. This instruction can be used for point sources only.
FRICODE: Records are printed by Friday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
HOUR: Records are printed by hour total for each day. This option implies the TEMPORAL instruction, so Smkreport automatically adds that instruction even if it was not included in the input.
INTEGRATE: Records are printed by the integration status of sources. “Y” willl appear for the integrated sources that were used to calculate the NONHAP[VOC|TOG] inventory pollutant.
LAYER: For point sources, daily emissions are printed by vertical layer. This option implies the LAYFRAC option (discussed
later) that requires input of the PLAY SMOKE intermediate file. In the report, records are written first for one layer, then the next, and so on. Only records with nonzero emissions in a layer are written. When used to together with the HOUR instruction (above), emissions will be written by hour as well as by layer. Since the
number of records the report when using HOUR instruction is very large, we recommend that a source group be used to subselect
the inventory records when appropriate.
MACT [NAME]: Records are printed by MACT code. NAME can be appended to the option to additionally output the MACT code description
(from the MACTDESC file) instead of only the MACT code.
MATBURNED: For wildfire point sources, records are printed by MATBURNED code.
METCODE: Records are printed by Meteorology-based hourly profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
MONCODE: Records are printed by Mothly profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
MNDCODE: Records are printed by Monday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
NFDRSCODE: For wildfire point sources, records are printed by NFDRSCODE code.
NAICS [NAME]: Records are printed by NAICS code. NAME can be appended to the option to additional output the NAICS code description
(from the NAICSDESC file) instead of only the NAICS code.
ORIS [NAME]: Records are printed by ORIS ID code. NAME can be appended to the option to additional output the ORIS ID code
description (from the ORISDESC file) instead of only the ORIS ID code.
PLANT [NAME]: For point sources, emissions are printed by plant total. This option cannot be used in conjunction with the
BY SOURCE option; if the REPCONFIG file contains both instructions, SMOKE will ignore the BY PLANT instruction.
When the NAME option is included, the plant name will be included in the report. Otherwise, only the plant number will be included.
ROADCLASS: Records are printed by road class total. This option can only be used for mobile sources.
SATCODE: Records are printed by Saturday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
SCC [N] [NAME]: Records are printed and summed by all or part of the SCC, depending on the value of N, which can be set to 1, 2, 3, or 4. These numbers correspond to the SCC levels described in Section 2.3.5, “Source Classification Codes”. When N = 4, the full SCC is used. When N = 1, 2, or 3, the records are summed and reported by the corresponding SCC level. Differences between point and nonpoint/mobile SCCs are handled as described by the SCC structures. If no value is given. N is assumed to be 4 by default.
The NAME option can be used for any N value. The SCC description is truncated assuming that semicolons separate the different parts of the SCC descriptions. If there are more than 3 semicolons in an SCC description (dividing into 4 parts), then all of the SCC sections after part 3 are put into part 4. The SCC description written by Smkreport will match the value of N by including all parts of the SCC description up to and including the value of N.
SCC10 [NAME]: This option maintains backward compatibility with previous versions of Smkreport. It is the same as the option "SCC 4 [NAME]".
SIC [NAME]: Records are printed by SIC totals.
When the “NAME” option is included, the SIC name will be included in the report. Otherwise, only the SIC code will be included. As with the BY SCC10 NAME instruction, the BY SIC NAME instruction will change the column delimiter from a semi-colon to the pipe symbol (“|”). The SIC name will also be enclosed in double quotes.
SOURCE [STACKPARM] [NAME] [LATLON]: Records are printed by source totals. Source characteristics are printed as well:
For area and mobile sources, the SCC descriptions will automatically be included in the report. This is the same as adding the “BY SCC10 NAME” instruction to the report instructions. There is no way to turn off this feature.
For point sources, STACKPARM can be appended to the option to also output the stack parameters (height, diameter, exit velocity, exit temperature). Also for point sources, NAME can be appended to the option to get the facility names in the output file. LATLON can be appended to the option to print each source’s x- and y-coordinates.
SPCCODE <POLLUTANT>: Records are printed by speciation profile codes assigned to sources by the speciation cross-reference
file. Only one pollutant can appear with this command throughout the entire REPCONFIG file. The pollutant should be one that is in the inventory file and that was processed as part of the chemical speciation file
run. This BY option does not imply the SPECIATION instruction (see below), and it can be used without included speciated emissions
in the report. For example, the BY SPCCODE instruction may be used to indicate which speciation profiles were assigned to
total VOC emissions (without reporting speciated VOC emissions). NOTE: this BY SPCCODE option can't be used more than once in a REPCONFIG file.
SRCTYPE: Records are printed by source type code.
SRGCODE [FALLBACK]: Records are printed by surrogate codes assigned to sources by the gridding cross-reference file. If no option is used, both primary and fallback surrogate codes are included in the output report. If the FALLBACK option is used, only the fallback surrogate codes are included in the output report, and a zero is used for all records that did not use a fallback surrogate (i.e., their primary surrogate did not cause emissions to go to zero). This BY option does not imply the GRIDDING instruction (see below); therefore, it can be used without applying the gridding matrix in the report. A value of -9 is used for fallback surrogate IDs in the resulting report.
STATE [NAME]: Records are printed by state totals. This option invokes the use of the COSTCY file. NAME can be appended to the option to additionally output the state name instead of only the state number.
SUNCODE: Records are printed by Sunday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
THUCODE: Records are printed by Thursday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
TUECODE: Records are printed by Tuesday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
WEKCODE: Records are printed by Weekly profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant. Note that this option spelling is not WEEKCODE.
WEDCODE: Records are printed by Wednesday diurnal profile code. This option will work correctly only when monthly temporal profiles have not been applied by pollutant.
The most detailed BY instruction will determine the resolution of the emissions and activity totals. For example, the COUNTRY, STATE, and COUNTY options can be used in the same report to affect the column headers, but the data output will not be different because the emissions totals will be at the finest resolution specified. In other words, if the instructs are to report BY COUNTY and BY STATE, the emission totals in that report will be by county, and the BY STATE instruction will merely add the state code to the columns printed. Another example is that the BY SCC10 instruction will override the resolution of BY ROADCLASS.
Future versions of the BY command may support the following options, if a need for them is identified by SMOKE users:
STACK [NAME]: For point sources only, records are printed as facility and stack totals. NAME can be appended to the option to get the facility names in the output file.
POINT [NAME]: For point sources only, records are printed as facility, stack, and point totals. NAME can be appended to the option to get the facility names in the output file.
VTYPE: For mobile sources only, records are printed as vehicle-type totals.
GROUP <option>: Records are printed based on the user-defined groups, with the following options:
The CONTROL instruction applies the multiplicative control matrix to all pollutants and species requested in the report. This instruction does not limit the options available for resolution of the report, so reports that have the CONTROL instruction can also include any combination of BY instructions. Smkreport is unable to apply the reactivity control matrix at this time.
The GRIDDING instruction controls whether or not the gridding matrix is used by Smkreport. When the instruction is present, the gridding matrix is used in generating the report; the matrix is applied to the emissions before the totals are made. The gridding matrix file name is determined by the environment variables set at run time. One use of the GRIDDING instruction would be the following: a report could be generated without GRIDDING to see emission totals before gridding, and another report could be generated with GRIDDING to see the totals after gridding. The totals from the two reports could be compared to see if any emissions were lost because of the gridding step.
The GRIDDING instruction is assumed when any of the following other instructions appear in the packet:
The LAYFRAC instruction controls whether or not the point source layer fractions file (PLAY) from the Laypoint program is used in determining elevated and low-level sources. If the PLAY file is not used for determining elevated sources, the PELV file from the Elevpoint program will be required.
The NORMALIZE instruction controls whether or not the emission values will be normalized using some other data value. Two normalize options are currently supported; CELLAREA and POPULATION. Emissions normalization can provide additional insight to the inventory, more than can be obtained by simply summarizing emissions values.
The syntax of the NORMALIZE instruction is:
NORMALIZE <option>
with the following valid options:
CELLAREA: Normalize emissions based on grid cell area. When the emissions are normalized by cell area, they are divided by the area of each cell (or just the cells selected, if a subgrid is used). Normalizing by grid cell area is useful for comparing emission reports from grids at different resolutions, including nested grids, to ensure that a consistent emissions density is maintained across the multiple grid resolutions.
For Lambert and UTM grids, the cell ares are computed using the formula:
DX * DY
where
For lat-lon grids, the area of the lat-lon cell are estimated using the formula:
(cos Y)*( π * DX * R / 180 )*( π * DY * R / 180 )
where
The NORMALIZE CELLAREA command cannot be used with polar stereographic grids at this time.
This instruction requires that the GRIDDING instruction also be used, because the gridding information is needed in order to normalize the emissions by grid area. If the GRIDDING instruction is left out of the report instructions, Smkreport will add it to the report and continue.
POPULATION: Normalize emission based on county population. Emissions in the report are divided by county population, regardless of whether the BY COUNTY instruction has been used in the report instructions.
This option requires that the COSTCY input file to Smkreport include an additional field and a #POPULATION header (as is described in the COSTCY documentation in Chapter 8, SMOKE Input Files).
Future versions of the NORMALIZE instruction may support the following option, if a need for this option is identified by SMOKE users:
NORMALIZE COUNTYAREA: Normalize emissions based on county area.
The NUMBER instruction controls the format used to display data values in the report. The argument for the number instruction applies to all data values that are written to the report, and the structure of the argument is simply the formats supported by Fortran. The data values in the reports are rounded to the nearest value allowed based on the format selected. A value of 5 is rounded up to the next decimal place, when such rounded is needed.
The syntax of the NUMBER instruction is simply:
NUMBER <format>
where <format> is the Fortran format specification. The common formats you might use are the following:
Float format: F<x>.<y>: where <x> is the number of digits for the number, including the decimal place, and <y> is the number of digits shown after the decimal place.
Exponential format: E<x>.<y>: where <x> is the complete width of the value, including five characters for “E+00” and the decimal, and <y> is the number of significant figures.
If the NUMBER instruction does not appear in the report instructions, the E8.3 format is used.
The PROJECTION instruction will apply the growth matrix to all pollutants and species requested in the report. This instruction does not limit the options available for resolution of the report, so reports that have the PROJECTION instruction can also include any combination of BY instructions.
The SELECT instruction controls which records in the inventory are used in generating the report. It allows the user to extract
particular records from the inventory, for inclusion in the report. This instruction also permits references to the groups
defined in the Define-groups section of the REPCONFIG file. If no SELECT instruction is used, then the other report instructions will be applied to all records in the inventory.
Only one SELECT statement of each type is permitted in per report; for example, only one SELECT REGION statement and one SELECT
SUBGRID statement could be used for a single report. Of course, different SELECT REGION or SELECT SUBGRID instructions could
be used for different reports in the same output file.
The syntax of the command is:
SELECT <options> <label>
where <label> is an optional field, depending on the <option> selected. The following options are available for the SELECT instruction:
DATA <label>: Selects data values to include in the report. When no SELECT DATA instruction is used, all pollutants, activities, or species found in the input file(s) are reported. When species are being reported, the corresponding pollutants in the inventory or hourly emissions file are reported as well as the speciated emission values. The <label> must be a space-delimited list of pollutant, activity, or species names. Do not include the pollutant names in the list when species are listed, as these will be included by default.
To specify a species value when the species name is the same as the pollutant name, an “S” and a hyphen can be inserted before the species name. You can also use this method for specifying the sum of post-speciated emissions. For instance, to specify carbon monoxide after speciation, the SELECT instruction should be:
SELECT DATA S-CO
To specify the sum of VOC emissions after speciation, the SELECT instruction should be:
SELECT DATA S-VOC
Note that Smkreport does not determine whether the summation makes sense, and does not correct for species molecular weights. You must ensure that the data you request makes sense.
Also note that the maximum number of characters that can be read on any line in this file is 1024. This can limit the number of pollutants that you can specifically request in a SELECT DATA statement.
ELEVATED [PING]: Selects all elevated point sources (recognized for point sources only). If no elevated sources are found
(after applying all other selection criteria), the report will contain a warning to that effect. If the PING option appears,
only plume-in-grid sources will be selected. When the ELEVATED instruction is used by any report, the PELV file (from Elevpoint) or PLAY file (from Laypoint) will be required to determine which sources are elevated. The latter will be used when the LAYFRAC instruction is also included
in the report instructions. If the PING option is used, the PELV file will be required in all cases, although the LAYFRAC instruction can still be used to set the elevated source status
based on the layer fractions.
NOELEVATED: Selects all low-level point sources (recognized for point sources only). If both the ELEVATED and NOELEVATED commands
appear in the same report, a warning will be given, and the latter setting will be used to generate the report. If no low-level
sources are found (after applying all other selection criteria), the report will contain a warning to this effect. The same
rules apply for use of the PELV or PLAY files as described for the ELEVATED option.
REGION <label>: Selects a region using the country/state/county code or a region group. For this option, <label> must be either
a country/state/county code in NSSCCC format, or a region group label from the Define-group section of the REPCONFIG file.
SUBGRID <label>: Selects a subgrid using the grid cell numbers or a subgrid group label. For this option, <label> must be either a range of grid cells, or a subgrid label from the Define-group Section of the file. When the <label> defines the cell range, you should use the same syntax that was specified above for the /DEFINE SUBGRID/ packet. However, the INCLUDE setting is assumed, and Smkreport will not understand the INCLUDE and EXCLUDE commands as part of the <label>.
For the REGION and SUBGRID options, the value of <label> must either match a group or subgrid label or match characteristics of the inventory or grid. Also, the <label> for the REGION and SUBGRID options must be 200 characters or fewer.
Future versions of Smkreport may support the following additional options, if a need is identified:
SCC <label>: Select a single SCC or SCC group for reporting.
PLANT <label>: Select a single point source plant, or a plant group for reporting.
STACK <label>: Select a single point source stack, or a stack group for reporting.
POINT <label>: Select a single point source point, or a point group for reporting.
HOURS <label>: Select a single hour or hour group for reporting.
SOURCE <label>: Select a single source or source group for reporting.
The SPECIATION instruction controls whether the speciation matrix is used by the program. This option controls the columns of data that will be printed in the output file. When the SPECIATION instruction is in the report instructions, the columns in the output file will include speciated emissions values as well as inventory emissions from the SMOKE inventory or hourly emissions file (depending on whether or not the TEMPORAL instruction is used). When the SPECIATION instruction is not used, the columns in the output file will be inventory emissions and/or activities.
The syntax of the SPECIATION instruction is:
SPECIATION <option>
where the following options are supported
MOLE: Uses the mole-based speciation matrix.
MASS: Uses the mass-based speciation matrix.
The TEMPORAL instruction controls whether or not emission values are used from the hourly emission files ATMP, MTMP, or PTMP. When this instruction is used, the default behavior of Smkreport is to sum up the emissions by day and report emissions as daily totals. To override this behavior, the BY HOUR instruction
must be used.
When dates and times are given in the report, the hours are reported in the time zone from the ATMP, MTMP, or PTMP file. Hours are reported as standard time values for the time zone stored in the header of the hourly emissions file; hours are never reported as daylight time values.
The TEMPORAL instruction is assumed when either of the following options appear in the report instructions:
In the future, we may be able to enhance this instruction to permit the reported hour values to be labeled with a different time zone than is in the hourly emissions file.
The TITLE instruction allows one or more titles to be added to a report. The titles are printed into the report in the order in which they appear in the packet. Quotes are not needed in titles with blank spaces. The title will be ended at the last character on the line, or at a double pound sign (##), whichever appears first on the line. Double pound signs cannot be printed in the titles of reports. It is recommended that titles be 80 characters wide. The maximum title width is 300 characters. The syntax of the TITLE instruction is the following:
TITLE <title text>
The UNITS instruction allows you to control the units of the output data. The current version of Smkreport does not permit you to vary the units by data value; instead, the same units must be used for all data values, or the default units will be used. Future versions of Smkreport may permit control of the units by data variable.
All unit conversions that can be done, will be done. For example, if the inventory is stored in tons/hour, and the output is requested in fathoms/day, the hour-to-day conversion will be made, while the impossible tons-to-fathoms conversion will not be made. The syntax of the UNITS instruction is the following:
UNITS ALL <units>
Valid values for the <units> option numerator are the following:
Valid values for the <units> option denominator are the following:
No quotes are needed around the unit labels, and they must be 30 characters or fewer. Some examples of the units instruction are the following:
UNITS ALL gm moles/s UNITS ALL tons/hr UNITS ALL kg/year