1. Spatial Allocator Raster Tools

The Spatial Allocator (SA) Raster Tools contain programs for processing land use data, satellite data, and agricultural fertilizer application data for meteorological and air quality modeling, particularly within the Weather Research and Forecasting (WRF) and Community Multiscale Air Quality (CMAQ) modeling systems.

Users who have difficulties running the tools with the compiled libraries contained within the downloaded system should do the following:

1) delete installed open-source library directories under the ./src/libs directory

2) download new source packages and install them under the ./libs directory

3) compile downloaded packages and install them under {package_path}/local, following the src/libs/README file

4) modify paths in ./bin/sa_setup.csh and ./src/raster/Makefile

5) in ./src/raster, do the following:

· make clean

· make

· make install

All sample script files for the SA Raster Tools are stored in the raster_scripts directory.

The SA Raster Tools are described in detail in the following sections of this document:

Section 2: Domain Description in SA Raster Tools
Section 3: Land Cover Data Processing Tools
Section 4: Satellite Cloud and Aerosol Product Processing Tools
Section 5: Agricultural Fertilizer Modeling Tools
Section 6: Other Tools and Utilities

2. Domain Description in SA Raster Tools

The SA Raster Tools define the modeling domain using the following environment variables:

· GRID_PROJ – defines the domain grid projection using the PROJ4 projection description format (http://www.remotesensing.org/geotiff/proj_list/). The following sample projection descriptions are used to match the projections in WRF:

§ Lambert Conformal Conic: "+proj=lcc +a=6370000.0 +b=6370000.0 +lat_1=33 +lat_2=45 +lat_0=40 +lon_0=-97"

§ Polar stereographic: "+proj=stere +a=6370000.0 +b=6370000.0 +lat_ts=33 +lat_0=90 +lon_0=-97 +k_0=1.0"

§ Mercator: "+proj=merc +a=6370000.0 +b=6370000.0 +lat_ts=33 +lon_0=0"

§ Geographic: "+proj=latlong +a=6370000.0 +b=6370000.0"

· GRID_ROWS – number of the rows of domain grid cells

· GRID_COLUMNS – number of the columns of domain grid cells

· GRID_XCELLSIZE – grid cell size in x direction

· GRID_YCELLSIZE – grid cell size in y direction

· GRID_XMIN – minimum x of the domain (lower left corner of the domain)

· GRID_YMIN – minimum y of the domain (lower left corner of the domain)

· GRID_NAME – Name of the domain, which is required by some of the tools

For WRF simulations, GRID_XMIN and GRID_YMIN can be computed using the first point longitude and latitude from the global attributes corner_lons and corner_lats in the domain’s WRF geogrid output file. For instance, to compute a WRF LCC domain with the geogrid output file attributes

:corner_lats = 20.85681f, 52.1644f, 50.63151f, 19.88695f, 20.84302f...

:corner_lons = -121.4918f, -135.7477f, -53.21942f, -69.02478f, -121.5451f…

users would use the cs2cs utility in the PROJ4 library directly at the command line (after installing the SA system):

>cs2cs +proj=latlong +a=6370000.0 +b=6370000.0 +to +proj=lcc +a=6370000.0 +b=6370000.0 +lat_1=33 +lat_2=45 +lat_0=40 +lon_0=-97

-121.4918 20.85681

-2622003.85 -1793999.28 0.00

Minimum x and y for the domain would be computed as follows:

GRID_XMIN = -2622003.85 - GRID_XCELLSIZE / 2

GRID_YMIN = -1793999.28 - GRID_YCELLSIZE / 2

3. Land Cover Data Processing Tools

There are two land cover processing tools in the SA Raster Tools: NLCD and MODIS land cover generation tool (Section 3.1), and Biogenic Emissions Landuse Database, version 4 (BELD4) land cover generation tool (Section 3.2).

3.1 NLCD and MODIS Land Cover Generation

The computeGridLandUse.exe tool is used to generate land cover data for the recently upgraded WRF/CMAQ Pleim-Xiu Land Surface Model (PX LSM), by directly using downloaded 2001 V2 or 2006 NLCD land cover data and the NASA MODIS land cover products MCD12Q1 or MOD12Q1. This tool generates 40 land cover classes (20 from MODIS and 20 from NLCD) instead of the 50 classes generated by the previous land cover processing tool.

This tool requires the following data sets:

NLCD land cover, canopy, and imperviousness data – can be obtained from http://www.mrlc.gov/nlcd2006.php.
MODIS land cover data sets – can be obtained from http://ladsweb.nascom.nasa.gov/ data/search.html. The tool can process MCD12Q1 data at 500 m from Combined Terra and Aqua MODIS, or can process MOD12Q1 data at 1 km from Terra MODIS.
List of land cover data sets to be processed – a sample file for CMAQ 12-km domain 2006 modeling, nlcd_modis_files_2006.txt, is provided in the data directory. This file has to have fixed header formats.

To run the computeGridLandUse tool, users can use the following sample script file, which has all of the required environment variables:

NLCD_MODIS_processor.csh

There are two output files generated from the NLCD/MODIS processing tool—one ASCII file and one netCDF file:

· The ASCII file contains the imperviousness, canopy, and land cover percent variables (if the user set all land cover data to “YES” when running the script file) for each grid cell, in comma-separated-values (CSV) format.

· The netCDF file contains imperviousness, canopy, and land cover fraction variables plus land/water mask and other variables that are similar to those in the WRF GEOGRID land cover output files. The land cover percent variable contains the 40 classes in Table 1.

Table 1. NLCD/MODIS output land cover classes from the computeGridLandUse tool

Array Index	MODIS Class IGBP (Type 1)	Class Name	Array Index	NLCD Class	Class Name
1	1	Evergreen Needleleaf forest	21	11	Open Water
2	2	Evergreen Broadleaf forest	22	12	Perennial Ice/Snow
3	3	Deciduous Needleleaf forest	23	21	Developed - Open Space
4	4	Deciduous Broadleaf forest	24	22	Developed - Low Intensity
5	5	Mixed forest	25	23	Developed - Medium Intensity
6	6	Closed shrublands	26	24	Developed High Intensity
7	7	Open shrublands	27	31	Barren Land (Rock/Sand/Clay)
8	8	Woody savannas	28	41	Deciduous Forest
9	9	Savannas	29	42	Evergreen Forest
10	10	Grasslands	30	43	Mixed Forest
11	11	Permanent wetlands	31	51	Dwarf Scrub
12	12	Croplands	32	52	Shrub/Scrub
13	13	Urban and built-up	33	71	Grassland/Herbaceous
14	14	Cropland/Natural vegetation mosaic	34	72	Sedge/Herbaceous
15	15	Snow and ice	35	73	Lichens
16	16	Barren or sparsely vegetated	36	74	Moss
17	0	Water	37	81	Pasture/Hay
18	18	Reserved (e.g., Unclassified)	38	82	Cultivated Crops
19	19	Reserved (e.g., Fill Value )	39	90	Woody Wetlands
20	20	Reserved	40	95	Emergent Herbaceous Wetlands

3.2 BELD4 Land Cover Generation

The BELD4 data with tree and crop percentages can be computed by using the computeGridLULC.exe tool with preprocessed USGS NLCD data sets, one MODIS land cover data set, and tree and crop fractions at the county level. The following sample script files contain all of the required environment variables for using the tool:

generateBELD4_cmaq12km_2001.csh and generateBELD4_cmaq12km_2006.csh

This tool requires the following data sets:

· Preprocessed USGS and C-GAP NLCD data sets including land cover, imperviousness, and canopy – can be obtained from the CMAS Center.

· Processed NA MODIS data set – can be obtained from the CMAS Center.

· List of land cover data sets to be processed – these are provided in the data directory: nlcd2001_files_v2_pp.txt for the 2001 NLCD V2, and nlcd2006_files_pp.txt for the 2006 NLCD. The files have to have the fixed format with the data set headers included.

· BELD3 FIA tree fraction table at county level – provided in the data directory: beld3-fia.dat.

· NASS crop fraction tables at county level – provided in the data directory: nass2001_beld4_ag.dat for the 2001 NASS and nass2006_beld4_ag.dat for the 2006 NASS.

· Canada crop fraction table at census-division level – provided in the data directory: can01_beld4_ag.dat for the 2001Census of Agriculture and can06_beld4_ag.dat for the 2006 Census of Agriculture.

· List of land cover, tree, and crop classes for the BELD4 tool – provided in the data directory: beld4_class_names_2001_50classes.txt and beld4_class_names_2006_50classes.txt.

· U.S. county shapefile – provided in the data directory: county_pophu02_48st.shp.

· Canada census-division shapefiles – provided in the data directory: can01_cd_sel.shp for the 2001 Census and can06_cd_sel.shp for the 2006 Census.

Two output files are generated from the tool—one ASCII file and one netCDF file:

The ASCII file contains the imperviousness, canopy, and land cover fraction variables (if the user set all land cover data to “YES” when running the script file) for each grid cell, in CSV format.
The netCDF file contains imperviousness, canopy, land cover, tree, and crop percentage variables as well as land/water mask and other variables that are similar to those in the WRF GEOGRID land cover output files.

The land cover data generated by applying this tool is used in CMAQ bidirectional ammonia flux modeling and can be used in CMAQ biogenic, land surface, and dry deposition modeling. The land cover percent array in the output contains 30 land cover classes from the NLCD and 20 MODIS IGBP land cover classes (Table 2). In the output NLCD land cover table, the class numbers consist of the original NLCD class numbers with a “1” prepended to them. In the output MODIS land use table, the class numbers consist of the original MODIS class numbers with a “2” prepended to them.

Table 2. NLCD/MODIS output land cover classes from the computeGridLULC tool

NLCD				MODIS
Array Index	Output ClassID	NLCD Class	Class Name	Array Index	Output ClassID	MODIS Class IGBP	MODIS Class Name
1	111	11	Open Water	31	20	0	Water
2	112	12	Perennial Ice/Snow	32	21	1	Evergreen Needleleaf Forest
3	121	21	Developed Open Space	33	22	2	Evergreen Broadleaf Forest
4	122	22	Developed Low Intensity	34	23	3	Deciduous Needleleaf Forest
5	123	23	Developed Medium Intensity	35	24	4	Deciduous Broadleaf Forest
6	124	24	Developed High Intensity	36	25	5	Mixed Forests
7	131	31	Barren Land (Rock/Sand/Clay)	37	26	6	Closed Shrublands
8	132	32	Unconsolidated Shore	38	27	7	Open Shrublands
9	141	41	Deciduous Forest	39	28	8	Woody Savannas
10	142	42	Evergreen Forest	40	29	9	Savannas
11	143	43	Mixed Forest	41	210	10	Grasslands
12	151	51	Dwarf Scrub	42	211	11	Permanent Wetlands
13	152	52	Shrub/Scrub	43	212	12	Croplands
14	171	71	Grassland/Herbaceous	44	213	13	Urban and Built Up
15	172	72	Sedge/Herbaceous	45	214	14	Cropland/Natural Vegetation Mosaic
16	173	73	Lichens	46	215	15	Permanent Snow and Ice
17	174	74	Moss	47	216	16	Barren or Sparsely Vegetated
18	175	75	Tundra	48	217	17	IGBP Water
19	181	81	Pasture/Hay	49	2254	254	Unclassified
20	182	82	Cultivated Crops	50	2255	255	Fill Value (normally ocean water)
21	190	90	Woody Wetlands
22	191	91	Palustrine Forested Wetland
23	192	92	Palustrine Scrub/Shrub Wetland
24	193	93	Estuarine Forested Wetland
25	194	94	Estuarine Scrub/Shrub Wetland
26	195	95	Emergent Herbaceous Wetlands
27	196	96	Palustrine Emergent Wetland
28	197	97	Estuarine Emergent Wetland
29	198	98	Palustrine Aquatic Bed
30	199	99	Estuarine Aquatic Bed

The tree percentage variable in the netCDF output file contains 194 BELD4 tree classes (Table 3). The crop percentage variable contains 42 crops for 2001 BELD4 (Table 4) and and 42 crops for 2006 BELD4 (Table 5).

Table 3. BELD4 tree classes

Index	Variable	Index	Variable	Index	Variable	Index	Variable	Index	Variable
1	Acacia	40	Hackberry	79	Oak_bur	118	Paulownia	157	Pine_whitebark
2	Ailanthus	41	Hawthorn	80	Oak_CA_black	119	Pawpaw	158	Pine_Wwhite
3	Alder	42	Hemlock	81	Oak_CA_live	120	Persimmon	159	Pine_yellow
4	Apple	43	Hickory	82	Oak_CA_white	121	Pine_Apache	160	Populus
5	Ash	44	Holly_American	83	Oak_canyon_live	122	Pine_Austrian	161	Prunus
6	Basswood	45	Hornbeam	84	Oak_chestnut	123	Pine_AZ	162	Redbay
7	Beech	46	Incense_cedar	85	Oak_chinkapin	124	Pine_Bishop	163	Robinia_locust
8	Birch	47	Juniper	86	Oak_delta_post	125	Pine_blackjack	164	Sassafras
9	Bumelia_gum	48	KY_coffeetree	87	Oak_Durand	126	Pine_brstlcone	165	Sequoia
10	Cajeput	49	Larch	88	Oak_Emery	127	Pine_chihuahua	166	Serviceberry
11	Califor-laurel	50	Loblolly_bay	89	Oak_Engelmann	128	Pine_Coulter	167	Silverbell
12	Cascara-buckthor	51	Madrone	90	Oak_evergreen_sp	129	Pine_digger	168	Smoketree
13	Castanea	52	Magnolia	91	Oak_Gambel	130	Pine_Ewhite	169	Soapberry_westrn
14	Catalpa	53	Mahogany	92	Oak_interio_live	131	Pine_foxtail	170	Sourwood
15	Cedar_chamaecyp	54	Maple_bigleaf	93	Oak_laurel	132	Pine_jack	171	Sparkleberry
16	Cedar_thuja	55	Maple_bigtooth	94	Oak_live	133	Pine_Jeffrey	172	Spruce_black
17	Chestnut_buckeye	56	Maple_black	95	Oak_Mexicanblue	134	Pine_knobcone	173	Spruce_blue
18	Chinaberry	57	Maple_boxelder	96	Oak_Northrn_pin	135	Pine_limber	174	Spruce_Brewer
19	Cypress_cupress	58	Maple_FL	97	Oak_Northrn_red	136	Pine_loblolly	175	Spruce_Englemann
20	Cypress_taxodium	59	Maple_mtn	98	Oak_nuttall	137	Pine_lodgepole	176	Spruce_Norway
21	Dogwood	60	Maple_Norway	99	Oak_OR_white	138	Pine_longleaf	177	Spruce_red
22	Douglas_fir	61	Maple_red	100	Oak_overcup	139	Pine_Monterey	178	Spruce_Sitka
23	East_hophornbean	62	Maple_RkyMtn	101	Oak_pin	140	Pine_pinyon	179	Spruce_spp
24	Elder	63	Maple_silver	102	Oak_post	141	Pine_pinyon_brdr	180	Spruce_white
25	Elm	64	Maple_spp	103	Oak_scarlet	142	Pine_pinyon_cmn	181	Sweetgum
26	Eucalyptus	65	Maple_striped	104	Oak_scrub	143	Pine_pitch	182	Sycamore
27	Fir_balsam	66	Maple_sugar	105	Oak_shingle	144	Pine_pond	183	Tallowtree-chins
28	Fir_CA_red	67	Mesquite	106	Oak_Shumrd_red	145	Pine_ponderosa	184	Tamarix
29	Fir_corkbark	68	Misc-hardwoods	107	Oak_silverleaf	146	Pine_red	185	Tanoak
30	Fir_fraser	69	Mixed_conifer_sp	108	Oak_Southrn_red	147	Pine_sand	186	Torreya
31	Fir_grand	70	Mountain_ash	109	Oak_spp	148	Pine_scotch	187	Tung-oil-tree
32	Fir_noble	71	Mulberry	110	Oak_swamp_cnut	149	Pine_shortleaf	188	Unknown_tree
33	Fir_Pacf_silver	72	Nyssa	111	Oak_swamp_red	150	Pine_slash	189	Walnut
34	Fir_SantaLucia	73	Oak_AZ_white	112	Oak_swamp_white	151	Pine_spruce	190	Water-elm
35	Fir_Shasta_red	74	Oak_bear	113	Oak_turkey	152	Pine_sugar	191	Willow
36	Fir_spp	75	Oak_black	114	Oak_water	153	Pine_Swwhite	192	Yellow_poplar
37	Fir_subalpine	76	Oak_blackjack	115	Oak_white	154	Pine_tablemtn	193	Yellowwood
38	Fir_white	77	Oak_blue	116	Oak_willow	155	Pine_VA	194	Yucca_Mojave
39	Gleditsia_locust	78	Oak_bluejack	117	Osage-orange	156	Pine_Washoe

Table 4. BELD4 2001 crop classes

Index	Variable	Index	Variable	Index	Variable
1	Hay	15	Cotton	29	SorghumSilage
2	Hay_ir	16	Cotton_ir	30	SorghumSilage_ir
3	Alfalfa	17	Oats	31	Soybeans
4	Alfalfa_ir	18	Oats_ir	32	Soybeans_ir
5	Other_Grass	19	Peanuts	33	Wheat_Spring
6	Other_Grass_ir	20	Peanuts_ir	34	Wheat_Spring_ir
7	Barley	21	Potatoes	35	Wheat_Winter
8	Barley_ir	22	Potatoes_ir	36	Wheat_Winter_ir
9	BeansEdible	23	Rice	37	Other_Crop
10	BeansEdible_ir	24	Rice_ir	38	Other_Crop_ir
11	CornGrain	25	Rye	39	Canola
12	CornGrain_ir	26	Rye_ir	40	Canola_ir
13	CornSilage	27	SorghumGrain	41	Beans
14	CornSilage_ir	28	SorghumGrain_ir	42	Beans_ir

Table 5. BELD4 2006 crop classes

Index	Variable	Index	Variable	Index	Variable
1	Hay	15	Cotton	29	SorghumSilage
2	Hay_ir	16	Cotton_ir	30	SorghumSilage_ir
3	Alfalfa	17	Oats	31	Soybeans
4	Alfalfa_ir	18	Oats_ir	32	Soybeans_ir
5	Other_Grass	19	Peanuts	33	Wheat_Spring
6	Other_Grass_ir	20	Peanuts_ir	34	Wheat_Spring_ir
7	Barley	21	Potatoes	35	Wheat_Winter
8	Barley_ir	22	Potatoes_ir	36	Wheat_Winter_ir
9	BeansEdible	23	Rice	37	Canola
10	BeansEdible_ir	24	Rice_ir	38	Canola_ir
11	CornGrain	25	Rye	39	Beans
12	CornGrain_ir	26	Rye_ir	40	Beans_ir
13	CornSilage	27	SorghumGrain	41	Other_Crop
14	CornSilage_ir	28	SorghumGrain_ir	42	Other_Crop_ir

Information on NLCD data sets used by the tool can be obtained from:

USGS NLCD: http://www.mrlc.gov/nlcd2001.php

NOAA C-GAP NLCD: http://www.csc.noaa.gov/digitalcoast/data/ccapregional/faq

Users can follow the sample script file, preProcessLanduseImages.csh, to preprocess the downloaded NLCD data for the tool. As noted earlier, the processed NLCD and NA MODIS data set can be obtained from the CMAS Center.

3.3 Current and Future Development for the Land Cover Data Processing Tools

We are working on combing the two land cover processing tools discussed above so that they can generate one set of land cover and land use data suitable for use in WRF, CMAQ, and SMOKE modeling, allowing the entire air quality modeling system to have one consistent land use data set. In addition, in the future we plan to use USDA’s NLCD Cropland Data Layer (CDL) data instead of NASS crop fractions at the county level for the BELD4 data tool. Thus, we can use USDA crop coverage NLCD data instead of crop census data at the county level to estimate crop spatial distribution.

4. Satellite Cloud and Aerosol Product Processing Tools

4.1 GOES Cloud Product Processing Tool

The GOES data tool processes the GOES data downloaded from the Earth System Science Center (ESSC) at the University of Alabama in Huntsville. The GOES data web site is http://satdas.nsstc.nasa.gov/.

Downloaded GOES data need to be stored under subdirectories named using this format: gp_YYYYMMDD. The ./util/goes_untar.pl utility can be used to unzip downloaded GOES data (daily tar files) into the daily directories required by the tool.

Users can follow the sample script file with all required environment variables:

allocateGOES2WRFGrids.csh

The current tool contains the following three programs:

· correctGOESHeader.exe – to correct GOES data position shifting by redefining a new Earth radius and new image extent. The program converts GOES data in Grib (i.e., *.grb) format to files in ERDAS Imagine (i.e., *.img) format with corrections.

· computeGridGOES.exe – to regrid corrected Imagine-format GOES data to a defined grid domain.

· toDataAssimilationFMT.exe – to convert the gridded netCDF file into a format suitable for WRF assimilation.

We plan to update the tool when new GOES data spatial specifications become available.

Notes: When running the GOES cloud product processing tool, GDAL will generate the following messages:

· Warning: Inside GRIB2Inventory, Message # 2

· ERROR: Ran out of file reading SECT0

These messages do not indicate any errors in regridding and so can be ignored.

4.2 MODIS Level 2 Cloud/Aerosol Products Tool

The MODIS Level 2 (swath) cloud and aerosol products tool processes MODIS L2 cloud or aerosol products for a defined grid domain. MODIS data in HDF4 format can be downloaded from the NASA LAADS web site: http://ladsweb.nascom.nasa.gov/data/search.html.

Cloud product variables contain 5-km and 1-km data. To use this regridding tool, users have to download the following cloud data and Level 1 Geolocation 1-km data into the input directory:

· MOD06_L2 and MOD03 (Level 1 Geolocation 1-km ) for Terra, or

· MYD06_L2 and MYD03 (Level 1 Geolocation 1-km ) for Aqua

The following download options can be selected during the downloading process:

MODIS Cloud:

· Select Level 2 products and select L2 Cloud products

· Select time: “your download time period”

· Collection 5

· Select Latitude/Longitude with area longitude and latitude extent

· Coverage options: select day, night, and both (all)

· Select all other defaults and click search

· Display all files

· Download all files into one directory

MODIS Geolocation 1-km:

· Select Level 1 products and select 03 Geolocation - 1km

· Select time: “same as cloud products”

· Collection 5

· Select Latitude/Longitude with the above geographic extent

· Coverage options: select day, night, and both (all)

· Display all files

· Download all files into the MODIS Cloud file directory

MODIS aerosol products contain variable data at 10-km resolution (nadir). Users have to download MOD04 for Terra or MYD04 for Aqua into the input data directory. The following download options can be selected when downloading Terra aerosol products:

· Select Terra MODIS

· MODIS Aerosol products

· Select Level 2 products and select L2 aerosol product

· Select time: “your download time period”

· Collection 5

· Select Latitude/Longitude with area longitude and latitude extent

· Coverage options: select day, night, and both (all)

· Select all other defaults and click search

· Display all files

· Download all files into one directory

Downloading Aqua aerosol products has the similar options. The tool generates one netCDF file for the defined domain.

Users can modify the following sample script file provided for regridding:

allocateMODISL2CloudVars2Grids.csh

4.3 OMI Level 2 Product Tool

The OMI Level 2 products (swath) tool is used to regrid OMI L2 aerosol and NO₂ products for a defined grid domain. The input data can be downloaded from the NASA mirador site: http://mirador.gsfc.nasa.gov/cgi-bin/mirador/presentNavigation.pl?tree=project&project=OMI

The downloaded data are in HDF5 format and should be stored in one directory, which is defined in the following sample script file:

allocateOMIL2vars2Grids.csh

4.4 OMI L2G and L3 Product Tools

The OMI L2G and L3 product tools process the following OMI products:

· OMI L3 aerosol products (OMAEROe) in HDF4

· OMI NO2 L2G products (OMNO2G) in HDF4

· OMI NO2 L3 products (NO2TropCS30) in HDF5

The data can be downloaded from the NASA Giovanni web site: http://gdata1.sci.gsfc.nasa.gov/daac-bin/G3/gui.cgi?instance_id=omi

OMI product information can be viewed from http://disc.sci.gsfc.nasa.gov/giovanni/additional/ users-manual/G3_manual_Chapter_10_OMIL2G.shtml#what_l2g and from ftp://aurapar2u.ecs .nasa.gov/data/s4pa//Aura_OMI_Level2/OMAERUV.003/doc/README.OMI_DUG.pdf

The following sample script can be modified for regridding:

allocateOMIvar2Grids.csh

5. Agricultural Fertilizer Modeling Tools

Four tools have been developed for use when performing Environmental Policy Integrated Climate (EPIC) modeling; these tools generate gridded agricultural fertilizer data to be used in CMAQ bidirectional ammonia flux modeling. The four tools can be called from the Fertilizer Emission Scenario Tool for CMAQ (FEST-C) Interface (to be released later in 2013) based on user input information, they can be run by script files with defined environment variables at the command line. These tools, discussed in Sections 5.1 through 5.4, are the EPIC site information generation tool, the MCIP/CMAQ-to-EPIC tool, the EPIC-to-CMAQ tool, and the EPIC yearly extraction tool.

5.1 EPIC Site Information Generation Tool

This tool generates two CSV data files that are needed to create EPIC site databases for a user-defined domain:

· EPICSites_Info.csv – contains GRIDID, XLONG, YLAT, ELEVATION, SLOPE_P, HUC8, REG10, STFIPS, CNTYFIPS, GRASS, CROPS, CROP_P, COUNTRY, and COUNTRY-PROVINCE items.

· EPICSites_Crop.csv – contains GRIDID, 42 crop acreages, COUNTRY, and HUC8 items.

The tool processes the following input spatial data files modified specifically for the tool:

· BELD4 file for the domain (beld4_cmaq12km_2006.nc)

· U.S. county shapefiles (co99_d00_conus_cmaq_epic.shp)

· North American State political boundary shapefile (na_bnd_camq_epic.shp)

· U.S. 8-digit HUC shapefile (conus_hucs_8_cmaq.shp)

· Elevation image file (na_dem_epic.img)

· Slope image file (na_slope_epic.img)

Those processed spatial data sets can be obtained from the CMAS. Users can follow the sample script file with all required environment variables to run the tool from the command line window:

generateEPICSiteData.csh

5.2 MCIP/CMAQ-to-EPIC Tool

This tool generates EPIC daily weather and nitrogen deposition data files from MCIP meteorology and CMAQ nitrogen deposition files for EPIC modeling sites. The input MCIP and CMAQ data are stored in two directories defined by the environment variables DATA_DIR and DATA_DIR_CMAQ.

MCIP output files have to be named as METCRO2D*{date} (e.g., METCRO2D_020725). The date format can be in one of the following formats:

YYYYMMDD or YYMMDD or YYYYDDD or YYDDD

CMAQ dry and wet deposition files have to be named as *DRYDEP*{date} and *WETDEP*{date} (e.g., CCTM_N4a_06emisv2soa_12km_wrf.DRYDEP.20020630 and CCTM_N4a_06emisv2soa_12km_wrf.WETDEP1.20020630). The date can be in any of the formats listed above.

Deposition for EPIC modeling can take the following three inputs:

1) CMAQ dry and wet deposition file directory

