source: XIOS/trunk/doc/XIOS_user_guide.lyx @ 655

#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