CRTM_ChannelInfo_Define.f90

Go to the documentation of this file.

!
! CRTM_ChannelInfo_Define
!
! Module defining the CRTM ChannelInfo data structure and containing
! routines to manipulate it.
!       
!
! CREATION HISTORY:
!       Written by:     Paul van Delst, 13-May-2004
!                       paul.vandelst@noaa.gov
!

MODULE crtm_channelinfo_define

  ! -----------------
  ! Environment setup
  ! -----------------
  ! Intrinsic modules
  USE iso_fortran_env      , ONLY: output_unit
  ! Module use
  USE message_handler      , ONLY: success, failure, display_message
  USE file_utility         , ONLY: file_open
  USE crtm_parameters      , ONLY: strlen
  USE sensorinfo_parameters, ONLY: invalid_sensor, &
                                   invalid_wmo_satellite_id, &
                                   invalid_wmo_sensor_id 
  USE sort_utility         , ONLY: insertionsort  
  ! Disable implicit typing
  IMPLICIT NONE


  ! ------------
  ! Visibilities
  ! ------------
  ! Everything private by default
  PRIVATE
  ! Structure definition
  PUBLIC :: crtm_channelinfo_type
  ! Operators
  PUBLIC :: OPERATOR(==)
  ! Structure procedures
  PUBLIC :: crtm_channelinfo_associated
  PUBLIC :: crtm_channelinfo_destroy
  PUBLIC :: crtm_channelinfo_create
  PUBLIC :: crtm_channelinfo_inspect
  PUBLIC :: crtm_channelinfo_defineversion
  PUBLIC :: crtm_channelinfo_n_channels
  PUBLIC :: crtm_channelinfo_channels
  PUBLIC :: crtm_channelinfo_subset


  ! ---------------------
  ! Procedure overloading
  ! ---------------------
  INTERFACE OPERATOR(==)
    MODULE PROCEDURE crtm_channelinfo_equal
  END INTERFACE OPERATOR(==)
  
  
  ! -----------------
  ! Module parameters
  ! -----------------
  ! Version Id for the module
  CHARACTER(*), PARAMETER :: module_version_id = &
  '$Id: CRTM_ChannelInfo_Define.f90 60152 2015-08-13 19:19:13Z paul.vandelst@noaa.gov $'
  ! Message string length
  INTEGER, PARAMETER :: ml = 256
  

  ! --------------------------------
  ! ChannelInfo data type definition
  ! --------------------------------
  !:tdoc+:
  TYPE :: crtm_channelinfo_type
    ! Allocation indicator
    LOGICAL :: is_allocated = .false.
    ! Dimensions
    INTEGER :: n_channels = 0  ! L dimension
    ! Scalar data
    CHARACTER(STRLEN) :: sensor_id        = ''
    INTEGER           :: sensor_type      = invalid_sensor
    INTEGER           :: wmo_satellite_id = invalid_wmo_satellite_id
    INTEGER           :: wmo_sensor_id    = invalid_wmo_sensor_id
    INTEGER           :: sensor_index     = 0
    ! Array data
    LOGICAL, ALLOCATABLE :: process_channel(:)  ! L
    INTEGER, ALLOCATABLE :: sensor_channel(:)   ! L
    INTEGER, ALLOCATABLE :: channel_index(:)    ! L
  END TYPE crtm_channelinfo_type
  !:tdoc-:


CONTAINS


!################################################################################
!################################################################################
!##                                                                            ##
!##                         ## PUBLIC MODULE ROUTINES ##                       ##
!##                                                                            ##
!################################################################################
!################################################################################

!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_Associated
!
! PURPOSE:
!       Elemental function to test the status of the allocatable components
!       of a CRTM ChannelInfo object.
!
! CALLING SEQUENCE:
!       Status = CRTM_ChannelInfo_Associated( ChannelInfo )
!
! OBJECTS:
!       ChannelInfo:   ChannelInfo object which is to have its member's
!                      status tested.
!                      UNITS:      N/A
!                      TYPE:       TYPE(CRTM_ChannelInfo_type)
!                      DIMENSION:  Scalar or any rank
!                      ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       Status:        The return value is a logical value indicating the
!                      status of the ChannelInfo members.
!                        .TRUE.  - if the array components are allocated.
!                        .FALSE. - if the array components are not allocated.
!                      UNITS:      N/A
!                      TYPE:       LOGICAL
!                      DIMENSION:  Same as input ChannelInfo argument
!
!:sdoc-:
!--------------------------------------------------------------------------------

  ELEMENTAL FUNCTION crtm_channelinfo_associated( ChannelInfo ) RESULT( Status )
    TYPE(crtm_channelinfo_type), INTENT(IN) :: channelinfo
    LOGICAL :: status
    status = channelinfo%Is_Allocated
  END FUNCTION crtm_channelinfo_associated
  

