polished index mapping readme

INDEX_MAP_README.txt

-CLM/ELM indexes column variables in a manner that cannot be reproduced using C++. In this project, 
-we use basic C-style arrays with an index starting at 0 for storage of column data. Described below 
-are the conventions we use to map column data indices between CLM/ELM and this project.  
+CLM/ELM column variables are indexed in a manner that result in the top subsurface layer's 
+index = 1 in every type of column-based data structure. This indexing cannot be reproduced 
+using the basic subset of C++ we have constrained ourselves to without introducing unacceptable 
+overhead. 
 
-SUBSURFACE VARIABLES (CLM example: (1:nlevgrnd) or (1:nlevsoi))
+In this project,we use basic C-style arrays with an index starting at 0 for storage of all column 
+data. This shouldn't cause problems, but will require index conversion to occur throughout the 
+code, and special consideration when concurrently operating on subsurface only and above ground 
+data.  Described below are the conventions we use to map column data indices between CLM/ELM and 
+this project.  
+
+SUBSURFACE ONLY VARIABLES (CLM example: (1:nlevgrnd) or (1:nlevsoi))
 SHIFT CLM INDEX BY -1
 CLM/ELM variables that exist only in the subsurface are indexed top to bottom from 1:nlevgrnd (typically 15), 
 where var(1) is the topmost layer, and var(nlevgrnd) is the bottom layer. This project's equivalent 
@@ -12,14 +19,15 @@ ABOVE SURFACE VARIABLES (CLM example: (-nlevsno+1:0) or (-nlevsno+1:1))
 SHIFT CLM INDEX BY  nlevsno - 1
 CLM/ELM variables that exist on and above the surface (snow, canopy) are indexed from top to bottom,
 like (-nlevcan+1:0) (only above ground component) or (-nlevsno+1:1) (ground surface and above ground component).
-This project's equivalent data structure will be shifted by nlevsno - 1, (or nlevcan - 1) so the top layer is 
-var[0] and the bottom layer is var[nlevsno] (if ground surface included) or var[nlevsno] (if ground surface excluded). 
+This project's equivalent data structure will be shifted by (nlevsno - 1), (or nlevcan - 1) so the top 
+layer is var[0] and the bottom layer is var[nlevsno] (if ground surface included) or var[nlevsno - 1] 
+(if ground surface excluded). 
 
 SURFACE SUBSURFACE VARIABLES (CLM example: (-nlevsno+1:nlevgrnd))
 SHIFT CLM INDEX BY  nlevsno - 1
-CLM/ELM variables that exist both in the snowpack/canopy and through the subsurface are indexed from top to bottom,
-following logically from the convention discussed above. This project's equivalent data structure will be shifted by 
-nlevsno - 1, similar to the surface data. The surface/subsurface data
+CLM/ELM variables that exist both in the snowpack/canopy and through the subsurface are indexed from top 
+to bottom, following logically from the convention discussed above. This project's equivalent data structure 
+will be shifted by (nlevsno - 1), similar to the surface data.
 
 
   IMPORTANT INDEX CONVERSIONS:
@@ -29,22 +37,22 @@ nlevsno - 1, similar to the surface data. The surface/subsurface data
 
   ABOVE SURFACE DATA AND ABOVE AND BELOW SURFACE DATA:
   snow or canopy bottom layer (adjacent to ground surface) - CLM: var(0), THIS PROJECT: var[nlevsno-1]
-  surface layer in above surface data (or top subsurface) - CLM: var(1), THIS PROJECT: var[nlevsno]
-  top active snow layer -  CLM: var(snl+1), THIS PROJECT: var[nlevsno-snl] -- snl is neg in CLM, pos here
+  surface/top subsurface layer - CLM: var(1), THIS PROJECT: var[nlevsno]
+  top active snow layer -  CLM: var(snl+1), THIS PROJECT: var[nlevsno-snl] -- snl is negative in CLM, positive here
+  second from top active snow layer -  CLM: var(snl+2), THIS PROJECT: var[nlevsno-snl+1]
   bottom subsurface layer - CLM: var(nlevgrnd), THIS PROJECT: var[nlevgrnd+nlevsno-1]
 
   CONCURRENTLY WORKING WITH SUBSURFACE ONLY AND ABOVE SURFACE DATA:
   subsurface data's index is offset from above surface data by nlevsno  
-    AboveAndBelow[i + nlevsno] is same layer as BelowOnly[i]  
+    AboveAndBelow[i + nlevsno] is same layer as BelowOnly[i],
+  top subsurface layer - AboveAndBelow[nlevsno] & BelowOnly[0]
+  bottom layer - AboveAndBelow[nlevsno + nlevgrnd - 1] & BelowOnly[nlevgrnd - 1]
 
 
-THOUGHTS:
-CLM's data structures conveniently result in the top subsurface layer's index = 1. This library will not be 
-able to reproduce this feature. This shouldn't cause problems, but will require index conversion to occur 
-throughout the code, and special consideration when concurrently operating on subsurface only and above ground data.  
+VISUAL INDEX MAPPING:
 
 ABOVE GROUND DATA
-CLM variable indices      indices
+CLM variable indices    new indices
 |-4|   top snow layer     |0|
  --                       ---
 |-3|   snow layer         |1|
@@ -59,7 +67,7 @@ CLM variable indices      indices
 
 
 ABOVE/BELOW GROUND DATA
-CLM variable indices      indices
+CLM variable indices    new indices
 |-4|   top snow layer     |0|
  --                       ---
 |-3|   snow layer         |1|
@@ -80,11 +88,11 @@ CLM variable indices      indices
 .
 .
 --                        ---
-|nlevgrnd|   botom layer  |nlevgrnd + nlevsno - 1|
+|nlevgrnd|   bottom layer  |nlevgrnd + nlevsno - 1|
 
 
 BELOW GROUND DATA
-CLM variable indices      indices
+CLM variable indices    new indices
 -----  ground interface  ------
 | 1| top subsurface layer |0| 
  --                       ---
@@ -96,4 +104,4 @@ CLM variable indices      indices
 .
 .
 --                        ---
-|nlevgrnd|   botom layer  |nlevgrnd - 1|
\ No newline at end of file
+|nlevgrnd|   bottom layer  |nlevgrnd - 1|