Line data Source code
1 : !------------------------------------------------------------------------------
2 : ! Harmonized Emissions Component (HEMCO) !
3 : !------------------------------------------------------------------------------
4 : !BOP
5 : !
6 : ! !MODULE: hco_driver_mod.F90
7 : !
8 : ! !DESCRIPTION: Module HCO\_Driver\_Mod contains the driver routines
9 : ! (INIT, RUN, FINAL) for the HEMCO core module. It calls all the
10 : ! subroutines to initialize, execute and finalize the HEMCO core
11 : ! emissions calculations, i.e. all emissions not calculated in a HEMCO
12 : ! extension (See module hcox\_driver\_mod.F90 for the extensions).
13 : !\\
14 : !\\
15 : ! Call this module at the HEMCO - model interface level to execute the
16 : ! HEMCO core operations.
17 : !\\
18 : !\\
19 : ! !INTERFACE:
20 : !
21 : MODULE HCO_Driver_Mod
22 : !
23 : ! !USES:
24 : !
25 : USE HCO_Error_Mod
26 : USE HCO_State_Mod, ONLY : HCO_State
27 :
28 : IMPLICIT NONE
29 : PRIVATE
30 : !
31 : ! !PUBLIC MEMBER FUNCTIONS:
32 : !
33 : PUBLIC :: HCO_Init
34 : PUBLIC :: HCO_Run
35 : PUBLIC :: HCO_Final
36 : !
37 : ! !REVISION HISTORY:
38 : ! 27 May 2012 - C. Keller - Initialization
39 : ! See https://github.com/geoschem/hemco for complete history
40 : !EOP
41 : !------------------------------------------------------------------------------
42 : !BOC
43 : CONTAINS
44 : !EOC
45 : !------------------------------------------------------------------------------
46 : ! Harmonized Emissions Component (HEMCO) !
47 : !------------------------------------------------------------------------------
48 : !BOP
49 : !
50 : ! !IROUTINE: HCO_Run
51 : !
52 : ! !DESCRIPTION: Subroutine HCO\_Run is the HEMCO core run routine. It
53 : ! calculates the HEMCO emissions as specified in the HEMCO configuration
54 : ! file. All calculation settings, such as the extension number, the
55 : ! lowest and highest species ID, and the lowest and highest emission
56 : ! category, are passed through the HEMCO options object (HcoState%Opt).
57 : ! The time stamp is taken from the HEMCO clock object. Subroutine
58 : ! HcoClock\_Set should be used to update the HEMCO clock (see module
59 : ! hco\_clock\_mod.F90). This should be done at the HEMCO - model
60 : ! interface level.
61 : !\\
62 : !\\
63 : ! !INTERFACE:
64 : !
65 0 : SUBROUTINE HCO_Run( HcoState, Phase, RC, IsEndStep )
66 : !
67 : ! !USES:
68 : !
69 : USE HCO_Calc_Mod, ONLY : HCO_CalcEmis
70 : USE HCO_ReadList_Mod, ONLY : ReadList_Read
71 : USE HCO_Clock_Mod, ONLY : HcoClock_Get
72 : USE HCO_Clock_Mod, ONLY : HcoClock_First
73 : USE HCO_Clock_Mod, ONLY : HcoClock_InitTzPtr
74 : USE HCOIO_DIAGN_MOD, ONLY : HcoDiagn_Write
75 : !
76 : ! !INPUT PARAMETERS:
77 : !
78 : INTEGER, INTENT(IN ) :: Phase ! Run phase (1 or 2)
79 : LOGICAL, INTENT(IN ), OPTIONAL :: IsEndStep ! Last timestep of simulation?
80 : !
81 : ! !INPUT/OUTPUT PARAMETERS:
82 : !
83 : TYPE(HCO_State), POINTER :: HcoState ! HEMCO state object
84 : INTEGER, INTENT(INOUT) :: RC ! Success or failure?
85 : !
86 : ! !REVISION HISTORY:
87 : ! 27 May 2012 - C. Keller - Initialization
88 : ! See https://github.com/geoschem/hemco for complete history
89 : !EOP
90 : !------------------------------------------------------------------------------
91 : !BOC
92 : !
93 : ! !LOCAL VARIABLES:
94 : !
95 : ! Scalars
96 : LOGICAL :: IsEmisTime
97 : LOGICAL :: notDryRun
98 : LOGICAL :: ItIsEndStep
99 :
100 : ! Strings
101 : CHARACTER(LEN=255) :: MSG, LOC
102 :
103 : !=================================================================
104 : ! HCO_RUN begins here!
105 : !=================================================================
106 0 : LOC = 'HCO_RUN (HCO_DRIVER_MOD.F90)'
107 :
108 : ! Enter
109 0 : CALL HCO_ENTER( HcoState%Config%Err, LOC, RC )
110 0 : IF ( RC /= HCO_SUCCESS ) THEN
111 0 : CALL HCO_ERROR( 'ERROR 0', RC, THISLOC=LOC )
112 0 : RETURN
113 : ENDIF
114 :
115 : ! Define a local convenience variable to negate HcoState%Options%isDryRun
116 0 : notDryRun = ( .not. HcoState%Options%isDryRun )
117 :
118 : ! Define a shadow variable for optional argument IsEndStep
119 0 : IF ( PRESENT( IsEndStep ) ) THEN
120 0 : ItIsEndStep = IsEndStep
121 : ELSE
122 : ItIsEndStep = .FALSE.
123 : ENDIF
124 :
125 : !--------------------------------------------------------------
126 : ! 1. Check if it's time for emissions
127 : !--------------------------------------------------------------
128 0 : CALL HcoClock_Get ( HcoState%Clock, IsEmisTime=IsEmisTime, RC=RC )
129 0 : IF ( RC /= HCO_SUCCESS ) THEN
130 0 : CALL HCO_ERROR( 'ERROR 1', RC, THISLOC=LOC )
131 0 : RETURN
132 : ENDIF
133 :
134 : !--------------------------------------------------------------
135 : ! 2. Write HEMCO diagnostics. Do this only if the corresponding
136 : ! option is enabled. Otherwise, let the user decide when to
137 : ! call HcoDiagn_Write. Skip if it is a GEOS-Chem "dry-run".
138 : !--------------------------------------------------------------
139 0 : IF ( HcoState%Options%HcoWritesDiagn .and. notDryRun ) THEN
140 0 : CALL HcoDiagn_Write( HcoState, .FALSE., RC )
141 0 : IF ( RC /= HCO_SUCCESS ) THEN
142 0 : CALL HCO_ERROR( 'ERROR 2', RC, THISLOC=LOC )
143 0 : RETURN
144 : ENDIF
145 : ENDIF
146 :
147 : ! Check if this is the last timestep of simulation. If so, return
148 : ! and not read in update data.
149 0 : IF ( ItIsEndStep .and. notDryRun ) RETURN
150 :
151 : !--------------------------------------------------------------
152 : ! 3. Read/update data
153 : !
154 : ! Check if there are any data files that need to be read or
155 : ! updated, e.g. on the first call of HEMCO or if we enter a new
156 : ! month, year, etc.
157 : !
158 : ! NOTE: If this is a GEOS-Chem "dry-run", then HEMCO will
159 : ! print the files that will be read to either the stdout
160 : ! (log file) and HEMCO log file, but will not read them.
161 : !--------------------------------------------------------------
162 :
163 : ! Update data, as specified in ReadList.
164 0 : IF ( Phase /= 2 ) THEN
165 0 : CALL ReadList_Read( HcoState, RC )
166 0 : IF ( RC /= HCO_SUCCESS ) THEN
167 0 : PRINT *, "Error in ReadList_Read called from hco_run"
168 0 : RETURN
169 : ENDIF
170 :
171 : ! If we are reading timezone data (i.e. offsets from UTC in hours)
172 : ! from a file, then we need to initialize the TIMEZONES pointer
173 : ! variable in hco_clock_mod.F90. This has to be done only on the
174 : ! very first emissions timestep, after the call to READLIST_READ.
175 : ! We must leave this call here (instead of in the more customary
176 : ! initialization routine HCO_INIT) because the HEMCO configuration
177 : ! file has to be read in its entirety before the timezone data
178 : ! is loaded into a data container. (bmy, 2/23/15)
179 0 : IF ( HcoClock_First(HcoState%Clock,.FALSE.) ) THEN
180 0 : CALL HcoClock_InitTzPtr( HcoState, RC )
181 : ENDIF
182 :
183 : ENDIF
184 :
185 :
186 : !-----------------------------------------------------------------
187 : ! 4. Calculate the emissions for current time stamp based on the
188 : ! content of EmisList. Emissions become written into HcoState.
189 : ! Do this only if it's time for emissions and NOT a dry-run.
190 : !-----------------------------------------------------------------
191 0 : IF ( IsEmisTime .AND. Phase > 1 .and. notDryRun ) THEN
192 :
193 : ! Use emission data only
194 0 : CALL HCO_CalcEmis( HcoState, .FALSE., RC )
195 0 : IF ( RC /= HCO_SUCCESS ) THEN
196 0 : CALL HCO_ERROR( 'ERROR 3', RC, THISLOC=LOC )
197 0 : RETURN
198 : ENDIF
199 :
200 : ! Use concentration data only
201 : ! This is currently not being used. Concentrations can be read
202 : ! through HEMCO but should be assembled manually.
203 : !CALL HCO_CalcEmis( HcoState, .TRUE., RC )
204 : !IF ( RC /= HCO_SUCCESS ) RETURN
205 : ENDIF
206 :
207 : ! Leave w/ success
208 0 : CALL HCO_LEAVE( HcoState%Config%Err, RC )
209 :
210 : END SUBROUTINE HCO_Run
211 : !EOC
212 : !------------------------------------------------------------------------------
213 : ! Harmonized Emissions Component (HEMCO) !
214 : !------------------------------------------------------------------------------
215 : !BOP
216 : !
217 : ! !IROUTINE: HCO_Init
218 : !
219 : ! !DESCRIPTION: Subroutine HCO\_INIT initializes the HEMCO core modules.
220 : ! This routine assumes that the HEMCO configuration file has already been
221 : ! read to buffer (subroutine Config\_ReadFile in HCO\_CONFIG\_MOD.F90)
222 : ! and that the HEMCO state object has already been initialized. This has
223 : ! to be done at the HEMCO - model interface level.
224 : !\\
225 : !\\
226 : ! !INTERFACE:
227 : !
228 0 : SUBROUTINE HCO_Init( HcoState, RC )
229 : !
230 : ! !USES:
231 : !
232 : USE HCO_Diagn_Mod, ONLY : HcoDiagn_Init
233 : USE HCO_tIdx_Mod, ONLY : tIDx_Init
234 : USE HCO_Clock_Mod, ONLY : HcoClock_Init
235 : USE HCO_Config_Mod, ONLY : SetReadList
236 : USE HCO_Scale_Mod, ONLY : HCO_ScaleInit
237 : !
238 : ! !INPUT/OUTPUT PARAMETERS:
239 : !
240 : TYPE(HCO_State), POINTER :: HcoState ! HcoState object
241 : INTEGER, INTENT(INOUT) :: RC ! Failure or success
242 : !
243 : ! !REVISION HISTORY:
244 : ! 27 May 2012 - C. Keller - Initialization
245 : ! See https://github.com/geoschem/hemco for complete history
246 : !EOP
247 : !------------------------------------------------------------------------------
248 : !BOC
249 : !
250 : !
251 : ! !LOCAL VARIABLES:
252 : !
253 : CHARACTER(LEN=255) :: LOC
254 : !=================================================================
255 : ! HCO_INIT begins here!
256 : !=================================================================
257 0 : LOC = 'HCO_INIT (HCO_DRIVER_MOD.F90)'
258 :
259 : ! Enter
260 0 : CALL HCO_ENTER( HcoState%Config%Err, LOC, RC )
261 0 : IF ( RC /= HCO_SUCCESS ) THEN
262 0 : PRINT *, "Error in HCO_ENTER called from HCO_Init"
263 0 : RETURN
264 : ENDIF
265 :
266 : ! Initialize time slice pointers
267 0 : CALL tIDx_Init( HcoState, RC )
268 0 : IF ( RC /= HCO_SUCCESS ) THEN
269 0 : PRINT *, "Error in tIDx_Init called from HCO_Init"
270 0 : RETURN
271 : ENDIF
272 :
273 : ! Initialize HEMCO Clock
274 0 : HcoState%Clock => NULL()
275 0 : CALL HcoClock_Init( HcoState, RC )
276 0 : IF ( RC /= HCO_SUCCESS ) THEN
277 0 : PRINT *, "Error in HcoClock_Init called from HCO_Init"
278 0 : RETURN
279 : ENDIF
280 :
281 : ! Initialize the HEMCO diagnostics
282 0 : CALL HcoDiagn_Init( HcoState, RC )
283 0 : IF ( RC /= HCO_SUCCESS ) THEN
284 0 : PRINT *, "Error in HcoDiagn_Init called from HCO_Init"
285 0 : RETURN
286 : ENDIF
287 :
288 : ! Set ReadList based upon the content of the configuration file.
289 0 : CALL SetReadList( HcoState, RC )
290 0 : IF ( RC /= HCO_SUCCESS ) THEN
291 0 : PRINT *, "Error in SetReadList called from HCO_Init"
292 0 : RETURN
293 : ENDIF
294 :
295 : ! Define universal scale factor for each HEMCO species
296 0 : CALL Hco_ScaleInit( HcoState, RC )
297 0 : IF ( RC /= HCO_SUCCESS ) THEN
298 0 : PRINT *, "Error in Hco_ScaleInit called from HCO_Init"
299 0 : RETURN
300 : ENDIF
301 :
302 : ! Leave w/ success
303 0 : CALL HCO_LEAVE ( HcoState%Config%Err, RC )
304 :
305 : END SUBROUTINE HCO_Init
306 : !EOC
307 : !------------------------------------------------------------------------------
308 : ! Harmonized Emissions Component (HEMCO) !
309 : !------------------------------------------------------------------------------
310 : !BOP
311 : !
312 : ! !IROUTINE: HCO_Final
313 : !
314 : ! !DESCRIPTION: Subroutine HCO\_Final finalizes HEMCO core.
315 : !\\
316 : !\\
317 : ! !INTERFACE:
318 : !
319 0 : SUBROUTINE HCO_Final( HcoState, ERROR, RC )
320 : !
321 : ! !USES:
322 : !
323 : USE HCO_Clock_Mod, ONLY : HcoClock_Cleanup
324 : USE HCO_tIdx_Mod, ONLY : tIDx_Cleanup
325 : USE HCO_DataCont_Mod, ONLY : cIDList_Cleanup
326 : USE HCO_ReadList_Mod, ONLY : ReadList_Cleanup
327 : USE HCO_DataCont_Mod, ONLY : ListCont_Cleanup
328 : USE HCO_ExtList_Mod, ONLY : ExtFinal
329 : USE HCOIO_DIAGN_MOD, ONLY : HcoDiagn_Write
330 : USE HCO_Scale_Mod, ONLY : HCO_ScaleFinal
331 : !
332 : ! !INPUT PARAMETERS:
333 : !
334 : LOGICAL, INTENT(IN ) :: ERROR ! Cleanup because of crash?
335 : !
336 : ! !INPUT/OUTPUT PARAMETERS:
337 : !
338 : TYPE(HCO_State), POINTER :: HcoState ! HcoState object
339 : INTEGER, INTENT(INOUT) :: RC ! Failure or success
340 : !
341 : ! !REMARKS:
342 : ! (1) ConfigFile_Cleanup also cleans up the data containers, while routine
343 : ! EmisList_Cleanup and ReadList_Cleanup only removes the pointers to
344 : ! them. Hence, we have to call these routines before ConfigFile_Cleanup!
345 : ! (2) HcoState is cleaned up in the HEMCO-module interface.
346 : !
347 : ! !REVISION HISTORY:
348 : ! 27 May 2012 - C. Keller - Initialization
349 : ! See https://github.com/geoschem/hemco for complete history
350 : !EOP
351 : !------------------------------------------------------------------------------
352 : !BOC
353 :
354 : !=================================================================
355 : ! HCO_FINAL begins here
356 : !=================================================================
357 :
358 : ! Write diagnostics if needed
359 0 : IF ( HcoState%Options%HcoWritesDiagn .AND. .NOT. ERROR ) THEN
360 0 : CALL HcoDiagn_Write( HcoState, .FALSE., RC )
361 0 : CALL HcoDiagn_Write( HcoState, .TRUE., RC )
362 : ENDIF
363 :
364 0 : CALL cIDList_Cleanup ( HcoState )
365 0 : CALL HcoClock_Cleanup ( HcoState%Clock )
366 0 : CALL tIDx_Cleanup ( HcoState%AlltIDx )
367 0 : CALL ReadList_Cleanup ( HcoState%ReadLists, .FALSE. )
368 0 : CALL ListCont_Cleanup ( HcoState%EmisList, .FALSE. )
369 0 : CALL ListCont_Cleanup ( HcoState%Config%ConfigList, .TRUE. )
370 0 : HcoState%nnEmisCont = 0
371 0 : HcoState%SetReadListCalled = .FALSE.
372 :
373 : ! Cleanup scaling factors
374 0 : CALL HCO_ScaleFinal()
375 :
376 : ! Cleanup the extension list object
377 0 : CALL ExtFinal ( HcoState%Config%ExtList )
378 :
379 : ! Close the logfile and cleanup error object.
380 0 : CALL HCO_Error_Final ( HcoState%Config%Err )
381 :
382 : ! Return w/ success
383 0 : RC = HCO_SUCCESS
384 :
385 0 : END SUBROUTINE HCO_Final
386 : !EOC
387 : END MODULE HCO_Driver_Mod
|
