Index: /XIOS/trunk/doc/XIOS_user_guide.lyx
===================================================================
--- /XIOS/trunk/doc/XIOS_user_guide.lyx	(revision 560)
+++ /XIOS/trunk/doc/XIOS_user_guide.lyx	(revision 560)
@@ -0,0 +1,1217 @@
+#LyX 2.1 created this file. For more info see http://www.lyx.org/
+\lyxformat 474
+\begin_document
+\begin_header
+\textclass book
+\begin_preamble
+\usepackage{MnSymbol}
+\end_preamble
+\use_default_options true
+\begin_modules
+logicalmkup
+\end_modules
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_math auto
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize a4paper
+\use_geometry false
+\use_package amsmath 1
+\use_package amssymb 1
+\use_package cancel 1
+\use_package esint 1
+\use_package mathdots 1
+\use_package mathtools 1
+\use_package mhchem 1
+\use_package stackrel 1
+\use_package stmaryrd 1
+\use_package undertilde 1
+\cite_engine basic
+\cite_engine_type default
+\biblio_style plain
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\justification true
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Title
+XIOS User Guide
+\end_layout
+
+\begin_layout Author
+Draft
+\end_layout
+
+\begin_layout Chapter
+Calendar
+\end_layout
+
+\begin_layout Section
+How to define a calendar
+\end_layout
+
+\begin_layout Standard
+XIOS has an embedded calendar module which needs to be configured before
+ you can run your simulation.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Only the calendar type and the time step used by your simulation are mandatory
+ to have a well defined calendar.
+ For example, a minimal calendar definition could be:
+\end_layout
+
+\begin_layout Itemize
+from the XML configuration file:
+\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="1.5h" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+from the Fortran interface:
+\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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context initialization 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_define_calendar(type="Gregorian", timestep=1.5*xios_hour)
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The calendar type definition is done once and for all, either from the XML
+ configuration file or the Fortran interface, and cannot be modified.
+ However there is no such restriction regarding the time step which can
+ be defined at a different time than the calendar type and even redefined
+ multiple times.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+For example, it is possible to the achieve the same minimal configuration
+ as above by using both the XML configuration 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" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+and 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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context initialization 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
+
+! xios_define_calendar cannot be used here because the type was already
+ defined in the configuration file.
+\end_layout
+
+\begin_layout Plain Layout
+
+! Ommiting the following line would lead to an error because the timestep
+ would be undefined.
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_timestep(timestep=1.5*xios_hour)
+\end_layout
+
+\end_inset
+
+The calendar also has two optional date parameters:
+\end_layout
+
+\begin_layout Itemize
+the start date which corresponds to the beginning of the simulation
+\end_layout
+
+\begin_layout Itemize
+the time origin which corresponds to the origin of the time axis.
+\end_layout
+
+\begin_layout Standard
+If they are undefined, those parameters are set by default to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+0000-01-01 00:00:00
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ If you are not interested in specific dates, you can ignore those parameters
+ completely.
+ However if you wish to set them, please note that they must not be set
+ before the calendar is defined.
+ Thus the following XML configuration file would be for example invalid:
+\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
+
+		<!-- Invalid because the calendar type cannot be known at that point -->
+\end_layout
+
+\begin_layout Plain Layout
+
+		<calendar start_date="2011-11-11 13:37:42" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+while the following configuration file would be valid:
+\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
+
+		<!-- The order of the arguments does not matter so this is valid -->
+\end_layout
+
+\begin_layout Plain Layout
+
+		<calendar time_origin="2011-11-11 13:37:42" type="Gregorian" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+Of course, it is always possible to define or redefine those parameters
+ from the Fortran interface, directly when defining the calendar:
+\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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context initialization 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_define_calendar(type="Gregorian", time_origin=xios_date(1977,
+ 10, 19, 00, 00, 00), start_date=xios_date(2011, 11, 11, 13, 37, 42))
+\end_layout
+
+\end_inset
+
+or at a later time:
+\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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context initialization 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_define_calendar(type="Gregorian")
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_time_origin(time_origin=xios_date(1977, 10, 19, 00, 00, 00))
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_set_start_date(start_date=xios_date(2011, 11, 11, 13, 37, 42))
+\end_layout
+
+\end_inset
+
+To simplify the use of dates in the XML configuration files, it is possible
+ to partially define a date as long as the omitted parts are the rightmost.
+ In this case the remainder of the date is initialized as in the default
+ date.
+ For example, it would be valid to write: 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+start_date="1977-10-19"
+\end_layout
+
+\end_inset
+
+ instead of 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+start_date="1977-10-19 00:00:00"
+\end_layout
+
+\end_inset
+
+ or even 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+time_origin="1789"
+\end_layout
+
+\end_inset
+
+ instead of 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+time_origin="1789-01-01 00:00:00"
+\end_layout
+
+\end_inset
+
+.
+ Similarly, it is possible to express a date with an optional duration offset
+ in the configuration file by using the 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+date + duration
+\end_layout
+
+\end_inset
+
+ notation, with 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+date
+\end_layout
+
+\end_inset
+
+ potentially partially defined or even completely omitted.
+ Consequently the following examples are all valid in the XML configuration
+ file:
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+time_origin="2011-11-11 13:37:00 + 42s"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+time_origin="2014 + 1y 2d"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+start_date="+ 36h"
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+How to define a user defined calendar
+\end_layout
+
+\begin_layout Standard
+Predefined calendars might not be enough for your needs if you simulate
+ phenomenons on another planet than the Earth.
+ For this reason, XIOS can let you configure a completely user defined calendar
+ by setting the 
+\series bold
+type
+\series default
+ attribute to 
+\begin_inset Quotes eld
+\end_inset
+
+
+\series bold
+\emph on
+user_defined
+\series default
+\emph default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ In that case, the calendar type alone is not sufficient to define the calendar
+ and other parameters should be provided since the duration of a day or
+ a year are not known in advance.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Two approaches are possible depending on whether you want that your custom
+ calendar to have months or not: either use the 
+\series bold
+month_lengths
+\series default
+ attribute to define the duration of each months in days or use the 
+\series bold
+year_length
+\series default
+ attribute to define the duration of the year in seconds.
+ In both cases, you have to define 
+\series bold
+day_length
+\series default
+, the duration of a day in seconds.
+ Those attributes have to be defined at the same time than the calendar
+ type, either from the XML configuration file or the Fortran interface,
+ for 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="user_defined" day_length="86400" month_lengths="(1, 12)
+ [31 28 31 30 31 30 31 31 30 31 30 31]" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+or
+\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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+! Context initialization 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_define_calendar(type="Gregorian", day_length=86400, year_length=315576
+00)
+\end_layout
+
+\end_inset
+
+Note that if no months are defined, the format of the dates is modified
+ in the XML configuration file since the month must be omitted.
+ For example, 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+"2015-71 13:37:42"
+\end_layout
+
+\end_inset
+
+ would be the correct way to refer to the 71st day of the year 2015 at 13:37:42.
+ If you use the Fortran interface, the month cannot be omitted but you have
+ to make sure to always set it to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+
+ in that case.
+ For example, use 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_date(2015, 01, 71, 13, 37, 42)
+\end_layout
+
+\end_inset
+
+for 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+"2015-71 13:37:42"
+\end_layout
+
+\end_inset
+
+.
+ Moreover, it is possible that the duration of the day is greater than the
+ duration of the year on some planets.
+ In this case, it obviously not possible to define months so you have to
+ use the 
+\series bold
+year_length
+\series default
+ attribute.
+ Additionally the day must also be omitted from the dates in the configuration
+ file (for example 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+"2015 13:37:42"
+\end_layout
+
+\end_inset
+
+) and must always be set to 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+
+ when using the Fortran interface (for example 
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+xios_date(2015, 01, 01, 13, 37, 42)
+\end_layout
+
+\end_inset
+
+).
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+If months have been defined, you might want to have leap years to correct
+ the drift between the calendar year and the astronomical year.
+ This can be achieved by using the 
+\series bold
+leap_year_drift
+\series default
+ and 
+\series bold
+leap_year_month
+\series default
+ attributes and optionally the 
+\series bold
+leap_year_drift_offset
+\series default
+ attribute.
+ The idea is to define 
+\series bold
+leap_year_drift
+\series default
+, the yearly drift between the calendar year and the astronomical year as
+ a fraction of a day.
+ This yearly drift is summed each year to know the current drift and each
+ time the current drift is greater or equal to one day, the year is considered
+ a leap year.
+ In that case, an extra day is added to the month defined by 
+\series bold
+leap_year_month
+\series default
+ and one day is subtracted to the current drift.
+ The initial drift is null by default but it can be fixed by the 
+\series bold
+leap_year_drift_offset
+\series default
+ attribute.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+The following configuration file defines a simplified Gregorian calendar
+ using the user calendar feature:
+\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="user_defined"
+\end_layout
+
+\begin_layout Plain Layout
+
+					day_length="86400"
+\end_layout
+
+\begin_layout Plain Layout
+
+					month_lengths="(1, 12) [31 28 31 30 31 30 31 31 30 31 30 31]"
+\end_layout
+
+\begin_layout Plain Layout
+
+					leap_year_month="2"
+\end_layout
+
+\begin_layout Plain Layout
+
+					leap_year_drift="0.25"
+\end_layout
+
+\begin_layout Plain Layout
+
+					leap_year_drift_offset="0.75"
+\end_layout
+
+\begin_layout Plain Layout
+
+					time_origin="2012-02-29 15:00:00"
+\end_layout
+
+\begin_layout Plain Layout
+
+					start_date="2012-03-01 15:00:00" />
+\end_layout
+
+\begin_layout Plain Layout
+
+	</context>
+\end_layout
+
+\begin_layout Plain Layout
+
+</simulation>
+\end_layout
+
+\end_inset
+
+As you know, the astronomical year on Earth is approximately a quarter of
+ day longer than the Gregorian calendar year so we have to define the yearly
+ drift as 0.25 day.
+ In case of a leap year, an extra day is added at the end of February which
+ is the second month of the year so 
+\series bold
+leap_year_month
+\series default
+ should be set to 2.
+ We start our time axis in 2012 which was a leap year in the Gregorian calendar.
+ This means there was previously three non-leap years in a row so the current
+ drift was (approximately) 
+\begin_inset Formula $3\times0.25$
+\end_inset
+
+ days, hence 
+\series bold
+leap_year_drift_offset
+\series default
+ should be set to 0.75.
+ At the beginning of 2013, the drift would have been 
+\begin_inset Formula $0.75+0.25=1$
+\end_inset
+
+ day so 2012 will be a leap year as expected.
+\end_layout
+
+\begin_layout Section
+How to use the calendar
+\end_layout
+
+\begin_layout Standard
+The calendar is created immediately after the calendar type has been defined
+ and thus can be used even before the context definition has been closed.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Once the calendar is created, you have to keep it updated so that it is
+ in sync with your simulation.
+ To do that, you have to call the 
+\series bold
+xios_update_calendar
+\series default
+ subroutine for each iteration of your 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
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+INTEGER :: ts
+\end_layout
+
+\begin_layout Plain Layout
+
+! ...
+\end_layout
+
+\begin_layout Plain Layout
+
+DO ts=1,end
+\end_layout
+
+\begin_layout Plain Layout
+
+	CALL xios_update_calendar(ts)
+\end_layout
+
+\begin_layout Plain Layout
+
+	! Do useful stuff
+\end_layout
+
+\begin_layout Plain Layout
+
+ENDDO
+\end_layout
+
+\end_inset
+
+The current date is updated to 
+\begin_inset Formula $start\_date+ts\times timestep$
+\end_inset
+
+ after each call.
+\begin_inset Newline newline
+\end_inset
+
+
+\begin_inset Newline newline
+\end_inset
+
+Many other calendar operations are available, including:
+\end_layout
+
+\begin_layout Itemize
+accessing various calendar related information like the time step, the time
+ origin, the start date, the duration of a day or a year, the current date,
+ etc.
+ 
+\end_layout
+
+\begin_layout Itemize
+doing arithmetic and comparison operations on date:
+\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
+
+TYPE(xios_date) :: date1, date2
+\end_layout
+
+\begin_layout Plain Layout
+
+TYPE(xios_duration) :: duration
+\end_layout
+
+\begin_layout Plain Layout
+
+LOGICAL :: res
+\end_layout
+
+\begin_layout Plain Layout
+
+! we suppose a calendar is defined
+\end_layout
+
+\begin_layout Plain Layout
+
+CALL xios_get_current_date(date1)
+\end_layout
+
+\begin_layout Plain Layout
+
+duration = xios_duration(0, 0, 1, 0, 0, 0, 0, 0) + 12 * xios_hour
+\end_layout
+
+\begin_layout Plain Layout
+
+date2 = date1 + duration + 0.5 * xios_hour
+\end_layout
+
+\begin_layout Plain Layout
+
+res = date2 > date1
+\end_layout
+
+\begin_layout Plain Layout
+
+duration = date2 - date1
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+converting dates to
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+the number of seconds since the time origin, the beginning of the year or
+ the beginning of the day,
+\end_layout
+
+\begin_layout Itemize
+the number of days since the beginning of the year,
+\end_layout
+
+\begin_layout Itemize
+the fraction of the day or the year.
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+For more detailed about the calendar attributes and operations, see the
+ XIOS reference guide.
+\end_layout
+
+\end_body
+\end_document
