Hwrf v4.0a

README.SF_CLM_HWRF

@@ -0,0 +1,18 @@
+The new CLM surface scheme (sf_surface_physics=5) compiles very slowly
+on the Intel compiler when optimization is enabled.  For that reason,
+optimization of that file is disabled by default in the HWRF
+repository.  If you want to run with the CLM surface scheme, we
+strongly recommend you re-enable optimization on that file and
+recompile.  To do that:
+
+1. Remove these two lines from arch/noopt_exceptions_f:
+module_sf_clm.o: module_sf_clm.F
+module_sf_clm.o \
+
+2. Run ./clean -a
+
+3. Rerun "configure" and "compile" as you normally would.
+
+The compile time will be 50%-100% longer with the Intel compiler, but
+the model will eventually compile.  The CLM surface scheme will run
+much faster due to optimization being enabled.

README.hybrid_vert_coord

@@ -0,0 +1,223 @@
+Hybrid Vertical Coordinate
+--------------------------
+
+Starting with the WRF v3.9 release (Spring 2017), the option for a Hybrid 
+Vertical Coordinate (HVC) has been added to the existing Terrain Following 
+(TF) vertical coordinate in the WRF model. The HVC option requires that a user 
+activate both a compile-time and a run-time flag. 
+
+HVC: What is it, what's available
+---------------------------------
+
+The HVC option is a "hybrid" vertical coordinate, in that the eta levels are 
+terrain following near the surface, and then relax towards an isobaric surface
+aloft.  The purpose of this coordinate option is to reduce the artificial 
+influence of topography towards the top of the model.
+
+Due to the usual annual upgrades in physics and dynamics, the WRF model never 
+gives bit-reproducible results from one release to the next. However, within 
+this single release, the WRF model is able to give bit-for-bit results when 
+the TF model is compared to the WRF model built with the HVC option (but with 
+the run-time options set to emulate the TF coordinate).
+
+The "2d flow over a hill" and LES ideal cases both fully support the HVC option.
+All of the other ideal cases are essentially hard-coded to be used in the TF 
+mode only. Any ideal case (other than 2d hill and LES) will gracefully stop if 
+a user requests to activate the HVC option at run time. Also for bullet-
+proofing, any attempt to use the HVC run-time option for any WRF simulation 
+when the code was built for TF only, will result in a graceful fatal error.
+
+The real program and the WRF model need to consistently use the same run-time 
+setting for either TF or HVC. The code will stop if the user mixes the vertical 
+coordinate run-time settings between real and WRF (or between ideal and WRF). 
+The WRF code has been modified to use pre-v3.9 input and lateral boundary 
+files, but only for the run-time choice of the TF coordinate.
+
+Choosing the TF vs the HVC Option
+---------------------------------
+
+By default, both the compile-time and run-time options are set to use the 
+TF coordinate option. 
+
+To activate the HVC build, the "configure" command is given an additional 
+option:
+./configure -hyb
+
+Once the code is built with the HVC option, still by default the model will 
+produce results bit-wise identical to the TF build results. To turn on the HVC 
+run-time option, a switch is set in the namelist.input file:
+&dynamics
+ hybrid_opt = 2
+/
+
+This is a single entry value, which is set to zero by default through the 
+Registry. For completeness, to explicitly turn off the HVC in the 
+namelist.input file:
+&dynamics
+ hybrid_opt = 0
+/
+
+A second run-time option is available for the HVC capability, which allows the 
+user to select the eta level at which the WRF model surfaces become completely 
+isobaric. Setting this value is not intuitive, and a reasonable value that 
+should work globally has been set as the default. For sensitivity testing of 
+the model results to the level at which the model eta coordinates become 
+isobaric, the user may modify the critical eta level defined in the 
+namelist.input file.
+&dynamics
+ etac = 0.2
+/
+
+As the value of etac increases (from 0 towards 1), more eta levels are impacted 
+as increasing numbers of levels (downward from the model top) are flattened 
+out. On the one hand, that is a good thing, and this "flattening of the 
+coordinate surfaces" is the entire purpose of the HVC option. However, over 
+areas of high topography (not necessarily steep or complex), the vertical eta 
+levels get too compressed when etac values larger than about etac = 0.22. Over 
+the Himalayan Plateau with a 10 hPa model lid, a value of etac = 0.25 causes 
+model failures. Globally then, a value of 0.2 is considered "safe".
+
+Run-time and Compile-time options for HVC
+-----------------------------------------
+
+Here is a easy reference table showing the WRF model behavior with the 
+combination of the compile-time and run-time settings for the HVC.
+
+                                         Compile-time Option
+                                 ----------------------------------------
+                                 | ./configure      |  ./configure -hyb |
+                                 |     TF           |     HVC           |
+                                 |                  |                   |
+                 --------------------------------------------------------
+                 |               |                  |                   |
+                 | Default       |   Default        |  Default          |
+                 | hybrid_opt=0  |   TF             |  TF               |
+                 |               |  Behavior        | Behavior          |
+Run-Time Option  |-------------------------------------------------------
+                 |               |                  |                   |
+                 | HVC           | Model            |  HVC              |
+                 | hybrid_opt=2  | stops -          |  Behavior         |
+                 |               |  FATAL           |                   |
+                 --------------------------------------------------------
+
+How the code has been modified
+------------------------------
+
+For the v3.9 release, the largest block of modifications required to the source 
+code for the HVC capability is with the variable defined as the column pressure 
+in the TF coordinate (referred to generally as "mu").  This is one of the 
+variables that has both a perturbation and a base-state value, also staggerings 
+for different variables, and even different time levels. All together, nearly 
+thirty "mu" variables needed to be processed. For the HVC modification, the 2d 
+"mu" fields still retain the meaning of column pressure, but the definition of 
+d(p_dry))/d(eta) has been generalized, and is now 3d.
+
+Almost all instances of a 2d "mu" field have been transformed into a 3d field 
+with the application of two 1d arrays (a multiplication and an addition).  For 
+the base-state "mu" and total "mu" fields, functionally this new field is 
+defined as:
+mu_new_3d(i,k,j) = c1(k) * mu(i,j) + c2(k)
+
+For perturbation "mu" fields, only the multiplicative scaling is applied:
+mu_new_3d(i,k,j) = c1(k) * mu(i,j)
+
+Even with each instance of "mu" being scaled and most instances of "mu" getting 
+an offset applied, the elapsed time to run TF vs HVC appears to be quite small. 
+Most of the instances of the required 3d "mu" are handled on the fly, meaning 
+that no new 3d arrays for "mu" have been introduced in the Registry. Inside the 
+WRF modeling system, most of the "mu" variables are transformed into 3d arrays 
+within each computational DO LOOP in which they appear. This technique of 
+computing the 3d "mu" fields only as required removes the need to introduce 
+more temporary 3d arrays, and as mentioned, the redundant computation does 
+not seem to impact the overall timing of the model.
+
+Cautionary note
+---------------
+
+Since the references to the "mu" fields are modified automatically at 
+compile-time within the source, users are strongly encouraged to thoroughly 
+test any code addition that needs to directly utilize one or more of the "mu" 
+fields. 
+
+Users are also warned that the original definitions of base-state and 
+dry pressure are no longer generally valid. Most users will find either p'+pb 
+or p_hyd as satisfactory pressure substitutes.
+
+CPP: variable argument list macros
+----------------------------------
+
+To introduce this vertical coordinate capability required changes to thousands 
+of lines of code. Fortunately, most of this "convert 2d mu to 3d mu" was 
+handled with some traditional Unix text processing utilities. You will notice 
+extra intermediate files that are constructed during the WRF build (if you are 
+viewing the build log), and there are cpp header lines in quite a few of the 
+modules in the dyn_em directory.
+
+A side-effect of the HVC build is that the cpp flag -traditional-cpp is no 
+longer available, and has been removed from the arch/configure_new.defaults 
+file.
+
+What to Notice on Output
+------------------------
+
+There are a couple of ways to determine if the model output (and as stated 
+previously, mandatorially the model IC and BC files also) was built and run 
+with the HVC option.
+
+Visually, with a simple netcdf viewer (such as ncview), look at the horizontal 
+levels of the field "PB" in an area of topography. For a few consecutive levels 
+downward from the model lid, each value on a specific level should be 
+nearly identical. For the TF option, the signature of the topography is 
+evident even at the penultimate level.
+
+The netcdf files also have metadata included to indicate if the hybrid 
+vertical coordinate option was used.
+
+For code that was built with the TF compile-time option:
+>ncdump -h wrfinput_d01 | grep HYBRID
+		:HYBRID_OPT = -1 ;
+
+For code that was built with the HVC compile-time option, but with the TF 
+run-time option:
+>ncdump -h wrfinput_d01 | grep HYBRID
+		:HYBRID_OPT = 0 ;
+
+For code that was built with the HVC compile-time option, and with the HVC 
+run-time option:
+>ncdump -h wrfinput_d01 | grep HYBRID
+		:HYBRID_OPT = 2 ;
+
+What WRF capabilities are OK with HVC
+-------------------------------------
+
+With WRF v3.9, this is an initial release of the HVC capability. We would like 
+as many users as possible to try the HVC option and provide feedback. However, 
+this is an initial release of a new capability within WRF ARW, so care should be 
+taken. The default behavior is still TF. Tests have been conducted with a 
+number of the WRF system's other signature features: FDDA, adaptive time 
+stepping, DFI, global domains, nesting, moving nests, and ndown. A couple of 
+physics schemes had to be modified, so now all physical parameterization 
+schemes fully support the HVC option.
+
+The WRF developers have worked in conjunction with the developers of the other 
+major WRF system components. Both WRF DA 3dVAR and WRF Chem fully function with the 
+hybrid coordinate. With the introduction of the HVC option, the standard WRF 
+post-processing tools are also fully supported: NCL, UPP, and RIP.
+
+What WRF capabilities are NOT supported with HVC
+------------------------------------------------
+
+Only two of the idealized initialization programs are enabled with the HVC 
+option. However, those unsupported cases have a flat surface, so the expected 
+impact with the HVC option would not be large.
+
+The one capability that is not functioning with the HVC option is vertical 
+refinement. 
+
+Registry information
+--------------------
+
+The Registry file that contains all of the information for the hybrid 
+coordinate is Registry/registry.hybrid. In the comments at the top of this file 
+is a brief description of the component pieces that constitute new 3d "mu": 
+d(p_dry)/d(eta).