2) Zero – assume zero nitrogen deposition

3) Default – assume nitrogen mix ratio of 0.8 ppm for wet default deposition computation

The input site location file defined by the environment variable EPIC_SITE_FILE has to be a comma-separated file, with the first three items being site ID, longitude, and latitude.

The tool generates three outputs:

· dailyWETH directory containing EPIC daily weather and nitrogen deposition files named as “grid ID”.dly (e.g., 96.dly). The daily file contains the 14 variables listed in Table 6.

· netCDF file with daily weather and nitrogen deposition data for all EPIC sites.

· EPICW2YR.2YR, to be used in EPIC modeling.

Table 6. EPIC daily weather and nitrogen deposition variables

Index	Variable	Index	Variable
1	Year	8	Daily Average Relative Humidity
2	Month	9	Daily Average 10m Windspeed (m s^-1)
3	Day	10	Daily Total Wet Oxidized N (g/ha)
4	Daily Total Radiation (MJ m^02)	11	Daily Total Wet Reduced N (g/ha)
5	Daily Maximum 2m Temperature (C)	12	Daily Total Dry Oxidized N (g/ha)
6	Daily minimum 2m temperature (C)	13	Daily Total Dry Reduced N (g/ha)
7	Daily Total Precipitation (mm)	14	Daily Total Wet Organic N (g/ha)

