WRFCAMx version 4.0 (release 05/06/13)

--------------------------------------

**********************************************************************

********** WRFCAMx translates WRF output meteorological fields to CAMx inputs.

NOTE: THIS VERSION WAS DEVELOPED SPECIFICALLY TO CONVERT FROM WRF/ARW

v3.2
AND LATER TO CAMX v6.0 AND LATER

++++ NOTE: IMPORTANT GUIDANCE ++++ Some users are reporting that WRFCAMx will not correctly read WRF output data
files if WRF uses the netCDF v3.6 64

- bit library and WRFCAMx uses the

netCDF
v3.5 32

- bit library (or earlier). Apparently the reverse is allowed
since the
later version of netCDF is backwards

- compatible. To be safe, be sure

to use the same library for both WRF an d WRFCAMx.

++++++++++++++++++++++++++++++++++

++++ NOTE: IMPORTANT GUIDANCE ++++ The sample job script below provides some important information regarding how to properly process WRF output files in WRFCAMx with res pect to precipitation data. If you do not follow this guidance, you may see erroneously large jumps in precipitation rates for hours that span across 2 different WRF

runs. See the sample job script below.

+++++++++ +++++++++++++++++++++++++

**********************************************************************

**********

Changes in WRFCAMx version 4.0 (released 05/06/13):

1) New CAMx met file format. See user control section (below) and sample script
for list of new CAMx files. See CAMx User's Guide for details.

Snow cover is now automatically put into the 2D time

- varying surface met file along with surface temperature. The 2

- D time varying file may also contain PBL depth, rainfall rate, and total cloud optical depth

-- these are diagnostic fieldsavailable to the user, but are not used by CAMx. The landuse file
carries 26 categories for Zhang deposition (from USGS or NLCD categories)

and CAMx internally maps these to 11 categ ories if Wesely deposition is run.

2) Code has been expanded to allow users to generate Kv fields using

all Kv options in a single run (pending available data on WRF file).

Results from each Kv option are output to separate files with the option ke yword appended
on the end of each Kv filename.

3) Added capability to read fractional landuse fiields (LANDUSEF) for

USGS and NLCD land cover types. If LANDUSEF is not found, program goes

back to using the dominant landuse at each grid point (LU _INDEX). Thanks to Alex Cohan at LADCO for this update.

Changes in WRFCAMx version 3.4 (released 11/09/12):

1) Altered the diagnosis of vertical precipitation profiles to: (1)

remove artificial constraints that reduce or remove precipitation water;
(2) set constant precipitation water profiles through cloud depth, and (3)

ensure adequate cloud water is present and coincident with precipitation

water profiles. Higher rates of wet deposition in CAMx will result.

CAMx tests have resulted in better agreement with PM deposition and
concentration

measurements.

Changes in WRFCAMx version 3.3 (released 04/19/12):

1) Improved reading efficiency of WRF netCDF files. The entries for

user control in the job script have chan ged slightly (see example below). As a result, precipitation processing is slightly different and cannot guarantee

proper handling of accumulated precip across different WRF runs; the quidance for precipitation processing has changed (see end of this file).

2) In WRF v3

- 3, the variable field labeled "TKE_MYJ" was changed to

"TKE_PBL",and the variable field labelled "EL_MYJ" was changed to "EL_PBL".
This effects WRFCAMx only when using the MYJ/TKE Kv method.

3) WRFCAMx has been updated to include processing of NLCD/MODIS

landuse categories to the 11 and 26 CAMx categories.

4) The routine INTERP_CART.F90 was updated to use double

- precision trig for wind rotation between WRF projection and CAMx projection. This

adds accuracy for h igh

- resolution WRF runs and should prevent Nan's.

5) Fixed a bug in the MICROMET argument list within KVCALC_ACM2 that

led to segmentation faults.

Changes in WRFCAMx version 3.2 (released 10/7/11):

1) Fixed a bug in the argument list to INTERP_CART t hat was incorrectly interpolating TKE to grids and projections that do not match the WRF grid projection. This impacted the calculation of Kv in such

cases.

2) Added the YSU Kv option, based on the YSU bulk boundary layer

scheme (option 1 in WRF). Also replaced the TKE option with the MYJ TKE

scheme.

Changes in WRFCAMx version 3.1 (released 1/26/11):

