Subsections

6 The Navigator

6.1 Module m_Navigator - An Object for Indexing Segments of a Vector (Source File: m_Navigator.F90)

A Navigator is a table used to index or Navigate segments of a vector, or segments of a dimension of a higher-dimensional array. In MCT, this concept is embodied in the Navigator datatype, which contains the following components:

This module defines the Navigator datatype, creation and destruction methods, a variety of query methods, and a method for resizing the Navigator.


INTERFACE:

 
  module m_Navigator
USES:
   No external modules are used in the declaration section of this module.
 
       implicit none
 
       private	! except
PUBLIC TYPES:
 
       public :: Navigator		! The class data structure
 
     Type Navigator
       integer :: NumSegments	! Number of defined Segments
       integer :: VectorLength	! Length of the Vector being indexed
       integer,pointer,dimension(:) :: displs ! Segment start displacements
       integer,pointer,dimension(:) :: counts ! Segment lengths
     End Type Navigator
PUBLIC MEMBER FUNCTIONS:
 
       public :: Navigator_init,init ! initialize an object
       public :: clean               ! clean an object
       public :: NumSegments         ! number of vector segments
       public :: VectorLength        ! indexed vector's total length
       public :: msize               ! the maximum size
       public :: resize              ! adjust the true size
       public :: get                 ! get an entry
       public :: ptr_displs          ! referencing %displs(:)
       public :: ptr_counts          ! referencing %counts(:)
 
     interface Navigator_init; module procedure	&
        init_
     end interface
     interface init  ; module procedure init_  ; end interface
     interface clean ; module procedure clean_ ; end interface
     interface NumSegments ; module procedure  &
        NumSegments_
     end interface
     interface VectorLength ; module procedure  &
        VectorLength_
     end interface
     interface msize ; module procedure msize_ ; end interface
     interface resize; module procedure resize_; end interface
     interface get   ; module procedure get_   ; end interface
     interface ptr_displs; module procedure &
        ptr_displs_
     end interface
     interface ptr_counts; module procedure &
        ptr_counts_
     end interface
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> - initial prototype/prolog/code
   26Aug02 - J. Larson <larson@mcs.anl.gov> - expanded datatype to inlcude
             VectorLength component.

6.1.1 init_ - Create a Navigator

This routine creates a Navigator Nav capable of storing information about NumSegments segments. The user can supply the length of the vector (or array subspace) being indexed by supplying the optional input INTEGER argument VectorLength (if it is not supplied, this component of Nav will be set to zero, signifying to other Navigator routines that vector length information is unavailable). The success (failure) of this operation is signified by the zero (non-zero) value of the optional output INTEGER argument stat.


INTERFACE:

 
     subroutine init_(Nav, NumSegments, VectorLength, stat)
USES:
 
       use m_mall,only : mall_ison,mall_mci
       use m_die ,only : die,perr
       use m_stdio, only : stderr
 
       implicit none
INPUT PARAMETERS:
 
       integer,                   intent(in)  :: NumSegments
       integer,         optional, intent(in)  :: VectorLength
OUTPUT PARAMETERS:
 
       type(Navigator),           intent(out) :: Nav
       integer,         optional, intent(out) :: stat
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> - initial prototype/prolog/code

6.1.2 clean_ - Destroy a Navigator

This routine deallocates allocated memory associated with the input/output Navigator argument Nav, and clears the vector length and number of segments components The success (failure) of this operation is signified by the zero (non-zero) value of the optional output INTEGER argument stat.


INTERFACE:

 
  subroutine clean_(Nav, stat)
USES:
 
       use m_mall, only : mall_ison,mall_mco
       use m_die,  only : warn
 
       implicit none
INPUT/OUTPUT PARAMETERS:
 
       type(Navigator),intent(inout) :: Nav
OUTPUT PARAMETERS:
 
       integer,optional,intent(out) :: stat
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> initial prototype/prolog/code

6.1.3 NumSegments_ - Return the Number of Segments

This INTEGER query function returns the number of segments in the input Navigator argument Nav for which segment start and length information are defined .


INTERFACE:

 
  integer function NumSegments_(Nav)
USES:
 
       implicit none
INPUT PARAMETERS:
 
       type(Navigator), intent(in) :: Nav
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> initial prototype/prolog/code
    1Mar02 - E.T. Ong <eong@mcs.anl.gov> - removed die to prevent crashes.

6.1.4 msize_ - Return the Maximum Capacity for Segment Storage

This INTEGER query function returns the maximum number of segments for which start and length information can be stored in the input Navigator argument Nav.


INTERFACE:

 
  integer function msize_(Nav)
USES:
 
       implicit none
INPUT PARAMETERS:
 
       type(Navigator),intent(in) :: Nav
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> initial prototype/prolog/code

6.1.5 VectorLength_ - Return the Navigated Vector's Length

This INTEGER query function returns the total length of the vector navigated by the input Navigator argument Nav. Note that the vector length is a quantity the user must have set when Nav was initialized. If it has not been set, the return value will be zero.


INTERFACE:

 
  integer function VectorLength_(Nav)
USES:
 
       implicit none
INPUT PARAMETERS:
 
       type(Navigator), intent(in) :: Nav