Users can follow the sample script file with required environment variables to run the tool from the command line window:

generateEPICsiteDailyWeatherNdep.csh

5.3 EPIC-to-CMAQ Tool

This tool processes merged daily output from EPIC simulations for the 42 crops defined for the BELD4 tool output. It generates two types of outputs in netCDF format for CMAQ bidirectional ammonia modeling:

· soil output file

· EPIC daily output files

The 13 variables contained in the soil output file are listed in Table 7.

Table 7. EPIC for CMAQ soil output variables

Index	Soil Variable	Index	Soil Variable
1	Soil Number (none)	8	Layer2 Bulk Density (t/m**3)
2	Layer1 Bulk Density (t/m**3)	9	Layer2 Wilting Point (m/m)
3	Layer1 Wilting Point(m/m)	10	Layer2 Field Capacity (m/m)
4	Layer1 Field Capacity (m/m)	11	Layer2 Porosity (%)
5	Layer1 Porosity (%)	12	Layer2 PH (none)
6	Layer1 PH (none)	13	Layer2 Cation Ex (cmol/kg)
7	Layer1 Cation Ex (cmol/kg )

EPIC daily output files for CMAQ contain the 49 variables listed in Table 8.

Table 8. EPIC for CMAQ daily output variables

Index	Variable	Index	Variable
1	N Loss in Surface Runoff (kg/ha)	26	Layer1 Carbon (kg/ha)
2	N in Subsurface Flow (kg/ha)	27	Layer1 N in NO3 (kg/ha)
3	N Loss in Percolate (kg/ha)	28	Layer2 Depth (m)
4	Denitrification (kg/ha)	29	Layer2 Bulk Density (t/m**3)
5	Denitrification_N2 (kg/ha)	30	Layer2 Nitrate (kg/ha)
6	N Volatilization (kg/ha)	31	Layer2 Ammonia (kg/ha)
7	OC Change by Soil Respiration (kg/ha)	32	Layer2 Organic N (kg/ha)
8	N Fixation (kg/ha)	33	Layer2 Mineral P (kg/ha)
9	Fertilizer App. Rate (kg/ha)	34	Layer2 Organic P (kg/ha)
10	Fertilizer App. Depth (m)	35	Layer2 Carbon (kg/ha)
11	Mineral N (kg/ha)	36	Layer2 N in NO3 (kg/ha)
12	Ammonia (kg/ha)	37	Layert Depth (m)
13	Organic N (kg/ha)	38	Layert Bulk Density (t/m**3)
14	Mineral P (kg/ha)	39	Layert Nitrate (kg/ha)
15	Organic P (kg/ha)	40	Layert Ammonia (kg/ha)
16	Heat Unit Schedule (none)	41	Layert Organic N (kg/ha)
17	Base Heat Unit (none)	42	Layert Mineral P (kg/ha)
18	Heat Unit fraction (none)	43	Layert Organic P (kg/ha)
19	Layer1 Depth (m)	44	Layert Carbon (kg/ha)
20	Layer1 Bulk Density (t/m**3)	45	Layert N in NO3 (kg/ha)
21	Layer1 Nitrate (kg/ha)	46	N Uptake by Crop (kg/ha)
22	Layer1 Ammonia (kg/ha)	47	Heat Unit Index (none)
23	Layer1 Organic N (kg/ha)	48	Leaf Area Index (none)
24	Layer1 Mineral P (kg/ha)	49	Crop Height (m)
25	Layer1 Organic P (kg/ha)