1) Fixed a bug in KVCALC_ACM2 (ACM2 Kv option) in calculations of H/L
and z/L. Usually minor reductions in Kv values in tra nsition between stable

and convective conditions (spatially and temporally).

Changes in WRFCAMx version 3.0 (released 10/12/10):

1) Added the ability to read optional sub

- grid cloud fields from the

Grell cumulus scheme (cu_physics=5) instead of dia gnosing them from
output thermodynamic fields. See example run script for a list of sub

grid cloud processing options.

2) Modified the definition of cloud optical depth to support the in

line TUVcloud photolysis adjustment in CAMx v5.30 and lat er. THE CAMX CLOUD/RAIN FILE HAS CHANGED: THE CLOUD/RAIN FILE IS NOW LABELLED "CAMx_V5.3
CLOUD_RAIN". CAMx will continue to be able to read V4.3 CLOUD/RAIN files, but in

that case, will only use the original RADM cloud adjustment.

3) Modified th e definition of the landuse file to support the CAMx Zhang (2003) dry deposition option. There is a new flag to output either the original 11 landuse categories (for Wesely 1989 dry deposition) or the new

26 landuse categories (for Zhang 2003 dry deposition). See example run script

for
usage. THE CAMx LANDUSE FILE HAS CHANGED, AND WILL ONLY WORK WITH

CAMx V5.30 AND LATER. However, CAMX will continue to be able to read

the old landuse format files, but i n that case, will only use the Wesely
(1989) dry deposition algorithm.

4) WRFCAMx now reads new WRF surface precip fields "PREC_ACC_C", "PREC_ACC_NC", and "SNOW_ACC_NC" recently added in WRF v3.2. These

are accumulated convective and non

- convec tive precip rates over the
output interval (e.g., 60 min), which alleviates the need for WRFCAMx to calculate output interval accumulations from RAINC and RAINNC. The original RAINC and RAINNC fields will be read and processed if the

new
"ACC" variables are not found.

5) Removed the sub

- grid stratus component (RH threshold technique from
MCIP)
from the sub

- grid cloud diagnostic algorithm (added in v2.3). The
CMAQ
sub

- grid convection component is retained as an option.

6) Expanded the T KE Kv option to use TKE from 2 PBL schemes (bl_pbl_phys = 2 and 4).

7) Raised the minimum temperature for liquid water from 255 K to 258 K
in PCPDIAG.F

8) Fixed a bug in which atmospheric density was not updated in the equation

for excess water for rainout in CLDDIAG.F9) Updated OB70 option to improve definition of surface boundary layer. This increases daytime Kv values by roughly 2x, which mostly

balances
the Kv reductions that resulted from the correction made in v2.2 (item #3).

Changes in WRFCAMx version 2.3 (released 05/07/10):

1) Improved the sub

- grid cloud diagnostic approach based on a hybrid of routines in CMAQ/MCIP. Note that there is a new user input flag

to select the diagnosis of sub

- grid cloud fields. See sample script

below.

2) Improved robustness of LCPGEO mapping routine for case when

truelat1 = truelat2.

3) Code generalized to handle cases when WRF LCP standard latitude
differ from
CAMx standard latitude.

4) Increased fidelity of rounding math for LC P mapping projection
variables
in READWRF.F90. Altered "makefile" for 64

- bit PG compiler flags, adding IEEE flag to ensure rigorous coordinate math is applied.

5) Fixed a bug in INTERP_CART.F90 routine that could occasionally lead

to a
NaN for w ind rotation angle when argument to arc

- cosine slightly

exceeds 1 (related to single

- precision math).

Changes in WRFCAMx version 2.2 (released 09/18/09):

1) Added ACM2 option for deriving Kv fields, following the methodology
in CMAQ (Pleim, 2007). The valid Kv options are now: TKE, OB70, CMAQ, ACM2

2) Improved checks with associated error messages for missing
variables on WRF output files.

3) Fixed a mis

- typed equation in KVCALC_OB70.F90 related to calculating Kv at the top of layer 1 during unstable conditions. This correction
leads to reduced values of Kv through the unstable PBL when using the OB70 option.4) Modified the Earth radius in INTERP_CART.F90 to be equivalent to

the value
in the LCPGEO.F rout ine (6370 km).

