Next: 7 The Global Map Up: 1 Basic API's and Previous: 5 The General Grid Contents
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_NavigatorUSES:
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.
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
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
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.
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
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
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
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:
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
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.
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
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.
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