WRFCAMx version 5.1 (release 12/14/15)
--------------------------------------------

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

NOTE: THIS VERSION WAS DEVELOPED SPECIFICALLY TO CONVERT FROM WRF/ARW v3.2+
      TO CAMX v7.0+

===========THIS VERSION GENERATES CAMx MET INPUT FILES IN NETCDF================

                    ++++ NOTE: IMPORTANT GUIDANCE ++++
This program will generate CAMx input meteorological and surface (landuse) files
in netCDF format.  Either netCDF-3 or netCDF-4 can be used to build the program,
but only the latter supports file compression upon read/write. Be sure to change
the following variabiles in the WRFCAMx Make script to set the path to your
netCDF library and include files, and to use the "chunking" algorithm for file
compression:

LIBS  = -L/usr/local/netcdf/lib
INC   = -I/usr/local/netcdf/include
FLAGG = -lnetcdff -lnetcdf
#CHUNK = -DCHUNK

In the example above, chunking is turned off by commenting out the CHUNK
variable.  To turn on chunking for file compression, simply remove the "#"
comment delimeter.
                    ++++++++++++++++++++++++++++++++++

                    ++++ NOTE: IMPORTANT GUIDANCE ++++
In WRF v3.8, the MODIS landuse classification scheme increased from 20 to 21
categories, where category 21 is fresh water lakes.  A similar update was made
for USGS, adding fresh water lakes as category 28.

If this additional category is available on the WRF output files, WRFCAMx will
map it to CAMx/Zhang landuse category 3 to differentiate between oceans and
inland water to support the CAMx in-line haloagen emissions algorithm.  In any
case, we strongly recommend that you analyze the resulting CAMx landuse file to
ensure that category 1 properly represents only ocean (salt water) bodies and
category 3 properly represents only in-land (fresh water) bodies inclusive of
lakes, rivers, etc.  The differentiation between ocean and lakes is not made in
the WRF NLCD schemes. Use the CAMx "WATERMASK" pre-processor to remap water
between ocean and lakes if you plan to use the CAMx in-line halogen emissions
option.
                    ++++++++++++++++++++++++++++++++++

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

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

DESCRIPTION:

A single WRFCAMx run generates 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 time-averaged (or
time-accumulated in the case of precipitation), so cloud/precipitation files 
contain 24 hours of valid data (25th hour is ignored by CAMx).

The program offers several horizontal mapping and interpolation options:

  1) The CAMx grid is defined on the same Lambert, Mercator or Polar 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 operates 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 Lambert or Mercator 
     projection as WRF, and/or of different resolution, as long as it fits 
     within the area covered by the WRF grid "cross" points (midpoints between
     wind points); WRFCAMx interpolates all needed variables TO CAMx GRID CELL
     CENTERS.  This option is not allowed for the WRF Polar projection.

  5) The CAMx grid is defined on a geodetic (latitude/longitude) projection of
     any resolution, as long as it fits within the area covered by the WRF grid 
     "cross" points (midpoints between wind points); WRFCAMx interpolates all 
     needed variables TO CAMx GRID CELL CENTERS. This option is supported for
     WRF Lambert and Mercator projections, but is not allowed for the WRF Polar
     projection.

  4) The CAMx grid is defined on a Universal Transverse Mercator (UTM)
     projection of any resolution, as long as it fits within the area covered by
     the WRF grid "cross" points (midpoints between wind points); WRFCAMx 
     interpolates all needed variables TO CAMx GRID CELL CENTERS.  This option
     is supported for WRF Lambert and Mercator projections, but is not allowed
     for the WRF Polar projection.

The user may wish to modify this program to horizontally interpolate WRF data 
to other map projections.  In that case, the user needs to modify the 
projection mapping setup in the READWRF routine to prepare mapping variables for
the WRF_INTERP subroutine.  Other subroutines do not need to be modified.

The CAMx physical height layer structure (meters AGL) is defined from the 
geopotential heights at each of WRF's "eta" or hybrid eta/pressure 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 information.

Several options are available to derive vertical diffusivity (Kv) fields from
WRF output.  If turbulent kinetic energy (TKE) is available on the WRF output
files, Kv can be derived from this; otherwise, other options diagnose Kv from 
wind, temperature, surface and PBL parameters.

WRFCAMx will process the following WRF landuse datasets directly to CAMx landuse
categories: USGS, MODIS-NLCD, MODIS-IGBP.  If WRF was not run with any of these
three landcover data sources, or the landcover fields are not output, then no
landuse fields will be generated for CAMx; in such cases the user will need to
develop landcover inputs for CAMx independently.  WRFCAMx will preferentially
use fractional landcover fields output by WRF, or if missing, will revert to the
dominant landcover field output by WRF.

