nf_fread2d_bry.F

Go to the documentation of this file.

#include "cppdefs.h"
      MODULE nf_fread2d_bry_mod
!
!git $Id$
!================================================== Hernan G. Arango ===
!  Copyright (c) 2002-2025 The ROMS Group                              !
!    Licensed under a MIT/X style license                              !
!    See License_ROMS.md                                               !
!=======================================================================
!                                                                      !
!  This module reads in a generic floating point 2D boundary array     !
!  from input file using either the standard NetCDF library or the     !
!  Parallel-IO (PIO) library.                                          !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     ng           Nested grid number (integer)                        !
!     model        Calling model identifier (integer)                  !
!     ncname       NetCDF output file name (string)                    !
!     ncvname      NetCDF variable name (string)                       !
!     ncid         NetCDF file ID (integer)                            !
#if defined PIO_LIB && defined DISTRIBUTE
!or   pioFile      PIO file descriptor structure, TYPE(file_desc_t)    !
!                    pioFile%fh         file handler                   !
!                    pioFile%iosystem   IO system descriptor (struct)  !
#endif
!     ncvarid      NetCDF variable ID (integer)                        !
#if defined PIO_LIB && defined DISTRIBUTE
!or   pioVar       PIO variable descriptor structure, TYPE(My_VarDesc) !
!                    pioVar%vd     variable descriptor TYPE(Var_Desc_t)!
!                    pioVar%dkind  variable data kind                  !
!                    pioVar%gtype  variable C-gridtype                 !
#endif
!     tindex       NetCDF time record index to write (integer)         !
!     gtype        Grid type (integer)                                 !
#if defined PIO_LIB && defined DISTRIBUTE
!or   pioDesc      IO data decomposition descriptor, TYPE(IO_desc_t)   !
#endif
!     LBij         IJ-dimension Lower bound (integer)                  !
!     UBij         IJ-dimension Upper bound (integer)                  !
!     Nrec         Number of boundary records (integer)                !
!     Ascl         Factor to scale field before writing (real)         !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     Amin         Field minimum value (real)                          !
!     Amax         Field maximum value (real)                          !
!     Abry         2D boundary field to read in (real array)           !
!     checksum     Field checksum value (integer*8; OPTIONAL)          !
!                                                                      !
!     status       Error flag (integer)                                !
!                                                                      !
!=======================================================================
!
      USE mod_param
      USE mod_parallel
      USE mod_iounits
      USE mod_ncparam
      USE mod_scalars
 
#ifdef DISTRIBUTE
!
      USE distribute_mod, ONLY : mp_bcastf
#endif
      USE get_hash_mod,   ONLY : get_hash
      USE strings_mod,    ONLY : founderror
!
      implicit none
!
      INTERFACE nf_fread2d_bry
        MODULE PROCEDURE nf90_fread2d_bry
#if defined PIO_LIB && defined DISTRIBUTE
        MODULE PROCEDURE pio_fread2d_bry
#endif
      END INTERFACE nf_fread2d_bry
!
      CONTAINS
!
!***********************************************************************
      FUNCTION nf90_fread2d_bry (ng, model, ncname, ncid,               &
     &                           ncvname, ncvarid,                      &
     &                           tindex, gtype,                         &
     &                           LBij, UBij, Nrec,                      &
     &                           Ascl, Amin, Amax,                      &
     &                           Abry, checksum)  RESULT(status)
!***********************************************************************
!
      USE mod_netcdf
!
!  Imported variable declarations.
!
      integer, intent(in) :: ng, model, ncid, ncvarid, tindex, gtype
      integer, intent(in) :: lbij, ubij, nrec
!
      integer(i8b), intent(out), optional :: checksum
!
      real(dp), intent(in)  :: ascl
      real(r8), intent(out) :: amin
      real(r8), intent(out) :: amax
!
      character (len=*), intent(in) :: ncname
      character (len=*), intent(in) :: ncvname
 
#ifdef ASSUMED_SHAPE
      real(r8), intent(out) :: abry(lbij:,:,:)
#else
      real(r8), intent(out) :: abry(lbij:ubij,4,nrec)
#endif
!
!  Local variable declarations.
!
      logical :: lchecksum
      logical, dimension(3) :: foundit
      logical, dimension(4) :: bounded
