Changes between Initial Version and Version 1 of Documentation/UserGuide/HistoryOperators

Timestamp:

2012-09-12T10:23:28+02:00 (12 years ago)

Author:

dsolyga

Comment:

--

Documentation/UserGuide/HistoryOperators

@@ +1 @@
+= How to understand the operations performed on the variables when written in the history files =
+ '''1. IOIPSL/src/histcom.f90'''[[BR]]
+
+First read more about the IOIPSL module that manages the history files here:
+http://www.ipsl.jussieu.fr/~ioipsl/WWW2/index.html
+
+The main information __useful for ORCHIDEE__ is reproduced below:[[BR]]
+
+''histdef'': The variables which will be written are declared and the following information is passed:
+ * name of variable
+ * title 
+ * units 
+ * size of the variable 
+ * '''operation to be carried out on the variable before writing it'''
+ * frequency at which the operations need to be done (positive values are in units of seconds and negative values are in units of month) 
+ * frequency at which the resulting data need to be written into the file(positive values are in units of seconds and negative values are in units of month) 
+
+'''Allowed operations'''[[BR]]
+
+In ''histdef'' the user may specify for each field that is going to be archived a number of operations. 3 types may be distinguished: Vector operations, vector-scalar operations and index operations on the vector. In the description of the operations to be carried out the vector will be represented by x. For instance a gather operation will be written "gather(x)". It must be noted that the indexing operations will use as index vector the one passed to histwrite. On top of this a time operation has to be chosen. There only one is allowed and it should be outer most operator. For instance the time averaging of the gather operation will be written as "ave(gather(x))".
+
+ * Allowed time operations:
+||ave||time average of the field||
+||inst||instantaneous values of the field is going to be written||
+||t_min||the minimum value over the time period is going to be archived||
+||t_max||the maximum value over the time period is going to be archived||
+||t_sum||sums the variable over time||
+||once||the field is written once on the file without any time axis||
+||never||the field is never written||
+
+ * Allowed vector operations:[[BR]]
+Usage: cels(x)
+||cels||transforms the field into degrees Celsius||
+
+ * Allowed vector-scalar operations:[[BR]]
+Usage: scal*x
+||*||multiplication||
+
+ * Allowed indexing operations:[[BR]]
+Usage: gather(x)
+||gather||Gathers from the input data all the points listed in index and puts them onto the file. Other points in the resulting array are going to labeled as missing. This operation could be used to reduce the resolution of  the history file.||
+||scatter||Scatters from the input data onto the points which are listed in the index. Other points are going to be labeled as missing. This is used for instance to put a variable only available over oceans onto a global grid.||
+
+Examples:[[BR]]
+ * ave(scatter(cels(X)): Will average the variables (temperature for instance) in celsius and scatter it onto the grid. This could be used in an ocean model where all grid points are in a vector and cover only ocean points. Thus in the history file you will have the field placed correctly on the map.
+ * ave(max(cels(x),0.)): Average over time only the temperature (if that is the variable in Kelvin) which are above 0.
+ * t_max(X): Computes the maximum over the time between two writes of the variable.
+
+
+ '''2. src_sechiba/intersurf.f90'''[[BR]]
+
+The ''histdef'' calls are made in the ''intsurf_history'' subroutine for the sechiba history file and similarly in the ''stom_define_history'' subroutine for the stomate history file.
+
+Characters strings are first declared to perform units conversion for fluxes:
+
+{{{
+!! Operations to be performed on fluxes
+CHARACTER(LEN=30)   :: flux_op     
+!! Operations which do not include a scatter               
+CHARACTER(LEN=30)   :: flux_sc    
+!! Operation in seconds                
+CHARACTER(LEN=30)   :: flux_insec, flux_scinsec 
+}}}
+  
+
+The history level will determine the number of output variables:
+
+{{{
+!! history output level (default is 10 => maximum output)
+INTEGER(i_std)     :: hist_level 
+}}}
+
+The following strings arrays will contain the operation to perform from 1 to hist_level and contain ‘never’ from hist_level to 10, meaning there is nothing to do (the variable is not written in the history file).
+
+{{{
+!! The various operations to be performed
+CHARACTER(LEN=40),DIMENSION(max_hist_level) :: &
+         & ave, avecels, avescatter, fluxop, &
+         & fluxop_scinsec, tmincels, tmaxcels, once, sumscatter  
+}}}
+
+For fluxes, the operation is written as a string with IOIPSL operators including a multiplication by the number required to obtain the desired output unit:
+
+{{{
+WRITE(flux_op,'("ave(scatter(X*",F8.1,"))")') one_day/dt
+WRITE(flux_sc,'("ave(X*",F8.1,")")') one_day/dt
+WRITE(flux_insec,'("ave(X*",F8.6,")")') un/dt
+WRITE(flux_scinsec,'("ave(scatter(X*",F8.6,"))")') un/dt
+}}}
+
+Reading of the chosen history level from the run.def file:
+
+{{{
+!Config  Key  = SECHIBA_HISTLEVEL
+!Config  Desc = SECHIBA history output level (0..10)
+!Config  Def  = 5
+!Config  Help = Chooses the list of variables in the history file. 
+!Config         Values between 0: nothing is written; 10: everything is 
+!Config         written are available More details can be found on the web under documentation.
+!Config         web under documentation.
+hist_level = 5
+CALL getin_p('SECHIBA_HISTLEVEL', hist_level)
+}}}
+
+
+
+{{{
+!- define operations as a function of history level.
+!- Above hist_level, operation='never'
+ave(1:max_hist_level) = 'ave(X)'
+IF (hist_level < max_hist_level) THEN
+       ave(hist_level+1:max_hist_level) = 'never'
+ENDIF
+sumscatter(1:max_hist_level) = 't_sum(scatter(X))'
+IF (hist_level < max_hist_level) THEN
+       sumscatter(hist_level+1:max_hist_level) = 'never'
+ENDIF
+avecels(1:max_hist_level) = 'ave(cels(X))'
+IF (hist_level < max_hist_level) THEN
+       avecels(hist_level+1:max_hist_level) = 'never'
+ENDIF
+avescatter(1:max_hist_level) = 'ave(scatter(X))'
+IF (hist_level < max_hist_level) THEN
+       avescatter(hist_level+1:max_hist_level) = 'never'
+ENDIF
+tmincels(1:max_hist_level) = 't_min(cels(X))'
+IF (hist_level < max_hist_level) THEN
+       tmincels(hist_level+1:max_hist_level) = 'never'
+ENDIF
+tmaxcels(1:max_hist_level) = 't_max(cels(X))'
+IF (hist_level < max_hist_level) THEN
+       tmaxcels(hist_level+1:max_hist_level) = 'never'
+ENDIF
+fluxop(1:max_hist_level) = flux_op
+IF (hist_level < max_hist_level) THEN
+       fluxop(hist_level+1:max_hist_level) = 'never'
+ENDIF
+fluxop_scinsec(1:max_hist_level) = flux_scinsec
+IF (hist_level < max_hist_level) THEN
+       fluxop_scinsec(hist_level+1:max_hist_level) = 'never'
+ENDIF
+once(1:max_hist_level) = 'once(scatter(X))'
+IF (hist_level < max_hist_level) THEN
+       once(hist_level+1:max_hist_level) = 'never'
+ENDIF
+}}}
+
+
+If for example ''hist_lev''=5, for a variable with a corresponding ''histdef'' call containing ''operator''(6), ''operator''(6) is ‘never’ and the variable won’t appear in the history file. For another variable with a corresponding ''histdef'' call containing ''operator''(4), the variable will be processing according to the ''operator'' definition and written in the history file.[[BR]]
+
+
+
+Example:[[BR]]
+
+ALMA convention [[BR]]
+
+Here we divide per dt to get per seconds:
+
+
+{{{
+CALL histdef(hist_id, 'Evap', 'Total Evapotranspiration', 'kg/m2/s', & 
+           & iim,jjm, hori_id, 1,1,1, -99, 32, fluxop_scinsec(1), dt, dw) 
+}}}
+
+NOT ALMA [[BR]]
+
+Here we multiply per one_day/dt to get per days: 
+
+{{{
+CALL histdef(hist_id, 'evap', 'Evaporation', 'mm/d', & 
+           & iim,jjm, hori_id, 1,1,1, -99, 32, fluxop(1), dt, dw) 
+}}}
+