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

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

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

Changes in WRFCAMx version 5.1 (released 12/15/20):

1) Added CAMx nested grid flag that informs WRFCAMx to process met for a CAMx
   nested grid that will automatically include nested grid buffer cells.
   See the README for more information.

2) Changed NetCDF global variable NAME to CAMx_NAME. Other minor netCDF updates
   to ensure variables names are sufficiently padded with blanks.

3) Modified surface soil moisture output: uses P-X soil layer 1 directly.
   THIS CHANGE WAS SPECIFICALLY IMPLEMENTED TO IMPROVE WIND BLOWN DUST EMISSION
   ESTIMATES FROM THE WBDUST MODEL.

4) Updated landuse assignments between WRF and CAMx for crop/grassland mosaic
   and barren tundra.

5) Bug fix: the hybrid vertical coordinate flag was moved to WRF module so that
   its value can be retained after initial setting at first hour step.

Changes in WRFCAMx version 5.0 (released 06/01/20):

1) Restructured to generate CAMx met input files in netCDF-3/4 format.
   NetCDF-4 files can be compressed using default chunking parameters taken
   from WRF.

2) Includes all changes in v4.8 below.

Changes in WRFCAMx version 4.8 (released 05/31/20):

1) Added option to 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.

2) Updated to handle expanded USGS land cover categories (up to 28) in recent
   versions of WRF.  Original 24-category USGS data are still supported.

3) Revised to set surface roughness based on mapped CAMx land cover categories
   instead of reading surface roughness from WRF or setting roughness to
   default WRF values.  Surface roughness is only set if WRF land cover fields
   were available to map to CAMx land cover.  This only affects Kv methods CMAQ
   and YSU, and impacts are expected to be minor.

4) Added ability to handle WRF hybrid vertical coordinate, which is the default
   starting with WRF v4.0.

5) Added attenuation of surface downward solar flux (diagnostic field) by
   diagnosed or K-F sub-grid clouds generated by WRFCAMx.

6) Removed old snow cover option that supported 2-D inputs from CAMx pre-v6.3.
   Now only snow equivalent water depth and age are provided to CAMx.

Changes in WRFCAMx version 4.7 (released 02/26/19):
   
1) Added soil moisture from NOAH or P-X LSMs, written as a CAMx 2-D surface met
   field to support windblown dust pre-processor (not used in CAMx).  Soil
   moisture is written as a "diagnostic" field, so the diagnostic flag must be
   set to true in the job script.

2) Added convective cloud top and CAPE calculations, written to CAMx 2-D surface
   met file to support LNOx pre-processor (not used in CAMx).  These are
   written as "diagnostic" fields, so the diagnostic flag must be set to true
   in the job script.

3) Added check for new WRF hybrid vertical coordinate.  Program will stop if
   if it finds that the new hybrid coordinate was used.

4) Removed OB70 and ACM2 Kv options.  OB70 typically generated Kv values that
   were too small/weak; ACM2 typically generated values that were far too
   large.  MYJ (TKE), CMAQ and YSU remain available options.

Changes in WRFCAMx version 4.6 Patch (released 07/11/17):

1) Fixed bug in LUCAT variable that can lead to memory overflow into SCMETH
   variable.

Changes in WRFCAMx version 4.6 (released 02/08/17):

1) Added a new capability to define CAMx grid cell size as a fraction (e.g.,
   4/3) instead of a decimal (e.g., 1.33).  This ensures that the best decimal
   representation of grid size is defined for this program, and should alleviate
   issues with round off error impacting the diagnosis of CAMx-WRF grid
   alignments.  Thanks to Alex Cohan, LADCO, for this solution.

Changes in WRFCAMx version 4.5 (released 09/20/16):

1) Generalized the read of WRF landuse categories to accomodate recent changes
   in WRF v3.8.  WRFCAMx continues to support "USGS" (24 categories), "Modified
   IGBP MODIS NOAH" (20 or 21 categories), and NLCD (50 or 40 categories).