The WRF and 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@ramboll.com

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

HOW TO RUN:

An example 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
Run note           |Sample WRFCAMx run
CAMx nested grid   |T
Diagnostic fields  |T
Seaice adjustment  |T
KV Method          |YSU
Minimum Kv         |0.1
Projection         |LAMBERT
Subgrid Convection |DIAG
Subgrid Stratiform |T
Start/end date     |15060100 15060200
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.150601.test.nc
CAMx 3D file       |./camx.3dmet.150601.test.nc
CAMx 2D file       |./camx.2dmet.150601.test.nc
CAMx Kv file       |./camx.kv.150601.test.nc
Input snow age     |./snow.file.150531
Initial snow age   |36
Output snow age    |./snow.file.150601
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:
Run note           |Message written to CAMx input files for documentation.

CAMx nested grid   |Logical flag (T or F)
                   |Inform WRFCAMx that you are processing met for a CAMx 2-way
                   |nested grid (can set to F for independent 1-way nests).
                   |If "T", WRFCAMx will automatically develop met fields
                   |that include nested grid buffer cells, so the user does not
                   |need to determine grid dimensions and grid X/Y origin that
                   |account for buffer cells. If "F", WRFCAMx will process met
                   |fields for the specified grid parameters without adding
                   |buffers (such as for a "master" grid or 1-way nested grid). 
                   |ALWAYS SPECIFY GRID PARAMETERS THAT DO NOT INCLUDE BUFFER
                   |CELLS.

Diagnostic fields  |Logical flag (T or F)
                   |Output the following diagnostic fields:
                   |10-m U/V wind components (used for SEASALT processor)
                   |2-m temperature
                   |surface downward solar flux
                   |WRF PBL depths
                   |CAMx PBL depths (according to KV Method below)
                   |surface precipitation rate
                   |vertically integrated total cloud optical depth
                   |soil moisture (used for WBDUST processor)
                   |convective cloud tops (used for LNOx processor)
                   |CAPE (used for LNOx processor)

