Changeset 684 for XIOS/trunk/doc

Timestamp:

09/10/15 14:38:15 (9 years ago)

Author:

rlacroix

Message:

User guide: Add new sections about files and fields.

Location:

XIOS/trunk/doc

Files:

• XIOS_user_guide.lyx (modified) (1 diff)
• XIOS_user_guide.pdf (modified) (previous)

XIOS/trunk/doc/XIOS_user_guide.lyx

@@ -1214 +1214 @@
 \end_layout
 
+\begin_layout Chapter
+Files
+\end_layout
+
+\begin_layout Standard
+Since files are central to an I/O server, the configuration of XIOS is built
+ around file objects.
+ Those objects correspond directly to files on the computer file system
+ which are either to be written or to be read.
+ Although, XIOS currently only supports the NetCDF format, XIOS files are
+ a generic abstraction.
+ Each file can contain one or more fields (each field being defined on a
+ grid) and optionally variables.
+ In the NetCDF nomenclature, fields defined in XIOS correspond to NetCDF
+ variables and XIOS variables are NetCDF attributes.
+ As fields, variables and grids are complex objects, they have their own
+ chapters and we will focus only on files in this section.
+\end_layout
+
+\begin_layout Section
+How to define your first file
+\end_layout
+
+\begin_layout Standard
+If you wish to input or to output data using XIOS, you will need to define
+ at least one file.
+ This can be done from both the XML configuration file and the Fortran interface.
+ Files are usually defined in the configuration file, although their definitions
+ are sometimes amended using the API.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+File objects are defined with the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+<file>
+\end_layout
+
+\end_inset
+
+ tag and should always be inside the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+<file_definition>
+\end_layout
+
+\end_inset
+
+ section.
+ Only the output frequency is mandatory to have a well defined file but
+ it is generally a good idea to give it a name.
+ The following example shows a minimal configuration file which defines
+ one file.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <!-- Content of the file ommited for now -->
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+Note that the file extension could depend of the format so it is automatically
+ added to the chosen name by XIOS.
+ Since XIOS only support NetCDF formats for now, the extension is always
+ 
+\begin_inset Quotes eld
+\end_inset
+
+.nc
+\begin_inset Quotes erd
+\end_inset
+
+.
+ If the name is not set, XIOS will use the id of the file object instead.
+ This id is generated automatically by XIOS if it was not set by the user.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The output frequency is particularly important since it defines the interval
+ of time between two consecutive outputs, that is in NetCDF nomenclature
+ the interval between two records.
+ In the example, the data would be written for every timestep (independently
+ of the timestep duration).
+ It is possible to use any duration as the output frequency but be careful
+ if you are not using a duration which is a multiple of the timestep duration
+ since XIOS might not be doing what you want.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The same configuration could be obtained from the Fortran interface as well:
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset listings
+lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_context)   :: ctx_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_file)          :: file_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_filegroup) :: filegroup_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context and calendar initializations ommited, see the corresponding section
+ of this user manual and of the reference manual
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_get_handle("test", ctx_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_current_context(ctx_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_get_filegroup_handle("file_definition", filegroup_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_add_file(filegroup_hdl, file_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_attr(file_hdl, name="output", output_freq=xios_timestep)
+\end_layout
+
+\end_inset
+
+Another important parameter for file is the 
+\series bold
+mode
+\series default
+ attribute which is set by default to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+write
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ You need to set it to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+read
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ if you want to use XIOS to handle inputs.
+ Note that in this case the 
+\series bold
+output_freq
+\series default
+ attribute must correspond to the output frequency used to create the input
+ file.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+When using the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+write
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode, it is possible to append the data to an existing file instead of
+ overwriting it by setting the 
+\series bold
+append
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+true
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ In this case, you must be careful not to modify the structure of the file,
+ in particular no fields should be added, modified nor removed, or XIOS
+ will throw an error.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+If you wish to disable a file without having to remove its definition from
+ the configuration file, you can set the 
+\series bold
+enabled
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+false
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+How to use parallel I/O
+\end_layout
+
+\begin_layout Standard
+By default XIOS will create one file by server, each file being suffixed
+ with the rank of the server.
+ For example, if the sample configuration used in the previous section was
+ used with two servers, two files named 
+\begin_inset Quotes eld
+\end_inset
+
+output_0.nc
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+output_1.nc
+\begin_inset Quotes erd
+\end_inset
+
+ would be created.
+ Each file would contain only the portion of the fields affected to the
+ corresponding server.
+ This default mode can also be explicitly configured by setting the 
+\series bold
+type
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+multiple_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Using the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+multiple_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode is often a reliable way to achieve good performances, particularly
+ if you only have a few servers.
+ However having multiple files also increases the complexity of the post-process
+ing chains and it is often much easier to always get one file regardless
+ of how many servers are used.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+It is possible to achieve such behavior in XIOS by setting the 
+\series bold
+type
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+one_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ This feature depends directly on the NetCDF library capabilities so you
+ need to make sure that XIOS was properly linked with a parallel version
+ of NetCDF.
+ If the library was not compiled with parallel input/output support, XIOS
+ will issue a warning and revert to the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+multiple_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode.
+\end_layout
+
+\begin_layout Section
+Supported NetCDF formats
+\end_layout
+
+\begin_layout Standard
+XIOS supports only the version 4 or later of NetCDF library.
+ It uses by default the new NetCDF-4 format which relies on HDF5 format
+ as a back-end.
+ This format can also be selected explicitly by setting the 
+\series bold
+format
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+netcdf4
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Alternatively, it also possible to force NetCDF-4 to use the classic NetCDF-3
+ binary format by setting the 
+\series bold
+format
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+netcdf4_classic
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ When using this older format, some features might be unavailable but current
+ version of XIOS should not be affected much.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Depending on the format, there are some specific requirements on how the
+ NetCDF library should have been compiled:
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+netcdf4
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ format requires that HDF5 support has been enabled in NetCDF using the
+ configuration option 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+-\SpecialChar \nobreakdash-
+-enable-netcdf4
+\end_layout
+
+\end_inset
+
+ and that the HDF5 library has been properly linked.
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+netcdf4
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ format used in 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+one_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode requires that the HDF5 library has been compiled with parallel support
+ using the configuration option 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+-\SpecialChar \nobreakdash-
+-enable-parallel
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+netcdf4_classic
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ format used in 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+one_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode requires that Parallel NetCDF support has been enabled in NetCDF using
+ the configuration option 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+-\SpecialChar \nobreakdash-
+-enable-pnetcdf
+\end_layout
+
+\end_inset
+
+ and that the Parallel NetCDF library has been properly linked.
+\end_layout
+
+\begin_layout Section
+How to use file splitting
+\end_layout
+
+\begin_layout Standard
+Output files can often be quite huge, particularly if the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+one_file
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ mode is used.
+ In this case, it can be interesting to periodically split the file in order
+ to have a few smaller files containing contiguous temporal portions of
+ the output data.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+This behavior can be achieved in XIOS by setting the 
+\series bold
+split_freq
+\series default
+ attribute to the duration you want, as illustrated in the following example:
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d" split_freq="1y">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <!-- Content of the file ommited for now -->
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+With this configuration, some data will be outputted every day and a new
+ file will be created every year.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Note that the split frequency is the duration after which a new file will
+ be created, it does not mean that a new file will be created at the beginning
+ of each period.
+ For example, if you start your simulation the first of June 2014 and run
+ it for two years with a split frequency of one year:
+\end_layout
+
+\begin_layout Itemize
+you will get two files containing respectively the period from June 1st,
+ 2014 to May 31th, 2015 and from June 1st, 2015 to May 31th, 2016.
+\end_layout
+
+\begin_layout Itemize
+you will NOT get three files containing respectively the last six months
+ of 2014, the full year of 2015 and the first six months of 2016.
+\end_layout
+
+\begin_layout Standard
+XIOS automatically suffixes the file names with the start and end dates
+ when using file splitting.
+ By default, it will try to use the shortest date that still enables to
+ distinguish the files.
+ Thus in the above example, the files would be named 
+\begin_inset Quotes eld
+\end_inset
+
+output_2014-2015.nc
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+output_2015-2016.nc
+\begin_inset Quotes erd
+\end_inset
+
+.
+ If you wish to force the date format used to prefix the files, you can
+ define the 
+\series bold
+split_freq_format
+\series default
+ attribute to override the default behavior.
+\end_layout
+
+\begin_layout Section
+A word about file synchronization
+\end_layout
+
+\begin_layout Standard
+File synchronization is usually not something you should worry about.
+ However, it is important to understand that data written by XIOS might
+ not be immediately written on the disk in practice.
+ Input/output libraries like NetCDF and HDF5 and parallel file systems generally
+ use complex caching policies for performance reasons.
+ This means that your data might still be stored in memory after it was
+ supposedly written.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+It might become critical to control this behavior for two main reasons:
+\end_layout
+
+\begin_layout Itemize
+if you want to mitigate the impact of a crash, as all buffered data would
+ be lost ;
+\end_layout
+
+\begin_layout Itemize
+if you want to be able to access the data from the output file immediately
+ after writing it.
+\end_layout
+
+\begin_layout Standard
+By default, XIOS will never force file synchronization but you can require
+ it to do so by setting the 
+\series bold
+sync_freq
+\series default
+ attribute to the wanted duration.
+ In this case, XIOS will regularly instruct NetCDF to synchronize the file
+ on disk by flushing its internal buffers.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Note file synchronization must be used sparingly as it can have a disastrous
+ impact on performance.
+ Make sure to use a reasonably high synchronization frequency to avoid any
+ issue.
+\end_layout
+
+\begin_layout Chapter
+Fields and variables
+\end_layout
+
+\begin_layout Standard
+XIOS outsources the input/output definitions in its XML configuration file.
+ In the last chapter we presented some general points about file objects.
+ This chapter focuses on how to use fields and variables (that is variables
+ and attributes in NetCDF nomenclature) to populate files.
+\begin_inset Newline newline
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+How to define your first field
+\end_layout
+
+\begin_layout Standard
+If you wish to input or to output data using XIOS, you will need to define
+ at least one file with one field.
+ This can be done from both the XML configuration file and the Fortran interface.
+ Fields are often defined in the configuration file, although their definitions
+ are sometimes amended using the API.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Field objects are defined with the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+<field>
+\end_layout
+
+\end_inset
+
+ tag and should always be inside a 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+<field_definition>
+\end_layout
+
+\end_inset
+
+ or a 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+<file>
+\end_layout
+
+\end_inset
+
+ section.
+ Only the grid and the operation attached to the field are mandatory to
+ have a well defined field but it is generally a good idea to give it an
+ identifier.
+ The following example shows a minimal configuration file which defines
+ one file with one field.
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" type="one_file" output_freq="1ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A" grid_ref="grid_A" operation="instant" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+It defines one file named 
+\begin_inset Quotes eld
+\end_inset
+
+
+\emph on
+output
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ which contains one field 
+\begin_inset Quotes eld
+\end_inset
+
+
+\emph on
+field_A
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ defined on a grid 
+\begin_inset Quotes eld
+\end_inset
+
+
+\emph on
+grid_A
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ The file and the field are configured so that the data is written in the
+ file at every timestep (using the 
+\series bold
+output_freq
+\series default
+ file attribute) without any transformation (using the 
+\series bold
+operation
+\series default
+ field attribute set to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+instant
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+).
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The corresponding Fortran simulation loop could be:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+DO ts=1,numberOfTimestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Inform XIOS of the current timestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        CALL xios_update_calendar(ts)
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Compute field_A for current timestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Output the data
+\end_layout
+
+\begin_layout Plain Layout
+
+        CALL xios_send_field("field_A", field_A)
+\end_layout
+
+\begin_layout Plain Layout
+
+ENDDO
+\end_layout
+
+\end_inset
+
+As you can see, the 
+\series bold
+id
+\series default
+ of the field is used in the model to select the field for which data is
+ being provided which makes this attribute extremely important.
+ Note that it must be unique for all fields even if they are defined in
+ different files.
+ By default, the 
+\series bold
+id
+\series default
+ of a field is also used as the name of the corresponding NetCDF variable.
+ It is however possible to override this default name using the field attribute
+ 
+\series bold
+name
+\series default
+.
+ Two fields can share the same 
+\series bold
+name
+\series default
+ as long as they are not used in the same file.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The second argument of the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field
+\end_layout
+
+\end_inset
+
+ function is an array containing the data.
+ Its shape and content are not described here as they depend directly on
+ the grid.
+ For more information on the data layout, refer to the chapters focusing
+ on grids, domains and axis.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The same configuration could also be obtained using the Fortran interface:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_context)   :: ctx_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_file)          :: file_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_filegroup) :: filegroup_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_field)        :: field_hdl
+\end_layout
+
+\begin_layout Plain Layout
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context, calendar and grid initializations ommited, see the corresponding
+ section of this user manual and of the reference manual
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_get_handle("test", ctx_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_current_context(ctx_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_get_filegroup_handle("file_definition", filegroup_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_add_file(filegroup_hdl, file_hdl)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_attr(file_hdl, name="output", output_freq=xios_timestep)
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_add_field(file_hdl, field_hdl, "field_A")
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_attr(field_hdl, grid_ref="grid_A", operation="instant")
+\end_layout
+
+\end_inset
+
+Note that if you want to define a field on a grid with only one domain and/or
+ one axis, it is possible to use the 
+\series bold
+domain_ref
+\series default
+ and 
+\series bold
+axis_ref
+\series default
+ attributes instead of the 
+\series bold
+grid_ref
+\series default
+ attribute.
+ A temporary grid will be created based on the domain and/or axis defined
+ this way.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+If you are using a grid with some masked points (see the relevant sections
+ of this manual), you must set the 
+\series bold
+default_value
+\series default
+ attribute to define the default value that will replace the missing values
+ in the output file.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+If you wish to disable a field without having to remove its definition from
+ the configuration file, you can set the 
+\series bold
+enabled
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+false
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+How to use temporal operations
+\end_layout
+
+\begin_layout Standard
+The last section showed a very basic example where the data was outputted
+ at every timestep using the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+instant
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ 
+\series bold
+operation
+\series default
+.
+ However in many use cases, it might be more interesting to output only
+ the mean value on a certain period of time for example.
+ This section describes the use of temporal operations available in XIOS.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The field attribute 
+\series bold
+operation
+\series default
+ currently supports six modes:
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+instant
+\series default
+\emph default
+: no temporal operation is applied which means the new data always overrides
+ the previous one even if it was not outputted,
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+average
+\series default
+\emph default
+: compute and output the mean value,
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+accumulate
+\series default
+\emph default
+: compute and output the sum,
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+minimum
+\series default
+\emph default
+: compute and output the minimum value,
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+maximum
+\series default
+\emph default
+: compute and output the maximum value,
+\end_layout
+
+\begin_layout Itemize
+
+\series bold
+\emph on
+once
+\series default
+\emph default
+ : the data is written to the file only the first time it is received from
+ the model, any subsequent data is ignored.
+ The corresponding NetCDF variable does not have a time dimension.
+\end_layout
+
+\begin_layout Standard
+The output frequency of the file defined by the 
+\series bold
+output_freq
+\series default
+ attribute is used as the temporal operation period (except for the 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+once
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+ 
+\series bold
+operation
+\series default
+ for which there is no period).
+ This means it is for example not possible to output a daily average and
+ a weekly average in the same file.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+This updated example shows how to output the daily average instead of the
+ instant data for all timesteps:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" type="one_file" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A" grid_ref="grid_A" operation="average" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+Compared to the previous example, only the file attribute 
+\series bold
+output_freq
+\series default
+ and the field attribute 
+\series bold
+operation
+\series default
+ have been modified.
+ Computing the weekly minimum instead of the daily average would be as simple
+ as using 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+output_freq="7d"
+\end_layout
+
+\end_inset
+
+and 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+operation="minimum"
+\end_layout
+
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Note that if you use a temporal operation and have 
+\series bold
+default_value
+\series default
+ defined, it might be useful to set the attribute
+\series bold
+ detect_missing_value
+\series default
+ to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+true
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ This way temporal operations will not be applied when a default value is
+ detected.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+For example, we consider the values of a 2x2 domain for three timesteps:
+\begin_inset Formula 
+\[
+\begin{bmatrix}3 & -1\\
+7 & 1
+\end{bmatrix},\qquad\begin{bmatrix}5 & 6\\
+-1 & 2
+\end{bmatrix},\qquad\begin{bmatrix}-1 & 8\\
+3 & 4
+\end{bmatrix}.
+\]
+
+\end_inset
+
+If we suppose that the field is configured to compute the average on three
+ timesteps, the resulting field would be: 
+\begin_inset Formula 
+\[
+\begin{bmatrix}\nicefrac{7}{3} & \nicefrac{13}{3}\\
+3 & \nicefrac{7}{3}
+\end{bmatrix}.
+\]
+
+\end_inset
+
+If 
+\series bold
+default_value
+\series default
+ is set to 
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+-1
+\begin_inset Quotes erd
+\end_inset
+
+
+\emph default
+ and 
+\series bold
+detect_missing_value
+\series default
+ is set to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+true
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+, the resulting field would be: 
+\begin_inset Formula 
+\[
+\begin{bmatrix}4 & 7\\
+5 & \nicefrac{7}{3}
+\end{bmatrix}.
+\]
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+How to use a specific data sampling
+\end_layout
+
+\begin_layout Standard
+It is sometimes useful to have more control on the data sampling.
+ By default, the input data is used at every timestep but sometimes it is
+ not what you want.
+ The following examples illustrate such cases:
+\end_layout
+
+\begin_layout Enumerate
+the model is not computing updated values at the same frequency for all
+ fields (for example, a field is updated every two timesteps).
+\end_layout
+
+\begin_layout Enumerate
+you want to output a specific instant value in the interval between two
+ outputs.
+\end_layout
+
+\begin_layout Enumerate
+you want to compute an average without taking into account all instant values
+ in the interval between two outputs.
+\end_layout
+
+\begin_layout Standard
+Data sampling can be controlled in XIOS using the 
+\series bold
+freq_op
+\series default
+ (one timestep by default) and 
+\series bold
+freq_offset
+\series default
+ (null by default) attributes.
+ Those attributes define respectively how often data from the model must
+ be used and the amount of time before starting to use it.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+For following excerpts of configuration files show you to use those attributes
+ to handle the motivating examples.
+\end_layout
+
+\begin_layout Enumerate
+In this example, we suppose that we get two fields from the model: 
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+ which is computed for each timestep and 
+\begin_inset Quotes eld
+\end_inset
+
+field_B
+\begin_inset Quotes erd
+\end_inset
+
+ which is only computed every two timesteps.
+ For both fields, we show how to compute and output the sum of all values
+ received during 6 timesteps:
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <file name="output" output_freq="6ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="accumulate" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_B" grid_ref="grid_B" operation="accumulate" freq_op="2ts"
+ />
+\end_layout
+
+\begin_layout Plain Layout
+
+        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+</file_definition>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Enumerate
+In this example, we show how to output the 11th instant value every 12 timesteps
+:
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <file name="output" output_freq="12ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="instant" freq_op="11ts"
+ freq_offset="12ts" />
+\end_layout
+
+\begin_layout Plain Layout
+
+        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+</file_definition>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Enumerate
+In this example, we suppose that the timestep is equal to one hour and that
+ the simulation starts at midnight.
+ We show how to compute the weekly average of the field value at midday:
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <file name="output" output_freq="1w">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="average" freq_op="1d"
+ freq_offset="12h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+</file_definition>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+How to use field references
+\end_layout
+
+\begin_layout Standard
+It is quite common that different temporal operations must be applied to
+ the same instant data provided by the model.
+ In theory, the only solution to handle this scenario would be to define
+ a field for each operation, give them different 
+\series bold
+id
+\series default
+ and and call 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field
+\end_layout
+
+\end_inset
+
+ with the same array of data for each of those fields.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The following example illustrates this solution for a field for which we
+ want to compute the average, minimal and maximal values:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A_avg" grid_ref="grid_A" operation="average"
+ />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A_min" grid_ref="grid_A" operation="min" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A_max" grid_ref="grid_A" operation="max" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+To simplify the handling of such scenarios, XIOS has a 
+\begin_inset Quotes eld
+\end_inset
+
+reference
+\begin_inset Quotes erd
+\end_inset
+
+ feature which allows one field to inherit the attributes (except the 
+\series bold
+id
+\series default
+) and the instant data of another field.
+ The above example can then be rewritten:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A" name="field_A_avg" grid_ref="grid_A" operation="av
+erage" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field field_ref="field_A" name="field_A_min" operation="min"
+ />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field field_ref="field_A" name="field_A_max" operation="max"
+ />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+With this configuration, only one call to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field(
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+, field_A)
+\end_layout
+
+\end_inset
+
+ is needed.
+ Note how inherited attributes (like 
+\series bold
+name
+\series default
+ or 
+\series bold
+operation
+\series default
+ for example) are overwritten to obtain the desired configuration.
+ Additionally, be aware that it is the instant values which are inherited,
+ not the result of the operation on the field.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Similarly, it is sometimes useful to output the result of a temporal operation
+ on a field for different periods.
+ In this case, it does not really make sense to define the field that will
+ be then inherited in one file rather than another.
+ A solution is to make use of the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+field_definition
+\end_layout
+
+\end_inset
+
+ section so that it is clear that the field can be reused in any file.
+ This is illustrated in the following sample configuration file:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" name="field_A" grid_ref="grid_A" operation="average
+" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                </field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output_1d" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field field_ref="field_A" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output_1mo" output_freq="1mo">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field field_ref="field_A" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+How to use arithmetic operations
+\end_layout
+
+\begin_layout Standard
+Since XIOS aims to reduce as much as possible the need for post-processing,
+ it can apply some arithmetic operations on the data it handles (regardless
+ of its provenance).
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+All usual operators (+, -, *, /, ^, that is addition, subtraction, multiplicatio
+n, division and exponentiation) and some common functions (like cos, sin,
+ tan, exp, log, log10, sqrt) are supported.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The following example shows how to use arithmetic operations:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="average" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                </field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_B" field_ref="field_A">field_A + 273.15</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_C" field_ref="field_A">log10(field_B)</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+With this configuration, only one call to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field(
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+, field_A)
+\end_layout
+
+\end_inset
+
+ is needed.
+ In this example 
+\series bold
+field_ref
+\series default
+ is used only to inherit the attributes from 
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+, the instant values are not inherited since an expression has been given
+ for 
+\begin_inset Quotes eld
+\end_inset
+
+field_B
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+field_C
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Note that it is possible to use fields obtained from an expression in another
+ expression, thus the expression of 
+\begin_inset Quotes eld
+\end_inset
+
+field_C
+\begin_inset Quotes erd
+\end_inset
+
+ is equivalent to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+log10(field_A + 273.15)
+\end_layout
+
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The special keyword 
+\series bold
+this
+\series default
+ can be used in an expression to refer to the instant data received from
+ the model by the current field.
+ For example, the previous configuration file could be rewritten as follow:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_B" grid_ref="grid_A" operation="average">this
+ + 273.15</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_C" field_ref="field_B">log10(field_B)</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+and the Fortran call would be replaced by 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field(
+\begin_inset Quotes eld
+\end_inset
+
+field_B
+\begin_inset Quotes erd
+\end_inset
+
+, field_A)
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+How to chain multiple temporal operations
+\end_layout
+
+\begin_layout Standard
+By default, all field names appearing in an expression refer to the instant
+ data of those fields.
+ To refer to the result of a temporal operation, the field name must be
+ prefixed with 
+\begin_inset Quotes eld
+\end_inset
+
+@
+\begin_inset Quotes erd
+\end_inset
+
+.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+This feature allows to chain multiple temporal operations as illustrated
+ bellow:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="average" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                </field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="7d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field name="field_A_min_of_average" grid_ref="grid_A" operation="min"
+ freq_op="1d">@field_A</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+This example shows how to compute the minimum on 7 days of the daily average
+ of 
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+.
+ In this context, the 
+\series bold
+freq_op
+\series default
+ attribute defines the period of the temporal operation for all fields pointed
+ with the 
+\begin_inset Quotes eld
+\end_inset
+
+@
+\begin_inset Quotes erd
+\end_inset
+
+ operator in the expression.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Another use of this feature is to do arithmetic operations on the result
+ of temporal operations.
+  The following configuration file for example shows how to output the standard
+ deviation for a field on a one day period: 
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="average" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A_square" field_ref="grid_A">field_A * field_A</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1d">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field name="field_A_std_dev" grid_ref="grid_A" operation="instant"
+ freq_op="1d">sqrt(@field_A_square - @field_A^2)</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+Note that since an 
+\series bold
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+instant
+\begin_inset Quotes erd
+\end_inset
+
+
+\series default
+ 
+\emph default
+operation is used, 
+\series bold
+freq_op
+\series default
+ and 
+\series bold
+output_freq
+\series default
+ are identical in this scenario.
+\end_layout
+
+\begin_layout Section
+How to access the data of a field
+\end_layout
+
+\begin_layout Standard
+In order not to waste memory, the instant data of a field can be read from
+ the model only if:
+\end_layout
+
+\begin_layout Itemize
+it is part of a file whose attribute 
+\series bold
+mode
+\series default
+ is 
+\series bold
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+read
+\begin_inset Quotes erd
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+or its attribute 
+\series bold
+read_access
+\series default
+ is set to 
+\series bold
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+true
+\begin_inset Quotes erd
+\end_inset
+
+
+\series default
+\emph default
+.
+\end_layout
+
+\begin_layout Standard
+In any other case, trying to access the field data would cause an error.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The following configuration file:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="input" output_freq="1ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A" grid_ref="grid_A" operation="instant" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+can be used with this Fortran code:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+DO ts=1,numberOfTimestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Get field_A for current timestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        CALL xios_recv_field("field_A", field_A) ! field_A must be an allocated
+ array with the right size
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Do useful things...
+\end_layout
+
+\begin_layout Plain Layout
+
+        ! Inform XIOS of the current timestep
+\end_layout
+
+\begin_layout Plain Layout
+
+        CALL xios_update_calendar(ts)
+\end_layout
+
+\begin_layout Plain Layout
+
+ENDDO
+\end_layout
+
+\end_inset
+
+The call to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_recv_field
+\end_layout
+
+\end_inset
+
+ might block for a while if the data was not yet received from the server(s)
+ but it should not happen too often thanks to the prefetching done by XIOS.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Since the 
+\series bold
+read_access
+\series default
+ attribute allows to the access fields which depend directly on data from
+ the model, you must be very careful with the order of the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field
+\end_layout
+
+\end_inset
+
+ and 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_recv_field
+\end_layout
+
+\end_inset
+
+ calls.
+ For example, consider the following configuration file (just a simple example
+ as in practice it does not make much sense to use it):
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                <field id="field_A" grid_ref="grid_A" operation="instant" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                </field_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1ts">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_B" grid_ref="grid_A" operation="instant" read_access=
+"true">field_A / 42</field>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+If you call 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_recv_field(
+\begin_inset Quotes eld
+\end_inset
+
+field_B
+\begin_inset Quotes erd
+\end_inset
+
+, field_B)
+\end_layout
+
+\end_inset
+
+ before 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_send_field(
+\begin_inset Quotes eld
+\end_inset
+
+field_A
+\begin_inset Quotes erd
+\end_inset
+
+, field_A)
+\end_layout
+
+\end_inset
+
+, the requested data will never be available and a deadlock could occur.
+ In practice, XIOS will detect the problem and throw an error.
+\end_layout
+
+\begin_layout Section
+How to reduce the size of an output file
+\end_layout
+
+\begin_layout Standard
+The size of the output files can sometimes become a problem.
+ XIOS provides some features which may help to reduce the size of the output
+ files losslessly.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The first solution is to use the compression feature provided by HDF5 which
+ allows a field to be compressed using gzip.
+ Since it depends directly on HDF5, this feature works only when the NetCDF-4
+ format is used.
+ Unfortunately, HDF5 does not support compression (yet) for parallel output
+ so you have to use only one server or to engage the 
+\series bold
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+multiple_file
+\begin_inset Quotes erd
+\end_inset
+
+
+\series default
+\emph default
+ mode.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+To enable the gzip compression of a field, you need to set the 
+\series bold
+compression_level
+\series default
+ attribute to any integer between 1 and 9 (by default this attribute is
+ set to 0 which means that compression is disabled).
+ Using an higher compression level should improve the compression ratio
+ at the cost of using more processing power.
+ Generally using a compression level of 2 should be a good trade-off.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The following example illustrates the use of the gzip compression:
+\begin_inset listings
+lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+<?xml version="1.0"?>
+\end_layout
+
+\begin_layout Plain Layout
+
+<simulation>
+\end_layout
+
+\begin_layout Plain Layout
+
+        <context id="test">
+\end_layout
+
+\begin_layout Plain Layout
+
+                <calendar type="Gregorian" timestep="1h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <grid id="grid_A"><!-- Definition ommited --></grid>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </grid_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+                <file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <file name="output" output_freq="1ts" compression_level="2">
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_A" grid_ref="grid_A" operation="average" compression_
+level="4" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_B" grid_ref="grid_A" operation="average" compression_
+level="0" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        <field id="field_C" grid_ref="grid_A" operation="average" />
+\end_layout
+
+\begin_layout Plain Layout
+
+                        </file>
+\end_layout
+
+\begin_layout Plain Layout
+
+                </file_definition>
+\end_layout
+
+\begin_layout Plain Layout
+
+        </context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+Note that the 
+\series bold
+compression_level
+\series default
+ attribute can also be set at a file level, in this case it is inherited
+ by all fields of the file unless they explicitly override the attribute.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The second solution is available only if you are using a grid with masked
+ values.
+ In this case, you can choose to output the indexed grid instead of the
+ full grid by setting the 
+\series bold
+indexed_output
+\series default
+ attribute to 
+\series bold
+\emph on
+
+\begin_inset Quotes eld
+\end_inset
+
+true
+\begin_inset Quotes erd
+\end_inset
+
+
+\series default
+\emph default
+.
+ Missing values are then omitted and extra arrays are outputted so that
+ the translation from the 
+\begin_inset Quotes eld
+\end_inset
+
+compressed
+\begin_inset Quotes erd
+\end_inset
+
+ indexes to the true indexes can be done.
+ Due to those arrays of indexes, indexed output should be considered only
+ if there is enough masked values.
+ For more details about this feature, please refer to section 8.2 
+\begin_inset Quotes eld
+\end_inset
+
+Compression by Gathering
+\begin_inset Quotes erd
+\end_inset
+
+ of the Climate and Forecast (CF) Convention.
+\end_layout
+
 \begin_layout Standard
 \begin_inset CommandInset include