!
      integer :: bc, ghost, i, ib, ic, ij, ir, j, tile
      integer :: cgrid, iorj, imin, imax, jmin, jmax, npts
      integer :: istr, iend, jstr, jend
      integer, dimension(4) :: start, total
 
      integer :: status
!
      real(r8) :: afactor, aoffset, aspval
!
      real(r8), allocatable :: cwrk(:)           ! used for checksum
 
      real(r8), dimension(3) :: attvalue
 
#if !defined PARALLEL_IO && defined DISTRIBUTE
      real(r8), dimension(3) :: rbuffer
#endif
      real(r8), dimension(LBij:UBij,4,Nrec) :: wrk
!
      character (len=12), dimension(3) :: attname
 
      character (len=*), parameter :: myfile =                          &
     &  __FILE__//", pio_fread2d_bry"
!
!-----------------------------------------------------------------------
!  Set starting and ending indices to process.
!-----------------------------------------------------------------------
!
      status=nf90_noerr
!
!  Set first and last grid point according to staggered C-grid
!  classification.
!
!  Notice that (Imin,Jmin) and (Imax,Jmax) are the corner of the
!  computational tile. If ghost=0, ghost points are not processed.
!  They will be processed elsewhere by the appropriate call to any
!  of the routines in "mp_exchange.F".  If ghost=1, the ghost points
!  are read.
!
      IF (model.eq.iadm) THEN
        ghost=0                      ! non-overlapping, no ghost points
      ELSE
        ghost=1                      ! overlapping, read ghost points
      END IF
!
      SELECT CASE (gtype)
        CASE (p2dvar, p3dvar)
          cgrid=1
        CASE (r2dvar, r3dvar)
          cgrid=2
        CASE (u2dvar, u3dvar)
          cgrid=3
        CASE (v2dvar, v3dvar)
          cgrid=4
        CASE DEFAULT
          cgrid=2
      END SELECT
!
#ifdef DISTRIBUTE
      tile=myrank
      imin=bounds(ng)%Imin(cgrid,ghost,tile)
      imax=bounds(ng)%Imax(cgrid,ghost,tile)
      jmin=bounds(ng)%Jmin(cgrid,ghost,tile)
      jmax=bounds(ng)%Jmax(cgrid,ghost,tile)
#else
      tile=-1
      imin=lbij
      imax=ubij
      jmin=lbij
      jmax=ubij
#endif
!
      iorj=iobounds(ng)%IorJ
      npts=iorj*4*nrec
!
!  Get tile bounds.
!
      istr=bounds(ng)%Istr (tile)
      iend=bounds(ng)%Iend (tile)
      jstr=bounds(ng)%Jstr (tile)
      jend=bounds(ng)%Jend (tile)
!
!  Set switch to process boundary data by their associated tiles.
!
      bounded(iwest )=domain(ng)%Western_Edge(tile)
      bounded(ieast )=domain(ng)%Eastern_Edge(tile)
      bounded(isouth)=domain(ng)%Southern_Edge(tile)
      bounded(inorth)=domain(ng)%Northern_Edge(tile)
!
!  Set NetCDF dimension counters for processing requested field.
!
      start(1)=1
      total(1)=iorj
      start(2)=1
      total(2)=4
      start(3)=1
      total(3)=nrec
      start(4)=tindex
      total(4)=1
!
!  Check if the following attributes: "scale_factor", "add_offset", and
!  "_FillValue" are present in the input NetCDF variable:
!
!  If the "scale_value" attribute is present, the data is multiplied by
!  this factor after reading.
!  If the "add_offset" attribute is present, this value is added to the
!  data after reading.
!  If both "scale_factor" and "add_offset" attributes are present, the
!  data are first scaled before the offset is added.
!  If the "_FillValue" attribute is present, the data having this value
!  is treated as missing and it is replaced with zero. This feature it
!  is usually related with the land/sea masking.
!
      attname(1)='scale_factor'
      attname(2)='add_offset  '
      attname(3)='_FillValue  '
 
      CALL netcdf_get_fatt (ng, model, ncname, ncvarid, attname,        &
     &                      attvalue, foundit,                          &
     &                      ncid = ncid)
      IF (founderror(exit_flag, noerror, __line__, myfile)) THEN
        status=ioerror
        RETURN
      END IF
 
      IF (.not.foundit(1)) THEN
        afactor=1.0_r8
      ELSE
        afactor=attvalue(1)
      END IF
 
      IF (.not.foundit(2)) THEN
        aoffset=0.0_r8
      ELSE
        aoffset=attvalue(2)
      END IF
 
      IF (.not.foundit(3)) THEN
        aspval=spval_check
      ELSE
        aspval=attvalue(3)
      END IF
