#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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\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