Changes in WRFCAMx version 2.1 (released 3/02/09):

1) Several bugs found since the release of version 2.0 have been
fixed:

- Cloud variables were initialized before arrays were allocated

- WRF coordinates were rounded to the nearest km

- WRF precip units were assumed to be cm, not mm

- Initialization of constant "pi" was missing for cloud/rain processing

- Array reading in layer mapping indices was too short

- NetCDF close statement was missing

2) WRFCAMx was expanded to allow for interpolation to geodetic, UTM,

or other LCP projections

Changes in WRFCAMx version 2.0 (released 2/21/08):

1) Recoded entirely in F90; improved memory management through

allocatable arrays and removed parameter statements defining grid sizes.

2) Generalized date/time algorithms to handle met output frequency

less than
1 hour.

3) The program now passes landuse/landcover and topography fields from WRF to CAMx by generating a CAMx landuse file. NOTE that WRF uses

the dominant landuse code for each grid point, and this characteristic
is passed to CAMx. This only works for USGS 24

- category lanudse
fields.

4) The processing of an extra hour of precipitation at the end of the specified date/time range was removed because it is not needed.

5) Processing of snow cover fields was added as an option (see sample job script below). Snow cover (0 or 1) is output to a separate file in

the CAMx Albedo/haze/ozone (AHO) colu mn text file format. You must

concatenate these panels onto your AHO file yourself (WRFCAMx does not do this for you).----------------------------------------------------------------------

----------

DESCRIPTION:

A single WRFCAMx run provides meteo rological fields for a single CAMx grid, whether defined as a CAMx master coarse grid, or a nested grid. The

program will generate the files for any duration (from a single hour to several days), but we find that running WRFCAMx to develop daily (25

- hou r) input
files allows the greatest flexibility, as these met files can get rather large.

For a single day, 25 hours of meteorology must be present (midnight through midnight, inclusive) as these fields represent hourly instantaneous conditions

and CAMx internally time

- interpolates these fields to each model time step.

CLoud and precipitation fields are not time

- interpolated, but rather time

averaged (or
time

- accumulated in the case of precipitation), so cloud/precipitation
files contain one less hour than other met files (e.g., 24 hours of cloud/precip vs. 25 hours of other met).

The program offers four horizontal interpolation options:

1) the CAMx grid is defined on the same projection and horizontal grid
structure/resol ution as WRF; WRFCAMx simply windows data from a portion of the WRF grid and outputs the subset to the CAMx files. Since WRF is developed on an Arakawa "C" grid configuration, no interpolation is necessary

-- CAMx wind fields retain the Ara kawa

"C"
stagger.

2) the CAMx grid is defined on the same or different LCP projection from WRF, and/or of different resolution, as long as it fits
within the area defined by outer rows/columns of WRF grid cell midpoints;
WRFCAMx inte rpolates all needed variables TO CAMX GRID CELL

CENTERS.

4) the CAMx grid is defined on a UTM projection of any resolution, as long as it fits within the area defined by outer rows/columns of WRF gridcell midpoints; WRFCAMx interpolates all n eeded variables TO CAMX

GRID

CELL CENTERS.

5) the CAMx grid is defined on a geodetic (lat/lon) projection of

any resolution, as long as it fits within the area defined by outer rows/columns of WRF grid cell midpoints; WRFCAMx interpolates all

needed
variables TO CAMX GRID CELL CENTERS.

The user may wish to modify this program to horizontally interpolate

WRF data to another map projection. In that case, the user needs to modify the projection mapping setup in the READWRF routine to prepare mapping
variables for the INTERP_CART subroutine. All other subroutines need not be
modified.

The CAMx physical height layer structure (meters AGL) is defined from

the geopotenti al heights at each of WRF's "eta" levels, and thus varies in

space and time. Vertical averaging of WRF layers to a coarser CAMx layer

structure is allowed. The set of WRF layers to combine into CAMx layers is specified in the script file. Variables in e ach WRF layer are mass

- weighted to

each bulk CAMx layer. See internal code documentation for more info.

Several options are available to derive Kv fields from WRF output. If
TKE is available, Kv can be derived from this; otherwise, other options diagnos e Kv from wind, temperature, and PBL parameters.

The WRF anc CAMx array fields are dynamically allocated. To compile
this program, edit (for your compiler) and run the "makefile". The program requires that the NetCDF library exists on your system

