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

Last change on this file since 916 was 916, checked in by rlacroix, 5 years ago

User guide: Document the buffer size related options.

File size: 86.7 KB
Line 
1#LyX 2.1 created this file. For more info see http://www.lyx.org/
2\lyxformat 474
3\begin_document
4\begin_header
5\textclass book
6\begin_preamble
7\usepackage{MnSymbol}
8\end_preamble
9\use_default_options true
10\begin_modules
11logicalmkup
12\end_modules
13\maintain_unincluded_children false
14\language english
15\language_package default
16\inputencoding auto
17\fontencoding global
18\font_roman default
19\font_sans default
20\font_typewriter default
21\font_math auto
22\font_default_family default
23\use_non_tex_fonts false
24\font_sc false
25\font_osf false
26\font_sf_scale 100
27\font_tt_scale 100
28\graphics default
29\default_output_format default
30\output_sync 0
31\bibtex_command default
32\index_command default
33\paperfontsize default
34\spacing single
35\use_hyperref false
36\papersize a4paper
37\use_geometry false
38\use_package amsmath 1
39\use_package amssymb 1
40\use_package cancel 1
41\use_package esint 1
42\use_package mathdots 1
43\use_package mathtools 1
44\use_package mhchem 1
45\use_package stackrel 1
46\use_package stmaryrd 1
47\use_package undertilde 1
48\cite_engine basic
49\cite_engine_type default
50\biblio_style plain
51\use_bibtopic false
52\use_indices false
53\paperorientation portrait
54\suppress_date false
55\justification true
56\use_refstyle 0
57\index Index
58\shortcut idx
59\color #008000
60\end_index
61\secnumdepth 3
62\tocdepth 3
63\paragraph_separation indent
64\paragraph_indentation default
65\quotes_language english
66\papercolumns 1
67\papersides 1
68\paperpagestyle default
69\tracking_changes false
70\output_changes false
71\html_math_output 0
72\html_css_as_file 0
73\html_be_strict false
74\end_header
75
76\begin_body
77
78\begin_layout Title
79XIOS User Guide
80\end_layout
81
82\begin_layout Author
83Draft
84\end_layout
85
86\begin_layout Chapter
87Calendar
88\end_layout
89
90\begin_layout Section
91How to define a calendar
92\end_layout
93
94\begin_layout Standard
95XIOS has an embedded calendar module which needs to be configured before
96 you can run your simulation.
97\begin_inset Newline newline
98\end_inset
99
100
101\begin_inset Newline newline
102\end_inset
103
104Only the calendar type and the time step used by your simulation are mandatory
105 to have a well defined calendar.
106 For example, a minimal calendar definition could be:
107\end_layout
108
109\begin_layout Itemize
110from the XML configuration file:
111\begin_inset Newline newline
112\end_inset
113
114
115\begin_inset listings
116lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
117inline false
118status open
119
120\begin_layout Plain Layout
121
122<?xml version="1.0"?>
123\end_layout
124
125\begin_layout Plain Layout
126
127<simulation>
128\end_layout
129
130\begin_layout Plain Layout
131
132        <context id="test">
133\end_layout
134
135\begin_layout Plain Layout
136
137                <calendar type="Gregorian" timestep="1.5h" />
138\end_layout
139
140\begin_layout Plain Layout
141
142        </context>
143\end_layout
144
145\begin_layout Plain Layout
146
147</simulation>
148\end_layout
149
150\end_inset
151
152
153\end_layout
154
155\begin_layout Itemize
156from the Fortran interface:
157\begin_inset Newline newline
158\end_inset
159
160
161\begin_inset listings
162lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
163inline false
164status open
165
166\begin_layout Plain Layout
167
168! ...
169\end_layout
170
171\begin_layout Plain Layout
172
173TYPE(xios_context) :: ctx_hdl
174\end_layout
175
176\begin_layout Plain Layout
177
178! ...
179\end_layout
180
181\begin_layout Plain Layout
182
183! Context initialization ommited, see the corresponding section of this
184 user manual and of the reference manual
185\end_layout
186
187\begin_layout Plain Layout
188
189CALL xios_get_handle("test",ctx_hdl)
190\end_layout
191
192\begin_layout Plain Layout
193
194CALL xios_set_current_context(ctx_hdl)
195\end_layout
196
197\begin_layout Plain Layout
198
199CALL xios_define_calendar(type="Gregorian", timestep=1.5*xios_hour)
200\end_layout
201
202\end_inset
203
204
205\end_layout
206
207\begin_layout Standard
208The calendar type definition is done once and for all, either from the XML
209 configuration file or the Fortran interface, and cannot be modified.
210 However there is no such restriction regarding the time step which can
211 be defined at a different time than the calendar type and even redefined
212 multiple times.
213\begin_inset Newline newline
214\end_inset
215
216
217\begin_inset Newline newline
218\end_inset
219
220For example, it is possible to the achieve the same minimal configuration
221 as above by using both the XML configuration file:
222\end_layout
223
224\begin_layout Standard
225\begin_inset listings
226lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
227inline false
228status open
229
230\begin_layout Plain Layout
231
232<?xml version="1.0"?>
233\end_layout
234
235\begin_layout Plain Layout
236
237<simulation>
238\end_layout
239
240\begin_layout Plain Layout
241
242        <context id="test">
243\end_layout
244
245\begin_layout Plain Layout
246
247                <calendar type="Gregorian" />
248\end_layout
249
250\begin_layout Plain Layout
251
252        </context>
253\end_layout
254
255\begin_layout Plain Layout
256
257</simulation>
258\end_layout
259
260\end_inset
261
262and the Fortran interface:
263\end_layout
264
265\begin_layout Standard
266\begin_inset listings
267lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
268inline false
269status open
270
271\begin_layout Plain Layout
272
273! ...
274\end_layout
275
276\begin_layout Plain Layout
277
278TYPE(xios_context) :: ctx_hdl
279\end_layout
280
281\begin_layout Plain Layout
282
283! ...
284\end_layout
285
286\begin_layout Plain Layout
287
288! Context initialization ommited, see the corresponding section of this
289 user manual and of the reference manual
290\end_layout
291
292\begin_layout Plain Layout
293
294CALL xios_get_handle("test",ctx_hdl)
295\end_layout
296
297\begin_layout Plain Layout
298
299CALL xios_set_current_context(ctx_hdl)
300\end_layout
301
302\begin_layout Plain Layout
303
304! xios_define_calendar cannot be used here because the type was already
305 defined in the configuration file.
306\end_layout
307
308\begin_layout Plain Layout
309
310! Ommiting the following line would lead to an error because the timestep
311 would be undefined.
312\end_layout
313
314\begin_layout Plain Layout
315
316CALL xios_set_timestep(timestep=1.5*xios_hour)
317\end_layout
318
319\end_inset
320
321The calendar also has two optional date parameters:
322\end_layout
323
324\begin_layout Itemize
325the start date which corresponds to the beginning of the simulation
326\end_layout
327
328\begin_layout Itemize
329the time origin which corresponds to the origin of the time axis.
330\end_layout
331
332\begin_layout Standard
333If they are undefined, those parameters are set by default to
334\begin_inset Quotes eld
335\end_inset
336
337
338\series bold
339\emph on
3400000-01-01 00:00:00
341\series default
342\emph default
343
344\begin_inset Quotes erd
345\end_inset
346
347.
348 If you are not interested in specific dates, you can ignore those parameters
349 completely.
350 However if you wish to set them, please note that they must not be set
351 before the calendar is defined.
352 Thus the following XML configuration file would be for example invalid:
353\end_layout
354
355\begin_layout Standard
356\begin_inset listings
357lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
358inline false
359status open
360
361\begin_layout Plain Layout
362
363<?xml version="1.0"?>
364\end_layout
365
366\begin_layout Plain Layout
367
368<simulation>
369\end_layout
370
371\begin_layout Plain Layout
372
373        <context id="test">
374\end_layout
375
376\begin_layout Plain Layout
377
378                <!-- Invalid because the calendar type cannot be known at that point -->
379\end_layout
380
381\begin_layout Plain Layout
382
383                <calendar start_date="2011-11-11 13:37:42" />
384\end_layout
385
386\begin_layout Plain Layout
387
388        </context>
389\end_layout
390
391\begin_layout Plain Layout
392
393</simulation>
394\end_layout
395
396\end_inset
397
398while the following configuration file would be valid:
399\end_layout
400
401\begin_layout Standard
402\begin_inset listings
403lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
404inline false
405status open
406
407\begin_layout Plain Layout
408
409<?xml version="1.0"?>
410\end_layout
411
412\begin_layout Plain Layout
413
414<simulation>
415\end_layout
416
417\begin_layout Plain Layout
418
419        <context id="test">
420\end_layout
421
422\begin_layout Plain Layout
423
424                <!-- The order of the arguments does not matter so this is valid -->
425\end_layout
426
427\begin_layout Plain Layout
428
429                <calendar time_origin="2011-11-11 13:37:42" type="Gregorian" />
430\end_layout
431
432\begin_layout Plain Layout
433
434        </context>
435\end_layout
436
437\begin_layout Plain Layout
438
439</simulation>
440\end_layout
441
442\end_inset
443
444Of course, it is always possible to define or redefine those parameters
445 from the Fortran interface, directly when defining the calendar:
446\end_layout
447
448\begin_layout Standard
449\begin_inset listings
450lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
451inline false
452status open
453
454\begin_layout Plain Layout
455
456! ...
457\end_layout
458
459\begin_layout Plain Layout
460
461TYPE(xios_context) :: ctx_hdl
462\end_layout
463
464\begin_layout Plain Layout
465
466! ...
467\end_layout
468
469\begin_layout Plain Layout
470
471! Context initialization ommited, see the corresponding section of this
472 user manual and of the reference manual
473\end_layout
474
475\begin_layout Plain Layout
476
477CALL xios_get_handle("test",ctx_hdl)
478\end_layout
479
480\begin_layout Plain Layout
481
482CALL xios_set_current_context(ctx_hdl)
483\end_layout
484
485\begin_layout Plain Layout
486
487CALL xios_define_calendar(type="Gregorian", time_origin=xios_date(1977,
488 10, 19, 00, 00, 00), start_date=xios_date(2011, 11, 11, 13, 37, 42))
489\end_layout
490
491\end_inset
492
493or at a later time:
494\end_layout
495
496\begin_layout Standard
497\begin_inset listings
498lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
499inline false
500status open
501
502\begin_layout Plain Layout
503
504! ...
505\end_layout
506
507\begin_layout Plain Layout
508
509TYPE(xios_context) :: ctx_hdl
510\end_layout
511
512\begin_layout Plain Layout
513
514! ...
515\end_layout
516
517\begin_layout Plain Layout
518
519! Context initialization ommited, see the corresponding section of this
520 user manual and of the reference manual
521\end_layout
522
523\begin_layout Plain Layout
524
525CALL xios_get_handle("test",ctx_hdl)
526\end_layout
527
528\begin_layout Plain Layout
529
530CALL xios_set_current_context(ctx_hdl)
531\end_layout
532
533\begin_layout Plain Layout
534
535CALL xios_define_calendar(type="Gregorian")
536\end_layout
537
538\begin_layout Plain Layout
539
540CALL xios_set_time_origin(time_origin=xios_date(1977, 10, 19, 00, 00, 00))
541\end_layout
542
543\begin_layout Plain Layout
544
545CALL xios_set_start_date(start_date=xios_date(2011, 11, 11, 13, 37, 42))
546\end_layout
547
548\end_inset
549
550To simplify the use of dates in the XML configuration files, it is possible
551 to partially define a date as long as the omitted parts are the rightmost.
552 In this case the remainder of the date is initialized as in the default
553 date.
554 For example, it would be valid to write:
555\begin_inset Flex Code
556status open
557
558\begin_layout Plain Layout
559start_date="1977-10-19"
560\end_layout
561
562\end_inset
563
564 instead of
565\begin_inset Flex Code
566status open
567
568\begin_layout Plain Layout
569start_date="1977-10-19 00:00:00"
570\end_layout
571
572\end_inset
573
574 or even
575\begin_inset Flex Code
576status open
577
578\begin_layout Plain Layout
579time_origin="1789"
580\end_layout
581
582\end_inset
583
584 instead of
585\begin_inset Flex Code
586status open
587
588\begin_layout Plain Layout
589time_origin="1789-01-01 00:00:00"
590\end_layout
591
592\end_inset
593
594.
595 Similarly, it is possible to express a date with an optional duration offset
596 in the configuration file by using the
597\begin_inset Flex Code
598status open
599
600\begin_layout Plain Layout
601date + duration
602\end_layout
603
604\end_inset
605
606 notation, with
607\begin_inset Flex Code
608status open
609
610\begin_layout Plain Layout
611date
612\end_layout
613
614\end_inset
615
616 potentially partially defined or even completely omitted.
617 Consequently the following examples are all valid in the XML configuration
618 file:
619\end_layout
620
621\begin_layout Itemize
622\begin_inset Flex Code
623status open
624
625\begin_layout Plain Layout
626time_origin="2011-11-11 13:37:00 + 42s"
627\end_layout
628
629\end_inset
630
631
632\end_layout
633
634\begin_layout Itemize
635\begin_inset Flex Code
636status open
637
638\begin_layout Plain Layout
639time_origin="2014 + 1y 2d"
640\end_layout
641
642\end_inset
643
644
645\end_layout
646
647\begin_layout Itemize
648\begin_inset Flex Code
649status open
650
651\begin_layout Plain Layout
652start_date="+ 36h"
653\end_layout
654
655\end_inset
656
657.
658\end_layout
659
660\begin_layout Section
661How to define a user defined calendar
662\end_layout
663
664\begin_layout Standard
665Predefined calendars might not be enough for your needs if you simulate
666 phenomenons on another planet than the Earth.
667 For this reason, XIOS can let you configure a completely user defined calendar
668 by setting the
669\series bold
670type
671\series default
672 attribute to
673\begin_inset Quotes eld
674\end_inset
675
676
677\series bold
678\emph on
679user_defined
680\series default
681\emph default
682
683\begin_inset Quotes erd
684\end_inset
685
686.
687 In that case, the calendar type alone is not sufficient to define the calendar
688 and other parameters should be provided since the duration of a day or
689 a year are not known in advance.
690\begin_inset Newline newline
691\end_inset
692
693
694\begin_inset Newline newline
695\end_inset
696
697Two approaches are possible depending on whether you want that your custom
698 calendar to have months or not: either use the
699\series bold
700month_lengths
701\series default
702 attribute to define the duration of each months in days or use the
703\series bold
704year_length
705\series default
706 attribute to define the duration of the year in seconds.
707 In both cases, you have to define
708\series bold
709day_length
710\series default
711, the duration of a day in seconds.
712 Those attributes have to be defined at the same time than the calendar
713 type, either from the XML configuration file or the Fortran interface,
714 for example:
715\begin_inset Newline newline
716\end_inset
717
718
719\begin_inset listings
720lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
721inline false
722status open
723
724\begin_layout Plain Layout
725
726<?xml version="1.0"?>
727\end_layout
728
729\begin_layout Plain Layout
730
731<simulation>
732\end_layout
733
734\begin_layout Plain Layout
735
736        <context id="test">
737\end_layout
738
739\begin_layout Plain Layout
740
741                <calendar type="user_defined" day_length="86400" month_lengths="(1, 12)
742 [31 28 31 30 31 30 31 31 30 31 30 31]" />
743\end_layout
744
745\begin_layout Plain Layout
746
747        </context>
748\end_layout
749
750\begin_layout Plain Layout
751
752</simulation>
753\end_layout
754
755\end_inset
756
757or
758\end_layout
759
760\begin_layout Standard
761\begin_inset listings
762lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
763inline false
764status open
765
766\begin_layout Plain Layout
767
768! ...
769\end_layout
770
771\begin_layout Plain Layout
772
773TYPE(xios_context) :: ctx_hdl
774\end_layout
775
776\begin_layout Plain Layout
777
778! ...
779\end_layout
780
781\begin_layout Plain Layout
782
783! Context initialization ommited, see the corresponding section of this
784 user manual and of the reference manual
785\end_layout
786
787\begin_layout Plain Layout
788
789CALL xios_get_handle("test",ctx_hdl)
790\end_layout
791
792\begin_layout Plain Layout
793
794CALL xios_set_current_context(ctx_hdl)
795\end_layout
796
797\begin_layout Plain Layout
798
799CALL xios_define_calendar(type="Gregorian", day_length=86400, year_length=315576
80000)
801\end_layout
802
803\end_inset
804
805Note that if no months are defined, the format of the dates is modified
806 in the XML configuration file since the month must be omitted.
807 For example,
808\begin_inset Flex Code
809status open
810
811\begin_layout Plain Layout
812"2015-71 13:37:42"
813\end_layout
814
815\end_inset
816
817 would be the correct way to refer to the 71st day of the year 2015 at 13:37:42.
818 If you use the Fortran interface, the month cannot be omitted but you have
819 to make sure to always set it to
820\begin_inset Flex Code
821status open
822
823\begin_layout Plain Layout
8241
825\end_layout
826
827\end_inset
828
829 in that case.
830 For example, use
831\begin_inset Flex Code
832status open
833
834\begin_layout Plain Layout
835xios_date(2015, 01, 71, 13, 37, 42)
836\end_layout
837
838\end_inset
839
840for
841\begin_inset Flex Code
842status open
843
844\begin_layout Plain Layout
845"2015-71 13:37:42"
846\end_layout
847
848\end_inset
849
850.
851 Moreover, it is possible that the duration of the day is greater than the
852 duration of the year on some planets.
853 In this case, it obviously not possible to define months so you have to
854 use the
855\series bold
856year_length
857\series default
858 attribute.
859 Additionally the day must also be omitted from the dates in the configuration
860 file (for example
861\begin_inset Flex Code
862status open
863
864\begin_layout Plain Layout
865"2015 13:37:42"
866\end_layout
867
868\end_inset
869
870) and must always be set to
871\begin_inset Flex Code
872status open
873
874\begin_layout Plain Layout
8751
876\end_layout
877
878\end_inset
879
880 when using the Fortran interface (for example
881\begin_inset Flex Code
882status open
883
884\begin_layout Plain Layout
885xios_date(2015, 01, 01, 13, 37, 42)
886\end_layout
887
888\end_inset
889
890).
891\begin_inset Newline newline
892\end_inset
893
894
895\begin_inset Newline newline
896\end_inset
897
898If months have been defined, you might want to have leap years to correct
899 the drift between the calendar year and the astronomical year.
900 This can be achieved by using the
901\series bold
902leap_year_drift
903\series default
904 and
905\series bold
906leap_year_month
907\series default
908 attributes and optionally the
909\series bold
910leap_year_drift_offset
911\series default
912 attribute.
913 The idea is to define
914\series bold
915leap_year_drift
916\series default
917, the yearly drift between the calendar year and the astronomical year as
918 a fraction of a day.
919 This yearly drift is summed each year to know the current drift and each
920 time the current drift is greater or equal to one day, the year is considered
921 a leap year.
922 In that case, an extra day is added to the month defined by
923\series bold
924leap_year_month
925\series default
926 and one day is subtracted to the current drift.
927 The initial drift is null by default but it can be fixed by the
928\series bold
929leap_year_drift_offset
930\series default
931 attribute.
932\begin_inset Newline newline
933\end_inset
934
935
936\begin_inset Newline newline
937\end_inset
938
939The following configuration file defines a simplified Gregorian calendar
940 using the user calendar feature:
941\end_layout
942
943\begin_layout Standard
944\begin_inset listings
945lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
946inline false
947status open
948
949\begin_layout Plain Layout
950
951<?xml version="1.0"?>
952\end_layout
953
954\begin_layout Plain Layout
955
956<simulation>
957\end_layout
958
959\begin_layout Plain Layout
960
961        <context id="test">
962\end_layout
963
964\begin_layout Plain Layout
965
966                <calendar type="user_defined"
967\end_layout
968
969\begin_layout Plain Layout
970
971                                        day_length="86400"
972\end_layout
973
974\begin_layout Plain Layout
975
976                                        month_lengths="(1, 12) [31 28 31 30 31 30 31 31 30 31 30 31]"
977\end_layout
978
979\begin_layout Plain Layout
980
981                                        leap_year_month="2"
982\end_layout
983
984\begin_layout Plain Layout
985
986                                        leap_year_drift="0.25"
987\end_layout
988
989\begin_layout Plain Layout
990
991                                        leap_year_drift_offset="0.75"
992\end_layout
993
994\begin_layout Plain Layout
995
996                                        time_origin="2012-02-29 15:00:00"
997\end_layout
998
999\begin_layout Plain Layout
1000
1001                                        start_date="2012-03-01 15:00:00" />
1002\end_layout
1003
1004\begin_layout Plain Layout
1005
1006        </context>
1007\end_layout
1008
1009\begin_layout Plain Layout
1010
1011</simulation>
1012\end_layout
1013
1014\end_inset
1015
1016As you know, the astronomical year on Earth is approximately a quarter of
1017 day longer than the Gregorian calendar year so we have to define the yearly
1018 drift as 0.25 day.
1019 In case of a leap year, an extra day is added at the end of February which
1020 is the second month of the year so
1021\series bold
1022leap_year_month
1023\series default
1024 should be set to 2.
1025 We start our time axis in 2012 which was a leap year in the Gregorian calendar.
1026 This means there was previously three non-leap years in a row so the current
1027 drift was (approximately)
1028\begin_inset Formula $3\times0.25$
1029\end_inset
1030
1031 days, hence
1032\series bold
1033leap_year_drift_offset
1034\series default
1035 should be set to 0.75.
1036 At the beginning of 2013, the drift would have been
1037\begin_inset Formula $0.75+0.25=1$
1038\end_inset
1039
1040 day so 2012 will be a leap year as expected.
1041\end_layout
1042
1043\begin_layout Section
1044How to use the calendar
1045\end_layout
1046
1047\begin_layout Standard
1048The calendar is created immediately after the calendar type has been defined
1049 and thus can be used even before the context definition has been closed.
1050\begin_inset Newline newline
1051\end_inset
1052
1053
1054\begin_inset Newline newline
1055\end_inset
1056
1057Once the calendar is created, you have to keep it updated so that it is
1058 in sync with your simulation.
1059 To do that, you have to call the
1060\series bold
1061xios_update_calendar
1062\series default
1063 subroutine for each iteration of your code:
1064\end_layout
1065
1066\begin_layout Standard
1067\begin_inset listings
1068lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1069inline false
1070status open
1071
1072\begin_layout Plain Layout
1073
1074! ...
1075\end_layout
1076
1077\begin_layout Plain Layout
1078
1079INTEGER :: ts
1080\end_layout
1081
1082\begin_layout Plain Layout
1083
1084! ...
1085\end_layout
1086
1087\begin_layout Plain Layout
1088
1089DO ts=1,end
1090\end_layout
1091
1092\begin_layout Plain Layout
1093
1094        CALL xios_update_calendar(ts)
1095\end_layout
1096
1097\begin_layout Plain Layout
1098
1099        ! Do useful stuff
1100\end_layout
1101
1102\begin_layout Plain Layout
1103
1104ENDDO
1105\end_layout
1106
1107\end_inset
1108
1109The current date is updated to
1110\begin_inset Formula $start\_date+ts\times timestep$
1111\end_inset
1112
1113 after each call.
1114\begin_inset Newline newline
1115\end_inset
1116
1117
1118\begin_inset Newline newline
1119\end_inset
1120
1121Many other calendar operations are available, including:
1122\end_layout
1123
1124\begin_layout Itemize
1125accessing various calendar related information like the time step, the time
1126 origin, the start date, the duration of a day or a year, the current date,
1127 etc.
1128 
1129\end_layout
1130
1131\begin_layout Itemize
1132doing arithmetic and comparison operations on date:
1133\begin_inset Newline newline
1134\end_inset
1135
1136
1137\begin_inset listings
1138lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1139inline false
1140status open
1141
1142\begin_layout Plain Layout
1143
1144TYPE(xios_date) :: date1, date2
1145\end_layout
1146
1147\begin_layout Plain Layout
1148
1149TYPE(xios_duration) :: duration
1150\end_layout
1151
1152\begin_layout Plain Layout
1153
1154LOGICAL :: res
1155\end_layout
1156
1157\begin_layout Plain Layout
1158
1159! we suppose a calendar is defined
1160\end_layout
1161
1162\begin_layout Plain Layout
1163
1164CALL xios_get_current_date(date1)
1165\end_layout
1166
1167\begin_layout Plain Layout
1168
1169duration = xios_duration(0, 0, 1, 0, 0, 0, 0, 0) + 12 * xios_hour
1170\end_layout
1171
1172\begin_layout Plain Layout
1173
1174date2 = date1 + duration + 0.5 * xios_hour
1175\end_layout
1176
1177\begin_layout Plain Layout
1178
1179res = date2 > date1
1180\end_layout
1181
1182\begin_layout Plain Layout
1183
1184duration = date2 - date1
1185\end_layout
1186
1187\end_inset
1188
1189
1190\end_layout
1191
1192\begin_layout Itemize
1193converting dates to
1194\end_layout
1195
1196\begin_deeper
1197\begin_layout Itemize
1198the number of seconds since the time origin, the beginning of the year or
1199 the beginning of the day,
1200\end_layout
1201
1202\begin_layout Itemize
1203the number of days since the beginning of the year,
1204\end_layout
1205
1206\begin_layout Itemize
1207the fraction of the day or the year.
1208\end_layout
1209
1210\end_deeper
1211\begin_layout Standard
1212For more detailed about the calendar attributes and operations, see the
1213 XIOS reference guide.
1214\end_layout
1215
1216\begin_layout Chapter
1217Files
1218\end_layout
1219
1220\begin_layout Standard
1221Since files are central to an I/O server, the configuration of XIOS is built
1222 around file objects.
1223 Those objects correspond directly to files on the computer file system
1224 which are either to be written or to be read.
1225 Although, XIOS currently only supports the NetCDF format, XIOS files are
1226 a generic abstraction.
1227 Each file can contain one or more fields (each field being defined on a
1228 grid) and optionally variables.
1229 In the NetCDF nomenclature, fields defined in XIOS correspond to NetCDF
1230 variables and XIOS variables are NetCDF attributes.
1231 As fields, variables and grids are complex objects, they have their own
1232 chapters and we will focus only on files in this section.
1233\end_layout
1234
1235\begin_layout Section
1236How to define your first file
1237\end_layout
1238
1239\begin_layout Standard
1240If you wish to input or to output data using XIOS, you will need to define
1241 at least one file.
1242 This can be done from both the XML configuration file and the Fortran interface.
1243 Files are usually defined in the configuration file, although their definitions
1244 are sometimes amended using the API.
1245\begin_inset Newline newline
1246\end_inset
1247
1248
1249\begin_inset Newline newline
1250\end_inset
1251
1252File objects are defined with the
1253\begin_inset Flex Code
1254status open
1255
1256\begin_layout Plain Layout
1257<file>
1258\end_layout
1259
1260\end_inset
1261
1262 tag and should always be inside the
1263\begin_inset Flex Code
1264status open
1265
1266\begin_layout Plain Layout
1267<file_definition>
1268\end_layout
1269
1270\end_inset
1271
1272 section.
1273 Only the output frequency is mandatory to have a well defined file but
1274 it is generally a good idea to give it a name.
1275 The following example shows a minimal configuration file which defines
1276 one file.
1277\end_layout
1278
1279\begin_layout Standard
1280\begin_inset listings
1281lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1282inline false
1283status open
1284
1285\begin_layout Plain Layout
1286
1287<?xml version="1.0"?>
1288\end_layout
1289
1290\begin_layout Plain Layout
1291
1292<simulation>
1293\end_layout
1294
1295\begin_layout Plain Layout
1296
1297        <context id="test">
1298\end_layout
1299
1300\begin_layout Plain Layout
1301
1302                <calendar type="Gregorian" timestep="1h" />
1303\end_layout
1304
1305\begin_layout Plain Layout
1306
1307\end_layout
1308
1309\begin_layout Plain Layout
1310
1311                <file_definition>
1312\end_layout
1313
1314\begin_layout Plain Layout
1315
1316                        <file name="output" output_freq="1ts">
1317\end_layout
1318
1319\begin_layout Plain Layout
1320
1321                        <!-- Content of the file ommited for now -->
1322\end_layout
1323
1324\begin_layout Plain Layout
1325
1326                        </file>
1327\end_layout
1328
1329\begin_layout Plain Layout
1330
1331                </file_definition>
1332\end_layout
1333
1334\begin_layout Plain Layout
1335
1336        </context>
1337\end_layout
1338
1339\begin_layout Plain Layout
1340
1341</simulation>
1342\end_layout
1343
1344\end_inset
1345
1346Note that the file extension could depend of the format so it is automatically
1347 added to the chosen name by XIOS.
1348 Since XIOS only support NetCDF formats for now, the extension is always
1349 
1350\begin_inset Quotes eld
1351\end_inset
1352
1353.nc
1354\begin_inset Quotes erd
1355\end_inset
1356
1357.
1358 If the name is not set, XIOS will use the id of the file object instead.
1359 This id is generated automatically by XIOS if it was not set by the user.
1360\begin_inset Newline newline
1361\end_inset
1362
1363
1364\begin_inset Newline newline
1365\end_inset
1366
1367The output frequency is particularly important since it defines the interval
1368 of time between two consecutive outputs, that is in NetCDF nomenclature
1369 the interval between two records.
1370 In the example, the data would be written for every timestep (independently
1371 of the timestep duration).
1372 It is possible to use any duration as the output frequency but be careful
1373 if you are not using a duration which is a multiple of the timestep duration
1374 since XIOS might not be doing what you want.
1375\begin_inset Newline newline
1376\end_inset
1377
1378
1379\begin_inset Newline newline
1380\end_inset
1381
1382The same configuration could be obtained from the Fortran interface as well:
1383\begin_inset Newline newline
1384\end_inset
1385
1386
1387\begin_inset listings
1388lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1389inline false
1390status open
1391
1392\begin_layout Plain Layout
1393
1394! ...
1395\end_layout
1396
1397\begin_layout Plain Layout
1398
1399TYPE(xios_context)   :: ctx_hdl
1400\end_layout
1401
1402\begin_layout Plain Layout
1403
1404TYPE(xios_file)          :: file_hdl
1405\end_layout
1406
1407\begin_layout Plain Layout
1408
1409TYPE(xios_filegroup) :: filegroup_hdl
1410\end_layout
1411
1412\begin_layout Plain Layout
1413
1414! ...
1415\end_layout
1416
1417\begin_layout Plain Layout
1418
1419! Context and calendar initializations ommited, see the corresponding section
1420 of this user manual and of the reference manual
1421\end_layout
1422
1423\begin_layout Plain Layout
1424
1425CALL xios_get_handle("test", ctx_hdl)
1426\end_layout
1427
1428\begin_layout Plain Layout
1429
1430CALL xios_set_current_context(ctx_hdl)
1431\end_layout
1432
1433\begin_layout Plain Layout
1434
1435CALL xios_get_filegroup_handle("file_definition", filegroup_hdl)
1436\end_layout
1437
1438\begin_layout Plain Layout
1439
1440CALL xios_add_file(filegroup_hdl, file_hdl)
1441\end_layout
1442
1443\begin_layout Plain Layout
1444
1445CALL xios_set_attr(file_hdl, name="output", output_freq=xios_timestep)
1446\end_layout
1447
1448\end_inset
1449
1450Another important parameter for file is the
1451\series bold
1452mode
1453\series default
1454 attribute which is set by default to
1455\begin_inset Quotes eld
1456\end_inset
1457
1458
1459\series bold
1460\emph on
1461write
1462\series default
1463\emph default
1464
1465\begin_inset Quotes erd
1466\end_inset
1467
1468.
1469 You need to set it to
1470\begin_inset Quotes eld
1471\end_inset
1472
1473
1474\series bold
1475\emph on
1476read
1477\series default
1478\emph default
1479
1480\begin_inset Quotes erd
1481\end_inset
1482
1483 if you want to use XIOS to handle inputs.
1484 Note that in this case the
1485\series bold
1486output_freq
1487\series default
1488 attribute must correspond to the output frequency used to create the input
1489 file.
1490\begin_inset Newline newline
1491\end_inset
1492
1493
1494\begin_inset Newline newline
1495\end_inset
1496
1497When using the
1498\begin_inset Quotes eld
1499\end_inset
1500
1501
1502\series bold
1503\emph on
1504write
1505\series default
1506\emph default
1507
1508\begin_inset Quotes erd
1509\end_inset
1510
1511 mode, it is possible to append the data to an existing file instead of
1512 overwriting it by setting the
1513\series bold
1514append
1515\series default
1516 attribute to
1517\begin_inset Quotes eld
1518\end_inset
1519
1520
1521\series bold
1522\emph on
1523true
1524\series default
1525\emph default
1526
1527\begin_inset Quotes erd
1528\end_inset
1529
1530.
1531 In this case, you must be careful not to modify the structure of the file,
1532 in particular no fields should be added, modified nor removed, or XIOS
1533 will throw an error.
1534\begin_inset Newline newline
1535\end_inset
1536
1537
1538\begin_inset Newline newline
1539\end_inset
1540
1541If you wish to disable a file without having to remove its definition from
1542 the configuration file, you can set the
1543\series bold
1544enabled
1545\series default
1546 attribute to
1547\begin_inset Quotes eld
1548\end_inset
1549
1550
1551\series bold
1552\emph on
1553false
1554\series default
1555\emph default
1556
1557\begin_inset Quotes erd
1558\end_inset
1559
1560.
1561\end_layout
1562
1563\begin_layout Section
1564How to use parallel I/O
1565\end_layout
1566
1567\begin_layout Standard
1568By default XIOS will create one file by server, each file being suffixed
1569 with the rank of the server.
1570 For example, if the sample configuration used in the previous section was
1571 used with two servers, two files named
1572\begin_inset Quotes eld
1573\end_inset
1574
1575output_0.nc
1576\begin_inset Quotes erd
1577\end_inset
1578
1579 and
1580\begin_inset Quotes eld
1581\end_inset
1582
1583output_1.nc
1584\begin_inset Quotes erd
1585\end_inset
1586
1587 would be created.
1588 Each file would contain only the portion of the fields affected to the
1589 corresponding server.
1590 This default mode can also be explicitly configured by setting the
1591\series bold
1592type
1593\series default
1594 attribute to
1595\begin_inset Quotes eld
1596\end_inset
1597
1598
1599\series bold
1600\emph on
1601multiple_file
1602\series default
1603\emph default
1604
1605\begin_inset Quotes erd
1606\end_inset
1607
1608.
1609\begin_inset Newline newline
1610\end_inset
1611
1612
1613\begin_inset Newline newline
1614\end_inset
1615
1616Using the
1617\begin_inset Quotes eld
1618\end_inset
1619
1620
1621\series bold
1622\emph on
1623multiple_file
1624\series default
1625\emph default
1626
1627\begin_inset Quotes erd
1628\end_inset
1629
1630 mode is often a reliable way to achieve good performances, particularly
1631 if you only have a few servers.
1632 However having multiple files also increases the complexity of the post-process
1633ing chains and it is often much easier to always get one file regardless
1634 of how many servers are used.
1635\begin_inset Newline newline
1636\end_inset
1637
1638
1639\begin_inset Newline newline
1640\end_inset
1641
1642It is possible to achieve such behavior in XIOS by setting the
1643\series bold
1644type
1645\series default
1646 attribute to
1647\begin_inset Quotes eld
1648\end_inset
1649
1650
1651\series bold
1652\emph on
1653one_file
1654\series default
1655\emph default
1656
1657\begin_inset Quotes erd
1658\end_inset
1659
1660.
1661 This feature depends directly on the NetCDF library capabilities so you
1662 need to make sure that XIOS was properly linked with a parallel version
1663 of NetCDF.
1664 If the library was not compiled with parallel input/output support, XIOS
1665 will issue a warning and revert to the
1666\begin_inset Quotes eld
1667\end_inset
1668
1669
1670\series bold
1671\emph on
1672multiple_file
1673\series default
1674\emph default
1675
1676\begin_inset Quotes erd
1677\end_inset
1678
1679 mode.
1680\end_layout
1681
1682\begin_layout Section
1683Supported NetCDF formats
1684\end_layout
1685
1686\begin_layout Standard
1687XIOS supports only the version 4 or later of NetCDF library.
1688 It uses by default the new NetCDF-4 format which relies on HDF5 format
1689 as a back-end.
1690 This format can also be selected explicitly by setting the
1691\series bold
1692format
1693\series default
1694 attribute to
1695\begin_inset Quotes eld
1696\end_inset
1697
1698
1699\series bold
1700\emph on
1701netcdf4
1702\series default
1703\emph default
1704
1705\begin_inset Quotes erd
1706\end_inset
1707
1708.
1709\begin_inset Newline newline
1710\end_inset
1711
1712
1713\begin_inset Newline newline
1714\end_inset
1715
1716Alternatively, it also possible to force NetCDF-4 to use the classic NetCDF-3
1717 binary format by setting the
1718\series bold
1719format
1720\series default
1721 attribute to
1722\begin_inset Quotes eld
1723\end_inset
1724
1725
1726\series bold
1727\emph on
1728netcdf4_classic
1729\series default
1730\emph default
1731
1732\begin_inset Quotes erd
1733\end_inset
1734
1735.
1736 When using this older format, some features might be unavailable but current
1737 version of XIOS should not be affected much.
1738\begin_inset Newline newline
1739\end_inset
1740
1741
1742\begin_inset Newline newline
1743\end_inset
1744
1745Depending on the format, there are some specific requirements on how the
1746 NetCDF library should have been compiled:
1747\end_layout
1748
1749\begin_layout Itemize
1750\begin_inset Quotes eld
1751\end_inset
1752
1753
1754\series bold
1755\emph on
1756netcdf4
1757\series default
1758\emph default
1759
1760\begin_inset Quotes erd
1761\end_inset
1762
1763 format requires that HDF5 support has been enabled in NetCDF using the
1764 configuration option
1765\begin_inset Flex Code
1766status open
1767
1768\begin_layout Plain Layout
1769-\SpecialChar \nobreakdash-
1770-enable-netcdf4
1771\end_layout
1772
1773\end_inset
1774
1775 and that the HDF5 library has been properly linked.
1776\end_layout
1777
1778\begin_layout Itemize
1779\begin_inset Quotes eld
1780\end_inset
1781
1782
1783\series bold
1784\emph on
1785netcdf4
1786\series default
1787\emph default
1788
1789\begin_inset Quotes erd
1790\end_inset
1791
1792 format used in
1793\begin_inset Quotes eld
1794\end_inset
1795
1796
1797\series bold
1798\emph on
1799one_file
1800\series default
1801\emph default
1802
1803\begin_inset Quotes erd
1804\end_inset
1805
1806 mode requires that the HDF5 library has been compiled with parallel support
1807 using the configuration option
1808\begin_inset Flex Code
1809status open
1810
1811\begin_layout Plain Layout
1812-\SpecialChar \nobreakdash-
1813-enable-parallel
1814\end_layout
1815
1816\end_inset
1817
1818.
1819\end_layout
1820
1821\begin_layout Itemize
1822\begin_inset Quotes eld
1823\end_inset
1824
1825
1826\series bold
1827\emph on
1828netcdf4_classic
1829\series default
1830\emph default
1831
1832\begin_inset Quotes erd
1833\end_inset
1834
1835 format used in
1836\begin_inset Quotes eld
1837\end_inset
1838
1839
1840\series bold
1841\emph on
1842one_file
1843\series default
1844\emph default
1845
1846\begin_inset Quotes erd
1847\end_inset
1848
1849 mode requires that Parallel NetCDF support has been enabled in NetCDF using
1850 the configuration option
1851\begin_inset Flex Code
1852status open
1853
1854\begin_layout Plain Layout
1855-\SpecialChar \nobreakdash-
1856-enable-pnetcdf
1857\end_layout
1858
1859\end_inset
1860
1861 and that the Parallel NetCDF library has been properly linked.
1862\end_layout
1863
1864\begin_layout Section
1865How to use file splitting
1866\end_layout
1867
1868\begin_layout Standard
1869Output files can often be quite huge, particularly if the
1870\begin_inset Quotes eld
1871\end_inset
1872
1873
1874\series bold
1875\emph on
1876one_file
1877\series default
1878\emph default
1879
1880\begin_inset Quotes erd
1881\end_inset
1882
1883 mode is used.
1884 In this case, it can be interesting to periodically split the file in order
1885 to have a few smaller files containing contiguous temporal portions of
1886 the output data.
1887\begin_inset Newline newline
1888\end_inset
1889
1890
1891\begin_inset Newline newline
1892\end_inset
1893
1894This behavior can be achieved in XIOS by setting the
1895\series bold
1896split_freq
1897\series default
1898 attribute to the duration you want, as illustrated in the following example:
1899\begin_inset Newline newline
1900\end_inset
1901
1902
1903\begin_inset listings
1904lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1905inline false
1906status open
1907
1908\begin_layout Plain Layout
1909
1910<?xml version="1.0"?>
1911\end_layout
1912
1913\begin_layout Plain Layout
1914
1915<simulation>
1916\end_layout
1917
1918\begin_layout Plain Layout
1919
1920        <context id="test">
1921\end_layout
1922
1923\begin_layout Plain Layout
1924
1925                <calendar type="Gregorian" timestep="1h" />
1926\end_layout
1927
1928\begin_layout Plain Layout
1929
1930\end_layout
1931
1932\begin_layout Plain Layout
1933
1934                <file_definition>
1935\end_layout
1936
1937\begin_layout Plain Layout
1938
1939                        <file name="output" output_freq="1d" split_freq="1y">
1940\end_layout
1941
1942\begin_layout Plain Layout
1943
1944                        <!-- Content of the file ommited for now -->
1945\end_layout
1946
1947\begin_layout Plain Layout
1948
1949                        </file>
1950\end_layout
1951
1952\begin_layout Plain Layout
1953
1954                </file_definition>
1955\end_layout
1956
1957\begin_layout Plain Layout
1958
1959        </context>
1960\end_layout
1961
1962\begin_layout Plain Layout
1963
1964</simulation>
1965\end_layout
1966
1967\end_inset
1968
1969With this configuration, some data will be outputted every day and a new
1970 file will be created every year.
1971\begin_inset Newline newline
1972\end_inset
1973
1974
1975\begin_inset Newline newline
1976\end_inset
1977
1978Note that the split frequency is the duration after which a new file will
1979 be created, it does not mean that a new file will be created at the beginning
1980 of each period.
1981 For example, if you start your simulation the first of June 2014 and run
1982 it for two years with a split frequency of one year:
1983\end_layout
1984
1985\begin_layout Itemize
1986you will get two files containing respectively the period from June 1st,
1987 2014 to May 31th, 2015 and from June 1st, 2015 to May 31th, 2016.
1988\end_layout
1989
1990\begin_layout Itemize
1991you will NOT get three files containing respectively the last six months
1992 of 2014, the full year of 2015 and the first six months of 2016.
1993\end_layout
1994
1995\begin_layout Standard
1996XIOS automatically suffixes the file names with the start and end dates
1997 when using file splitting.
1998 By default, it will try to use the shortest date that still enables to
1999 distinguish the files.
2000 Thus in the above example, the files would be named
2001\begin_inset Quotes eld
2002\end_inset
2003
2004output_2014-2015.nc
2005\begin_inset Quotes erd
2006\end_inset
2007
2008 and
2009\begin_inset Quotes eld
2010\end_inset
2011
2012output_2015-2016.nc
2013\begin_inset Quotes erd
2014\end_inset
2015
2016.
2017 If you wish to force the date format used to prefix the files, you can
2018 define the
2019\series bold
2020split_freq_format
2021\series default
2022 attribute to override the default behavior.
2023\end_layout
2024
2025\begin_layout Section
2026A word about file synchronization
2027\end_layout
2028
2029\begin_layout Standard
2030File synchronization is usually not something you should worry about.
2031 However, it is important to understand that data written by XIOS might
2032 not be immediately written on the disk in practice.
2033 Input/output libraries like NetCDF and HDF5 and parallel file systems generally
2034 use complex caching policies for performance reasons.
2035 This means that your data might still be stored in memory after it was
2036 supposedly written.
2037\begin_inset Newline newline
2038\end_inset
2039
2040
2041\begin_inset Newline newline
2042\end_inset
2043
2044It might become critical to control this behavior for two main reasons:
2045\end_layout
2046
2047\begin_layout Itemize
2048if you want to mitigate the impact of a crash, as all buffered data would
2049 be lost ;
2050\end_layout
2051
2052\begin_layout Itemize
2053if you want to be able to access the data from the output file immediately
2054 after writing it.
2055\end_layout
2056
2057\begin_layout Standard
2058By default, XIOS will never force file synchronization but you can require
2059 it to do so by setting the
2060\series bold
2061sync_freq
2062\series default
2063 attribute to the wanted duration.
2064 In this case, XIOS will regularly instruct NetCDF to synchronize the file
2065 on disk by flushing its internal buffers.
2066\begin_inset Newline newline
2067\end_inset
2068
2069
2070\begin_inset Newline newline
2071\end_inset
2072
2073Note file synchronization must be used sparingly as it can have a disastrous
2074 impact on performance.
2075 Make sure to use a reasonably high synchronization frequency to avoid any
2076 issue.
2077\end_layout
2078
2079\begin_layout Chapter
2080Fields and variables
2081\end_layout
2082
2083\begin_layout Standard
2084XIOS outsources the input/output definitions in its XML configuration file.
2085 In the last chapter we presented some general points about file objects.
2086 This chapter focuses on how to use fields and variables (that is variables
2087 and attributes in NetCDF nomenclature) to populate files.
2088\begin_inset Newline newline
2089\end_inset
2090
2091
2092\end_layout
2093
2094\begin_layout Section
2095How to define your first field
2096\end_layout
2097
2098\begin_layout Standard
2099If you wish to input or to output data using XIOS, you will need to define
2100 at least one file with one field.
2101 This can be done from both the XML configuration file and the Fortran interface.
2102 Fields are often defined in the configuration file, although their definitions
2103 are sometimes amended using the API.
2104\begin_inset Newline newline
2105\end_inset
2106
2107
2108\begin_inset Newline newline
2109\end_inset
2110
2111Field objects are defined with the
2112\begin_inset Flex Code
2113status open
2114
2115\begin_layout Plain Layout
2116<field>
2117\end_layout
2118
2119\end_inset
2120
2121 tag and should always be inside a
2122\begin_inset Flex Code
2123status open
2124
2125\begin_layout Plain Layout
2126<field_definition>
2127\end_layout
2128
2129\end_inset
2130
2131 or a
2132\begin_inset Flex Code
2133status open
2134
2135\begin_layout Plain Layout
2136<file>
2137\end_layout
2138
2139\end_inset
2140
2141 section.
2142 Only the grid and the operation attached to the field are mandatory to
2143 have a well defined field but it is generally a good idea to give it an
2144 identifier.
2145 The following example shows a minimal configuration file which defines
2146 one file with one field.
2147\end_layout
2148
2149\begin_layout Standard
2150\begin_inset listings
2151lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2152inline false
2153status open
2154
2155\begin_layout Plain Layout
2156
2157<?xml version="1.0"?>
2158\end_layout
2159
2160\begin_layout Plain Layout
2161
2162<simulation>
2163\end_layout
2164
2165\begin_layout Plain Layout
2166
2167        <context id="test">
2168\end_layout
2169
2170\begin_layout Plain Layout
2171
2172                <calendar type="Gregorian" timestep="1h" />
2173\end_layout
2174
2175\begin_layout Plain Layout
2176
2177\end_layout
2178
2179\begin_layout Plain Layout
2180
2181                <grid_definition>
2182\end_layout
2183
2184\begin_layout Plain Layout
2185
2186                        <grid id="grid_A"><!-- Definition ommited --></grid>
2187\end_layout
2188
2189\begin_layout Plain Layout
2190
2191                </grid_definition>
2192\end_layout
2193
2194\begin_layout Plain Layout
2195
2196\end_layout
2197
2198\begin_layout Plain Layout
2199
2200                <file_definition>
2201\end_layout
2202
2203\begin_layout Plain Layout
2204
2205                        <file name="output" type="one_file" output_freq="1ts">
2206\end_layout
2207
2208\begin_layout Plain Layout
2209
2210                        <field id="field_A" grid_ref="grid_A" operation="instant" />
2211\end_layout
2212
2213\begin_layout Plain Layout
2214
2215                        </file>
2216\end_layout
2217
2218\begin_layout Plain Layout
2219
2220                </file_definition>
2221\end_layout
2222
2223\begin_layout Plain Layout
2224
2225        </context>
2226\end_layout
2227
2228\begin_layout Plain Layout
2229
2230</simulation>
2231\end_layout
2232
2233\end_inset
2234
2235It defines one file named
2236\begin_inset Quotes eld
2237\end_inset
2238
2239
2240\emph on
2241output
2242\emph default
2243
2244\begin_inset Quotes erd
2245\end_inset
2246
2247 which contains one field
2248\begin_inset Quotes eld
2249\end_inset
2250
2251
2252\emph on
2253field_A
2254\emph default
2255
2256\begin_inset Quotes erd
2257\end_inset
2258
2259 defined on a grid
2260\begin_inset Quotes eld
2261\end_inset
2262
2263
2264\emph on
2265grid_A
2266\emph default
2267
2268\begin_inset Quotes erd
2269\end_inset
2270
2271.
2272 The file and the field are configured so that the data is written in the
2273 file at every timestep (using the
2274\series bold
2275output_freq
2276\series default
2277 file attribute) without any transformation (using the
2278\series bold
2279operation
2280\series default
2281 field attribute set to
2282\begin_inset Quotes eld
2283\end_inset
2284
2285
2286\series bold
2287\emph on
2288instant
2289\series default
2290\emph default
2291
2292\begin_inset Quotes erd
2293\end_inset
2294
2295).
2296\begin_inset Newline newline
2297\end_inset
2298
2299
2300\begin_inset Newline newline
2301\end_inset
2302
2303The corresponding Fortran simulation loop could be:
2304\end_layout
2305
2306\begin_layout Standard
2307\begin_inset listings
2308lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2309inline false
2310status open
2311
2312\begin_layout Plain Layout
2313
2314DO ts=1,numberOfTimestep
2315\end_layout
2316
2317\begin_layout Plain Layout
2318
2319        ! Inform XIOS of the current timestep
2320\end_layout
2321
2322\begin_layout Plain Layout
2323
2324        CALL xios_update_calendar(ts)
2325\end_layout
2326
2327\begin_layout Plain Layout
2328
2329        ! Compute field_A for current timestep
2330\end_layout
2331
2332\begin_layout Plain Layout
2333
2334        ! ...
2335\end_layout
2336
2337\begin_layout Plain Layout
2338
2339        ! Output the data
2340\end_layout
2341
2342\begin_layout Plain Layout
2343
2344        CALL xios_send_field("field_A", field_A)
2345\end_layout
2346
2347\begin_layout Plain Layout
2348
2349ENDDO
2350\end_layout
2351
2352\end_inset
2353
2354As you can see, the
2355\series bold
2356id
2357\series default
2358 of the field is used in the model to select the field for which data is
2359 being provided which makes this attribute extremely important.
2360 Note that it must be unique for all fields even if they are defined in
2361 different files.
2362 By default, the
2363\series bold
2364id
2365\series default
2366 of a field is also used as the name of the corresponding NetCDF variable.
2367 It is however possible to override this default name using the field attribute
2368 
2369\series bold
2370name
2371\series default
2372.
2373 Two fields can share the same
2374\series bold
2375name
2376\series default
2377 as long as they are not used in the same file.
2378\begin_inset Newline newline
2379\end_inset
2380
2381
2382\begin_inset Newline newline
2383\end_inset
2384
2385The second argument of the
2386\begin_inset Flex Code
2387status open
2388
2389\begin_layout Plain Layout
2390xios_send_field
2391\end_layout
2392
2393\end_inset
2394
2395 function is an array containing the data.
2396 Its shape and content are not described here as they depend directly on
2397 the grid.
2398 For more information on the data layout, refer to the chapters focusing
2399 on grids, domains and axis.
2400\begin_inset Newline newline
2401\end_inset
2402
2403
2404\begin_inset Newline newline
2405\end_inset
2406
2407The same configuration could also be obtained using the Fortran interface:
2408\end_layout
2409
2410\begin_layout Standard
2411\begin_inset listings
2412lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2413inline false
2414status open
2415
2416\begin_layout Plain Layout
2417
2418! ...
2419\end_layout
2420
2421\begin_layout Plain Layout
2422
2423TYPE(xios_context)   :: ctx_hdl
2424\end_layout
2425
2426\begin_layout Plain Layout
2427
2428TYPE(xios_file)          :: file_hdl
2429\end_layout
2430
2431\begin_layout Plain Layout
2432
2433TYPE(xios_filegroup) :: filegroup_hdl
2434\end_layout
2435
2436\begin_layout Plain Layout
2437
2438TYPE(xios_field)        :: field_hdl
2439\end_layout
2440
2441\begin_layout Plain Layout
2442
2443! ...
2444\end_layout
2445
2446\begin_layout Plain Layout
2447
2448! Context, calendar and grid initializations ommited, see the corresponding
2449 section of this user manual and of the reference manual
2450\end_layout
2451
2452\begin_layout Plain Layout
2453
2454CALL xios_get_handle("test", ctx_hdl)
2455\end_layout
2456
2457\begin_layout Plain Layout
2458
2459CALL xios_set_current_context(ctx_hdl)
2460\end_layout
2461
2462\begin_layout Plain Layout
2463
2464CALL xios_get_filegroup_handle("file_definition", filegroup_hdl)
2465\end_layout
2466
2467\begin_layout Plain Layout
2468
2469CALL xios_add_file(filegroup_hdl, file_hdl)
2470\end_layout
2471
2472\begin_layout Plain Layout
2473
2474CALL xios_set_attr(file_hdl, name="output", output_freq=xios_timestep)
2475\end_layout
2476
2477\begin_layout Plain Layout
2478
2479CALL xios_add_field(file_hdl, field_hdl, "field_A")
2480\end_layout
2481
2482\begin_layout Plain Layout
2483
2484CALL xios_set_attr(field_hdl, grid_ref="grid_A", operation="instant")
2485\end_layout
2486
2487\end_inset
2488
2489Note that if you want to define a field on a grid with only one domain and/or
2490 one axis, it is possible to use the
2491\series bold
2492domain_ref
2493\series default
2494 and
2495\series bold
2496axis_ref
2497\series default
2498 attributes instead of the
2499\series bold
2500grid_ref
2501\series default
2502 attribute.
2503 A temporary grid will be created based on the domain and/or axis defined
2504 this way.
2505\begin_inset Newline newline
2506\end_inset
2507
2508
2509\begin_inset Newline newline
2510\end_inset
2511
2512If you are using a grid with some masked points (see the relevant sections
2513 of this manual), you must set the
2514\series bold
2515default_value
2516\series default
2517 attribute to define the default value that will replace the missing values
2518 in the output file.
2519\begin_inset Newline newline
2520\end_inset
2521
2522
2523\begin_inset Newline newline
2524\end_inset
2525
2526If you wish to disable a field without having to remove its definition from
2527 the configuration file, you can set the
2528\series bold
2529enabled
2530\series default
2531 attribute to
2532\begin_inset Quotes eld
2533\end_inset
2534
2535
2536\series bold
2537\emph on
2538false
2539\series default
2540\emph default
2541
2542\begin_inset Quotes erd
2543\end_inset
2544
2545.
2546\end_layout
2547
2548\begin_layout Section
2549How to use temporal operations
2550\end_layout
2551
2552\begin_layout Standard
2553The last section showed a very basic example where the data was outputted
2554 at every timestep using the
2555\begin_inset Quotes eld
2556\end_inset
2557
2558
2559\series bold
2560\emph on
2561instant
2562\series default
2563\emph default
2564
2565\begin_inset Quotes erd
2566\end_inset
2567
2568 
2569\series bold
2570operation
2571\series default
2572.
2573 However in many use cases, it might be more interesting to output only
2574 the mean value on a certain period of time for example.
2575 This section describes the use of temporal operations available in XIOS.
2576\begin_inset Newline newline
2577\end_inset
2578
2579
2580\begin_inset Newline newline
2581\end_inset
2582
2583The field attribute
2584\series bold
2585operation
2586\series default
2587 currently supports six modes:
2588\end_layout
2589
2590\begin_layout Itemize
2591
2592\series bold
2593\emph on
2594instant
2595\series default
2596\emph default
2597: no temporal operation is applied which means the new data always overrides
2598 the previous one even if it was not outputted,
2599\end_layout
2600
2601\begin_layout Itemize
2602
2603\series bold
2604\emph on
2605average
2606\series default
2607\emph default
2608: compute and output the mean value,
2609\end_layout
2610
2611\begin_layout Itemize
2612
2613\series bold
2614\emph on
2615accumulate
2616\series default
2617\emph default
2618: compute and output the sum,
2619\end_layout
2620
2621\begin_layout Itemize
2622
2623\series bold
2624\emph on
2625minimum
2626\series default
2627\emph default
2628: compute and output the minimum value,
2629\end_layout
2630
2631\begin_layout Itemize
2632
2633\series bold
2634\emph on
2635maximum
2636\series default
2637\emph default
2638: compute and output the maximum value,
2639\end_layout
2640
2641\begin_layout Itemize
2642
2643\series bold
2644\emph on
2645once
2646\series default
2647\emph default
2648 : the data is written to the file only the first time it is received from
2649 the model, any subsequent data is ignored.
2650 The corresponding NetCDF variable does not have a time dimension.
2651\end_layout
2652
2653\begin_layout Standard
2654The output frequency of the file defined by the
2655\series bold
2656output_freq
2657\series default
2658 attribute is used as the temporal operation period (except for the
2659\begin_inset Quotes eld
2660\end_inset
2661
2662
2663\series bold
2664\emph on
2665once
2666\series default
2667\emph default
2668
2669\begin_inset Quotes erd
2670\end_inset
2671
2672 
2673\series bold
2674operation
2675\series default
2676 for which there is no period).
2677 This means it is for example not possible to output a daily average and
2678 a weekly average in the same file.
2679\begin_inset Newline newline
2680\end_inset
2681
2682
2683\begin_inset Newline newline
2684\end_inset
2685
2686This updated example shows how to output the daily average instead of the
2687 instant data for all timesteps:
2688\end_layout
2689
2690\begin_layout Standard
2691\begin_inset listings
2692lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2693inline false
2694status open
2695
2696\begin_layout Plain Layout
2697
2698<?xml version="1.0"?>
2699\end_layout
2700
2701\begin_layout Plain Layout
2702
2703<simulation>
2704\end_layout
2705
2706\begin_layout Plain Layout
2707
2708        <context id="test">
2709\end_layout
2710
2711\begin_layout Plain Layout
2712
2713                <calendar type="Gregorian" timestep="1h" />
2714\end_layout
2715
2716\begin_layout Plain Layout
2717
2718\end_layout
2719
2720\begin_layout Plain Layout
2721
2722                <grid_definition>
2723\end_layout
2724
2725\begin_layout Plain Layout
2726
2727                        <grid id="grid_A"><!-- Definition ommited --></grid>
2728\end_layout
2729
2730\begin_layout Plain Layout
2731
2732                </grid_definition>
2733\end_layout
2734
2735\begin_layout Plain Layout
2736
2737\end_layout
2738
2739\begin_layout Plain Layout
2740
2741                <file_definition>
2742\end_layout
2743
2744\begin_layout Plain Layout
2745
2746                        <file name="output" type="one_file" output_freq="1d">
2747\end_layout
2748
2749\begin_layout Plain Layout
2750
2751                        <field id="field_A" grid_ref="grid_A" operation="average" />
2752\end_layout
2753
2754\begin_layout Plain Layout
2755
2756                        </file>
2757\end_layout
2758
2759\begin_layout Plain Layout
2760
2761                </file_definition>
2762\end_layout
2763
2764\begin_layout Plain Layout
2765
2766        </context>
2767\end_layout
2768
2769\begin_layout Plain Layout
2770
2771</simulation>
2772\end_layout
2773
2774\end_inset
2775
2776Compared to the previous example, only the file attribute
2777\series bold
2778output_freq
2779\series default
2780 and the field attribute
2781\series bold
2782operation
2783\series default
2784 have been modified.
2785 Computing the weekly minimum instead of the daily average would be as simple
2786 as using
2787\begin_inset Flex Code
2788status open
2789
2790\begin_layout Plain Layout
2791output_freq="7d"
2792\end_layout
2793
2794\end_inset
2795
2796and
2797\begin_inset Flex Code
2798status open
2799
2800\begin_layout Plain Layout
2801operation="minimum"
2802\end_layout
2803
2804\end_inset
2805
2806.
2807\begin_inset Newline newline
2808\end_inset
2809
2810
2811\begin_inset Newline newline
2812\end_inset
2813
2814Note that if you use a temporal operation and have
2815\series bold
2816default_value
2817\series default
2818 defined, it might be useful to set the attribute
2819\series bold
2820 detect_missing_value
2821\series default
2822 to
2823\begin_inset Quotes eld
2824\end_inset
2825
2826
2827\series bold
2828\emph on
2829true
2830\series default
2831\emph default
2832
2833\begin_inset Quotes erd
2834\end_inset
2835
2836.
2837 This way temporal operations will not be applied when a default value is
2838 detected.
2839\begin_inset Newline newline
2840\end_inset
2841
2842
2843\begin_inset Newline newline
2844\end_inset
2845
2846For example, we consider the values of a 2x2 domain for three timesteps:
2847\begin_inset Formula
2848\[
2849\begin{bmatrix}3 & -1\\
28507 & 1
2851\end{bmatrix},\qquad\begin{bmatrix}5 & 6\\
2852-1 & 2
2853\end{bmatrix},\qquad\begin{bmatrix}-1 & 8\\
28543 & 4
2855\end{bmatrix}.
2856\]
2857
2858\end_inset
2859
2860If we suppose that the field is configured to compute the average on three
2861 timesteps, the resulting field would be:
2862\begin_inset Formula
2863\[
2864\begin{bmatrix}\nicefrac{7}{3} & \nicefrac{13}{3}\\
28653 & \nicefrac{7}{3}
2866\end{bmatrix}.
2867\]
2868
2869\end_inset
2870
2871If
2872\series bold
2873default_value
2874\series default
2875 is set to
2876\emph on
2877
2878\begin_inset Quotes eld
2879\end_inset
2880
2881-1
2882\begin_inset Quotes erd
2883\end_inset
2884
2885
2886\emph default
2887 and
2888\series bold
2889detect_missing_value
2890\series default
2891 is set to
2892\begin_inset Quotes eld
2893\end_inset
2894
2895
2896\series bold
2897\emph on
2898true
2899\series default
2900\emph default
2901
2902\begin_inset Quotes erd
2903\end_inset
2904
2905, the resulting field would be:
2906\begin_inset Formula
2907\[
2908\begin{bmatrix}4 & 7\\
29095 & \nicefrac{7}{3}
2910\end{bmatrix}.
2911\]
2912
2913\end_inset
2914
2915
2916\end_layout
2917
2918\begin_layout Section
2919How to use a specific data sampling
2920\end_layout
2921
2922\begin_layout Standard
2923It is sometimes useful to have more control on the data sampling.
2924 By default, the input data is used at every timestep but sometimes it is
2925 not what you want.
2926 The following examples illustrate such cases:
2927\end_layout
2928
2929\begin_layout Enumerate
2930the model is not computing updated values at the same frequency for all
2931 fields (for example, a field is updated every two timesteps).
2932\end_layout
2933
2934\begin_layout Enumerate
2935you want to output a specific instant value in the interval between two
2936 outputs.
2937\end_layout
2938
2939\begin_layout Enumerate
2940you want to compute an average without taking into account all instant values
2941 in the interval between two outputs.
2942\end_layout
2943
2944\begin_layout Standard
2945Data sampling can be controlled in XIOS using the
2946\series bold
2947freq_op
2948\series default
2949 (one timestep by default) and
2950\series bold
2951freq_offset
2952\series default
2953 (null by default) attributes.
2954 Those attributes define respectively how often data from the model must
2955 be used and the amount of time before starting to use it.
2956\begin_inset Newline newline
2957\end_inset
2958
2959
2960\begin_inset Newline newline
2961\end_inset
2962
2963For following excerpts of configuration files show you to use those attributes
2964 to handle the motivating examples.
2965\end_layout
2966
2967\begin_layout Enumerate
2968In this example, we suppose that we get two fields from the model:
2969\begin_inset Quotes eld
2970\end_inset
2971
2972field_A
2973\begin_inset Quotes erd
2974\end_inset
2975
2976 which is computed for each timestep and
2977\begin_inset Quotes eld
2978\end_inset
2979
2980field_B
2981\begin_inset Quotes erd
2982\end_inset
2983
2984 which is only computed every two timesteps.
2985 For both fields, we show how to compute and output the sum of all values
2986 received during 6 timesteps:
2987\begin_inset Newline newline
2988\end_inset
2989
2990
2991\begin_inset listings
2992lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2993inline false
2994status open
2995
2996\begin_layout Plain Layout
2997
2998<file_definition>
2999\end_layout
3000
3001\begin_layout Plain Layout
3002
3003        <file name="output" output_freq="6ts">
3004\end_layout
3005
3006\begin_layout Plain Layout
3007
3008                <field id="field_A" grid_ref="grid_A" operation="accumulate" />
3009\end_layout
3010
3011\begin_layout Plain Layout
3012
3013                <field id="field_B" grid_ref="grid_B" operation="accumulate" freq_op="2ts"
3014 />
3015\end_layout
3016
3017\begin_layout Plain Layout
3018
3019        </file>
3020\end_layout
3021
3022\begin_layout Plain Layout
3023
3024</file_definition>
3025\end_layout
3026
3027\end_inset
3028
3029
3030\end_layout
3031
3032\begin_layout Enumerate
3033In this example, we show how to output the 11th instant value every 12 timesteps
3034:
3035\begin_inset Newline newline
3036\end_inset
3037
3038
3039\begin_inset listings
3040lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3041inline false
3042status open
3043
3044\begin_layout Plain Layout
3045
3046<file_definition>
3047\end_layout
3048
3049\begin_layout Plain Layout
3050
3051        <file name="output" output_freq="12ts">
3052\end_layout
3053
3054\begin_layout Plain Layout
3055
3056                <field id="field_A" grid_ref="grid_A" operation="instant" freq_op="11ts"
3057 freq_offset="12ts" />
3058\end_layout
3059
3060\begin_layout Plain Layout
3061
3062        </file>
3063\end_layout
3064
3065\begin_layout Plain Layout
3066
3067</file_definition>
3068\end_layout
3069
3070\end_inset
3071
3072
3073\end_layout
3074
3075\begin_layout Enumerate
3076In this example, we suppose that the timestep is equal to one hour and that
3077 the simulation starts at midnight.
3078 We show how to compute the weekly average of the field value at midday:
3079\begin_inset Newline newline
3080\end_inset
3081
3082
3083\begin_inset listings
3084lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3085inline false
3086status open
3087
3088\begin_layout Plain Layout
3089
3090<file_definition>
3091\end_layout
3092
3093\begin_layout Plain Layout
3094
3095        <file name="output" output_freq="1w">
3096\end_layout
3097
3098\begin_layout Plain Layout
3099
3100                <field id="field_A" grid_ref="grid_A" operation="average" freq_op="1d"
3101 freq_offset="12h" />
3102\end_layout
3103
3104\begin_layout Plain Layout
3105
3106        </file>
3107\end_layout
3108
3109\begin_layout Plain Layout
3110
3111</file_definition>
3112\end_layout
3113
3114\end_inset
3115
3116
3117\end_layout
3118
3119\begin_layout Section
3120How to use field references
3121\end_layout
3122
3123\begin_layout Standard
3124It is quite common that different temporal operations must be applied to
3125 the same instant data provided by the model.
3126 In theory, the only solution to handle this scenario would be to define
3127 a field for each operation, give them different
3128\series bold
3129id
3130\series default
3131 and and call
3132\begin_inset Flex Code
3133status open
3134
3135\begin_layout Plain Layout
3136xios_send_field
3137\end_layout
3138
3139\end_inset
3140
3141 with the same array of data for each of those fields.
3142\begin_inset Newline newline
3143\end_inset
3144
3145
3146\begin_inset Newline newline
3147\end_inset
3148
3149The following example illustrates this solution for a field for which we
3150 want to compute the average, minimal and maximal values:
3151\end_layout
3152
3153\begin_layout Standard
3154\begin_inset listings
3155lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3156inline false
3157status open
3158
3159\begin_layout Plain Layout
3160
3161<?xml version="1.0"?>
3162\end_layout
3163
3164\begin_layout Plain Layout
3165
3166<simulation>
3167\end_layout
3168
3169\begin_layout Plain Layout
3170
3171        <context id="test">
3172\end_layout
3173
3174\begin_layout Plain Layout
3175
3176                <calendar type="Gregorian" timestep="1h" />
3177\end_layout
3178
3179\begin_layout Plain Layout
3180
3181\end_layout
3182
3183\begin_layout Plain Layout
3184
3185                <grid_definition>
3186\end_layout
3187
3188\begin_layout Plain Layout
3189
3190                        <grid id="grid_A"><!-- Definition ommited --></grid>
3191\end_layout
3192
3193\begin_layout Plain Layout
3194
3195                </grid_definition>
3196\end_layout
3197
3198\begin_layout Plain Layout
3199
3200\end_layout
3201
3202\begin_layout Plain Layout
3203
3204                <file_definition>
3205\end_layout
3206
3207\begin_layout Plain Layout
3208
3209                        <file name="output" output_freq="1d">
3210\end_layout
3211
3212\begin_layout Plain Layout
3213
3214                        <field id="field_A_avg" grid_ref="grid_A" operation="average"
3215 />
3216\end_layout
3217
3218\begin_layout Plain Layout
3219
3220                        <field id="field_A_min" grid_ref="grid_A" operation="min" />
3221\end_layout
3222
3223\begin_layout Plain Layout
3224
3225                        <field id="field_A_max" grid_ref="grid_A" operation="max" />
3226\end_layout
3227
3228\begin_layout Plain Layout
3229
3230                        </file>
3231\end_layout
3232
3233\begin_layout Plain Layout
3234
3235                </file_definition>
3236\end_layout
3237
3238\begin_layout Plain Layout
3239
3240        </context>
3241\end_layout
3242
3243\begin_layout Plain Layout
3244
3245</simulation>
3246\end_layout
3247
3248\end_inset
3249
3250To simplify the handling of such scenarios, XIOS has a
3251\begin_inset Quotes eld
3252\end_inset
3253
3254reference
3255\begin_inset Quotes erd
3256\end_inset
3257
3258 feature which allows one field to inherit the attributes (except the
3259\series bold
3260id
3261\series default
3262) and the instant data of another field.
3263 The above example can then be rewritten:
3264\begin_inset listings
3265lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3266inline false
3267status open
3268
3269\begin_layout Plain Layout
3270
3271<?xml version="1.0"?>
3272\end_layout
3273
3274\begin_layout Plain Layout
3275
3276<simulation>
3277\end_layout
3278
3279\begin_layout Plain Layout
3280
3281        <context id="test">
3282\end_layout
3283
3284\begin_layout Plain Layout
3285
3286                <calendar type="Gregorian" timestep="1h" />
3287\end_layout
3288
3289\begin_layout Plain Layout
3290
3291\end_layout
3292
3293\begin_layout Plain Layout
3294
3295                <grid_definition>
3296\end_layout
3297
3298\begin_layout Plain Layout
3299
3300                        <grid id="grid_A"><!-- Definition ommited --></grid>
3301\end_layout
3302
3303\begin_layout Plain Layout
3304
3305                </grid_definition>
3306\end_layout
3307
3308\begin_layout Plain Layout
3309
3310\end_layout
3311
3312\begin_layout Plain Layout
3313
3314                <file_definition>
3315\end_layout
3316
3317\begin_layout Plain Layout
3318
3319                        <file name="output" output_freq="1d">
3320\end_layout
3321
3322\begin_layout Plain Layout
3323
3324                        <field id="field_A" name="field_A_avg" grid_ref="grid_A" operation="av
3325erage" />
3326\end_layout
3327
3328\begin_layout Plain Layout
3329
3330                        <field field_ref="field_A" name="field_A_min" operation="min"
3331 />
3332\end_layout
3333
3334\begin_layout Plain Layout
3335
3336                        <field field_ref="field_A" name="field_A_max" operation="max"
3337 />
3338\end_layout
3339
3340\begin_layout Plain Layout
3341
3342                        </file>
3343\end_layout
3344
3345\begin_layout Plain Layout
3346
3347                </file_definition>
3348\end_layout
3349
3350\begin_layout Plain Layout
3351
3352        </context>
3353\end_layout
3354
3355\begin_layout Plain Layout
3356
3357</simulation>
3358\end_layout
3359
3360\end_inset
3361
3362With this configuration, only one call to
3363\begin_inset Flex Code
3364status open
3365
3366\begin_layout Plain Layout
3367xios_send_field(
3368\begin_inset Quotes eld
3369\end_inset
3370
3371field_A
3372\begin_inset Quotes erd
3373\end_inset
3374
3375, field_A)
3376\end_layout
3377
3378\end_inset
3379
3380 is needed.
3381 Note how inherited attributes (like
3382\series bold
3383name
3384\series default
3385 or
3386\series bold
3387operation
3388\series default
3389 for example) are overwritten to obtain the desired configuration.
3390 Additionally, be aware that it is the instant values which are inherited,
3391 not the result of the operation on the field.
3392\begin_inset Newline newline
3393\end_inset
3394
3395
3396\begin_inset Newline newline
3397\end_inset
3398
3399Similarly, it is sometimes useful to output the result of a temporal operation
3400 on a field for different periods.
3401 In this case, it does not really make sense to define the field that will
3402 be then inherited in one file rather than another.
3403 A solution is to make use of the
3404\begin_inset Flex Code
3405status open
3406
3407\begin_layout Plain Layout
3408field_definition
3409\end_layout
3410
3411\end_inset
3412
3413 section so that it is clear that the field can be reused in any file.
3414 This is illustrated in the following sample configuration file:
3415\begin_inset listings
3416lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3417inline false
3418status open
3419
3420\begin_layout Plain Layout
3421
3422<?xml version="1.0"?>
3423\end_layout
3424
3425\begin_layout Plain Layout
3426
3427<simulation>
3428\end_layout
3429
3430\begin_layout Plain Layout
3431
3432        <context id="test">
3433\end_layout
3434
3435\begin_layout Plain Layout
3436
3437                <calendar type="Gregorian" timestep="1h" />
3438\end_layout
3439
3440\begin_layout Plain Layout
3441
3442\end_layout
3443
3444\begin_layout Plain Layout
3445
3446                <grid_definition>
3447\end_layout
3448
3449\begin_layout Plain Layout
3450
3451                        <grid id="grid_A"><!-- Definition ommited --></grid>
3452\end_layout
3453
3454\begin_layout Plain Layout
3455
3456                </grid_definition>
3457\end_layout
3458
3459\begin_layout Plain Layout
3460
3461\end_layout
3462
3463\begin_layout Plain Layout
3464
3465                <field_definition>
3466\end_layout
3467
3468\begin_layout Plain Layout
3469
3470                <field id="field_A" name="field_A" grid_ref="grid_A" operation="average
3471" />
3472\end_layout
3473
3474\begin_layout Plain Layout
3475
3476                </field_definition>
3477\end_layout
3478
3479\begin_layout Plain Layout
3480
3481\end_layout
3482
3483\begin_layout Plain Layout
3484
3485                <file_definition>
3486\end_layout
3487
3488\begin_layout Plain Layout
3489
3490                        <file name="output_1d" output_freq="1d">
3491\end_layout
3492
3493\begin_layout Plain Layout
3494
3495                        <field field_ref="field_A" />
3496\end_layout
3497
3498\begin_layout Plain Layout
3499
3500                        </file>
3501\end_layout
3502
3503\begin_layout Plain Layout
3504
3505                        <file name="output_1mo" output_freq="1mo">
3506\end_layout
3507
3508\begin_layout Plain Layout
3509
3510                        <field field_ref="field_A" />
3511\end_layout
3512
3513\begin_layout Plain Layout
3514
3515                        </file>
3516\end_layout
3517
3518\begin_layout Plain Layout
3519
3520                </file_definition>
3521\end_layout
3522
3523\begin_layout Plain Layout
3524
3525        </context>
3526\end_layout
3527
3528\begin_layout Plain Layout
3529
3530</simulation>
3531\end_layout
3532
3533\end_inset
3534
3535
3536\end_layout
3537
3538\begin_layout Section
3539How to use arithmetic operations
3540\end_layout
3541
3542\begin_layout Standard
3543Since XIOS aims to reduce as much as possible the need for post-processing,
3544 it can apply some arithmetic operations on the data it handles (regardless
3545 of its provenance).
3546\begin_inset Newline newline
3547\end_inset
3548
3549
3550\begin_inset Newline newline
3551\end_inset
3552
3553All usual operators (+, -, *, /, ^, that is addition, subtraction, multiplicatio
3554n, division and exponentiation) and some common functions (like cos, sin,
3555 tan, exp, log, log10, sqrt) are supported.
3556\begin_inset Newline newline
3557\end_inset
3558
3559
3560\begin_inset Newline newline
3561\end_inset
3562
3563The following example shows how to use arithmetic operations:
3564\begin_inset listings
3565lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3566inline false
3567status open
3568
3569\begin_layout Plain Layout
3570
3571<?xml version="1.0"?>
3572\end_layout
3573
3574\begin_layout Plain Layout
3575
3576<simulation>
3577\end_layout
3578
3579\begin_layout Plain Layout
3580
3581        <context id="test">
3582\end_layout
3583
3584\begin_layout Plain Layout
3585
3586                <calendar type="Gregorian" timestep="1h" />
3587\end_layout
3588
3589\begin_layout Plain Layout
3590
3591\end_layout
3592
3593\begin_layout Plain Layout
3594
3595                <grid_definition>
3596\end_layout
3597
3598\begin_layout Plain Layout
3599
3600                        <grid id="grid_A"><!-- Definition ommited --></grid>
3601\end_layout
3602
3603\begin_layout Plain Layout
3604
3605                </grid_definition>
3606\end_layout
3607
3608\begin_layout Plain Layout
3609
3610\end_layout
3611
3612\begin_layout Plain Layout
3613
3614                <field_definition>
3615\end_layout
3616
3617\begin_layout Plain Layout
3618
3619                <field id="field_A" grid_ref="grid_A" operation="average" />
3620\end_layout
3621
3622\begin_layout Plain Layout
3623
3624                </field_definition>
3625\end_layout
3626
3627\begin_layout Plain Layout
3628
3629\end_layout
3630
3631\begin_layout Plain Layout
3632
3633                <file_definition>
3634\end_layout
3635
3636\begin_layout Plain Layout
3637
3638                        <file name="output" output_freq="1d">
3639\end_layout
3640
3641\begin_layout Plain Layout
3642
3643                        <field id="field_B" field_ref="field_A">field_A + 273.15</field>
3644\end_layout
3645
3646\begin_layout Plain Layout
3647
3648                        <field id="field_C" field_ref="field_A">log10(field_B)</field>
3649\end_layout
3650
3651\begin_layout Plain Layout
3652
3653                        </file>
3654\end_layout
3655
3656\begin_layout Plain Layout
3657
3658                </file_definition>
3659\end_layout
3660
3661\begin_layout Plain Layout
3662
3663        </context>
3664\end_layout
3665
3666\begin_layout Plain Layout
3667
3668</simulation>
3669\end_layout
3670
3671\end_inset
3672
3673With this configuration, only one call to
3674\begin_inset Flex Code
3675status open
3676
3677\begin_layout Plain Layout
3678xios_send_field(
3679\begin_inset Quotes eld
3680\end_inset
3681
3682field_A
3683\begin_inset Quotes erd
3684\end_inset
3685
3686, field_A)
3687\end_layout
3688
3689\end_inset
3690
3691 is needed.
3692 In this example
3693\series bold
3694field_ref
3695\series default
3696 is used only to inherit the attributes from
3697\begin_inset Quotes eld
3698\end_inset
3699
3700field_A
3701\begin_inset Quotes erd
3702\end_inset
3703
3704, the instant values are not inherited since an expression has been given
3705 for
3706\begin_inset Quotes eld
3707\end_inset
3708
3709field_B
3710\begin_inset Quotes erd
3711\end_inset
3712
3713 and
3714\begin_inset Quotes eld
3715\end_inset
3716
3717field_C
3718\begin_inset Quotes erd
3719\end_inset
3720
3721.
3722 Note that it is possible to use fields obtained from an expression in another
3723 expression, thus the expression of
3724\begin_inset Quotes eld
3725\end_inset
3726
3727field_C
3728\begin_inset Quotes erd
3729\end_inset
3730
3731 is equivalent to
3732\begin_inset Flex Code
3733status open
3734
3735\begin_layout Plain Layout
3736log10(field_A + 273.15)
3737\end_layout
3738
3739\end_inset
3740
3741.
3742\begin_inset Newline newline
3743\end_inset
3744
3745
3746\begin_inset Newline newline
3747\end_inset
3748
3749The special keyword
3750\series bold
3751this
3752\series default
3753 can be used in an expression to refer to the instant data received from
3754 the model by the current field.
3755 For example, the previous configuration file could be rewritten as follow:
3756\begin_inset listings
3757lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3758inline false
3759status open
3760
3761\begin_layout Plain Layout
3762
3763<?xml version="1.0"?>
3764\end_layout
3765
3766\begin_layout Plain Layout
3767
3768<simulation>
3769\end_layout
3770
3771\begin_layout Plain Layout
3772
3773        <context id="test">
3774\end_layout
3775
3776\begin_layout Plain Layout
3777
3778                <calendar type="Gregorian" timestep="1h" />
3779\end_layout
3780
3781\begin_layout Plain Layout
3782
3783\end_layout
3784
3785\begin_layout Plain Layout
3786
3787                <grid_definition>
3788\end_layout
3789
3790\begin_layout Plain Layout
3791
3792                        <grid id="grid_A"><!-- Definition ommited --></grid>
3793\end_layout
3794
3795\begin_layout Plain Layout
3796
3797                </grid_definition>
3798\end_layout
3799
3800\begin_layout Plain Layout
3801
3802\end_layout
3803
3804\begin_layout Plain Layout
3805
3806                <file_definition>
3807\end_layout
3808
3809\begin_layout Plain Layout
3810
3811                        <file name="output" output_freq="1d">
3812\end_layout
3813
3814\begin_layout Plain Layout
3815
3816                        <field id="field_B" grid_ref="grid_A" operation="average">this
3817 + 273.15</field>
3818\end_layout
3819
3820\begin_layout Plain Layout
3821
3822                        <field id="field_C" field_ref="field_B">log10(field_B)</field>
3823\end_layout
3824
3825\begin_layout Plain Layout
3826
3827                        </file>
3828\end_layout
3829
3830\begin_layout Plain Layout
3831
3832                </file_definition>
3833\end_layout
3834
3835\begin_layout Plain Layout
3836
3837        </context>
3838\end_layout
3839
3840\begin_layout Plain Layout
3841
3842</simulation>
3843\end_layout
3844
3845\end_inset
3846
3847and the Fortran call would be replaced by
3848\begin_inset Flex Code
3849status open
3850
3851\begin_layout Plain Layout
3852xios_send_field(
3853\begin_inset Quotes eld
3854\end_inset
3855
3856field_B
3857\begin_inset Quotes erd
3858\end_inset
3859
3860, field_A)
3861\end_layout
3862
3863\end_inset
3864
3865.
3866\end_layout
3867
3868\begin_layout Section
3869How to chain multiple temporal operations
3870\end_layout
3871
3872\begin_layout Standard
3873By default, all field names appearing in an expression refer to the instant
3874 data of those fields.
3875 To refer to the result of a temporal operation, the field name must be
3876 prefixed with
3877\begin_inset Quotes eld
3878\end_inset
3879
3880@
3881\begin_inset Quotes erd
3882\end_inset
3883
3884.
3885\begin_inset Newline newline
3886\end_inset
3887
3888
3889\begin_inset Newline newline
3890\end_inset
3891
3892This feature allows to chain multiple temporal operations as illustrated
3893 bellow:
3894\end_layout
3895
3896\begin_layout Standard
3897\begin_inset listings
3898lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3899inline false
3900status open
3901
3902\begin_layout Plain Layout
3903
3904<?xml version="1.0"?>
3905\end_layout
3906
3907\begin_layout Plain Layout
3908
3909<simulation>
3910\end_layout
3911
3912\begin_layout Plain Layout
3913
3914        <context id="test">
3915\end_layout
3916
3917\begin_layout Plain Layout
3918
3919                <calendar type="Gregorian" timestep="1h" />
3920\end_layout
3921
3922\begin_layout Plain Layout
3923
3924\end_layout
3925
3926\begin_layout Plain Layout
3927
3928                <grid_definition>
3929\end_layout
3930
3931\begin_layout Plain Layout
3932
3933                        <grid id="grid_A"><!-- Definition ommited --></grid>
3934\end_layout
3935
3936\begin_layout Plain Layout
3937
3938                </grid_definition>
3939\end_layout
3940
3941\begin_layout Plain Layout
3942
3943\end_layout
3944
3945\begin_layout Plain Layout
3946
3947                <field_definition>
3948\end_layout
3949
3950\begin_layout Plain Layout
3951
3952                <field id="field_A" grid_ref="grid_A" operation="average" />
3953\end_layout
3954
3955\begin_layout Plain Layout
3956
3957                </field_definition>
3958\end_layout
3959
3960\begin_layout Plain Layout
3961
3962\end_layout
3963
3964\begin_layout Plain Layout
3965
3966                <file_definition>
3967\end_layout
3968
3969\begin_layout Plain Layout
3970
3971                        <file name="output" output_freq="7d">
3972\end_layout
3973
3974\begin_layout Plain Layout
3975
3976                        <field name="field_A_min_of_average" grid_ref="grid_A" operation="min"
3977 freq_op="1d">@field_A</field>
3978\end_layout
3979
3980\begin_layout Plain Layout
3981
3982                        </file>
3983\end_layout
3984
3985\begin_layout Plain Layout
3986
3987                </file_definition>
3988\end_layout
3989
3990\begin_layout Plain Layout
3991
3992        </context>
3993\end_layout
3994
3995\begin_layout Plain Layout
3996
3997</simulation>
3998\end_layout
3999
4000\end_inset
4001
4002This example shows how to compute the minimum on 7 days of the daily average
4003 of
4004\begin_inset Quotes eld
4005\end_inset
4006
4007field_A
4008\begin_inset Quotes erd
4009\end_inset
4010
4011.
4012 In this context, the
4013\series bold
4014freq_op
4015\series default
4016 attribute defines the period of the temporal operation for all fields pointed
4017 with the
4018\begin_inset Quotes eld
4019\end_inset
4020
4021@
4022\begin_inset Quotes erd
4023\end_inset
4024
4025 operator in the expression.
4026\begin_inset Newline newline
4027\end_inset
4028
4029
4030\begin_inset Newline newline
4031\end_inset
4032
4033Another use of this feature is to do arithmetic operations on the result
4034 of temporal operations.
4035  The following configuration file for example shows how to output the standard
4036 deviation for a field on a one day period:
4037\begin_inset listings
4038lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4039inline false
4040status open
4041
4042\begin_layout Plain Layout
4043
4044<?xml version="1.0"?>
4045\end_layout
4046
4047\begin_layout Plain Layout
4048
4049<simulation>
4050\end_layout
4051
4052\begin_layout Plain Layout
4053
4054        <context id="test">
4055\end_layout
4056
4057\begin_layout Plain Layout
4058
4059                <calendar type="Gregorian" timestep="1h" />
4060\end_layout
4061
4062\begin_layout Plain Layout
4063
4064\end_layout
4065
4066\begin_layout Plain Layout
4067
4068                <grid_definition>
4069\end_layout
4070
4071\begin_layout Plain Layout
4072
4073                        <grid id="grid_A"><!-- Definition ommited --></grid>
4074\end_layout
4075
4076\begin_layout Plain Layout
4077
4078                </grid_definition>
4079\end_layout
4080
4081\begin_layout Plain Layout
4082
4083\end_layout
4084
4085\begin_layout Plain Layout
4086
4087                <field_definition>
4088\end_layout
4089
4090\begin_layout Plain Layout
4091
4092                <field id="field_A" grid_ref="grid_A" operation="average" />
4093\end_layout
4094
4095\begin_layout Plain Layout
4096
4097                <field id="field_A_square" field_ref="grid_A">field_A * field_A</field>
4098\end_layout
4099
4100\begin_layout Plain Layout
4101
4102                </field_definition>
4103\end_layout
4104
4105\begin_layout Plain Layout
4106
4107\end_layout
4108
4109\begin_layout Plain Layout
4110
4111                <file_definition>
4112\end_layout
4113
4114\begin_layout Plain Layout
4115
4116                        <file name="output" output_freq="1d">
4117\end_layout
4118
4119\begin_layout Plain Layout
4120
4121                        <field name="field_A_std_dev" grid_ref="grid_A" operation="instant"
4122 freq_op="1d">sqrt(@field_A_square - @field_A^2)</field>
4123\end_layout
4124
4125\begin_layout Plain Layout
4126
4127                        </file>
4128\end_layout
4129
4130\begin_layout Plain Layout
4131
4132                </file_definition>
4133\end_layout
4134
4135\begin_layout Plain Layout
4136
4137        </context>
4138\end_layout
4139
4140\begin_layout Plain Layout
4141
4142</simulation>
4143\end_layout
4144
4145\end_inset
4146
4147Note that since an
4148\series bold
4149\emph on
4150
4151\begin_inset Quotes eld
4152\end_inset
4153
4154instant
4155\begin_inset Quotes erd
4156\end_inset
4157
4158
4159\series default
4160 
4161\emph default
4162operation is used,
4163\series bold
4164freq_op
4165\series default
4166 and
4167\series bold
4168output_freq
4169\series default
4170 are identical in this scenario.
4171\end_layout
4172
4173\begin_layout Section
4174How to access the data of a field
4175\end_layout
4176
4177\begin_layout Standard
4178In order not to waste memory, the instant data of a field can be read from
4179 the model only if:
4180\end_layout
4181
4182\begin_layout Itemize
4183it is part of a file whose attribute
4184\series bold
4185mode
4186\series default
4187 is
4188\series bold
4189\emph on
4190
4191\begin_inset Quotes eld
4192\end_inset
4193
4194read
4195\begin_inset Quotes erd
4196\end_inset
4197
4198
4199\end_layout
4200
4201\begin_layout Itemize
4202or its attribute
4203\series bold
4204read_access
4205\series default
4206 is set to
4207\series bold
4208\emph on
4209
4210\begin_inset Quotes eld
4211\end_inset
4212
4213true
4214\begin_inset Quotes erd
4215\end_inset
4216
4217
4218\series default
4219\emph default
4220.
4221\end_layout
4222
4223\begin_layout Standard
4224In any other case, trying to access the field data would cause an error.
4225\begin_inset Newline newline
4226\end_inset
4227
4228
4229\begin_inset Newline newline
4230\end_inset
4231
4232The following configuration file:
4233\begin_inset listings
4234lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4235inline false
4236status open
4237
4238\begin_layout Plain Layout
4239
4240<?xml version="1.0"?>
4241\end_layout
4242
4243\begin_layout Plain Layout
4244
4245<simulation>
4246\end_layout
4247
4248\begin_layout Plain Layout
4249
4250        <context id="test">
4251\end_layout
4252
4253\begin_layout Plain Layout
4254
4255                <calendar type="Gregorian" timestep="1h" />
4256\end_layout
4257
4258\begin_layout Plain Layout
4259
4260\end_layout
4261
4262\begin_layout Plain Layout
4263
4264                <grid_definition>
4265\end_layout
4266
4267\begin_layout Plain Layout
4268
4269                        <grid id="grid_A"><!-- Definition ommited --></grid>
4270\end_layout
4271
4272\begin_layout Plain Layout
4273
4274                </grid_definition>
4275\end_layout
4276
4277\begin_layout Plain Layout
4278
4279\end_layout
4280
4281\begin_layout Plain Layout
4282
4283                <file_definition>
4284\end_layout
4285
4286\begin_layout Plain Layout
4287
4288                        <file name="input" output_freq="1ts">
4289\end_layout
4290
4291\begin_layout Plain Layout
4292
4293                        <field id="field_A" grid_ref="grid_A" operation="instant" />
4294\end_layout
4295
4296\begin_layout Plain Layout
4297
4298                        </file>
4299\end_layout
4300
4301\begin_layout Plain Layout
4302
4303                </file_definition>
4304\end_layout
4305
4306\begin_layout Plain Layout
4307
4308        </context>
4309\end_layout
4310
4311\begin_layout Plain Layout
4312
4313</simulation>
4314\end_layout
4315
4316\end_inset
4317
4318can be used with this Fortran code:
4319\end_layout
4320
4321\begin_layout Standard
4322\begin_inset listings
4323lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4324inline false
4325status open
4326
4327\begin_layout Plain Layout
4328
4329DO ts=1,numberOfTimestep
4330\end_layout
4331
4332\begin_layout Plain Layout
4333
4334        ! Get field_A for current timestep
4335\end_layout
4336
4337\begin_layout Plain Layout
4338
4339        CALL xios_recv_field("field_A", field_A) ! field_A must be an allocated
4340 array with the right size
4341\end_layout
4342
4343\begin_layout Plain Layout
4344
4345        ! Do useful things...
4346\end_layout
4347
4348\begin_layout Plain Layout
4349
4350        ! Inform XIOS of the current timestep
4351\end_layout
4352
4353\begin_layout Plain Layout
4354
4355        CALL xios_update_calendar(ts)
4356\end_layout
4357
4358\begin_layout Plain Layout
4359
4360ENDDO
4361\end_layout
4362
4363\end_inset
4364
4365The call to
4366\begin_inset Flex Code
4367status open
4368
4369\begin_layout Plain Layout
4370xios_recv_field
4371\end_layout
4372
4373\end_inset
4374
4375 might block for a while if the data was not yet received from the server(s)
4376 but it should not happen too often thanks to the prefetching done by XIOS.
4377\begin_inset Newline newline
4378\end_inset
4379
4380
4381\begin_inset Newline newline
4382\end_inset
4383
4384Since the
4385\series bold
4386read_access
4387\series default
4388 attribute allows to the access fields which depend directly on data from
4389 the model, you must be very careful with the order of the
4390\begin_inset Flex Code
4391status open
4392
4393\begin_layout Plain Layout
4394xios_send_field
4395\end_layout
4396
4397\end_inset
4398
4399 and
4400\begin_inset Flex Code
4401status open
4402
4403\begin_layout Plain Layout
4404xios_recv_field
4405\end_layout
4406
4407\end_inset
4408
4409 calls.
4410 For example, consider the following configuration file (just a simple example
4411 as in practice it does not make much sense to use it):
4412\begin_inset listings
4413lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4414inline false
4415status open
4416
4417\begin_layout Plain Layout
4418
4419<?xml version="1.0"?>
4420\end_layout
4421
4422\begin_layout Plain Layout
4423
4424<simulation>
4425\end_layout
4426
4427\begin_layout Plain Layout
4428
4429        <context id="test">
4430\end_layout
4431
4432\begin_layout Plain Layout
4433
4434                <calendar type="Gregorian" timestep="1h" />
4435\end_layout
4436
4437\begin_layout Plain Layout
4438
4439\end_layout
4440
4441\begin_layout Plain Layout
4442
4443                <grid_definition>
4444\end_layout
4445
4446\begin_layout Plain Layout
4447
4448                        <grid id="grid_A"><!-- Definition ommited --></grid>
4449\end_layout
4450
4451\begin_layout Plain Layout
4452
4453                </grid_definition>
4454\end_layout
4455
4456\begin_layout Plain Layout
4457
4458\end_layout
4459
4460\begin_layout Plain Layout
4461
4462                <field_definition>
4463\end_layout
4464
4465\begin_layout Plain Layout
4466
4467                <field id="field_A" grid_ref="grid_A" operation="instant" />
4468\end_layout
4469
4470\begin_layout Plain Layout
4471
4472                </field_definition>
4473\end_layout
4474
4475\begin_layout Plain Layout
4476
4477\end_layout
4478
4479\begin_layout Plain Layout
4480
4481                <file_definition>
4482\end_layout
4483
4484\begin_layout Plain Layout
4485
4486                        <file name="output" output_freq="1ts">
4487\end_layout
4488
4489\begin_layout Plain Layout
4490
4491                        <field id="field_B" grid_ref="grid_A" operation="instant" read_access=
4492"true">field_A / 42</field>
4493\end_layout
4494
4495\begin_layout Plain Layout
4496
4497                        </file>
4498\end_layout
4499
4500\begin_layout Plain Layout
4501
4502                </file_definition>
4503\end_layout
4504
4505\begin_layout Plain Layout
4506
4507        </context>
4508\end_layout
4509
4510\begin_layout Plain Layout
4511
4512</simulation>
4513\end_layout
4514
4515\end_inset
4516
4517If you call
4518\begin_inset Flex Code
4519status open
4520
4521\begin_layout Plain Layout
4522xios_recv_field(
4523\begin_inset Quotes eld
4524\end_inset
4525
4526field_B
4527\begin_inset Quotes erd
4528\end_inset
4529
4530, field_B)
4531\end_layout
4532
4533\end_inset
4534
4535 before
4536\begin_inset Flex Code
4537status open
4538
4539\begin_layout Plain Layout
4540xios_send_field(
4541\begin_inset Quotes eld
4542\end_inset
4543
4544field_A
4545\begin_inset Quotes erd
4546\end_inset
4547
4548, field_A)
4549\end_layout
4550
4551\end_inset
4552
4553, the requested data will never be available and a deadlock could occur.
4554 In practice, XIOS will detect the problem and throw an error.
4555\end_layout
4556
4557\begin_layout Section
4558How to reduce the size of an output file
4559\end_layout
4560
4561\begin_layout Standard
4562The size of the output files can sometimes become a problem.
4563 XIOS provides some features which may help to reduce the size of the output
4564 files losslessly.
4565\begin_inset Newline newline
4566\end_inset
4567
4568
4569\begin_inset Newline newline
4570\end_inset
4571
4572The first solution is to use the compression feature provided by HDF5 which
4573 allows a field to be compressed using gzip.
4574 Since it depends directly on HDF5, this feature works only when the NetCDF-4
4575 format is used.
4576 Unfortunately, HDF5 does not support compression (yet) for parallel output
4577 so you have to use only one server or to engage the
4578\series bold
4579\emph on
4580
4581\begin_inset Quotes eld
4582\end_inset
4583
4584multiple_file
4585\begin_inset Quotes erd
4586\end_inset
4587
4588
4589\series default
4590\emph default
4591 mode.
4592\begin_inset Newline newline
4593\end_inset
4594
4595
4596\begin_inset Newline newline
4597\end_inset
4598
4599To enable the gzip compression of a field, you need to set the
4600\series bold
4601compression_level
4602\series default
4603 attribute to any integer between 1 and 9 (by default this attribute is
4604 set to 0 which means that compression is disabled).
4605 Using an higher compression level should improve the compression ratio
4606 at the cost of using more processing power.
4607 Generally using a compression level of 2 should be a good trade-off.
4608\begin_inset Newline newline
4609\end_inset
4610
4611
4612\begin_inset Newline newline
4613\end_inset
4614
4615The following example illustrates the use of the gzip compression:
4616\begin_inset listings
4617lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4618inline false
4619status open
4620
4621\begin_layout Plain Layout
4622
4623<?xml version="1.0"?>
4624\end_layout
4625
4626\begin_layout Plain Layout
4627
4628<simulation>
4629\end_layout
4630
4631\begin_layout Plain Layout
4632
4633        <context id="test">
4634\end_layout
4635
4636\begin_layout Plain Layout
4637
4638                <calendar type="Gregorian" timestep="1h" />
4639\end_layout
4640
4641\begin_layout Plain Layout
4642
4643\end_layout
4644
4645\begin_layout Plain Layout
4646
4647                <grid_definition>
4648\end_layout
4649
4650\begin_layout Plain Layout
4651
4652                        <grid id="grid_A"><!-- Definition ommited --></grid>
4653\end_layout
4654
4655\begin_layout Plain Layout
4656
4657                </grid_definition>
4658\end_layout
4659
4660\begin_layout Plain Layout
4661
4662\end_layout
4663
4664\begin_layout Plain Layout
4665
4666                <file_definition>
4667\end_layout
4668
4669\begin_layout Plain Layout
4670
4671                        <file name="output" output_freq="1ts" compression_level="2">
4672\end_layout
4673
4674\begin_layout Plain Layout
4675
4676                        <field id="field_A" grid_ref="grid_A" operation="average" compression_
4677level="4" />
4678\end_layout
4679
4680\begin_layout Plain Layout
4681
4682                        <field id="field_B" grid_ref="grid_A" operation="average" compression_
4683level="0" />
4684\end_layout
4685
4686\begin_layout Plain Layout
4687
4688                        <field id="field_C" grid_ref="grid_A" operation="average" />
4689\end_layout
4690
4691\begin_layout Plain Layout
4692
4693                        </file>
4694\end_layout
4695
4696\begin_layout Plain Layout
4697
4698                </file_definition>
4699\end_layout
4700
4701\begin_layout Plain Layout
4702
4703        </context>
4704\end_layout
4705
4706\begin_layout Plain Layout
4707
4708</simulation>
4709\end_layout
4710
4711\end_inset
4712
4713Note that the
4714\series bold
4715compression_level
4716\series default
4717 attribute can also be set at a file level, in this case it is inherited
4718 by all fields of the file unless they explicitly override the attribute.
4719\begin_inset Newline newline
4720\end_inset
4721
4722
4723\begin_inset Newline newline
4724\end_inset
4725
4726The second solution is available only if you are using a grid with masked
4727 values.
4728 In this case, you can choose to output the indexed grid instead of the
4729 full grid by setting the
4730\series bold
4731indexed_output
4732\series default
4733 attribute to
4734\series bold
4735\emph on
4736
4737\begin_inset Quotes eld
4738\end_inset
4739
4740true
4741\begin_inset Quotes erd
4742\end_inset
4743
4744
4745\series default
4746\emph default
4747.
4748 Missing values are then omitted and extra arrays are outputted so that
4749 the translation from the
4750\begin_inset Quotes eld
4751\end_inset
4752
4753compressed
4754\begin_inset Quotes erd
4755\end_inset
4756
4757 indexes to the true indexes can be done.
4758 Due to those arrays of indexes, indexed output should be considered only
4759 if there is enough masked values.
4760 For more details about this feature, please refer to section 8.2
4761\begin_inset Quotes eld
4762\end_inset
4763
4764Compression by Gathering
4765\begin_inset Quotes erd
4766\end_inset
4767
4768 of the Climate and Forecast (CF) Convention.
4769\end_layout
4770
4771\begin_layout Standard
4772\begin_inset CommandInset include
4773LatexCommand include
4774filename "inputs/user/Grid.lyx"
4775
4776\end_inset
4777
4778
4779\end_layout
4780
4781\begin_layout Standard
4782\begin_inset CommandInset include
4783LatexCommand include
4784filename "inputs/user/Domain.lyx"
4785
4786\end_inset
4787
4788
4789\end_layout
4790
4791\begin_layout Standard
4792\begin_inset CommandInset include
4793LatexCommand include
4794filename "inputs/user/Axis.lyx"
4795
4796\end_inset
4797
4798
4799\end_layout
4800
4801\begin_layout Chapter
4802XIOS options
4803\end_layout
4804
4805\begin_layout Standard
4806Some of XIOS behaviors can be configured using options.
4807 Those options must be expressed as variables in a specific context whose
4808 
4809\series bold
4810id
4811\series default
4812 must be
4813\series bold
4814\emph on
4815
4816\begin_inset Quotes eld
4817\end_inset
4818
4819xios
4820\begin_inset Quotes erd
4821\end_inset
4822
4823
4824\series default
4825\emph default
4826 as shown below.
4827\end_layout
4828
4829\begin_layout Standard
4830\begin_inset listings
4831lstparams "breaklines=true,frame=tb,language=XML,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}},tabsize=2"
4832inline false
4833status open
4834
4835\begin_layout Plain Layout
4836
4837<?xml version="1.0"?>
4838\end_layout
4839
4840\begin_layout Plain Layout
4841
4842<simulation>
4843\end_layout
4844
4845\begin_layout Plain Layout
4846
4847        <!-- Actual context(s) used by the simulation ommited -->
4848\end_layout
4849
4850\begin_layout Plain Layout
4851
4852\end_layout
4853
4854\begin_layout Plain Layout
4855
4856        <context id="xios">
4857\end_layout
4858
4859\begin_layout Plain Layout
4860
4861                <variable_definition>
4862\end_layout
4863
4864\begin_layout Plain Layout
4865
4866                        <variable id="option_name" type="option_type">option_value</variable>
4867\end_layout
4868
4869\begin_layout Plain Layout
4870
4871                </variable_definition>
4872\end_layout
4873
4874\begin_layout Plain Layout
4875
4876        </context>
4877\end_layout
4878
4879\begin_layout Plain Layout
4880
4881</simulation>
4882\end_layout
4883
4884\end_inset
4885
4886
4887\end_layout
4888
4889\begin_layout Section
4890Buffer related options
4891\end_layout
4892
4893\begin_layout Standard
4894By default, XIOS tries to guess the required buffers sizes to ensure efficient
4895 client-server communications.
4896 However it might sometimes be useful to tweak the buffers sizes so XIOS
4897 provides the following options:
4898\end_layout
4899
4900\begin_layout Itemize
4901
4902\series bold
4903optimal_buffer_size
4904\series default
4905 (type:
4906\series bold
4907string
4908\series default
4909) can be either
4910\series bold
4911\emph on
4912
4913\begin_inset Quotes eld
4914\end_inset
4915
4916memory
4917\begin_inset Quotes erd
4918\end_inset
4919
4920
4921\series default
4922\emph default
4923 or
4924\series bold
4925\emph on
4926
4927\begin_inset Quotes erd
4928\end_inset
4929
4930performance
4931\begin_inset Quotes erd
4932\end_inset
4933
4934
4935\series default
4936\emph default
4937.
4938 When using the
4939\series bold
4940\emph on
4941
4942\begin_inset Quotes eld
4943\end_inset
4944
4945memory
4946\begin_inset Quotes erd
4947\end_inset
4948
4949
4950\series default
4951\emph default
4952 mode, XIOS will try to use buffers as small as possible while still ensuring
4953 that the bigger message will fit.
4954 When using the
4955\series bold
4956\emph on
4957
4958\begin_inset Quotes erd
4959\end_inset
4960
4961performance
4962\begin_inset Quotes erd
4963\end_inset
4964
4965
4966\series default
4967\emph default
4968 mode, XIOS will ensure that all active fields can be buffered without having
4969 to flush the buffers.
4970 This mode is used by default since it allows more asynchronism and thus
4971 better performance at the cost of being quite memory hungry.
4972\end_layout
4973
4974\begin_layout Itemize
4975
4976\series bold
4977minimum_buffer_size
4978\series default
4979 (type:
4980\series bold
4981int
4982\series default
4983) defines the mimimum buffer size in bytes (8192 by default).
4984 This value will be used by XIOS only for buffers whose detected size is
4985 smaller than the user defined mimimum size.
4986\end_layout
4987
4988\begin_layout Itemize
4989
4990\series bold
4991buffer_size_factor
4992\series default
4993(type:
4994\series bold
4995int
4996\series default
4997) allows to modify the buffers sizes by multiplying the detected sizes by
4998 an user defined factor (
4999\begin_inset Formula $1.0$
5000\end_inset
5001
5002 by default).
5003 For each allocated buffers, the used size is defined as
5004\begin_inset Formula
5005\[
5006{\scriptstyle used\_size\;=\;\min\left(minimum\_buffer\_size,\; detected\_size\;\times\; buffer\_size\_factor\right)}
5007\]
5008
5009\end_inset
5010
5011
5012\end_layout
5013
5014\end_body
5015\end_document
Note: See TracBrowser for help on using the repository browser.