% $Id$
%
% 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.

%TODO: This file started as an exact copy of the Fortran version of this file.
%TODO: Changes were made to correctly reflect the current status of the C API.
%TODO: Eventually this file should be removed again and replaced by a single
%TODO: generic version that can be included for both Fortran and C refdocs.

\label{sec:DistGrid}
The ESMF DistGrid class sits on top of the DELayout class (not currently
directly accessible through the ESMF C API) and holds domain
information in index space. 
A DistGrid object captures the index space topology
and describes its decomposition in terms of DEs. Combined with DELayout and VM
the DistGrid defines the data distribution of a domain decomposition across the
computational resources of an ESMF Component.

The global domain is defined as the union of logically
rectangular (LR) sub-domains or {\em tiles}. The DistGrid create methods allow
the specification of such a multi-tile global domain and its decomposition into
exclusive, DE-local LR regions according to various degrees of user specified
constraints. Complex index space topologies can be constructed by specifying
connection relationships between tiles during creation.

The DistGrid class holds domain information for all DEs. Each DE is associated
with a local LR region. No overlap of the regions is allowed. The DistGrid
offers query methods that allow DE-local topology information to be extracted,
e.g. for the construction of halos by higher classes.

A DistGrid object only contains decomposable dimensions. The minimum rank for a
DistGrid object is 1. A maximum rank does not exist for DistGrid objects, 
however, ranks greater than 7 may lead to difficulties with respect to the
Fortran API of higher classes based on DistGrid. The rank of a DELayout object
contained within a DistGrid object must be equal to the DistGrid rank. Higher
class objects that use the DistGrid, such as an Array object, may be of
different rank than the associated DistGrid object. The higher class object
will hold the mapping information between its dimensions and the DistGrid
dimensions.
