[Dart-dev] DART/branches Revision: 12371

dart at ucar.edu dart at ucar.edu
Fri Jan 19 16:08:14 MST 2018

nancy at ucar.edu
2018-01-19 16:08:13 -0700 (Fri, 19 Jan 2018)
added a new 'Usage' section which discusses issues
in using the location module in 'filter'.

Modified: DART/branches/rma_trunk/assimilation_code/location/threed_sphere/location_mod.html
--- DART/branches/rma_trunk/assimilation_code/location/threed_sphere/location_mod.html	2018-01-19 17:51:37 UTC (rev 12370)
+++ DART/branches/rma_trunk/assimilation_code/location/threed_sphere/location_mod.html	2018-01-19 23:08:13 UTC (rev 12371)
@@ -25,7 +25,9 @@
+<A HREF="#Usage Notes">USAGE</A> /
 <A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#Discussion">DISCUSSION</A> /
 <A HREF="#Interface">INTERFACES</A> /
 <A HREF="#FilesUsed">FILES</A> /
 <A HREF="#References">REFERENCES</A> /
@@ -53,10 +55,377 @@
 component with choices of vertical coordinate type such as pressure or 
 height in meters.
 A type that abstracts the location is provided along
-with operators to set, get, read, write, and compute distances between 
-locations. This is a member of a class of similar location modules that 
-provide the same abstraction for different represenations of physical space.
+with operators to set, get, read, write, and compute great circle
+distances between locations. This is a member of a class of similar 
+location modules that provide the same abstraction for different represenations 
+of physical space.
+<!--===================== USAGE NOTES ===================================-->
+<A NAME="Usage Notes"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+The location routines are general purpose code that can be used
+for a variety of utilities.  The following discussion is specifically
+restricted to how the location namelist settings affect the
+execution of the <em class=file>filter</em> assimilation program.
+Issues related to changing the results of an assimilation based on the location
+module settings:<br />
+<LI>Whether and how to treat the vertical separation when computing distances 
+between two locations.</LI>
+<LI>Whether to use different distances in the vertical for different
+observation types.</LI>
+Issues related to changing the results of an assimilation based on 
+code in the model-specific <em class=code>model_mod.f90</em> module:<br />
+<LI>Whether the model-specific code needs to convert vertical coordinates.</LI>
+<LI>Whether the model-specific code alters the distances in some other way.</LI>
+Issues related to the speed/efficiency of an assimilation based on the location
+module settings:<br />
+<LI>Whether to use a faster but less precise distance computation.</LI>
+<LI>Whether to change the number of internal bins used to
+more quickly find nearby locations.</LI>
+<H4>Vertical Issues</H4>
+The localization distance during an assimilation -- the maximum separation
+between an observation and a state vector item potentially affected by
+the assimilation -- is set in the
+<a href="../../modules/assimilation/assim_tools_mod.html">&assim_tools_nml</a>
+namelist (the <em class=code>cutoff</em> item).
+Setting <em class=code>horiz_dist_only = .TRUE.</em> in the
+namelist means the great circle distances will be computed using only
+the latitude and longitudes of the two locations, ignoring
+the vertical components of the locations.  The cutoff is specified in
+radians to be independent of the radius of the sphere.  For
+the Earth the radius is nominally 6,371 Km.  To compute the horizontal
+only localization distance, multiply 6,371 Km by the cutoff to get the 
+distance in Km.  The cutoff is by definition 1/2 the distance to where
+the increments go to 0, so multiply that result by 2 to get the maximum
+distance at which an observation can alter the state.
+Setting <em class=code>horiz_dist_only = .FALSE.</em> in the
+namelist means the code will compute a 3D distance, including the
+vertical separation.  In this case, the <em class=code>vert_normalization_xxx</em>
+namelist values will be used to convert from pressure, height, model level,
+or scale heights into radians so the distances are computed in a consistent
+unit system.  In practice, multiply the cutoff by the normalization factor
+(and then again by 2) to get the maximum vertical separation in each of
+the given units.  

More information about the Dart-dev mailing list