!
!  Initialize checsum value.
!
      IF (PRESENT(checksum)) THEN
        lchecksum=.true.
        checksum=0_i8b
      ELSE
        lchecksum=.false.
      END IF
!
!-----------------------------------------------------------------------
!  Read in requested data and scale it.
!-----------------------------------------------------------------------
!
      wrk=0.0_r8
 
      IF (inpthread) THEN
        status=nf90_get_var(ncid, ncvarid, wrk(lbij:,:,:), start, total)
        IF (status.eq.nf90_noerr) THEN
          amin=spval
          amax=-spval
          DO ir=1,nrec
            DO ib=1,4
              DO ij=lbij,ubij
                IF (abs(wrk(ij,ib,ir)).ge.abs(aspval)) THEN
                  wrk(ij,ib,ir)=0.0_r8
                ELSE
                  wrk(ij,ib,ir)=ascl*(afactor*wrk(ij,ib,ir)+aoffset)
                  amin=min(amin,wrk(ij,ib,ir))
                  amax=max(amax,wrk(ij,ib,ir))
                END IF
              END DO
            END DO
          END DO
          IF ((abs(amin).ge.abs(aspval)).and.                           &
   &          (abs(amax).ge.abs(aspval))) THEN
            amin=0.0_r8                       ! the entire data is all
            amax=0.0_r8                       ! field value, _FillValue
          END IF
!
          IF (lchecksum) THEN
            npts=(ubij-lbij+1)*nrec*4
            IF (.not.allocated(cwrk)) allocate ( cwrk(npts) )
            cwrk=pack(wrk(lbij:ubij, 1:4, 1:nrec), .true.)
            CALL get_hash (cwrk, npts, checksum)
            IF (allocated(cwrk)) deallocate (cwrk)
          END IF
        END IF
      END IF
 
#if !defined PARALLEL_IO && defined DISTRIBUTE
!
      rbuffer(1)=real(status,r8)
      rbuffer(2)=amin
      rbuffer(3)=amax
      CALL mp_bcastf (ng, model, rbuffer)
      status=int(rbuffer(1))
      amin=rbuffer(2)
      amax=rbuffer(3)
#endif
!
      IF (founderror(status, nf90_noerr, __line__, myfile)) THEN
        exit_flag=2
        ioerror=status
        RETURN
      END IF
 
#if !defined PARALLEL_IO && defined DISTRIBUTE
!
!  Broadcast data to all spawned nodes.
!
      CALL mp_bcastf (ng, model, wrk)
#endif
!
!-----------------------------------------------------------------------
!  Unpack read data.
!-----------------------------------------------------------------------
!
      abry=0.0_r8
 
      DO ir=1,nrec
        DO ib=1,4
          IF (bounded(ib)) THEN
            IF ((ib.eq.iwest).or.(ib.eq.ieast)) THEN
              DO j=jmin,jmax
                abry(j,ib,ir)=wrk(j,ib,ir)
              END DO
            ELSE IF ((ib.eq.isouth).or.(ib.eq.inorth)) THEN
              DO i=imin,imax
                abry(i,ib,ir)=wrk(i,ib,ir)
              END DO
            END IF
          END IF
        END DO
      END DO
!
      RETURN
      END FUNCTION nf90_fread2d_bry
 
#if defined PIO_LIB && defined DISTRIBUTE
!
!***********************************************************************
      FUNCTION pio_fread2d_bry (ng, model, ncname, pioFile,             &
     &                          ncvname, pioVar,                        &
     &                          tindex, pioDesc,                        &
     &                          LBij, UBij, Nrec,                       &
     &                          Ascl, Amin, Amax,                       &
     &                          Abry, checksum)  RESULT(status)
