source: CPL/oasis3-mct/branches/OASIS3-MCT_2.0_branch/lib/mct/mpeu/m_SortingTools.F90 @ 4775

!~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!       NASA/GSFC, Data Assimilation Office, Code 910.3, GEOS/DAS      !
!-----------------------------------------------------------------------
! CVS m_SortingTools.F90,v 1.4 2004-04-21 22:54:46 jacob Exp
! CVS MCT_2_8_0  
!BOP -------------------------------------------------------------------
!
! !MODULE: m_SortingTools - A collection of different sorting tools
!
! !DESCRIPTION:
!
!       This module contains a collection of sorting utilities.  The
!   utilities are accessed through three generic interfaces, IndexSet(),
!   IndexSort(), and IndexBin().
!
!       Note that, a version of IndexBin() for real arguments is not
!   implemented due to the difficulty of comparing two real values as
!   being equal.  For example, a bin for real values may be specified
!   as a single number, a range of two numbers, a number with an
!   absolute error-bar, or a number with a relative error-bar.
!
!       In general, one may have to map both keys(:) and bins(:) to
!   integer indices by the a given rule, then use the integer version
!   of IndexBin() with the two integer index arrays to do the sorting.
!   This mapping rule, however, is application dependent.
!
!       Also note that, in principle, it is possible to use both 
!   IndexSort() and IndexBin() in the same sorting task.
!
! !INTERFACE:

    module m_SortingTools

      use m_MergeSorts          !only : IndexSet,IndexSort
      use m_IndexBin_integer    !only : IndexBin
      use m_IndexBin_char       !only : IndexBin
      use m_IndexBin_logical    !only : IndexBin
      use m_rankMerge           !only : RankSet,RankMerge,IndexedRankMerge
      use m_Permuter            !only : Permute, Unpermute

      implicit none

      private   ! except

      public :: IndexSet         ! define an initial list of indices
      public :: IndexSort        ! index for a new rank out of the old
      public :: IndexBin         ! index for sorting bins
      public :: RankSet          ! define an initial list of ranks
      public :: RankMerge        ! merge two arrays by re-ranking
      public :: IndexedRankMerge ! index-merge two array segments
      public :: Permute          ! permute array entries
      public :: Unpermute        ! invert permutation

! !EXAMPLES:
!
!       - An example of using IndexSet()/IndexSort() in combination with
!   the convenience of the Fortran 90 array syntex can be found in the
!   prolog of m_MergeSorts.
!
!       - An example of using IndexSet()/IndexBin(): Copying all "good"
!   data to another array.
!
!       integer :: indx(n)
!       call IndexSet(n,indx)
!       call IndexBin(n,indx,allObs(:)%qcflag,GOOD,ln0=ln_GOOD)
!
!               ! Copy all "good" data to another array
!       goodObs(1:ln_GOOD)=allObs( indx(1:ln_GOOD) )
!
!               ! Refill all "good" data back to their original places
!       allObs( indx(1:ln_GOOD) ) = goodObs(1:ln_GOOD)
!
!       - Similarily, multiple keys may be used in an IndexBin() call
!   to selectively sort the data.  The following code will move data
!   with kt = kt_Us,kt_U,kt_Vs,kt_V up to the front:
!
!       call IndexBin(n,indx,allObs(:)%kt,(/kt_Us,kt_U,kt_Vs,kt_V/))
!       allObs(1:n) = allObs( indx(1:n) )
!
!       - Additional applications can also be implemented with other
!   argument combinations.
!
! !REVISION HISTORY:
!       15Mar00 - Jing Guo
!               . Added m_rankMerge module interface
!       20Apr99 - Jing Guo
!               - Commented "only" in use m_IndexBin_xxx to avoid an
!                 apperent compiler bug on DEC/OSF1
!       17Feb99 - Jing Guo <guo@thunder> - initial prototype/prolog/code
!       19Oct00 - J.W. Larson <larson@mcs.anl.gov> - added Permuter and
!                 Unpermuter to list of public functions.
!EOP ___________________________________________________________________

  character(len=*),parameter :: myname='MCT(MPEU)::m_SortingTools'

end module m_SortingTools