./DeMo

rmnlib/convert_ip123_int
rmnlib/FLOAT_IP
rmnlib/decode_ip_0
rmnlib/decode_ip_1
rmnlib/decode_ip_2
rmnlib/decode_ip_3
rmnlib/encode_ip_0
rmnlib/encode_ip_1
rmnlib/encode_ip_2
rmnlib/encode_ip_3

rmnlib/convert_ip123_int [ package ]

[ Top ] [ package ]

SYNOPSIS

module convert_ip123_int
use ISO_C_BINDING
implicit none

DESCRIPTION

  set of generic IP123 conversion functions (IP123 from RPN standard files)
  (ip1,ip2,ip3) triplet <-> 3 (real value,kind) pairs

  the Fortran user will call the generic functions
  - encode_ip   (real value,kind) pairs -> (ip1,ip2,ip3) triplet
  - decode_ip   (ip1,ip2,ip3) triplet   -> (real value,kind) pairs
  the kind of arguments will determine which specific conversion function will be used
  (see description of specific functions)
  encode_ip_0, encode_ip_1, encode_ip_2, encode_ip_3
  decode_ip_0, decode_ip_1, decode_ip_2, decode_ip_3

AUTHOR

  M.Valin 2013, 2014

EXAMPLES

!   use ISO_C_BINDING
!   implicit none
!   include 'convert_ip123.inc'
!   integer :: ip1, ip2, ip3, stat
!   integer, dimension(3) :: vip123
!   integer :: k1, k2, k3
!   integer, dimension(3) :: vk123
!   real    :: v1, v2, v3
!   real, dimension(3)    :: v123
!   type(FLOAT_IP) :: RP1,RP2,RP3
!   type(FLOAT_IP), dimension(3) :: VRP123
!
!   stat = encode_ip(ip1,ip2,ip3,v1,k1,v2,k2,v3,k3)  ! everything explicit (encode_ip_2)
!   stat = encode_ip(vip123,v123,vk123)              ! vector version of above (encode_ip_3)
!   stat = encode_ip(ip1,ip2,ip3,RP1,RP2,RP3)        ! ip <- multiple FLOAT_IP  (encode_ip_0)
!   stat = encode_ip(vip123,VRP123)                  ! vector version of above (encode_ip_1)
!
!   stat = decode_ip(v1,k1,v2,k2,v3,k3,ip1,ip2,ip3)  ! everything explicit (decode_ip_2)
!   stat = decode_ip(v123,vk123,vip123)              ! vector version of above (decode_ip_3)
!   stat = decode_ip(RP1,RP2,RP3,ip1,ip2,ip3)        ! ip -> multiple FLOAT_IP  (decode_ip_0)
!   stat = decode_ip(VRP123,vip123)                  ! vector version of above (decode_ip_1)
!
! program testip   ! very simple example of time range coding
!   use ISO_C_BINDING
!   implicit none
!   include 'convert_ip123.inc'
!   integer err
!   type(FLOAT_IP) :: RP1,RP2,RP3
!   integer :: ip1, ip2, ip3
!   RP1%lo=10.   ! 10 mb
!   RP1%hi=10.   ! 10 mb  hi == lo , no range
!   RP1%kind=KIND_PRESSURE
!   RP2%lo=6.    ! 6 hours
!   RP2%hi=16.   ! 16 hours
!   RP2%kind=KIND_HOURS
!   RP3%lo=0.    ! there is a range so an invalid RP3 is OK
!   RP3%hi=0.
!   RP3%kind=-1
!   err= encode_ip(IP1,IP2,IP3,RP1,RP2,RP3)
!   print*, err,IP1,IP2,IP3
!   stop
! end

NOTES

the FORTRAN user must include

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to access this package

individual IP to real value + kind conversions are performed by function convip_plus real value to formatted string encoding is performed by function value_to_string

rmnlib/FLOAT_IP [ type ]

[ Top ] [ type ]

SYNOPSIS

type, BIND(C)  :: FLOAT_IP
real(C_FLOAT)  :: lo         ! low bound
real(C_FLOAT)  :: hi         ! high bound
integer(C_INT) :: kind       ! type code (see table below)
end type