!***********************************************************************
!
      USE mod_pio_netcdf
!
!  Imported variable declarations.
!
      integer, intent(in) :: ng, model, tindex
      integer, intent(in) :: lbij, ubij, nrec
!
      integer(i8b), intent(out), optional :: checksum
!
      real(dp), intent(in)  :: ascl
      real(r8), intent(out) :: amin
      real(r8), intent(out) :: amax
!
      character (len=*), intent(in) :: ncname
      character (len=*), intent(in) :: ncvname
 
# ifdef ASSUMED_SHAPE
      real(r8), intent(out) :: abry(lbij:,:,:)
# else
      real(r8), intent(out) :: abry(lbij:ubij,4,nrec)
# endif
!
      TYPE (file_desc_t), intent(inout) :: piofile
      TYPE (io_desc_t),   intent(inout) :: piodesc
      TYPE (my_vardesc),  intent(inout) :: piovar
!
!  Local variable declarations.
!
      logical :: lchecksum
      logical, dimension(3) :: foundit
      logical, dimension(4) :: bounded
!
      integer :: i, ib, ic, ij, ir, j
      integer :: cgrid, dkind, ghost, gtype, tile
      integer :: iorj, imin, imax, jmin, jmax, npts
      integer :: istr, iend, jstr, jend
      integer, dimension(4) :: start, total
 
      integer :: status
!
      real(r8) :: afactor, aoffset, aspval
!
      real(r8), allocatable :: cwrk(:)           ! used for checksum
 
      real(r8), dimension(3) :: attvalue
 
      real(r8), dimension(LBij:UBij,4,Nrec) :: wrk
!
      character (len=12), dimension(3) :: attname
 
      character (len=*), parameter :: myfile =                          &
     &  __FILE__//", pio_fread2d_bry"
!
!-----------------------------------------------------------------------
!  Set starting and ending indices to process.
!-----------------------------------------------------------------------
!
      status=pio_noerr
 
!  Set first and last grid point according to staggered C-grid
!  classification.
!
!  Notice that (Imin,Jmin) and (Imax,Jmax) are the corner of the
!  computational tile. If ghost=0, ghost points are not processed.
!  They will be processed elsewhere by the appropriate call to any
!  of the routines in "mp_exchange.F".  If ghost=1, the ghost points
!  are read.
!
      IF (model.eq.iadm) THEN
        ghost=0                      ! non-overlapping, no ghost points
      ELSE
        ghost=1                      ! overlapping, read ghost points
      END IF
      dkind=piovar%dkind
      gtype=piovar%gtype
!
      SELECT CASE (gtype)
        CASE (p2dvar, p3dvar)
          cgrid=1
        CASE (r2dvar, r3dvar)
          cgrid=2
        CASE (u2dvar, u3dvar)
          cgrid=3
        CASE (v2dvar, v3dvar)
          cgrid=4
        CASE DEFAULT
          cgrid=2
      END SELECT
!
      tile=myrank
      imin=bounds(ng)%Imin(cgrid,ghost,tile)
      imax=bounds(ng)%Imax(cgrid,ghost,tile)
      jmin=bounds(ng)%Jmin(cgrid,ghost,tile)
      jmax=bounds(ng)%Jmax(cgrid,ghost,tile)
!
      iorj=iobounds(ng)%IorJ
      npts=iorj*4*nrec
!
!  Get tile bounds.
!
      istr=bounds(ng)%Istr(tile)
      iend=bounds(ng)%Iend(tile)
      jstr=bounds(ng)%Jstr(tile)
      jend=bounds(ng)%Jend(tile)
!
!  Set switch to process boundary data by their associated tiles.
!
      bounded(iwest )=domain(ng)%Western_Edge(tile)
      bounded(ieast )=domain(ng)%Eastern_Edge(tile)
      bounded(isouth)=domain(ng)%Southern_Edge(tile)
      bounded(inorth)=domain(ng)%Northern_Edge(tile)
!
!  Set NetCDF dimension counters for processing requested field.
!
      start(1)=1
      total(1)=iorj
      start(2)=1
      total(2)=4
      start(3)=1
      total(3)=nrec
      start(4)=tindex
      total(4)=1