2) The move from 20 to 21 categories in MODIS landuse adds fresh water lakes;
   if present in the WRF files, this additional category is mapped to CAMx/Zhang
   landuse category 3 to differentiate between oceans and inland water to
   support the CAMx in-line haloagen emissions algorithm.  The differentiation
   between ocean and lakes is not made in USGS or NLCD schemes. Use the CAMx 
   "WATERMASK" pre-processor to remap water between ocean and lakes.

Changes in WRFCAMx version 4.4 (released 04/08/16):

1) Added additional WRF projections (Polar Stereographic and Mercator).  New 
   LCPGEO routine, new MRCGEO routine.  READWRF signficantly updated.

2) Fixed minor bug in lat/lon projection diagnostic variable (only used for
   reporting lat/lon grid size info -- not used for internal calculations).

3) Added snow water equivalent depth and snow age to 2-D time-variant CAMx
   input file to support improvements to surface albedo treatment in CAMx.
   NOTE: This change works with CAMx v6.30+, but is not backward compatible
   with previous versions of CAMx; use the pre-v6.30 flag to make snow cover
   inputs for previous CAMx versions.

4) Updated WRF-to-CAMx landuse mapping for certain minor landuse types. This
   change ties into the snow cover updates to improve consistency in vegetation
   height across LU categories.

5) Fixed precip accumultion bug in case of WRF output files with single
   timestamps.

6) Fixed a dimension bug for U10 and V10 diagnostic variables that could lead
   to incorrect fields in the 2D met files. U10 and V10 are not used in
   CAMx.

7) Removed Grell sub-grid convection option, replaced with a Kain-Fritsch 
   sub-grid convection option that will support a new convective mixing option
   in later versions of CAMx.  You can use this option now for CAMx as
   an alternative to diagnostic sub-grid cloud option.  Specific fields from
   K-F need to be present in the WRF output to be able to use this option.

Changes in WRFCAMx version 4.3 (released 12/17/14):

1) Bug fix for WRF TKE vertical dimension.  Previously dimension was by layer
   (nz) but now needs to be by level (nz+1), which led to a program stop when
   NetCDF reading routines were checking variable dimensions.  Apparently this
   was a recent change in WRF as this error had never occured before.

2) Corrected a bug in correctly identifying IGBP landuse fields that led to a
   the inability to use default surface roughness when such fields are not
   available in WRF output.

Changes in WRFCAMx version 4.2 (released 05/27/14):

1) Landuse fields can now be processed from the modified IGBP MODIS 20 category
   LU fields in WRF.

2) Added checks to note if topographic fields are on WRF file

3) Minor fix to INTERP_CART for double-precision PI calculation
   (compiler compatibility)

Changes in WRFCAMx version 4.1 (released 12/19/13):

1) New diagnostic variables can now be optionally added to the 2D time-variant
   surface file: T2, U10/V10, SWDOWN, PBL heights.  These are not used by CAMx.
   A new "Diagnostic fields" switch is added to the user control section of the
   job script.  PBL heights are passed from WRF and are calculated for any 
   chosen Kv method.  Thanks to Weining Zhou at TCEQ.

2) The code to process NLCD landuse data has been updated to handle the new
   40 category classification scheme. Thanks to Kirk Baker at EPA and Bret
   Anderson at USFS.

3) The internal assignment of surface roughness by landuse category (USGS or
   NLCD) has been reinstated in cases where roughness is not provided on
   WRF output files.  Thanks to Bret Anderson at USFS.

4) The diagnostic of sub-grid stratiform cloudiness has been reactivated as a 
   new option (originally removed in v3.0).  A new "Subgrid Stratiform" switch
   is added to the control section of the job script.

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

Release 5/16/13: Bug fixes for indexing WRF landuse to CAMx categories and time/
                 date stamp for 2D surface file that caused CAMx to stop with
                 and error
   
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 sub-grid
   cloud processing options.

2) Modified the definition of cloud optical depth to support the in-line 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).
