%
% Earth System Modeling Framework
% Copyright (c) 2002-2023, University Corporation for Atmospheric Research, 
% Massachusetts Institute of Technology, Geophysical Fluid Dynamics 
% Laboratory, University of Michigan, National Centers for Environmental 
% Prediction, Los Alamos National Laboratory, Argonne National Laboratory, 
% NASA Goddard Space Flight Center.
% Licensed under the University of Illinois-NCSA License.

A location stream (LocStream) can be used to represent the locations of
a set of data points.  For example, in the data assimilation world, 
LocStreams can be used to represent a set of observations.  The values 
of the data points are stored within a Field or FieldBundle created 
using the LocStream.

The locations are generally described using Cartesian (x, y, z), or 
(lat, lon, radius) coordinates.  The coordinates are stored using 
constructs called {\it keys}.  A Key is essentially a list of point 
descriptors, one for each data point.  They may hold other information 
besides the coordinates - a mask, for example.  They may also hold a 
second set of coordinates.    Keys are referenced by name - see 
\ref{const:coordkeyname} and \ref{const:maskkeyname} for specific 
keynames required in regridding.  Each key must contain the same 
number of elements as there are data points in the LocStream.  While 
there is no assumption in the ordering of the points, the order 
chosen must be maintained in each of the keys.

LocStreams can be very large. Data assimilation systems might use
LocStreams with up to $10^{8}$ observations, so efficiency is critical.
LocStreams can be created from file, see \ref{locstream:createfromfile}.

Common operations involving LocStreams are similar to those involving Grids.
For example, LocStreams allow users to:

\begin{enumerate}
\item Create a Field or FieldBundle on a LocStream
\item Regrid data in Fields defined on LocStreams
\item Redistribute data between Fields defined on LocStreams
\item Gather or scatter a FieldBundle defined on a LocStream from/to a root DE
\item Extract Fortran array from Field which was defined on a LocStream
\end{enumerate}


%The operations on the Fortran arrays underlying LocStreams are usually simple numerical ones. However,
%it is necessary to sort them in place, and access only portions of the them. It would
%not be efficient to continually create new LocStreams to reflect this sorting. Instead,
%the sorting is managed by the application through permutation arrays while keeping
%the data in place. Locations can become inactive, e.g., if the quality control asserts that
%observation is invalid. This can be managed again by the application through masks.

A LocStream differs from a Grid in that no topological structure is
maintained between the points
(e.g. the class contains no information about which point is the neighbor
of which other point).

A LocStream is similar to a Mesh in that both are collections of irregularly positioned 
points.  However, the two structures differ because a Mesh also has connectivity: 
each data point represents either a center or corner of a cell. There is no requirement that the
points in a LocStream have connectivity, in fact there is no requirement that any two points 
have any particular spatial relationship at all.