!
!  Check if the following attributes: "scale_factor", "add_offset", and
!  "_FillValue" are present in the input NetCDF variable:
!
!  If the "scale_value" attribute is present, the data is multiplied by
!  this factor after reading.
!  If the "add_offset" attribute is present, this value is added to the
!  data after reading.
!  If both "scale_factor" and "add_offset" attributes are present, the
!  data are first scaled before the offset is added.
!  If the "_FillValue" attribute is present, the data having this value
!  is treated as missing and it is replaced with zero. This feature it
!  is usually related with the land/sea masking.
!
      attname(1)='scale_factor'
      attname(2)='add_offset  '
      attname(3)='_FillValue  '
 
      CALL pio_netcdf_get_fatt (ng, model, ncname, piovar%vd, attname,  &
     &                          attvalue, foundit,                      &
     &                          piofile = piofile)
      IF (founderror(exit_flag, noerror, __line__, myfile)) THEN
        status=ioerror
        RETURN
      END IF
 
      IF (.not.foundit(1)) THEN
        afactor=1.0_r8
      ELSE
        afactor=attvalue(1)
      END IF
 
      IF (.not.foundit(2)) THEN
        aoffset=0.0_r8
      ELSE
        aoffset=attvalue(2)
      END IF
 
      IF (.not.foundit(3)) THEN
        aspval=spval_check
      ELSE
        aspval=attvalue(3)
      END IF
!
!  Initialize checsum value.
!
      IF (PRESENT(checksum)) THEN
        lchecksum=.true.
        checksum=0_i8b
      ELSE
        lchecksum=.false.
      END IF
!
!-----------------------------------------------------------------------
!  Read in 2D boundary data and scale it.
!-----------------------------------------------------------------------
!
      wrk=0.0_r8
 
      status=pio_get_var(piofile, piovar%vd, start, total,              &
     &                   wrk(lbij:,:,:))
      IF (status.eq.pio_noerr) THEN
        amin=spval
        amax=-spval
        DO ir=1,nrec
          DO ib=1,4
            DO ij=lbij,ubij
              IF (abs(wrk(ij,ib,ir)).ge.abs(aspval)) THEN
                wrk(ij,ib,ir)=0.0_r8
              ELSE
                wrk(ij,ib,ir)=ascl*(afactor*wrk(ij,ib,ir)+aoffset)
                amin=min(amin,wrk(ij,ib,ir))
                amax=max(amax,wrk(ij,ib,ir))
              END IF
            END DO
          END DO
        END DO
        IF ((abs(amin).ge.abs(aspval)).and.                             &
   &        (abs(amax).ge.abs(aspval))) THEN
          amin=0.0_r8                         ! the entire data is all
          amax=0.0_r8                         ! field value, _FillValue
        END IF
!
        IF (lchecksum) THEN
          npts=(ubij-lbij+1)*nrec*4
          IF (.not.allocated(cwrk)) allocate ( cwrk(npts) )
          cwrk=pack(wrk(lbij:ubij, 1:4, 1:nrec), .true.)
          CALL get_hash (cwrk, npts, checksum)
          IF (allocated(cwrk)) deallocate (cwrk)
        END IF
      END IF
!
      IF (founderror(status, pio_noerr, __line__, myfile)) THEN
        exit_flag=2
        ioerror=status
        RETURN
      END IF
!
!-----------------------------------------------------------------------
!  Unpack read data.
!-----------------------------------------------------------------------
!
      abry=0.0_r8
 
      DO ir=1,nrec
        DO ib=1,4
          IF (bounded(ib)) THEN
            IF ((ib.eq.iwest).or.(ib.eq.ieast)) THEN
              DO j=jmin,jmax
                abry(j,ib,ir)=wrk(j,ib,ir)
              END DO
            ELSE IF ((ib.eq.isouth).or.(ib.eq.inorth)) THEN
              DO i=imin,imax
                abry(i,ib,ir)=wrk(i,ib,ir)
              END DO
            END IF
          END IF
        END DO
      END DO
!
      RETURN
      END FUNCTION pio_fread2d_bry
#endif
      END MODULE nf_fread2d_bry_mod