!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_Destroy
!
! PURPOSE:
!       Elemental subroutine to re-initialize CRTM ChannelInfo objects.
!
! CALLING SEQUENCE:
!       CALL CRTM_ChannelInfo_Destroy( ChannelInfo )
!
! OBJECTS:
!       ChannelInfo:    Re-initialized ChannelInfo object.
!                       UNITS:      N/A
!                       TYPE:       TYPE(CRTM_ChannelInfo_type)
!                       DIMENSION:  Scalar or any rank
!                       ATTRIBUTES: INTENT(OUT)
!
!:sdoc-:
!--------------------------------------------------------------------------------

  ELEMENTAL SUBROUTINE crtm_channelinfo_destroy( ChannelInfo )
    TYPE(crtm_channelinfo_type), INTENT(OUT) :: channelinfo
    channelinfo%Is_Allocated = .false.
    channelinfo%n_Channels = 0
  END SUBROUTINE crtm_channelinfo_destroy

  
!--------------------------------------------------------------------------------
!
! NAME:
!       CRTM_ChannelInfo_Create
!
! PURPOSE:
!       Elemental subroutine to create an instance of a CRTM ChannelInfo
!       object.
!
! CALLING SEQUENCE:
!       CALL CRTM_ChannelInfo_Create( ChannelInfo, n_Channels )
!
! OBJECTS:
!       ChannelInfo:       ChannelInfo object.
!                          UNITS:      N/A
!                          TYPE:       TYPE(CRTM_ChannelInfo_type)
!                          DIMENSION:  Scalar or any rank
!                          ATTRIBUTES: INTENT(OUT)
!
! INPUTS:
!       n_Channels:        The number of channels in the ChannelInfo structure.
!                          Must be > 0.
!                          UNITS:      N/A
!                          TYPE:       INTEGER
!                          DIMENSION:  Conformable with ChannelInfo argument
!                          ATTRIBUTES: INTENT(IN)
!
!:sdoc-:
!--------------------------------------------------------------------------------

  ELEMENTAL SUBROUTINE crtm_channelinfo_create( &
    ChannelInfo, &
    n_Channels   )
    ! Arguments
    TYPE(crtm_channelinfo_type), INTENT(OUT) :: channelinfo
    INTEGER,                     INTENT(IN)  :: n_channels
    ! Local variables
    INTEGER :: alloc_stat

    ! Check input
    IF ( n_channels < 1 ) RETURN


    ! Perform the allocations.
    ALLOCATE( channelinfo%Process_Channel( n_channels ), &
              channelinfo%Sensor_Channel( n_channels ), &
              channelinfo%Channel_Index( n_channels ), &
              stat = alloc_stat )
    IF ( alloc_stat /= 0 ) RETURN


    ! Initialise
    ! ...Dimensions
    channelinfo%n_Channels = n_channels
    ! ...Arrays
    channelinfo%Process_Channel = .true.
    channelinfo%Sensor_Channel  = 0
    channelinfo%Channel_Index   = 0


    ! Set allocation indicator
    channelinfo%Is_Allocated = .true.

  END SUBROUTINE crtm_channelinfo_create