TABLES

 kind     name              description                  range of values

   0  KIND_ABOVE_SEA   height (m) above mean sea level (-20,000 -> 100,000)
   1  KIND_SIGMA       sigma coordinates               (0.0 -> 1.0)
   2  KIND_PRESSURE    pressure (mb)                   (0 -> 1100)
   3  KIND_ARBITRARY   arbitrary number, no units      (-4.8e8 -> 1.0e10)
   4  KIND_ABOVE_GND   height (m) above ground         (-20,000 -> 100,000)
   5  KIND_HYBRID      hybrid coordinates              (0.0 -> 1.0)
   6  KIND_THETA       theta coordinates               (1 -> 200,000)
  10  KIND_HOURS       time (hours)                    (0.0 -> 1.0e10)
  15  KIND_SAMPLES     reserved (integer value)        (0 -> 1 999 999)
  17  KIND_MTX_IND     conversion matrix x subscript)  (1.0 -> 1.0e10)
                       (shared with kind=1 
  21  KIND_M_PRES      pressure-meters                 (0 -> 1,000,000) fact=1E+4
                       (shared with kind=5)

 return FLAGS for encode/decode functions (more than one flag may be set)
  CONVERT_OK     ( 0 = no FLAG set)
  CONVERT_GUESS  (= CONVERT_GOOD_GUESS || CONVERT_BAD_GUESS || CONVERT_TERRIBLE_GUESS)
  CONVERT_GOOD_GUESS
  CONVERT_BAD_GUESS
  CONVERT_TERRIBLE_GUESS
  CONVERT_WARNING
  CONVERT_ERROR

NOTES

the FORTRAN user must include

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to use this derived type and the symbolic names for kind

rmnlib/decode_ip_0 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function decode_ip_0(RP1,RP2,RP3,IP1V,IP2V,IP3V) result(status) BIND (C,name='DecodeIp')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT), value, intent(IN)  :: IP1V,IP2V,IP3V
  type(FLOAT_IP), intent(OUT) :: RP1,RP2,RP3

SUMMARY

 produce valid (real value,kind) pairs from (ip1,ip2,ip3) triplet

INPUTS

  ip1/2/3 should be encoded "new style" but old style encoding is accepted

OUTPUTS

  RP1 will contain a level (or a pair of levels in atmospheric ascending order) in the atmosphere
  RP2 will contain a time (or a pair of times in ascending order)
  RP3%hi will be the same as RP3%lo (if RP1 or RP2 contains a pair, RP3 is ignored)

RESULT

   CONVERT_ERROR          error, (ip1 not level, ip2 not time, etc...)
   CONVERT_OK             everything is OK
   CONVERT_GOOD_GUESS     old style ip1 and/or ip2 are present
   CONVERT_BAD_GUESS      old style ip3, interpreted as time
   CONVERT_TERRIBLE_GUESS old style ip3, interpreted as arbitrary code

 in case of error, RP1/2/3 are undefined (may contain anything)

AUTHOR

  M.Valin 2013

NOTES

this function is C interoperable
some reordering may take place when RP1 or RP2 contains a pair
levels: ip1 will be lower in atmosphere than ip2
times: ip2 will be the end of the time range, ip3 will be the start of the time range
ip1 not a level or ip2 not a time will be flagged as an error
RP1 and RP2 both containing a range will be flagged as an error
in case of error, ip1,2,3 will be returned as -1

the FORTRAN user must

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to access this function

rmnlib/decode_ip_1 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function decode_ip_1(RP,IP) result(status) BIND (C,name='DecodeIp_v')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT), dimension(3), intent(IN)  :: IP
  type(FLOAT_IP), dimension(3), intent(OUT) :: RP

SUMMARY

 vector version of decode_ip_0

RESULT

 same as decode_ip_0

NOTES

(see decode_ip_0)

rmnlib/decode_ip_2 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function decode_ip_2(RP1,kind1,RP2,kind2,RP3,kind3,IP1V,IP2V,IP3V) result(status) BIND(C,name='ConvertIPtoPK')
implicit none

ARGUMENTS

  integer(C_INT) :: status
  real(C_FLOAT),        intent(OUT)  :: RP1,RP2,RP3
  integer(C_INT),        intent(OUT) :: kind1,kind2,kind3
  integer(C_INT), value, intent(IN)  :: IP1V,IP2V,IP3V

SUMMARY

 decode ip1/2/3 into three (value,kind) pairs
 explicit, independent (ip) to (rp,kind) conversion

INPUTS

  IP1V,IP2V,IP3V IP values to be decoded

OUTPUTS

  RP1,kind1  result of IP1V decoding
  RP2,kind2  result of IP2V decoding
  RP3,kind3  result of IP3V decoding

RESULT

   CONVERT_OK           everything is OK
   CONVERT_ERROR        error (bad kind, ip1 not a level, etc ....)
   CONVERT_WARNING      coding convention violations
   CONVERT_GOOD_GUESS   old style ip1 and/or ip2 are present
   CONVERT_BAD_GUESS    old style ip3, interpreted as time
   CONVERT_TERRIBLE_GUESS old style ip3, interpreted as arbitrary code

AUTHOR

  M.Valin 2013

NOTES

this function is C interoperable
in case of error, (value,kind) pairs are undefined (may contain anything)

the FORTRAN user must

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to access this function

rmnlib/decode_ip_3 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function decode_ip_3(RP,kind,IP) result(status) BIND(C,name='ConvertIPtoPK_v')