-- you must edit the path to the NetCDF library and associated include files in the makefile (see

"LIBS" and "INC").

As WRFCAMx runs, it echoes diagnostic information to standard output. It is recommended that this output be redirected to a file so that it

may be inspected after each run and serves as a record as to how the

program wasconfigured. All user

- specified input information is echoed, and WRF and CAMx grid parameters are provided. Warning messages indicate problems with grid alignment, etc., and will lead to a program stop.

For each hour of data processed, the minimun, average, and maximum values of all output variables are provided. These statistics are calculated for each
individual CAMx layer and repres ent the horizontal variation over the entire grid.

If additional assistance is required, or bugs are found, please

contact:

Chris Emery cemery@environcorp.com

----------------------------------------------------------------------

----------

HOW TO RUN:

A sample C

- shell job script to run WRFCAMx is provided below: each
line of the job script is further described at the end.

############################################################
#START SAMPLE JOB SCRIPT #/bin/csh ./wrfcamx.linux << EOF

KV Method |MYJ Minimum Kv |0.1 Projection |LCP Subgrd Cloud Method|GRELL Start/end date |05060100 05060500 WRF output freq |60 Grid time zone |6 CAMx grid size |100, 100, 12 CAMx Dx, Dy |36. 36. CAMx orig & params |

- 1072.,

- 978.,

- 100., 40., 60., 30. Layer mapping | 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 18 CAMx LU file |camx.lu.test CAMx 3D file |camx.3d.test CAMx 2D file |camx.2d.test CAMx Kv file |camx.kv.test
CAMx Cld/rain file |camx.cr.test WRF filename |$PATH/wrfout_d02.20050601.00

- 23Z WRF filename |$PATH/wrfout_d02.20050602.00

- 23Z WRF filename |$PATH/wrfout_d02.20050603.00

- 23Z WRF filename |$PATH/wrfout_d02.20050604.00

- 23Z WRF filename |$PATH/wrf out_d02.20050605.00

- 23Z WRF filename |$PATH/wrfout_d02.20050606.00

- 23ZEOF #END SAMPLE JOB SCRIPT
############################################################

Description:

KV Method |Approach to diagnose vertical diffusivities |from PBL parameters output by WRF: |OB70 = O'Brien (1970) Kv profile within PBL depth | *** REQUIRES PBL DEPTH ON WRF FILE *** |CMAQ = Byun et al. (1999) integration methodology | *** REQUIRES PBL DEPTH AND Z0 ON WRF FILE

*** |ACM2 = Pleim (2007) ACM2 methodology | *** REQUIRES PBL DEPTH AND Z0 ON WRF FILE

*** |MYJ = Mellor, Yamada, and Janjic (1994) Level 2.5

TKE | *** REQUIRES TKE AND MIXING LENGTHS ON WRF

FILE *** |YSU = Hong and Noh, Yonsei University (2006) | *** REQUIRES PBL DEPTH AND Z0 ON WRF FILE

*** |ALL = Generate files for all options, pending

available | data on the WRF file

Minimum Kv |Minimum Kv threshold; any values of Kv calculated

below |this value will be set to this value. We recommend setting |a minumum of 0.1. Users may then use the KVPATCH

program to |set landuse

- dependent minimum Kv within the surface layer. |Perform sensitivity tests.

Projection |UTM = WRF variables will be interpolated to a

user

- | defined UTM grid (must fit within

confines of | a single WRF grid

-- cannot span across multi ple | WRF grids). | NOTE: ALL VARIABLES ARE INTERPOLATED TO

CAMX GRID | CELL CENTERS |LATLON = WRF variables will be interpolated to a

user

- | defined geodetic (lat/lon) grid (must fit

within| confines of a single WRF grid

-- cannot

span | across multiple WRF grids). | NOTE: ALL VARIABLES ARE INTERPOLATED TO

CAMX GRID | CELL CENTERS |LCP = WRF variables will be processed to a

user

- defined | LCP grid. | If the CAMx LCP projection and resolution

parameters | match the WRF LCP grid then: | ALL VARIABLES ARE MAINTAINED ON THE

ARAKAWA

- C | ARRANGEMENT | Else: | WRF variables will be interpolated to a

user