!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_Inspect
!
! PURPOSE:
!       Subroutine to print the contents of a CRTM ChannelInfo object
!       to stdout.
!
! CALLING SEQUENCE:
!       CALL CRTM_ChannelInfo_Inspect( chInfo, Unit=unit )
!
! OBJECTS:
!       chInfo:  ChannelInfo object to display.
!                UNITS:      N/A
!                TYPE:       TYPE(CRTM_ChannelInfo_type)
!                DIMENSION:  Scalar
!                ATTRIBUTES: INTENT(IN)
!
! OPTIONAL INPUTS:
!       Unit:    Unit number for an already open file to which the output
!                will be written.
!                If the argument is specified and the file unit is not
!                connected, the output goes to stdout.
!                UNITS:      N/A
!                TYPE:       INTEGER
!                DIMENSION:  Scalar
!                ATTRIBUTES: INTENT(IN), OPTIONAL
!
!:sdoc-:
!--------------------------------------------------------------------------------

  SUBROUTINE crtm_channelinfo_inspect( chInfo, Unit )
    ! Arguments
    TYPE(crtm_channelinfo_type), INTENT(IN) :: chinfo
    INTEGER,           OPTIONAL, INTENT(IN) :: unit
    ! Local variables
    INTEGER :: fid
    INTEGER :: i
    CHARACTER(3) :: process
    
    ! Setup
    fid = output_unit
    IF ( PRESENT(unit) ) THEN
      IF ( file_open(unit) ) fid = unit
    END IF


    WRITE(fid,'(1x,"ChannelInfo OBJECT")')
    WRITE(fid,'(3x,"n_Channels       :",1x,i0)') chinfo%n_Channels
    WRITE(fid,'(3x,"Sensor Id        :",1x,a )') trim(chinfo%Sensor_ID)
    WRITE(fid,'(3x,"Sensor_Type      :",1x,i0)') chinfo%Sensor_Type
    WRITE(fid,'(3x,"WMO_Satellite_ID :",1x,i0)') chinfo%WMO_Satellite_ID
    WRITE(fid,'(3x,"WMO_Sensor_ID    :",1x,i0)') chinfo%WMO_Sensor_ID   
    WRITE(fid,'(3x,"Sensor_Index     :",1x,i0)') chinfo%Sensor_Index    
    IF ( .NOT. crtm_channelinfo_associated(chinfo) ) RETURN
    WRITE(fid,'(3x,"Channel#     Index     Process?")')
    DO i = 1, chinfo%n_Channels
      IF ( chinfo%Process_Channel(i) ) THEN
        process = 'yes'
      ELSE
        process = 'no'
      END IF
      WRITE(fid,'(4x,i5,7x,i5,8x,a)') &
        chinfo%Sensor_Channel(i), chinfo%Channel_Index(i), process
    END DO
  END SUBROUTINE crtm_channelinfo_inspect


!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_n_Channels
!
! PURPOSE:
!       Elemental function to return the number of channels flagged for 
!       processing in a ChannelInfo object.
!
! CALLING SEQUENCE:
!       n_Channels = CRTM_ChannelInfo_n_Channels( ChannelInfo )
!
! OBJECTS:
!       ChannelInfo: ChannelInfo object which is to have its processed 
!                    channels counted.
!                    UNITS:      N/A
!                    TYPE:       TYPE(CRTM_ChannelInfo_type)
!                    DIMENSION:  Scalar or any rank
!                    ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       n_Channels:  The number of channels to be processed in the ChannelInfo
!                    object.
!                    UNITS:      N/A
!                    TYPE:       INTEGER
!                    DIMENSION:  Same as input ChannelInfo argument.
!
!:sdoc-:
!--------------------------------------------------------------------------------

  ELEMENTAL FUNCTION crtm_channelinfo_n_channels( ChannelInfo ) RESULT( n_Channels )
    TYPE(crtm_channelinfo_type), INTENT(IN) :: channelinfo
    INTEGER :: n_channels
    n_channels = count(channelinfo%Process_Channel)
  END FUNCTION crtm_channelinfo_n_channels


!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_Channels
!
! PURPOSE:
!       Pure function to return the list of channels to be processed in a
!       ChannelInfo object.
!
! CALLING SEQUENCE:
!       Channels = CRTM_ChannelInfo_Channels( ChannelInfo )
!
! OBJECTS:
!       ChannelInfo: ChannelInfo object which is to have its channel list queried.
!                    UNITS:      N/A
!                    TYPE:       TYPE(CRTM_ChannelInfo_type)
!                    DIMENSION:  Scalar
!                    ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       Channels:    The list of channels to be processed in the ChannelInfo
!                    object.
!                    UNITS:      N/A
!                    TYPE:       INTEGER
!                    DIMENSION:  Rank-1
!
!:sdoc-:
!--------------------------------------------------------------------------------

  PURE FUNCTION crtm_channelinfo_channels( ChannelInfo ) RESULT( Channels )
    TYPE(crtm_channelinfo_type), INTENT(IN) :: channelinfo
    INTEGER :: channels(crtm_channelinfo_n_channels(channelinfo))
    channels = pack(channelinfo%Sensor_Channel, mask=channelinfo%Process_Channel)
  END FUNCTION crtm_channelinfo_channels


