#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