LCOV - code coverage report
Current view: | top level - hemco/HEMCO/src/Core - hcoio_dataread_mod.F90 (source / functions) |  |  | Hit | Total | Coverage
Test: | coverage.info |  | Lines: | 0 | 13 | 0.0 %
Date: | 2024-12-17 22:39:59 |  | Functions: | 0 | 1 | 0.0 %

              Line data    Source code
           1             : !------------------------------------------------------------------------------
           2             : !                   Harmonized Emissions Component (HEMCO)                    !
           3             : !------------------------------------------------------------------------------
           4             : !BOP
           5             : !
           6             : ! !MODULE: hcoio_dataread_mod.F90
           7             : !
           8             : ! !DESCRIPTION: Module HCOIO\_DataRead\_Mod controls data processing
           9             : ! for HEMCO.
          10             : ! Depending on the model environment (standard, ESMF, etc.), it invokes
          11             : ! the corresponding routines to read the data from file, convert units
          12             : ! as required, and interpolate the data onto the model grid.
          13             : !\\
          14             : !\\
          15             : ! Currently, HEMCO can read data from the following data sources:
          16             : ! \begin{itemize}
          17             : ! \item Gridded data from netCDF file. The netCDF file should adhere to
          18             : !   the COARDS conventions and can hold data on resolutions different
          19             : !   than then simulation grid. Regridding is performed as part of the
          20             : !   data reading. Routine HCOIO\_DataRead is the driver routine to read
          21             : !   data from netCDF file. In an ESMF environment, this routine simply
          22             : !   calls down to the MAPL/ESMF - generic I/O routines. In a non-ESMF
          23             : !   environment, the HEMCO generic reading and remapping algorithms are
          24             : !   used. Those support vertical regridding, unit conversion, and more
          25             : !   (see below).
          26             : ! \item Scalar data directly specified in the HEMCO configuration file.
          27             : !   If multiple values - separated by the separator sign (/) - are
          28             : !   provided, they are interpreted as temporally changing values:
          29             : !   7 values = Sun, Mon, ..., Sat; 12 values = Jan, Feb, ..., Dec;
          30             : !   24 values = 0am, 1am, ..., 23pm (local time!). For masks, exactly
          31             : !   four values must be provided, interpreted as lower left and upper
          32             : !   right mask box corners (lon1/lat1/lon2/lat2).
          33             : ! \item Country-specific data specified in a separate ASCII file. This
          34             : !   file must end with the suffix '.txt' and hold the country specific
          35             : !   values listed by country ID. The IDs must correspond to the IDs of
          36             : !   a corresponding (netCDF) mask file. The container name of this mask
          37             : !   file must be given in the first line of the file, and must be listed
          38             : !   HEMCO configuration file. ID 0 is reserved for the default values,
          39             : !   applied to all countries with no specific values listed. The .txt
          40             : !   file must be structured as follows:
          41             : !
          42             : !   \# Country mask file name
          43             : !   CountryMask
          44             : !
          45             : !   \# CountryName CountryID CountryValues
          46             : !   DEFAULT   0 1.0/1.0/1.0/1.0/1.0/1.0/1/0
          47             : !   USA     840 0.8/0.9/1.0/1.1/1.2/1.1/0.9
          48             : !
          49             : !   The CountryValues are interpreted the same way as scalar values,
          50             : !   except that they are applied to all grid boxes with the given
          51             : !   country ID.
          52             : ! \end{itemize}
          53             : !
          54             : ! Outside of an ESMF environment, the GEOS-Chem netCDF reading utilities
          55             : ! are used to read netCDF data from disk. The selection of the time slice
          56             : ! to be read depends on the current simulation time and the datetime
          57             : ! settings assigned to a given data container (set in the configuration
          58             : ! file). These settings include:
          59             : ! \begin{itemize}
          60             : ! \item datetime range (srcTime), given as YYYY/MM/DD/hh. These can be
          61             : !  given as fixed date (e.g. 2010/1/1/0), ranges (e.g. 1990-2010/1/1/0
          62             : !  or 2000-2100/1-12/0/0-23), or using tokens (e.g. $YYYY/$MM/1/0).
          63             : !  Data is automatically updated if a 'dynamic' time attribute is given.
          64             : !  For instance, for attribute $YYYY/1/1/0 the file will be updated
          65             : !  every year, attribute $YYYY/$MM/$DD/0 every day, etc. The date time
          66             : !  tokens are replaced with the current simulation datetime. If a range
          67             : !  is provided, only time stamps within the given range are being used.
          68             : !  If there is no exact match between the preferred datetime (determined
          69             : !  from srcTime) and the time slices in the netCDF file, the cycle flag
          70             : !  determines what time slice index is selected.
          71             : ! \item Cycling behavior. This determines what to do if there is no
          72             : !  exact match between preferred datetime and available datetimes of a
          73             : !  file. The options are cycling (C, default), range (R), exact (E),
          74             : !  and interpolation (I). If cycling is used, data is recycled if the
          75             : !  simulation time is outside of the available data time interval.
          76             : !  If cycling is set to range, a data container is ignored if the
          77             : !  *simulation* time is outside the given range. For example, if the
          78             : !  range is set to 2010-2015/1-12/1/0, this data container is used
          79             : !  for simulation dates between 2010 and 2015. If the actual netCDF
          80             : !  file data is outside that range, the closest available time slice
          81             : !  is selected using the algorithm described below.
          82             : !  If cycling is set to exact, HEMCO returns w/ an error if no time
          83             : !  slice can be found in the netCDF file that exactly matches the
          84             : !  preferred time slices.
          85             : !  Finally, if interpolation is selected, data will be interpolated
          86             : !  between two time slices if the current preferred datetime cannot
          87             : !  be found in the input data.
          88             : !  If the preferred datetime does not match with any of the ncdf
          89             : !  datetimes, the following method is used to select the time slice
          90             : !  to be used:
          91             : !  If the preferred datetime is within the range of the available
          92             : !  dates, the closest available time stamp in the past is used in
          93             : !  most cases. For example, assume a file contains January data
          94             : !  between 2005 and 2010, and a simulation starts on July 2007. In
          95             : !  this case, the data from Jan 2007 will be used and replaced with
          96             : !  Jan 2008 as soon as the simulation date changes to 2008.
          97             : !  If the datetimes of the netCDF file contain discontinuities (e.g.
          98             : !  don't have the same time interval between all time stamps), an
          99             : !  attempt is made to maintain the highest cycling frequency. For
         100             : !  instance, if a file contains monthly data for years 2005 and 2020
         101             : !  and the srcTime attribute is set to $YYYY/1-12/1/0. For July 2008,
         102             : !  this will use the data from July 2005, and not December 2005 (which
         103             : !  would be the closest date). Data is updated to Aug 2005 once the
         104             : !  simulation time changes to Aug 2008.
         105             : !  The same principles are applied if the current datetime is outside
         106             : !  the data range of the ncdf file, but in this case it is also
         107             : !  possible to use datetimes in the future.
         108             : !  If the interpolation option is enabled, the second time slice is
         109             : !  selected in the same manner as for slice 1, but for future dates.
         110             : !  If there is no additional time step in a file, e.g. the selected
         111             : !  time slice is the only/last one of a file, a check is made to see
         112             : !  if there is another file with the same filename but other datetime
         113             : !  tokens. If this is the case, interpolation will be performed between
         114             : !  these two files. Note that at the moment, the first time slice of
         115             : !  the second file is always used!!
         116             : !  For example, assume data for years 2005 and 2010 is stored in files
         117             : !  file2005.nc and file2010.nc, respectively. The following entries
         118             : !  in the HEMCO configuration file will enable annual interpolation
         119             : !  between these two files:
         120             : !  0 TEST file$YYYY.nc VAL 2005-2010/1/1/0 I ...
         121             : ! \end{itemize}
         122             : ! !INTERFACE:
         123             : !
         124             : MODULE HCOIO_DataRead_Mod
         125             : !
         126             : ! !USES:
         127             : !
         128             :   USE HCO_Types_Mod
         129             :   USE HCO_Error_Mod
         130             :   USE HCO_CharTools_Mod
         131             :   USE HCO_State_Mod,       ONLY : Hco_State
         132             :
         133             :   IMPLICIT NONE
         134             :   PRIVATE
         135             : !
         136             : ! !PUBLIC MEMBER FUNCTIONS:
         137             : !
         138             :   PUBLIC  :: HCOIO_DataRead
         139             : !
         140             : ! !REVISION HISTORY:
         141             : !  22 Aug 2013 - C. Keller   - Initial version
         142             : !  See https://github.com/geoschem/hemco for complete history
         143             : !EOP
         144             : !------------------------------------------------------------------------------
         145             : !BOC
         146             : CONTAINS
         147             : !EOC
         148             : !------------------------------------------------------------------------------
         149             : !                   Harmonized Emissions Component (HEMCO)                    !
         150             : !------------------------------------------------------------------------------
         151             : !BOP
         152             : !
         153             : ! !IROUTINE: HCOIO_DataRead
         154             : !
         155             : ! !DESCRIPTION: Routine HCOIO\_DataRead invokes the appropriate data reading
         156             : ! routines for the given model environment.
         157             : !\\
         158             : !\\
         159             : ! !INTERFACE:
         160             :   !
         161           0 :   SUBROUTINE HCOIO_DataRead( HcoState, Lct, RC )
         162             : !
         163             : ! !USES:
         164             : !
         165             :     USE HCOIO_READ_MOD,   ONLY : HCOIO_READ
         166             : !
         167             : ! !INPUT PARAMETERS:
         168             : !
         169             :     TYPE(HCO_State),  POINTER        :: HcoState
         170             :     TYPE(ListCont),   POINTER        :: Lct
         171             : !
         172             : ! !INPUT/OUTPUT PARAMETERS:
         173             : !
         174             :     INTEGER,          INTENT(INOUT)  :: RC
         175             : !
         176             : ! !REVISION HISTORY:
         177             : !  28 Aug 2013 - C. Keller   - Initial version
         178             : !  See https://github.com/geoschem/hemco for complete history
         179             : !EOP
         180             : !------------------------------------------------------------------------------
         181             : !BOC
         182             : !
         183             : ! !LOCAL VARIABLES:
         184             : !
         185             :     ! Strings
         186             :     CHARACTER(LEN=512) :: MSG
         187             :     CHARACTER(LEN=255) :: LOC
         188             :
         189             :     !=======================================================================
         190             :     ! HCOIO_DATAREAD begins here
         191             :     !=======================================================================
         192           0 :     LOC = 'HCOIO_DATAREAD (HCOIO_DATAREAD_MOD.F90)'
         193             :
         194             :     ! Assume success until proven otherwise
         195           0 :     RC = HCO_SUCCESS
         196             :
         197             :     ! Denote we are entering this routine
         198           0 :     CALL HCO_ENTER( HcoState%Config%Err, LOC, RC )
         199           0 :     IF ( RC /= HCO_SUCCESS ) THEN
         200           0 :         CALL HCO_ERROR( 'ERROR 0', RC, THISLOC=LOC )
         201           0 :         RETURN
         202             :     ENDIF
         203             :
         204             :     ! Call the HEMCO Data Input Layer
         205             :     ! Selection of which HCOIO module to be used is performed at compile level
         206           0 :     CALL HCOIO_READ( HcoState, Lct, RC )
         207             :
         208             :     ! Trap potential errors
         209           0 :     IF ( RC /= HCO_SUCCESS ) THEN
         210           0 :        MSG = 'Error encountered in routine HCOIO_Read!'
         211           0 :        CALL HCO_ERROR( MSG, RC )
         212           0 :        RETURN
         213             :     ENDIF
         214             :
         215             :     ! Denote we are leaving this routine
         216           0 :     CALL HCO_LEAVE( HcoState%Config%Err, RC )
         217             :
         218             :   END SUBROUTINE HCOIO_DataRead
         219             : !EOC
         220             : END MODULE HCOIO_DataRead_Mod

Generated by: LCOV version 1.14