Seaice adjustment  |Logical Flag (T or F)
                   |Read time-varying WRF sea ice field and convert CAMx ocean
                   |water (LU #1) to ice (LU #2) for any non-zero sea ice
                   |coverage found.  If "F", sea ice conversion will not be
                   |applied. Requires SEAICE variable on WRF output file.

KV Method          |Approach to diagnose vertical diffusivities
                   |from PBL parameters output by WRF:
                   |CMAQ = Byun et al. (1999) integration 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         |LAMBERT  = WRF variables will be processed from WRF Lambert
                   |           projection to a user-defined Lambert grid.
                   |          *If the CAMx Lambert projection and resolution
                   |           parameters match the WRF Lambert grid:
                   |             WRF data is simply windowed to the CAMx grid.
                   |             NOTE: ALL VARIABLES ARE MAINTAINED ON THE
                   |                   ARAKAWA-C ARRANGEMENT
                   |          *Else:
                   |             WRF variables will be interpolated to a user-
                   |             defined Lambert 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
                   |POLAR    = WRF variables will be windowed from WRF Polar
                   |           projection to a user-defined Polar grid.
                   |           NOTE: THE CAMx POLAR PROJECTION AND RESOLUTION
                   |                 PARAMETERS MUST MATCH THE WRF POLAR GRID.
                   |                 ALL VARIABLES ARE MAINTAINED ON THE
                   |                 ARAKAWA-C ARRANGEMENT
                   |MERCATOR = WRF variables will be processed from WRF Mercator
                   |           projection to a user-defined Mercator grid.
                   |          *If the CAMx Mercator projection and resolution
                   |           parameters match the WRF Mercator grid:
                   |             WRF data is simply windowed to the CAMx grid.
                   |             NOTE: ALL VARIABLES ARE MAINTAINED ON THE
                   |                   ARAKAWA-C ARRANGEMENT
                   |          *Else:
                   |             WRF variables will be interpolated to a user-
                   |             defined Mercator 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 from WRF
                   |           Lambert or Mercator projection to a user-defined
                   |           geodetic (latitude/longitude) 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
                   |UTM      = WRF variables will be interpolated from WRF
                   |           Lambert or Mercator projection to a user-defined
                   |           Universal Transverse Mercator 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
         
Subgrid Convection |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.
                   |KF   = Use WRF output of specific Kain-Fritsch sub-grid
                   |       cloud fields to define sub-grid clouds for CAMx.
                   |       
                   |The DIAG option is based on MCIP/CMAQ. You should consider
                   |grid resolution in your selection; for small WRF grid 
                   |spacing of 1-5 km, explicit convection may be generated by
                   |WRF's grid-resolved cloud microphysics scheme.
                   |
                   |The KF option will support later capabilities in CAMx
                   |that address sub-grid convective transport.  It can be
                   |be used now to determine overall CAMx cloud cover,
                   |which will impact photolysis and wet deposition.
                   |   *** REQUIRES SPECIFIC K-F VARIABLES ON WRF FILE ***

Subgrid Stratiform |Logical flag (T or F)
                   |Diagnose sub-grid stratiform cloudiness using critical RH
                   |profile technique from MCIP. This option works in tandem
                   |with the convective diagnosis, and so is only active if
                   |Subgrid Convection is set to "DIAG" or "KF".

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 size in km (cartesian map projections), e.g.:
                   |12. 12.
                   |or in degrees (LATLON), e.g.:
                   |1.5 1.25
                   |You may enter fractions to ensure the best representation
                   |of rational decimals is used, e.g.:
                   |4/3 4/3 (instead of 1.33 1.33 km)
                   |3/4 2/3 (instead of 0.75 0.67 deg)

CAMx orig & params |X/Y coordinates of CAMx grid southwest corner and map
                   |projection parameters. Examples are given below.
                   |  NOTE: Longitude < 0 in western hemisphere 
                   |        Latitude < 0 in southern hemisphere
                   |LAMBERT:  *X/Y Lambert coordinates (km) of CAMx southwest
                   |           corner
                   |          *Lon/lat (deg) of Lambert projection origin (where
                   |           Lambert coordinates are 0,0)
                   |          *2 true latitutdes (deg): set both true latitudes 
                   |           to same value if your projection is defined by
                   |           only 1 true latitude:
                   |          Example: -1072.,-978.,-100.,40.,60.,30.
                   |POLAR:    *X/Y Polar coordinates (km) of CAMx southwest
                   |           corner
                   |          *Lon/Lat (deg) of Polar projection origin (where
                   |           Polar coordinates are 0,0)
                   |          *1 true latitude (deg): usually +90 or -90, but
                   |           can be <|90| for "secant" polar projections
                   |          Example: -1500.,-1000.,-120.,70.,90.
                   |MERCATOR: *X/Y Mercator coordinates (km) of CAMx southwest
                   |           corner
                   |          *Lon/Lat (deg) of Mercator projection origin
                   |           (where Mercator coordinates are 0,0)
                   |          *1 true latitude (deg): usually 0, but can be >0
                   |           for "secant" Mercator projections
                   |          Example: -2000., 500., -90., 0., 0.
                   |LATLON:   *X/Y geodetic coordinates (deg) of CAMx southwest
                   |           corner
                   |          Example: -112., 38.
                   |UTM:      *X/Y UTM coordinates (km) of CAMx southwest corner
                   |          *UTM zone (integer)
                   |          Example: -351., 3897, 12

Layer mapping      |Array of layer indices where CAMx layer interfaces match
                   |WRF layer interfaces (i.e., full eta levels).
                   | Example:
                   | 1, 2, 3, 4, 5, 6, 7, 9, 11, 14, 16, 18
                   |This 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. Eta
                   |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 (includes cloud/rain data)
                   |NOTE: This file contains mandatory 2-D surface fields,
                   |      but may also contain additional diagnostic fields if
                   |      sufficient WRF data are available on the output file.
                   |      These extra fields are for diagnostic purposes (not
                   |      used by CAMx) but some are needed for certain emission
                   |      pre-processors.
CAMx Kv file       |CAMx input file pathname (CAMx appends Kv option name)

Input snow age     |If not blank, this intermediate file is used to initialize
                   |gridded snow age field from a previous WRFCAMx run.
                   |Otherwise, it is ignored and initial snow age (if snow
                   |exists anywhere in the grid) is set to a user-defined value
                   |from next record. This record must be included whether or
                   |not snow age is used.

Initial snow age   |Set initial snow age in hours (integer!) if input file is
                   |not specified.  Otherwise it is ignored. This record must be
                   |included whether or not snow age is used.

Output snow age    |If not blank, this intermediate file is written at the end of
                   |the WRFCAMx run to initialize gridded snow age field in a
                   |subsequent run. This record must be included whether or
                   |not snow age is used.

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.

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