The following sample script file can be modified and run at the command line:

epic2CMAQ.csh

5.4 EPIC Yearly Extraction Tool

We developed this tool primarily for performing quality assurance (QA) for EPIC runs. For EPIC spin-up runs, it extracts the last-five-years average EPIC values. For EPIC application runs, it extracts application-year EPIC variables. The tool outputs one netCDF file with the 29 variables listed in Table 9.

Table 9. EPIC yearly extraction output variables

Index	Variable	Index	Variable
1	N Mineralized (kg/ha)	16	Total NO3 in Soil Profile (kg/ha)
2	Humus Mineralization (kg/ha)	17	Denitrification_N2 (kg/ha)
3	N Fixation (kg/ha)	18	Grain Yield (t/ha)
4	Nitrification (kg/ha)	19	Forage Yield (t/ha)
5	N Volatilization (kg/ha)	20	N Used by Crop (kg/ha)
6	Denitrification (kg/ha)	21	P Used by Crop (kg/ha)
7	N Loss with Sediment (kg/ha)	22	N Applied (kg/ha)
8	N Loss in Surface Runoff (kg/ha)	23	P Applied (kg/ha)
9	N in Subsurface Flow (kg/ha)	24	Irrigation Volume Applied (mm)
10	N Loss in Percolate (kg/ha)	25	Water Stress Days (days)
11	Organic N Fertilizer (kg/ha)	26	N Stress Days (days)
12	N Fertilizer Nitrate (kg/ha)	27	Planting Date (Julian Date)
13	N Fertilizer Ammonia (kg/ha)	28	Germination Date (Julian Date)
14	Organic Carbon in Plow Layer (kg/ha)	29	Harvest Date (Julian Date)
15	Organic Carbon in Soil Profile (kg/ha)

