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
|