- | defined LCP grid (must fit within

confines of | a single WRF grid

-- cannot span across multiple | WRF grids). | NOTE: ALL VARIABLES ARE INTERPOLATED TO

CAMX GRID | CELL CENTERS

Subgrd Cloud Method|Approach to process sub

- grid cloud data from
information |output by WRF: |NONE = Do not diagnose sub

- grid clouds |DIAG = Diagnose sub

- grid clouds from gridded met
fields. |GRELL = Pass through cloud fields from the Grell

cumulus | scheme | *** REQUIRES SPECIFIC OUTPUT VARIABLES IN WRF

REGISTRY *** | |For the DIAG option, you should consider grid

resolution; |for grid spacing less than ~10 km, small

- scale
convection |is likely generated by the grid

- resolved cloud physics in |WRF. The DIAG approach is based on CMAQ.

Start/end date |YYMMDDHH start and end date/hour for CAMx met

files

WRF output freq |Frequency of WRF output fields, in minutes; CAMx inputs|will be generated at this same frequency

Grid time zone |5=EST, 6=CST, 7=MST, 8=PST, 0=UTC

CAMx grid size |nx,ny,nz of output CAMx grid

CAMx Dx, Dy |X and Y grid resulution in km (LCP, UTM) or deg
(LATLON)

CAMx orig & params |X/Y coordinates of CAMx domain southwest corner (origin) |and projection parameters. |For UTM, supply km and the UTM zone, for exampl e: |

- 351., 3897, 12 |For LATLON, supply degrees (W.H. is negative longitude, | S.H. is negative latitude), for example: |

- 112., 38. |For LCP, supply km and the LCP projection
parameters: | central lat/lon and 2 true lats (W.H. is negative | longitude, S.H. is negative latitude, set both

true | latitudes to same value if your projection is

defin ed | by only 1 true latitude), for example: |

- 1072.,

- 978.,

- 100., 40., 60., 30.

Layer mapping |Array of layer indices where CAMx layer interfaces

match |WRF layer interfaces (i.e., full si gma

- p levels). Example: | 1, 2, 3, 4, 5, 6, 7, 9, 11, 14, 16, 18 |means CAMx layers 1

- 7 exactly match WRF layers 1

- 7, CAMx |layer 8 interface matches WRF layer interface 9,
CAMx layer |9 interface matches WRF layer interface 11, etc. Sigma

- p |level "0" is at the ground (0 meters).)

CAMx LU file |CAMx input file pathname CAMx 3D file |CAMx input file pathname CAMx 2D file |CAMx inp ut file pathname | NOTE: This file contains mandatory surface
temperature and | snow cover fields, but may also contain PBL, rainfall | rate and total cloud optical depth if

sufficient| WRF data are available on the output file.

These | extra fields are for diagnostic purposes

and are not | used by CAMx. CAMx Kv file |CAMx input file pathname (CAMx appends Kv option
name) CAMx Cld/rain file |CAMx input file pathname

WRF filename |the WRFOUT file name (repeat this record for each

WRF |output file that spans the period given by

YYMMDDHH above

++++ NOTE: IMPORTA NT GUIDANCE ++++
++++ FOLLOW THIS GUIDANCE IF THE WRF "PREC_ACC" VARIABLES ARE NOT

AVAILABLE ++++

WRFCAMx will look for the WRF output variables "PREC_ACC" that store precipitation rates at each output interval. If these variables ARE

NOT on file, then WRFCAMx will revert to using the precipitation accumulation
variables "RAINC" and "RAINNC" to calculate surface precipitation rates.

RAINC and RAINNC store total accumulated water from the start of each

WRF simulation. WRFCAMx must generate hourly precipitation rates by subtracting the
accumulation at the current hour from the accumulation from the previous hour. This works well across multiple output files from the same WRF run.

However, when output from t wo different WRF runs are to be processed by WRFCAMx for a single CAMx input file, the accumulated precipitation at the

cross

- over hour will cause problems as the second WRF run represents an entirely
different simulation of precipitation (and all other me teorological fields).
This can lead to unrealistic precipitation values at the cross

- over hour.

To avoid this situation, make sure that each CAMx input meteorological
file is generated from a single WRF run

-- DO NOT attempt to use WRF output files from different WRF runs to span a single CAMx file.

++++++++++++++++++++++++++++++++++