Users can modify the sample script file with defined environment variables in the raster tool script directory:

epicYearlyAverage4QA.csh

6. Other Tools and Utilities

6.1 Domain Grid Shapefile Generation Tool

Users can apply the domain grid shapefile generation tool to generate a polygon shapefile for a defined grid domain with the GRIDID attribute. The GRIDID attribute has values ranging from 1 for the lower left grid cell to the maximum number of cells for the upper right grid cell. The following sample script file can be modified for domain shapefile generation:

generateGridShapefile.csh

6.2 Other Utilities

The following utility programs are stored in the util directory:

· goes_untar.pl – used to untar downloaded GOES data into the format required for the GOES processing tool.

· updateWRFinput_landuse.R – used to update the wrfinput file using generated land use data from the 2006 NLCD and MODIS Land Cover Generation tool (see Section 3.1). The updated wrfinput file can be used in WRF simulations with the updated PX LSM, using the 40 classes of NLCD/MODIS land cover data shown in Table 1.

7. Acknowledgments

The SA Raster Tools were developed with support from multiple projects:

· Work assignments from the U.S. EPA under Contract No. EP-W-09-023, “Operation of the Center for Community Air Quality Modeling and Analysis (CMAS)”

· NASA Research Opportunities in Space and Earth Sciences (ROSES) projects awarded to (1) the Institute for the Environment at the University of North Carolina at Chapel Hill with contract number NNX08AL28G and (2) the National Space Science and Technology Center at the University of Alabama in Huntsville.