REVISION HISTORY:
   26Aug02 - J. Larson <larson@mcs.anl.gov> - initial implementation

6.1.6 resize_ - Reset the Number of Segments

This routine resets the number of segments stored in the input/output Navigator argument Nav. It behaves in one of two modes: If the optional INTEGER input argument NumSegments is provided, then this value is taken to be the new number of segments. If this routine is invoked without NumSegments provided, then the new number of segments is set as per the result of the Fortran size() function applied to the segment table arrays.


INTERFACE:

 
  subroutine resize_(Nav, NumSegments)
USES:
    
       use m_stdio, only : stderr
       use m_die,  only : die
 
       implicit none
INPUT PARAMETERS:
 
       integer,optional,intent(in) :: NumSegments
INPUT/OUTPUT PARAMETERS:
 
       type(Navigator),intent(inout) :: Nav
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> initial prototype/prolog/code

6.1.7 get_ - Retrieve Characteristics of a Segment

This multi-purpose query routine can be used to retrieve various characteristics of a given segment (identified by the input INTEGER argument iSeg) stored in the input Navigator argument Nav:

  1. The displacement of the first element in this segment from the first element of the vector. This quantity is returned in the optional output INTEGER argument displ
  2. The number of elements in this segment. This quantity is returned in the optional output INTEGER argument displ
  3. The index of the first element in this segment This quantity is returned in the optional output INTEGER argument lc.
  4. The index of the final element in this segment This quantity is returned in the optional output INTEGER argument le.
Any combination of the above characteristics may be obtained by invoking this routine with the corresponding optional arguments.


INTERFACE:

 
  subroutine get_(Nav, iSeg, displ, count, lc, le)
USES:
 
       use m_stdio, only : stderr
       use m_die,  only : die
 
       implicit none
INPUT PARAMETERS:
 
       type(Navigator),           intent(in)  :: Nav
       integer,                   intent(in)  :: iSeg
OUTPUT PARAMETERS:
 
       integer,         optional, intent(out) :: displ
       integer,         optional, intent(out) :: count
       integer,         optional, intent(out) :: lc
       integer,         optional, intent(out) :: le
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov>  initial prototype/prolog/code

6.1.8 ptr_displs_ - Returns Pointer to the displs(:) Component

This pointer-valued query function returns a pointer to the displacements information (the displacement of the first element of each segment from the beginning of the vector) contained in the input Navigator argument Nav. It has four basic modes of behavior, depending on which (if any) of the optional input INTEGER arguments lbnd and ubnd are supplied.

  1. If neither lbnd nor ubnd is supplied, then ptr_displs_ returns a pointer to all the elements in the array Nav%displs(:).
  2. If both lbnd and ubnd are supplied, then ptr_displs_ returns a pointer to the segment of the array Nav%displs(lbnd:ubnd).
  3. If lbnd is supplied but ubnd is not, then ptr_displs_ returns a pointer to the segment of the array Nav%displs(lbnd:msize), where msize is the length of the array Nav%displs(:).
  4. If lbnd is not supplied but ubnd is, then ptr_displs_ returns a pointer to the segment of the array Nav%displs(1:ubnd).


INTERFACE:

 
  function ptr_displs_(Nav, lbnd, ubnd)
USES:
 
       use m_stdio, only : stderr
       use m_die,  only : die
  
       implicit none
INPUT PARAMETERS:
 
       type(Navigator),           intent(in) :: Nav
       integer,         optional, intent(in) :: lbnd
       integer,         optional, intent(in) :: ubnd
OUTPUT PARAMETERS:
 
       integer,     dimension(:), pointer    :: ptr_displs_
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov> - initial prototype/prolog/code

6.1.9 ptr_counts_ - Returns Pointer to counts(:) Component

This pointer-valued query function returns a pointer to the counts information (that is, the number of elements in each of each segment the vector being navigated) contained in the input Navigator argument Nav. It has four basic modes of behavior, depending on which (if any) of the optional input INTEGER arguments lbnd and ubnd are supplied.

  1. If neither lbnd nor ubnd is supplied, then ptr_counts_ returns a pointer to all the elements in the array Nav%counts(:).
  2. If both lbnd and ubnd are supplied, then ptr_counts_ returns a pointer to the segment of the array Nav%counts(lbnd:ubnd).
  3. If lbnd is supplied but ubnd is not, then ptr_counts_ returns a pointer to the segment of the array Nav%counts(lbnd:msize), where msize is the length of the array Nav%counts(:).
  4. If lbnd is not supplied but ubnd is, then ptr_counts_ returns a pointer to the segment of the array Nav%counts(1:ubnd).


INTERFACE:

 
  function ptr_counts_(Nav, lbnd, ubnd)
USES:
 
       use m_stdio, only : stderr
       use m_die,  only : die
 
       implicit none
INPUT PARAMETERS:
 
       type(Navigator),           intent(in) :: Nav
       integer,         optional, intent(in) :: lbnd
       integer,         optional, intent(in) :: ubnd
OUTPUT PARAMETERS:
 
       integer, dimension(:),     pointer    :: ptr_counts_
REVISION HISTORY:
   22May00 - Jing Guo <guo@dao.gsfc.nasa.gov>- initial prototype/prolog/code


jacob@mcs.anl.gov