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 and WRFCAMx.

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

 ++++ NOTE: IMPORTANT GUIDANCE ++++

The sample job script below provides some important information 

regarding how

to properly process WRF output files in WRFCAMx with respect 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 fields
 available 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 categories 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 keyword 

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 changed 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 high-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 that 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 transition 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 diagnosing them from 

output

 thermodynamic fields. See example run script for a list of subgrid

 cloud processing options.

2) Modified the definition of cloud optical depth to support the inline TUV
 cloud photolysis adjustment in CAMx v5.30 and later. 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 the 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 in 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-convective 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 TKE 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.F
9) 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 LCP 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 wind 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 routine (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) column 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 meteorological 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-hour) 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 timeaveraged (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/resolution 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 Arakawa 

"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 interpolates 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 

grid
 cell midpoints; WRFCAMx interpolates all needed 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 

geopotential 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 each 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 

diagnose

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 was
configured. 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 represent 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/wrfout_d02.20050605.00-23Z

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

#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 

multiple

 | 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 example:

| -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 

defined

 | 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 sigma-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 input 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: IMPORTANT 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 two 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 meteorological 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.

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