ARGUMENTS

  integer(C_INT) :: status
  real(C_FLOAT),  dimension(3), intent(OUT) :: RP
  integer(C_INT), dimension(3), intent(OUT) :: kind
  integer(C_INT), dimension(3), intent(IN)  :: IP

SUMMARY

RESULT

 same as decode_ip_2

NOTES

see decode_ip_2

rmnlib/encode_ip_0 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

 FUNCTION encode_ip_0(IP1,IP2,IP3,RP1,RP2,RP3) RESULT(status) BIND (C,name='EncodeIp')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT), intent(OUT) :: IP1,IP2,IP3
  type(FLOAT_IP), intent(IN)  :: RP1,RP2,RP3

SUMMARY

 produce a valid (ip1,ip2,ip3) triplet from (real value,kind) pairs

INPUTS

 RP1 must contain a level (or a pair of levels) in the atmosphere
 RP2 must contain  a time (or a pair of times)
 RP3 may contain anything, RP3%hi will be ignored (if RP1 or RP2 contains a pair, RP3 is ignored)

OUTPUTS

 IP1,IP2,IP3 will contain the encoded values in case of success, and are undefined otherwise

RESULT

 the function returns CONVERT_ERROR in case of error, CONVERT_OK otherwise

NOTES

this function is C interoperable
reordering may happen if RP1 or RP2 contain a pair of values
levels: ip1 will be lower in atmosphere than ip2
times: ip2 will be the end of the time range, ip3 will be the start of the time range
RP1 not a level or RP2 not a time will be flagged as an error
RP1 and RP2 both containing a range will be flagged as an error
in case of error, one or more of ip1,2,3 may be returned as -1

the FORTRAN user must

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to access this function

rmnlib/encode_ip_1 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function encode_ip_1(IP,RP) result(status) BIND (C,name='EncodeIp_v')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT), dimension(3), intent(OUT) :: IP
  type(FLOAT_IP), dimension(3), intent(IN)  :: RP

SUMMARY

 vector version of encode_ip_0

RESULT

 same as encode_ip_0

AUTHOR

  M.Valin 2013

NOTES

(see encode_ip_0)

rmnlib/encode_ip_2 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function encode_ip_2(IP1,IP2,IP3,P1,kkind1,P2,kkind2,P3,kkind3) result(status) BIND(C,name='ConvertPKtoIP')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT),        intent(OUT) :: IP1,IP2,IP3
  real(C_FLOAT), value, intent(IN)   :: P1,P2,P3
  integer(C_INT), value, intent(IN)  :: kkind1,kkind2,kkind3

SUMMARY

 encode three (value,kind) pairs into three ip values

INPUTS

  P1,kkind1 must be a level
  P2,kkind2 should be a time but a level is accepted (and flagged as a WARNING)
  P3,kkind3 may be anything

OUTPUTS

  IP1,IP2,IP3 will contain the encoded values in case of success, and are undefined otherwise

RESULT

     CONVERT_OK           everything is OK
     CONVERT_ERROR        error (kind1 not a level, kind2 not level or time)
     CONVERT_WARNING      coding convention error, corrected

AUTHOR

  M.Valin 2013

NOTES

this function is C interoperable
tolerated coding deviations: kind2 a level instead of a time (will be pushed to position 3 and flagged as warning)
ip1/ip3 forced to the proper atmospheric ascending order coding (not flagged as warning)
ip2/ip3 forced to proper descending order (not flagged as warning)
in case of error, the contents of ip1/2/3 is undefined (possibly -1)

the FORTRAN user must

    use ISO_C_BINDING
    include 'convert_ip123.inc'

in order to access this function

rmnlib/encode_ip_3 [ Functions ]

[ Top ] [ Functions ]

SYNOPSIS

function encode_ip_3(IP,RP,kind) result(status) BIND(C,name='ConvertPKtoIP_v')

ARGUMENTS

  integer(C_INT) :: status
  integer(C_INT), dimension(3), intent(OUT) :: IP
  real(C_FLOAT), dimension(3), intent(IN)   :: RP
  integer(C_INT), dimension(3), intent(IN)  :: kind

SUMMARY

 vector version of encode_ip_2 (ConvertPKtoIP)

RESULT

 same as encode_ip_2

AUTHOR

  M.Valin 2013

NOTES

see encode_ip_2

TABLE OF CONTENTS

rmnlib/convert_ip123_int [ package ]

rmnlib/FLOAT_IP [ type ]

rmnlib/decode_ip_0 [ Functions ]

rmnlib/decode_ip_1 [ Functions ]

rmnlib/decode_ip_2 [ Functions ]

rmnlib/decode_ip_3 [ Functions ]

rmnlib/encode_ip_0 [ Functions ]

rmnlib/encode_ip_1 [ Functions ]

rmnlib/encode_ip_2 [ Functions ]

rmnlib/encode_ip_3 [ Functions ]