README for refactoring the use of associate.
PERTAINS to: refactor_new.pl
CWD: models/lnd/clm/tools/clm4_5/refactorTools/associate

Contents:

I) What happened in clm4_5_15
II) suggestions for how to merge your current sandbox up to trunk
III) hand modifications

=================================================================

I) What happened in clm4_5_15

Removed pointer declarations and move existing pointer assignements inside
of new associate blocks.  A portion of the diffs from biogeophys/FracWetMod.F90 
below show the refactor applied.

-    real(r8), pointer :: h2ocan(:)         ! total canopy water (mm H2O)
-!
-! local pointers to implicit out arguments
-!
-    real(r8), pointer :: fwet(:)           ! fraction of canopy that is wet (0 to 1)
-    real(r8), pointer :: fdry(:)           ! fraction of foliage that is green and dry [-] (new)
-!
-!
-! !OTHER LOCAL VARIABLES:
 !EOP
 !
     integer  :: fp,p             ! indices
@@ -80,15 +64,16 @@
     real(r8) :: dewmxi           ! inverse of maximum allowed dew [1/mm]
 !-----------------------------------------------------------------------
 
-    ! Assign local pointers to derived subtypes components (pft-level)
 
-    frac_veg_nosno => pps%frac_veg_nosno
-    dewmx => pps%dewmx
-    elai => pps%elai
-    esai => pps%esai
-    h2ocan => pws%h2ocan
-    fwet => pps%fwet
-    fdry => pps%fdry
+   associate(& 
+   frac_veg_nosno     => pps%frac_veg_nosno , & ! Input:  [integer (:)]  fraction of veg not covered by snow (0/1 now) [-]
+   dewmx              => pps%dewmx          , & ! Input:  [real(r8) (:)]  Maximum allowed dew [mm]                
+   elai               => pps%elai           , & ! Input:  [real(r8) (:)]  one-sided leaf area index with burying by snow
+   esai               => pps%esai           , & ! Input:  [real(r8) (:)]  one-sided stem area index with burying by snow
+   h2ocan             => pws%h2ocan         , & ! Input:  [real(r8) (:)]  total canopy water (mm H2O)             
+   fwet               => pps%fwet           , & ! Output: [real(r8) (:)]  fraction of canopy that is wet (0 to 1) 
+   fdry               => pps%fdry             & ! Output: [real(r8) (:)]  fraction of foliage that is green and dry [-] (new)
+   )
 
     ! Compute fraction of canopy that is wet and dry
 
@@ -114,6 +99,7 @@
        end if
     end do
 
-  end subroutine FracWet
+    end associate 
+   end subroutine FracWet

In order to convert code in a semi-automated way, we used a script, refactor_new.pl which parses a given 
piece of source code and does this conversion automatically.  There were many areas where we had to 
modify code by hand.  These hand modifications are listed in section III.

Once this was complete, testing ran as expected.

II) suggestions for how to merge your current sandbox up to trunk

NOTE:  The associate modifications are BFB.  Any changes you may see are due to your code modifications.

This is a work in progress and we will have to see how the process evolves in merging old with new code.  I recommend
checking any file by hand using a tool that allows you to view two files with visual delineation of code mods (gvimdiff,
eclipse, etc...)

   - Ideally, make your branch and branch-tags from at least clm4_5_15.  If you have a sandbox based on 
      an older trunk-tag you will have to merge in the changes yourself.  If you have to do this:
         1) Update branch to clm4_5_10 and run test suite.  Use models/lnd/clm/tools/clm4_5/refactorTools/clmType/README as a guide
            the refactor_new.pl script we provide and try to apply the refactoring in a semi-automated way.
         2) Update to clm4_5_14 and run test suite.  clm4_5_14 is a prepatory step to the clm4_5_15 refactor.  
         3) Update to clm4_5_15 and run test suite.  There are many ways to approach this, among them...
            a) Use refactorAssociate.pl on your branch before you update to 4_5_15
            b) Apply the associate refactor manually then merge in 4_5_15
            c) merge in 4_5_15, then resolve your conflicts

III) Some rough notes as to the hand-modifications that you may encounter.

 - CNDcompCascadeMod_BGC.F90 doesn't have associate and 'end associate stuff
 - CNDecompCascadeMod_BGC - add     real(r8), allocatable:: fr(:,:)
 - remove c13 check in clm_atmlnd.F90 so that clm_a2l%forc_pc13o2 is initialized
 - put in ifdef LCH4 for biogeophys/CanopyFluxesMod.F90 for grnd_ch4_cond and canopy_cond
 - put in ifdef CH for rc13_* variables.  make other mods for rc14_* variables
 - mods in biogeophys/SLakeTemperatureMod.F90 for LCH4 ifdef
 - mods in biogeophys/SoilHydrologyMod.F90 for VIC pointer b_infil, max_moist
 - mods in biogeochem/CNMRespMod.F90 -- grainn, take out croplive
 - mods in CNAllocationMod.F90 - put back in #ifndef NITRIF_DENITRIF in associate statement
 - move gddmaturity,huileaf out of crop_prog check in clmtypeInitMod.F90 - actually many mods here.  lots of stuff that had to be moved out of the prog_crop check because pointers were otherwise uninitialized.  moved htmx out of crop_prog
 - biogeochem/CNNStateupdate1Mod.F90 - put back NITRIF_DENIRIF
 - main/clmtypeInitMod.F90 - remove all use_c13 and use_c14.  these don't work with conditional assignments when using associate
 - biogeochem/CNVegStructUpdateMod.F90 - put back ifdef cndv in associate block
 - CNSummaryMod.F90 - add back ifdef CNDV and NITRIF_DENITRIF statement in associate block
 - biogeochem/CNAnnualUpdateMod.F90 - putback CNDV in associate block
 - biogeochem/CNBalanceCheckMod.F90 - putback CNDV in associate block
 - biogeochem/CNDecompMod.F90 - put back CH4 and else part of NITRIF_DENITRIF
 - biogeochem/CNNSTateUpdate3Mod.F90 - put back CH4 and else part of NITRIF_DENITRIF
 - biogeochem/CNPrecisionControlMod - put back CH4 and else part of NITRIF_DENITRIF