!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_Subset
!
! PURPOSE:
!       Function to specify a channel subset for processing in the CRTM.
!       By default, ALL channels are processed. This function allows the
!       list of channels that are to be processed to be altered.
!
! CALLING SEQUENCE:
!       Error_Status = CRTM_ChannelInfo_Subset( ChannelInfo   , &
!                                               Channel_Subset, &
!                                               Reset           )
!
! OBJECTS:
!       ChannelInfo:    Valid ChannelInfo object for which a channel subset is
!                       to be specified.
!                       UNITS:      N/A
!                       TYPE:       TYPE(CRTM_ChannelInfo_type)
!                       DIMENSION:  Scalar
!                       ATTRIBUTES: INTENT(IN OUT)
!
! OPTIONAL INPUTS:
!       Channel_Subset: An integer array containing the subset list of channels.
!                       Future calls to the CRTM main functions using the passed
!                       ChannelInfo object will process ONLY the channels
!                       specified in this list.
!                       *** NOTE: This argument is ignored if the Reset optional
!                       *** argument is specified with a .TRUE. value.            
!                       UNITS:      N/A
!                       TYPE:       INTEGER
!                       DIMENSION:  Rank-1
!                       ATTRIBUTES: INTENT(IN), OPTIONAL
!
!       Reset:          Logical flag to reset the ChannelInfo object channel
!                       processing subset to ALL channels.
!                       If == .TRUE.  Future calls to the CRTM main functions using
!                                     the passed ChannelInfo object will process
!                                     ALL the channels
!                          == .FALSE. Procedure execution is equivalent to the Reset
!                                     argument not being specified at all.
!                       UNITS:      N/A
!                       TYPE:       LOGICAL
!                       DIMENSION:  Scalar
!                       ATTRIBUTES: INTENT(IN), OPTIONAL
!
! FUNCTION RESULT:
!       Error_Status:   The return value is an integer defining the error status.
!                       The error codes are defined in the Message_Handler module.
!                       If == SUCCESS the channel subset setting was sucessful
!                          == FAILURE an error occurred
!                       UNITS:      N/A
!                       TYPE:       INTEGER
!                       DIMENSION:  Scalar
!
! COMMENTS:
!       - The ChannelInfo object can be modified by this procedure.
!       - An error in this procedure will DISABLE processing for ALL channels.
!
!:sdoc-:
!--------------------------------------------------------------------------------

  FUNCTION crtm_channelinfo_subset( &
    ChannelInfo   , &  ! In/output
    Channel_Subset, &  ! Optional input
    Reset         ) &  ! Optional input
  result( err_stat )
    ! Arguments
    TYPE(crtm_channelinfo_type), INTENT(IN OUT) :: channelinfo
    INTEGER,           OPTIONAL, INTENT(IN)     :: channel_subset(:)
    LOGICAL,           OPTIONAL, INTENT(IN)     :: reset
    ! Function result
    INTEGER :: err_stat
    ! Local parameters
    CHARACTER(*), PARAMETER :: routine_name = 'CRTM_ChannelInfo_Subset'
    ! Local variables
    CHARACTER(ML) :: msg
    INTEGER :: alloc_stat
    INTEGER :: i, j, n
    INTEGER :: channel_idx(channelinfo%n_channels)
    INTEGER, ALLOCATABLE :: subset_idx(:)
    
    ! Setup
    err_stat = success
    
    ! Process Reset option first
    IF ( PRESENT(reset) ) THEN
      IF ( reset ) THEN
        channelinfo%Process_Channel = .true.
        RETURN
      END IF
    END IF
    
    ! Process channel list
    IF ( PRESENT(channel_subset) ) THEN
      n = SIZE(channel_subset)
      ! Default: turn off all processing
      channelinfo%Process_Channel = .false.
      ! No channels specified
      IF ( n == 0 ) RETURN
      ! Too many specified
      IF ( n > channelinfo%n_Channels ) THEN
        err_stat = failure
        msg = 'Specified Channel_Subset contains too many channels!'
        CALL display_message( routine_name, msg, err_stat ); RETURN
      END IF
      ! Invalid channels specified
      IF ( any(channel_subset < minval(channelinfo%Sensor_Channel)) .OR. &
           any(channel_subset > maxval(channelinfo%Sensor_Channel)) ) THEN
        err_stat = failure
        msg = 'Specified Channel_Subset contains invalid channels!'
        CALL display_message( routine_name, msg, err_stat ); RETURN
      END IF
      ! Allocate subset index array
      ALLOCATE( subset_idx(n),stat=alloc_stat )
      IF ( alloc_stat /= 0 ) THEN
        err_stat = failure
        msg = 'Error allocating subset_idx array'
        CALL display_message( routine_name, msg, err_stat ); RETURN
      END IF
      ! Turn on processing for selected channels
      CALL insertionsort( channelinfo%Sensor_Channel, channel_idx )
      CALL insertionsort( channel_subset, subset_idx )
      j = 1
      channel_loop: DO i = 1, channelinfo%n_Channels
        IF ( channel_subset(subset_idx(j)) == channelinfo%Sensor_Channel(channel_idx(i)) ) THEN
          channelinfo%Process_Channel(channel_idx(i)) = .true.
          j = j + 1
          IF ( j > n ) EXIT channel_loop
        END IF
      END DO channel_loop
      ! Clean up
      DEALLOCATE( subset_idx )
    END IF

  END FUNCTION crtm_channelinfo_subset
  
  
!--------------------------------------------------------------------------------
!:sdoc+:
!
! NAME:
!       CRTM_ChannelInfo_DefineVersion
!
! PURPOSE:
!       Subroutine to return the module version information.
!
! CALLING SEQUENCE:
!       CALL CRTM_ChannelInfo_DefineVersion( Id )
!
! OUTPUTS:
!       Id:    Character string containing the version Id information
!              for the module.
!              UNITS:      N/A
!              TYPE:       CHARACTER(*)
!              DIMENSION:  Scalar
!              ATTRIBUTES: INTENT(OUT)
!
!:sdoc-:
!--------------------------------------------------------------------------------

  SUBROUTINE crtm_channelinfo_defineversion( Id )
    CHARACTER(*), INTENT(OUT) :: id
    id = module_version_id
  END SUBROUTINE crtm_channelinfo_defineversion


!##################################################################################
!##################################################################################
!##                                                                              ##
!##                          ## PRIVATE MODULE ROUTINES ##                       ##
!##                                                                              ##
!##################################################################################
!##################################################################################

!------------------------------------------------------------------------------
!
! NAME:
!       CRTM_ChannelInfo_Equal
!
! PURPOSE:
!       Elemental function to test the equality of two CRTM ChannelInfo objects.
!       Used in OPERATOR(==) interface block.
!
! CALLING SEQUENCE:
!       is_equal = CRTM_ChannelInfo_Equal( x, y )
!
!         or
!
!       IF ( x == y ) THEN
!         ...
!       END IF
!
! OBJECTS:
!       x, y:          Two CRTM ChannelInfo objects to be compared.
!                      UNITS:      N/A
!                      TYPE:       TYPE(CRTM_ChannelInfo_type)
!                      DIMENSION:  Scalar or any rank
!                      ATTRIBUTES: INTENT(IN)
!
! FUNCTION RESULT:
!       is_equal:      Logical value indicating whether the inputs are equal.
!                      UNITS:      N/A
!                      TYPE:       LOGICAL
!                      DIMENSION:  Same as inputs.
!
!------------------------------------------------------------------------------

  ELEMENTAL FUNCTION crtm_channelinfo_equal( x, y ) RESULT( is_equal )
    TYPE(crtm_channelinfo_type) , INTENT(IN)  :: x, y
    LOGICAL :: is_equal

    ! Set up
    is_equal = .false.
   
    ! Check the object association status
    IF ( (.NOT. crtm_channelinfo_associated(x)) .OR. &
         (.NOT. crtm_channelinfo_associated(y))      ) RETURN

    ! Check contents
    ! ...Dimensions
    IF ( x%n_Channels /= y%n_Channels ) RETURN
    ! ...Data
    IF ( (x%Sensor_ID        == y%Sensor_ID       ) .AND. &
         (x%Sensor_Type      == y%Sensor_Type     ) .AND. &
         (x%WMO_Satellite_ID == y%WMO_Satellite_ID) .AND. &
         (x%WMO_Sensor_ID    == y%WMO_Sensor_ID   ) .AND. &
         (x%Sensor_Index     == y%Sensor_Index    ) .AND. &
         all(x%Process_Channel .EQV. y%Process_Channel) .AND. &
         all(x%Sensor_Channel   ==   y%Sensor_Channel ) .AND. &
         all(x%Channel_Index    ==   y%Channel_Index  )       ) &
      is_equal = .true.
                       
  END FUNCTION crtm_channelinfo_equal
 
END MODULE crtm_channelinfo_define