source: XIOS/dev/dev_cmip6_omp/doc/XIOS_user_guide.lyx @ 1606

Last change on this file since 1606 was 1526, checked in by oabramkina, 2 years ago

Updating user's manual: UGRID and server-two.

File size: 94.8 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
1865UGRID
1866\end_layout
1867
1868\begin_layout Standard
1869In addition to the CF conventions, it is also possible to output data using
1870 
1871\begin_inset CommandInset href
1872LatexCommand href
1873name "UGRID"
1874target "https://ugrid-conventions.github.io/ugrid-conventions/"
1875
1876\end_inset
1877
1878 metadata conventions developed for unstructured meshes.
1879 It allows users to store the topology of an underlying unstructured mesh.
1880 Currently XIOS supports 2D unstructured meshes of any shape (triangular,
1881 quadrilateral, etc) and their mixture.
1882 
1883\end_layout
1884
1885\begin_layout Standard
1886A 2D mesh can be described by a set of nodes, edges and/or faces.
1887 XIOS allows one to define data on any of these three types of elements.
1888 XIOS will generate a full list of connectivity attributes proposed by the
1889 UGRID conventions.
1890 For example in case of a mesh comprised of faces the following connectivity
1891 parameters will be the calculated:
1892\end_layout
1893
1894\begin_layout Standard
1895
1896\family typewriter
1897edge_node_connectivity
1898\end_layout
1899
1900\begin_layout Standard
1901
1902\family typewriter
1903face_node_connectivity
1904\end_layout
1905
1906\begin_layout Standard
1907
1908\family typewriter
1909edge_nodes_connectivity
1910\end_layout
1911
1912\begin_layout Standard
1913
1914\family typewriter
1915face_nodes_connectivity
1916\end_layout
1917
1918\begin_layout Standard
1919
1920\family typewriter
1921face_edges_connectivity
1922\end_layout
1923
1924\begin_layout Standard
1925
1926\family typewriter
1927edge_face_connectivity
1928\end_layout
1929
1930\begin_layout Standard
1931
1932\family typewriter
1933face_face_connectivity
1934\end_layout
1935
1936\begin_layout Standard
1937In order to select UGRID output format, one has to set file attribute
1938\series bold
1939convention
1940\series default
1941 to
1942\series bold
1943\shape italic
1944"UGRID"
1945\series default
1946\shape default
1947 (its default value is
1948\series bold
1949\shape italic
1950
1951\begin_inset Quotes eld
1952\end_inset
1953
1954CF
1955\begin_inset Quotes erd
1956\end_inset
1957
1958
1959\series default
1960\shape default
1961).
1962 Domain attribute
1963\series bold
1964nvertex
1965\series default
1966 is mandatory for UGRID.
1967 It servers for identifying one of three types of mesh elements on which
1968 data can be defined: nodes (nvertex=1), edges (nvertex=2), and faces (nvertex
1969\begin_inset Formula $\geq$
1970\end_inset
1971
19723).
1973 In order to write fields on the same mesh but on its different elements,
1974 one has to assign the same domain name to each of the domains.
1975 Example given below illustrates this point for three fields defined on
1976 the same mesh but on its different elements: nodes, edges, and faces.
1977\end_layout
1978
1979\begin_layout Standard
1980\begin_inset listings
1981lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
1982inline false
1983status open
1984
1985\begin_layout Plain Layout
1986
1987<file_definition> 
1988\end_layout
1989
1990\begin_layout Plain Layout
1991
1992        <file id="output_UGRID" convention="UGRID">
1993\end_layout
1994
1995\begin_layout Plain Layout
1996
1997                <field id="varOnNodes" ...
1998 domain_ref="node"/>
1999\end_layout
2000
2001\begin_layout Plain Layout
2002
2003                <field id="varOnEdges" ...
2004 domain_ref="edge"/>
2005\end_layout
2006
2007\begin_layout Plain Layout
2008
2009                <field id="varOnFaces" ...
2010 domain_ref="face"/>
2011\end_layout
2012
2013\begin_layout Plain Layout
2014
2015        </file>
2016\end_layout
2017
2018\begin_layout Plain Layout
2019
2020</file_definition>
2021\end_layout
2022
2023\begin_layout Plain Layout
2024
2025\end_layout
2026
2027\begin_layout Plain Layout
2028
2029<domain_definition> 
2030\end_layout
2031
2032\begin_layout Plain Layout
2033
2034        <domain id="node" name="mesh2D" nvertex="1"/>
2035\end_layout
2036
2037\begin_layout Plain Layout
2038
2039        <domain id="edge" name="mesh2D" nvertex="2"/>
2040\end_layout
2041
2042\begin_layout Plain Layout
2043
2044        <domain id="face" name="mesh2D" nvertex="4"/>
2045\end_layout
2046
2047\begin_layout Plain Layout
2048
2049</domain_definition>
2050\end_layout
2051
2052\end_inset
2053
2054
2055\end_layout
2056
2057\begin_layout Section
2058How to use file splitting
2059\end_layout
2060
2061\begin_layout Standard
2062Output files can often be quite huge, particularly if the
2063\begin_inset Quotes eld
2064\end_inset
2065
2066
2067\series bold
2068\emph on
2069one_file
2070\series default
2071\emph default
2072
2073\begin_inset Quotes erd
2074\end_inset
2075
2076 mode is used.
2077 In this case, it can be interesting to periodically split the file in order
2078 to have a few smaller files containing contiguous temporal portions of
2079 the output data.
2080\begin_inset Newline newline
2081\end_inset
2082
2083
2084\begin_inset Newline newline
2085\end_inset
2086
2087This behavior can be achieved in XIOS by setting the
2088\series bold
2089split_freq
2090\series default
2091 attribute to the duration you want, as illustrated in the following example:
2092\begin_inset Newline newline
2093\end_inset
2094
2095
2096\begin_inset listings
2097lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2098inline false
2099status open
2100
2101\begin_layout Plain Layout
2102
2103<?xml version="1.0"?>
2104\end_layout
2105
2106\begin_layout Plain Layout
2107
2108<simulation>
2109\end_layout
2110
2111\begin_layout Plain Layout
2112
2113        <context id="test">
2114\end_layout
2115
2116\begin_layout Plain Layout
2117
2118                <calendar type="Gregorian" timestep="1h" />
2119\end_layout
2120
2121\begin_layout Plain Layout
2122
2123\end_layout
2124
2125\begin_layout Plain Layout
2126
2127                <file_definition>
2128\end_layout
2129
2130\begin_layout Plain Layout
2131
2132                        <file name="output" output_freq="1d" split_freq="1y">
2133\end_layout
2134
2135\begin_layout Plain Layout
2136
2137                        <!-- Content of the file ommited for now -->
2138\end_layout
2139
2140\begin_layout Plain Layout
2141
2142                        </file>
2143\end_layout
2144
2145\begin_layout Plain Layout
2146
2147                </file_definition>
2148\end_layout
2149
2150\begin_layout Plain Layout
2151
2152        </context>
2153\end_layout
2154
2155\begin_layout Plain Layout
2156
2157</simulation>
2158\end_layout
2159
2160\end_inset
2161
2162With this configuration, some data will be outputted every day and a new
2163 file will be created every year.
2164\begin_inset Newline newline
2165\end_inset
2166
2167
2168\begin_inset Newline newline
2169\end_inset
2170
2171Note that the split frequency is the duration after which a new file will
2172 be created, it does not mean that a new file will be created at the beginning
2173 of each period.
2174 For example, if you start your simulation the first of June 2014 and run
2175 it for two years with a split frequency of one year:
2176\end_layout
2177
2178\begin_layout Itemize
2179you will get two files containing respectively the period from June 1st,
2180 2014 to May 31th, 2015 and from June 1st, 2015 to May 31th, 2016.
2181\end_layout
2182
2183\begin_layout Itemize
2184you will NOT get three files containing respectively the last six months
2185 of 2014, the full year of 2015 and the first six months of 2016.
2186\end_layout
2187
2188\begin_layout Standard
2189XIOS automatically suffixes the file names with the start and end dates
2190 when using file splitting.
2191 By default, it will try to use the shortest date that still enables to
2192 distinguish the files.
2193 Thus in the above example, the files would be named
2194\begin_inset Quotes eld
2195\end_inset
2196
2197output_2014-2015.nc
2198\begin_inset Quotes erd
2199\end_inset
2200
2201 and
2202\begin_inset Quotes eld
2203\end_inset
2204
2205output_2015-2016.nc
2206\begin_inset Quotes erd
2207\end_inset
2208
2209.
2210 If you wish to force the date format used to prefix the files, you can
2211 define the
2212\series bold
2213split_freq_format
2214\series default
2215 attribute to override the default behavior.
2216\end_layout
2217
2218\begin_layout Section
2219A word about file synchronization
2220\end_layout
2221
2222\begin_layout Standard
2223File synchronization is usually not something you should worry about.
2224 However, it is important to understand that data written by XIOS might
2225 not be immediately written on the disk in practice.
2226 Input/output libraries like NetCDF and HDF5 and parallel file systems generally
2227 use complex caching policies for performance reasons.
2228 This means that your data might still be stored in memory after it was
2229 supposedly written.
2230\begin_inset Newline newline
2231\end_inset
2232
2233
2234\begin_inset Newline newline
2235\end_inset
2236
2237It might become critical to control this behavior for two main reasons:
2238\end_layout
2239
2240\begin_layout Itemize
2241if you want to mitigate the impact of a crash, as all buffered data would
2242 be lost ;
2243\end_layout
2244
2245\begin_layout Itemize
2246if you want to be able to access the data from the output file immediately
2247 after writing it.
2248\end_layout
2249
2250\begin_layout Standard
2251By default, XIOS will never force file synchronization but you can require
2252 it to do so by setting the
2253\series bold
2254sync_freq
2255\series default
2256 attribute to the wanted duration.
2257 In this case, XIOS will regularly instruct NetCDF to synchronize the file
2258 on disk by flushing its internal buffers.
2259\begin_inset Newline newline
2260\end_inset
2261
2262
2263\begin_inset Newline newline
2264\end_inset
2265
2266Note file synchronization must be used sparingly as it can have a disastrous
2267 impact on performance.
2268 Make sure to use a reasonably high synchronization frequency to avoid any
2269 issue.
2270\end_layout
2271
2272\begin_layout Chapter
2273Fields and variables
2274\end_layout
2275
2276\begin_layout Standard
2277XIOS outsources the input/output definitions in its XML configuration file.
2278 In the last chapter we presented some general points about file objects.
2279 This chapter focuses on how to use fields and variables (that is variables
2280 and attributes in NetCDF nomenclature) to populate files.
2281\begin_inset Newline newline
2282\end_inset
2283
2284
2285\end_layout
2286
2287\begin_layout Section
2288How to define your first field
2289\end_layout
2290
2291\begin_layout Standard
2292If you wish to input or to output data using XIOS, you will need to define
2293 at least one file with one field.
2294 This can be done from both the XML configuration file and the Fortran interface.
2295 Fields are often defined in the configuration file, although their definitions
2296 are sometimes amended using the API.
2297\begin_inset Newline newline
2298\end_inset
2299
2300
2301\begin_inset Newline newline
2302\end_inset
2303
2304Field objects are defined with the
2305\begin_inset Flex Code
2306status open
2307
2308\begin_layout Plain Layout
2309<field>
2310\end_layout
2311
2312\end_inset
2313
2314 tag and should always be inside a
2315\begin_inset Flex Code
2316status open
2317
2318\begin_layout Plain Layout
2319<field_definition>
2320\end_layout
2321
2322\end_inset
2323
2324 or a
2325\begin_inset Flex Code
2326status open
2327
2328\begin_layout Plain Layout
2329<file>
2330\end_layout
2331
2332\end_inset
2333
2334 section.
2335 Only the grid and the operation attached to the field are mandatory to
2336 have a well defined field but it is generally a good idea to give it an
2337 identifier.
2338 The following example shows a minimal configuration file which defines
2339 one file with one field.
2340\end_layout
2341
2342\begin_layout Standard
2343\begin_inset listings
2344lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2345inline false
2346status open
2347
2348\begin_layout Plain Layout
2349
2350<?xml version="1.0"?>
2351\end_layout
2352
2353\begin_layout Plain Layout
2354
2355<simulation>
2356\end_layout
2357
2358\begin_layout Plain Layout
2359
2360        <context id="test">
2361\end_layout
2362
2363\begin_layout Plain Layout
2364
2365                <calendar type="Gregorian" timestep="1h" />
2366\end_layout
2367
2368\begin_layout Plain Layout
2369
2370\end_layout
2371
2372\begin_layout Plain Layout
2373
2374                <grid_definition>
2375\end_layout
2376
2377\begin_layout Plain Layout
2378
2379                        <grid id="grid_A"><!-- Definition ommited --></grid>
2380\end_layout
2381
2382\begin_layout Plain Layout
2383
2384                </grid_definition>
2385\end_layout
2386
2387\begin_layout Plain Layout
2388
2389\end_layout
2390
2391\begin_layout Plain Layout
2392
2393                <file_definition>
2394\end_layout
2395
2396\begin_layout Plain Layout
2397
2398                        <file name="output" type="one_file" output_freq="1ts">
2399\end_layout
2400
2401\begin_layout Plain Layout
2402
2403                        <field id="field_A" grid_ref="grid_A" operation="instant" />
2404\end_layout
2405
2406\begin_layout Plain Layout
2407
2408                        </file>
2409\end_layout
2410
2411\begin_layout Plain Layout
2412
2413                </file_definition>
2414\end_layout
2415
2416\begin_layout Plain Layout
2417
2418        </context>
2419\end_layout
2420
2421\begin_layout Plain Layout
2422
2423</simulation>
2424\end_layout
2425
2426\end_inset
2427
2428It defines one file named
2429\begin_inset Quotes eld
2430\end_inset
2431
2432
2433\emph on
2434output
2435\emph default
2436
2437\begin_inset Quotes erd
2438\end_inset
2439
2440 which contains one field
2441\begin_inset Quotes eld
2442\end_inset
2443
2444
2445\emph on
2446field_A
2447\emph default
2448
2449\begin_inset Quotes erd
2450\end_inset
2451
2452 defined on a grid
2453\begin_inset Quotes eld
2454\end_inset
2455
2456
2457\emph on
2458grid_A
2459\emph default
2460
2461\begin_inset Quotes erd
2462\end_inset
2463
2464.
2465 The file and the field are configured so that the data is written in the
2466 file at every timestep (using the
2467\series bold
2468output_freq
2469\series default
2470 file attribute) without any transformation (using the
2471\series bold
2472operation
2473\series default
2474 field attribute set to
2475\begin_inset Quotes eld
2476\end_inset
2477
2478
2479\series bold
2480\emph on
2481instant
2482\series default
2483\emph default
2484
2485\begin_inset Quotes erd
2486\end_inset
2487
2488).
2489\begin_inset Newline newline
2490\end_inset
2491
2492
2493\begin_inset Newline newline
2494\end_inset
2495
2496The corresponding Fortran simulation loop could be:
2497\end_layout
2498
2499\begin_layout Standard
2500\begin_inset listings
2501lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2502inline false
2503status open
2504
2505\begin_layout Plain Layout
2506
2507DO ts=1,numberOfTimestep
2508\end_layout
2509
2510\begin_layout Plain Layout
2511
2512        ! Inform XIOS of the current timestep
2513\end_layout
2514
2515\begin_layout Plain Layout
2516
2517        CALL xios_update_calendar(ts)
2518\end_layout
2519
2520\begin_layout Plain Layout
2521
2522        ! Compute field_A for current timestep
2523\end_layout
2524
2525\begin_layout Plain Layout
2526
2527        ! ...
2528\end_layout
2529
2530\begin_layout Plain Layout
2531
2532        ! Output the data
2533\end_layout
2534
2535\begin_layout Plain Layout
2536
2537        CALL xios_send_field("field_A", field_A)
2538\end_layout
2539
2540\begin_layout Plain Layout
2541
2542ENDDO
2543\end_layout
2544
2545\end_inset
2546
2547As you can see, the
2548\series bold
2549id
2550\series default
2551 of the field is used in the model to select the field for which data is
2552 being provided which makes this attribute extremely important.
2553 Note that it must be unique for all fields even if they are defined in
2554 different files.
2555 By default, the
2556\series bold
2557id
2558\series default
2559 of a field is also used as the name of the corresponding NetCDF variable.
2560 It is however possible to override this default name using the field attribute
2561 
2562\series bold
2563name
2564\series default
2565.
2566 Two fields can share the same
2567\series bold
2568name
2569\series default
2570 as long as they are not used in the same file.
2571\begin_inset Newline newline
2572\end_inset
2573
2574
2575\begin_inset Newline newline
2576\end_inset
2577
2578The second argument of the
2579\begin_inset Flex Code
2580status open
2581
2582\begin_layout Plain Layout
2583xios_send_field
2584\end_layout
2585
2586\end_inset
2587
2588 function is an array containing the data.
2589 Its shape and content are not described here as they depend directly on
2590 the grid.
2591 For more information on the data layout, refer to the chapters focusing
2592 on grids, domains and axis.
2593\begin_inset Newline newline
2594\end_inset
2595
2596
2597\begin_inset Newline newline
2598\end_inset
2599
2600The same configuration could also be obtained using the Fortran interface:
2601\end_layout
2602
2603\begin_layout Standard
2604\begin_inset listings
2605lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2606inline false
2607status open
2608
2609\begin_layout Plain Layout
2610
2611! ...
2612\end_layout
2613
2614\begin_layout Plain Layout
2615
2616TYPE(xios_context)   :: ctx_hdl
2617\end_layout
2618
2619\begin_layout Plain Layout
2620
2621TYPE(xios_file)          :: file_hdl
2622\end_layout
2623
2624\begin_layout Plain Layout
2625
2626TYPE(xios_filegroup) :: filegroup_hdl
2627\end_layout
2628
2629\begin_layout Plain Layout
2630
2631TYPE(xios_field)        :: field_hdl
2632\end_layout
2633
2634\begin_layout Plain Layout
2635
2636! ...
2637\end_layout
2638
2639\begin_layout Plain Layout
2640
2641! Context, calendar and grid initializations ommited, see the corresponding
2642 section of this user manual and of the reference manual
2643\end_layout
2644
2645\begin_layout Plain Layout
2646
2647CALL xios_get_handle("test", ctx_hdl)
2648\end_layout
2649
2650\begin_layout Plain Layout
2651
2652CALL xios_set_current_context(ctx_hdl)
2653\end_layout
2654
2655\begin_layout Plain Layout
2656
2657CALL xios_get_filegroup_handle("file_definition", filegroup_hdl)
2658\end_layout
2659
2660\begin_layout Plain Layout
2661
2662CALL xios_add_file(filegroup_hdl, file_hdl)
2663\end_layout
2664
2665\begin_layout Plain Layout
2666
2667CALL xios_set_attr(file_hdl, name="output", output_freq=xios_timestep)
2668\end_layout
2669
2670\begin_layout Plain Layout
2671
2672CALL xios_add_field(file_hdl, field_hdl, "field_A")
2673\end_layout
2674
2675\begin_layout Plain Layout
2676
2677CALL xios_set_attr(field_hdl, grid_ref="grid_A", operation="instant")
2678\end_layout
2679
2680\end_inset
2681
2682Note that if you want to define a field on a grid with only one domain and/or
2683 one axis, it is possible to use the
2684\series bold
2685domain_ref
2686\series default
2687 and
2688\series bold
2689axis_ref
2690\series default
2691 attributes instead of the
2692\series bold
2693grid_ref
2694\series default
2695 attribute.
2696 A temporary grid will be created based on the domain and/or axis defined
2697 this way.
2698\begin_inset Newline newline
2699\end_inset
2700
2701
2702\begin_inset Newline newline
2703\end_inset
2704
2705If you are using a grid with some masked points (see the relevant sections
2706 of this manual), you must set the
2707\series bold
2708default_value
2709\series default
2710 attribute to define the default value that will replace the missing values
2711 in the output file.
2712\begin_inset Newline newline
2713\end_inset
2714
2715
2716\begin_inset Newline newline
2717\end_inset
2718
2719If you wish to disable a field without having to remove its definition from
2720 the configuration file, you can set the
2721\series bold
2722enabled
2723\series default
2724 attribute to
2725\begin_inset Quotes eld
2726\end_inset
2727
2728
2729\series bold
2730\emph on
2731false
2732\series default
2733\emph default
2734
2735\begin_inset Quotes erd
2736\end_inset
2737
2738.
2739\end_layout
2740
2741\begin_layout Section
2742How to use temporal operations
2743\end_layout
2744
2745\begin_layout Standard
2746The last section showed a very basic example where the data was outputted
2747 at every timestep using the
2748\begin_inset Quotes eld
2749\end_inset
2750
2751
2752\series bold
2753\emph on
2754instant
2755\series default
2756\emph default
2757
2758\begin_inset Quotes erd
2759\end_inset
2760
2761 
2762\series bold
2763operation
2764\series default
2765.
2766 However in many use cases, it might be more interesting to output only
2767 the mean value on a certain period of time for example.
2768 This section describes the use of temporal operations available in XIOS.
2769\begin_inset Newline newline
2770\end_inset
2771
2772
2773\begin_inset Newline newline
2774\end_inset
2775
2776The field attribute
2777\series bold
2778operation
2779\series default
2780 currently supports six modes:
2781\end_layout
2782
2783\begin_layout Itemize
2784
2785\series bold
2786\emph on
2787instant
2788\series default
2789\emph default
2790: no temporal operation is applied which means the new data always overrides
2791 the previous one even if it was not outputted,
2792\end_layout
2793
2794\begin_layout Itemize
2795
2796\series bold
2797\emph on
2798average
2799\series default
2800\emph default
2801: compute and output the mean value,
2802\end_layout
2803
2804\begin_layout Itemize
2805
2806\series bold
2807\emph on
2808accumulate
2809\series default
2810\emph default
2811: compute and output the sum,
2812\end_layout
2813
2814\begin_layout Itemize
2815
2816\series bold
2817\emph on
2818minimum
2819\series default
2820\emph default
2821: compute and output the minimum value,
2822\end_layout
2823
2824\begin_layout Itemize
2825
2826\series bold
2827\emph on
2828maximum
2829\series default
2830\emph default
2831: compute and output the maximum value,
2832\end_layout
2833
2834\begin_layout Itemize
2835
2836\series bold
2837\emph on
2838once
2839\series default
2840\emph default
2841 : the data is written to the file only the first time it is received from
2842 the model, any subsequent data is ignored.
2843 The corresponding NetCDF variable does not have a time dimension.
2844\end_layout
2845
2846\begin_layout Standard
2847The output frequency of the file defined by the
2848\series bold
2849output_freq
2850\series default
2851 attribute is used as the temporal operation period (except for the
2852\begin_inset Quotes eld
2853\end_inset
2854
2855
2856\series bold
2857\emph on
2858once
2859\series default
2860\emph default
2861
2862\begin_inset Quotes erd
2863\end_inset
2864
2865 
2866\series bold
2867operation
2868\series default
2869 for which there is no period).
2870 This means it is for example not possible to output a daily average and
2871 a weekly average in the same file.
2872\begin_inset Newline newline
2873\end_inset
2874
2875
2876\begin_inset Newline newline
2877\end_inset
2878
2879This updated example shows how to output the daily average instead of the
2880 instant data for all timesteps:
2881\end_layout
2882
2883\begin_layout Standard
2884\begin_inset listings
2885lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
2886inline false
2887status open
2888
2889\begin_layout Plain Layout
2890
2891<?xml version="1.0"?>
2892\end_layout
2893
2894\begin_layout Plain Layout
2895
2896<simulation>
2897\end_layout
2898
2899\begin_layout Plain Layout
2900
2901        <context id="test">
2902\end_layout
2903
2904\begin_layout Plain Layout
2905
2906                <calendar type="Gregorian" timestep="1h" />
2907\end_layout
2908
2909\begin_layout Plain Layout
2910
2911\end_layout
2912
2913\begin_layout Plain Layout
2914
2915                <grid_definition>
2916\end_layout
2917
2918\begin_layout Plain Layout
2919
2920                        <grid id="grid_A"><!-- Definition ommited --></grid>
2921\end_layout
2922
2923\begin_layout Plain Layout
2924
2925                </grid_definition>
2926\end_layout
2927
2928\begin_layout Plain Layout
2929
2930\end_layout
2931
2932\begin_layout Plain Layout
2933
2934                <file_definition>
2935\end_layout
2936
2937\begin_layout Plain Layout
2938
2939                        <file name="output" type="one_file" output_freq="1d">
2940\end_layout
2941
2942\begin_layout Plain Layout
2943
2944                        <field id="field_A" grid_ref="grid_A" operation="average" />
2945\end_layout
2946
2947\begin_layout Plain Layout
2948
2949                        </file>
2950\end_layout
2951
2952\begin_layout Plain Layout
2953
2954                </file_definition>
2955\end_layout
2956
2957\begin_layout Plain Layout
2958
2959        </context>
2960\end_layout
2961
2962\begin_layout Plain Layout
2963
2964</simulation>
2965\end_layout
2966
2967\end_inset
2968
2969Compared to the previous example, only the file attribute
2970\series bold
2971output_freq
2972\series default
2973 and the field attribute
2974\series bold
2975operation
2976\series default
2977 have been modified.
2978 Computing the weekly minimum instead of the daily average would be as simple
2979 as using
2980\begin_inset Flex Code
2981status open
2982
2983\begin_layout Plain Layout
2984output_freq="7d"
2985\end_layout
2986
2987\end_inset
2988
2989and
2990\begin_inset Flex Code
2991status open
2992
2993\begin_layout Plain Layout
2994operation="minimum"
2995\end_layout
2996
2997\end_inset
2998
2999.
3000\begin_inset Newline newline
3001\end_inset
3002
3003
3004\begin_inset Newline newline
3005\end_inset
3006
3007Note that if you use a temporal operation and have
3008\series bold
3009default_value
3010\series default
3011 defined, it might be useful to set the attribute
3012\series bold
3013 detect_missing_value
3014\series default
3015 to
3016\begin_inset Quotes eld
3017\end_inset
3018
3019
3020\series bold
3021\emph on
3022true
3023\series default
3024\emph default
3025
3026\begin_inset Quotes erd
3027\end_inset
3028
3029.
3030 This way temporal operations will not be applied when a default value is
3031 detected.
3032\begin_inset Newline newline
3033\end_inset
3034
3035
3036\begin_inset Newline newline
3037\end_inset
3038
3039For example, we consider the values of a 2x2 domain for three timesteps:
3040\begin_inset Formula
3041\[
3042\begin{bmatrix}3 & -1\\
30437 & 1
3044\end{bmatrix},\qquad\begin{bmatrix}5 & 6\\
3045-1 & 2
3046\end{bmatrix},\qquad\begin{bmatrix}-1 & 8\\
30473 & 4
3048\end{bmatrix}.
3049\]
3050
3051\end_inset
3052
3053If we suppose that the field is configured to compute the average on three
3054 timesteps, the resulting field would be:
3055\begin_inset Formula
3056\[
3057\begin{bmatrix}\nicefrac{7}{3} & \nicefrac{13}{3}\\
30583 & \nicefrac{7}{3}
3059\end{bmatrix}.
3060\]
3061
3062\end_inset
3063
3064If
3065\series bold
3066default_value
3067\series default
3068 is set to
3069\emph on
3070
3071\begin_inset Quotes eld
3072\end_inset
3073
3074-1
3075\begin_inset Quotes erd
3076\end_inset
3077
3078
3079\emph default
3080 and
3081\series bold
3082detect_missing_value
3083\series default
3084 is set to
3085\begin_inset Quotes eld
3086\end_inset
3087
3088
3089\series bold
3090\emph on
3091true
3092\series default
3093\emph default
3094
3095\begin_inset Quotes erd
3096\end_inset
3097
3098, the resulting field would be:
3099\begin_inset Formula
3100\[
3101\begin{bmatrix}4 & 7\\
31025 & \nicefrac{7}{3}
3103\end{bmatrix}.
3104\]
3105
3106\end_inset
3107
3108
3109\end_layout
3110
3111\begin_layout Section
3112How to use a specific data sampling
3113\end_layout
3114
3115\begin_layout Standard
3116It is sometimes useful to have more control on the data sampling.
3117 By default, the input data is used at every timestep but sometimes it is
3118 not what you want.
3119 The following examples illustrate such cases:
3120\end_layout
3121
3122\begin_layout Enumerate
3123the model is not computing updated values at the same frequency for all
3124 fields (for example, a field is updated every two timesteps).
3125\end_layout
3126
3127\begin_layout Enumerate
3128you want to output a specific instant value in the interval between two
3129 outputs.
3130\end_layout
3131
3132\begin_layout Enumerate
3133you want to compute an average without taking into account all instant values
3134 in the interval between two outputs.
3135\end_layout
3136
3137\begin_layout Standard
3138Data sampling can be controlled in XIOS using the
3139\series bold
3140freq_op
3141\series default
3142 (one timestep by default) and
3143\series bold
3144freq_offset
3145\series default
3146 (null by default) attributes.
3147 Those attributes define respectively how often data from the model must
3148 be used and the amount of time before starting to use it.
3149\begin_inset Newline newline
3150\end_inset
3151
3152
3153\begin_inset Newline newline
3154\end_inset
3155
3156For following excerpts of configuration files show you to use those attributes
3157 to handle the motivating examples.
3158\end_layout
3159
3160\begin_layout Enumerate
3161In this example, we suppose that we get two fields from the model:
3162\begin_inset Quotes eld
3163\end_inset
3164
3165field_A
3166\begin_inset Quotes erd
3167\end_inset
3168
3169 which is computed for each timestep and
3170\begin_inset Quotes eld
3171\end_inset
3172
3173field_B
3174\begin_inset Quotes erd
3175\end_inset
3176
3177 which is only computed every two timesteps.
3178 For both fields, we show how to compute and output the sum of all values
3179 received during 6 timesteps:
3180\begin_inset Newline newline
3181\end_inset
3182
3183
3184\begin_inset listings
3185lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3186inline false
3187status open
3188
3189\begin_layout Plain Layout
3190
3191<file_definition>
3192\end_layout
3193
3194\begin_layout Plain Layout
3195
3196        <file name="output" output_freq="6ts">
3197\end_layout
3198
3199\begin_layout Plain Layout
3200
3201                <field id="field_A" grid_ref="grid_A" operation="accumulate" />
3202\end_layout
3203
3204\begin_layout Plain Layout
3205
3206                <field id="field_B" grid_ref="grid_B" operation="accumulate" freq_op="2ts"
3207 />
3208\end_layout
3209
3210\begin_layout Plain Layout
3211
3212        </file>
3213\end_layout
3214
3215\begin_layout Plain Layout
3216
3217</file_definition>
3218\end_layout
3219
3220\end_inset
3221
3222
3223\end_layout
3224
3225\begin_layout Enumerate
3226In this example, we show how to output the 11th instant value every 12 timesteps
3227:
3228\begin_inset Newline newline
3229\end_inset
3230
3231
3232\begin_inset listings
3233lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3234inline false
3235status open
3236
3237\begin_layout Plain Layout
3238
3239<file_definition>
3240\end_layout
3241
3242\begin_layout Plain Layout
3243
3244        <file name="output" output_freq="12ts">
3245\end_layout
3246
3247\begin_layout Plain Layout
3248
3249                <field id="field_A" grid_ref="grid_A" operation="instant" freq_op="11ts"
3250 freq_offset="12ts" />
3251\end_layout
3252
3253\begin_layout Plain Layout
3254
3255        </file>
3256\end_layout
3257
3258\begin_layout Plain Layout
3259
3260</file_definition>
3261\end_layout
3262
3263\end_inset
3264
3265
3266\end_layout
3267
3268\begin_layout Enumerate
3269In this example, we suppose that the timestep is equal to one hour and that
3270 the simulation starts at midnight.
3271 We show how to compute the weekly average of the field value at midday:
3272\begin_inset Newline newline
3273\end_inset
3274
3275
3276\begin_inset listings
3277lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3278inline false
3279status open
3280
3281\begin_layout Plain Layout
3282
3283<file_definition>
3284\end_layout
3285
3286\begin_layout Plain Layout
3287
3288        <file name="output" output_freq="1w">
3289\end_layout
3290
3291\begin_layout Plain Layout
3292
3293                <field id="field_A" grid_ref="grid_A" operation="average" freq_op="1d"
3294 freq_offset="12h" />
3295\end_layout
3296
3297\begin_layout Plain Layout
3298
3299        </file>
3300\end_layout
3301
3302\begin_layout Plain Layout
3303
3304</file_definition>
3305\end_layout
3306
3307\end_inset
3308
3309
3310\end_layout
3311
3312\begin_layout Section
3313How to use field references
3314\end_layout
3315
3316\begin_layout Standard
3317It is quite common that different temporal operations must be applied to
3318 the same instant data provided by the model.
3319 In theory, the only solution to handle this scenario would be to define
3320 a field for each operation, give them different
3321\series bold
3322id
3323\series default
3324 and and call
3325\begin_inset Flex Code
3326status open
3327
3328\begin_layout Plain Layout
3329xios_send_field
3330\end_layout
3331
3332\end_inset
3333
3334 with the same array of data for each of those fields.
3335\begin_inset Newline newline
3336\end_inset
3337
3338
3339\begin_inset Newline newline
3340\end_inset
3341
3342The following example illustrates this solution for a field for which we
3343 want to compute the average, minimal and maximal values:
3344\end_layout
3345
3346\begin_layout Standard
3347\begin_inset listings
3348lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3349inline false
3350status open
3351
3352\begin_layout Plain Layout
3353
3354<?xml version="1.0"?>
3355\end_layout
3356
3357\begin_layout Plain Layout
3358
3359<simulation>
3360\end_layout
3361
3362\begin_layout Plain Layout
3363
3364        <context id="test">
3365\end_layout
3366
3367\begin_layout Plain Layout
3368
3369                <calendar type="Gregorian" timestep="1h" />
3370\end_layout
3371
3372\begin_layout Plain Layout
3373
3374\end_layout
3375
3376\begin_layout Plain Layout
3377
3378                <grid_definition>
3379\end_layout
3380
3381\begin_layout Plain Layout
3382
3383                        <grid id="grid_A"><!-- Definition ommited --></grid>
3384\end_layout
3385
3386\begin_layout Plain Layout
3387
3388                </grid_definition>
3389\end_layout
3390
3391\begin_layout Plain Layout
3392
3393\end_layout
3394
3395\begin_layout Plain Layout
3396
3397                <file_definition>
3398\end_layout
3399
3400\begin_layout Plain Layout
3401
3402                        <file name="output" output_freq="1d">
3403\end_layout
3404
3405\begin_layout Plain Layout
3406
3407                        <field id="field_A_avg" grid_ref="grid_A" operation="average"
3408 />
3409\end_layout
3410
3411\begin_layout Plain Layout
3412
3413                        <field id="field_A_min" grid_ref="grid_A" operation="min" />
3414\end_layout
3415
3416\begin_layout Plain Layout
3417
3418                        <field id="field_A_max" grid_ref="grid_A" operation="max" />
3419\end_layout
3420
3421\begin_layout Plain Layout
3422
3423                        </file>
3424\end_layout
3425
3426\begin_layout Plain Layout
3427
3428                </file_definition>
3429\end_layout
3430
3431\begin_layout Plain Layout
3432
3433        </context>
3434\end_layout
3435
3436\begin_layout Plain Layout
3437
3438</simulation>
3439\end_layout
3440
3441\end_inset
3442
3443To simplify the handling of such scenarios, XIOS has a
3444\begin_inset Quotes eld
3445\end_inset
3446
3447reference
3448\begin_inset Quotes erd
3449\end_inset
3450
3451 feature which allows one field to inherit the attributes (except the
3452\series bold
3453id
3454\series default
3455) and the instant data of another field.
3456 The above example can then be rewritten:
3457\begin_inset listings
3458lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3459inline false
3460status open
3461
3462\begin_layout Plain Layout
3463
3464<?xml version="1.0"?>
3465\end_layout
3466
3467\begin_layout Plain Layout
3468
3469<simulation>
3470\end_layout
3471
3472\begin_layout Plain Layout
3473
3474        <context id="test">
3475\end_layout
3476
3477\begin_layout Plain Layout
3478
3479                <calendar type="Gregorian" timestep="1h" />
3480\end_layout
3481
3482\begin_layout Plain Layout
3483
3484\end_layout
3485
3486\begin_layout Plain Layout
3487
3488                <grid_definition>
3489\end_layout
3490
3491\begin_layout Plain Layout
3492
3493                        <grid id="grid_A"><!-- Definition ommited --></grid>
3494\end_layout
3495
3496\begin_layout Plain Layout
3497
3498                </grid_definition>
3499\end_layout
3500
3501\begin_layout Plain Layout
3502
3503\end_layout
3504
3505\begin_layout Plain Layout
3506
3507                <file_definition>
3508\end_layout
3509
3510\begin_layout Plain Layout
3511
3512                        <file name="output" output_freq="1d">
3513\end_layout
3514
3515\begin_layout Plain Layout
3516
3517                        <field id="field_A" name="field_A_avg" grid_ref="grid_A" operation="av
3518erage" />
3519\end_layout
3520
3521\begin_layout Plain Layout
3522
3523                        <field field_ref="field_A" name="field_A_min" operation="min"
3524 />
3525\end_layout
3526
3527\begin_layout Plain Layout
3528
3529                        <field field_ref="field_A" name="field_A_max" operation="max"
3530 />
3531\end_layout
3532
3533\begin_layout Plain Layout
3534
3535                        </file>
3536\end_layout
3537
3538\begin_layout Plain Layout
3539
3540                </file_definition>
3541\end_layout
3542
3543\begin_layout Plain Layout
3544
3545        </context>
3546\end_layout
3547
3548\begin_layout Plain Layout
3549
3550</simulation>
3551\end_layout
3552
3553\end_inset
3554
3555With this configuration, only one call to
3556\begin_inset Flex Code
3557status open
3558
3559\begin_layout Plain Layout
3560xios_send_field(
3561\begin_inset Quotes eld
3562\end_inset
3563
3564field_A
3565\begin_inset Quotes erd
3566\end_inset
3567
3568, field_A)
3569\end_layout
3570
3571\end_inset
3572
3573 is needed.
3574 Note how inherited attributes (like
3575\series bold
3576name
3577\series default
3578 or
3579\series bold
3580operation
3581\series default
3582 for example) are overwritten to obtain the desired configuration.
3583 Additionally, be aware that it is the instant values which are inherited,
3584 not the result of the operation on the field.
3585\begin_inset Newline newline
3586\end_inset
3587
3588
3589\begin_inset Newline newline
3590\end_inset
3591
3592Similarly, it is sometimes useful to output the result of a temporal operation
3593 on a field for different periods.
3594 In this case, it does not really make sense to define the field that will
3595 be then inherited in one file rather than another.
3596 A solution is to make use of the
3597\begin_inset Flex Code
3598status open
3599
3600\begin_layout Plain Layout
3601field_definition
3602\end_layout
3603
3604\end_inset
3605
3606 section so that it is clear that the field can be reused in any file.
3607 This is illustrated in the following sample configuration file:
3608\begin_inset listings
3609lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3610inline false
3611status open
3612
3613\begin_layout Plain Layout
3614
3615<?xml version="1.0"?>
3616\end_layout
3617
3618\begin_layout Plain Layout
3619
3620<simulation>
3621\end_layout
3622
3623\begin_layout Plain Layout
3624
3625        <context id="test">
3626\end_layout
3627
3628\begin_layout Plain Layout
3629
3630                <calendar type="Gregorian" timestep="1h" />
3631\end_layout
3632
3633\begin_layout Plain Layout
3634
3635\end_layout
3636
3637\begin_layout Plain Layout
3638
3639                <grid_definition>
3640\end_layout
3641
3642\begin_layout Plain Layout
3643
3644                        <grid id="grid_A"><!-- Definition ommited --></grid>
3645\end_layout
3646
3647\begin_layout Plain Layout
3648
3649                </grid_definition>
3650\end_layout
3651
3652\begin_layout Plain Layout
3653
3654\end_layout
3655
3656\begin_layout Plain Layout
3657
3658                <field_definition>
3659\end_layout
3660
3661\begin_layout Plain Layout
3662
3663                <field id="field_A" name="field_A" grid_ref="grid_A" operation="average
3664" />
3665\end_layout
3666
3667\begin_layout Plain Layout
3668
3669                </field_definition>
3670\end_layout
3671
3672\begin_layout Plain Layout
3673
3674\end_layout
3675
3676\begin_layout Plain Layout
3677
3678                <file_definition>
3679\end_layout
3680
3681\begin_layout Plain Layout
3682
3683                        <file name="output_1d" output_freq="1d">
3684\end_layout
3685
3686\begin_layout Plain Layout
3687
3688                        <field field_ref="field_A" />
3689\end_layout
3690
3691\begin_layout Plain Layout
3692
3693                        </file>
3694\end_layout
3695
3696\begin_layout Plain Layout
3697
3698                        <file name="output_1mo" output_freq="1mo">
3699\end_layout
3700
3701\begin_layout Plain Layout
3702
3703                        <field field_ref="field_A" />
3704\end_layout
3705
3706\begin_layout Plain Layout
3707
3708                        </file>
3709\end_layout
3710
3711\begin_layout Plain Layout
3712
3713                </file_definition>
3714\end_layout
3715
3716\begin_layout Plain Layout
3717
3718        </context>
3719\end_layout
3720
3721\begin_layout Plain Layout
3722
3723</simulation>
3724\end_layout
3725
3726\end_inset
3727
3728
3729\end_layout
3730
3731\begin_layout Section
3732How to use arithmetic operations
3733\end_layout
3734
3735\begin_layout Standard
3736Since XIOS aims to reduce as much as possible the need for post-processing,
3737 it can apply some arithmetic operations on the data it handles (regardless
3738 of its provenance).
3739\begin_inset Newline newline
3740\end_inset
3741
3742
3743\begin_inset Newline newline
3744\end_inset
3745
3746All usual operators (+, -, *, /, ^, that is addition, subtraction, multiplicatio
3747n, division and exponentiation) and some common functions (like cos, sin,
3748 tan, exp, log, log10, sqrt) are supported.
3749\begin_inset Newline newline
3750\end_inset
3751
3752
3753\begin_inset Newline newline
3754\end_inset
3755
3756The following example shows how to use arithmetic operations:
3757\begin_inset listings
3758lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3759inline false
3760status open
3761
3762\begin_layout Plain Layout
3763
3764<?xml version="1.0"?>
3765\end_layout
3766
3767\begin_layout Plain Layout
3768
3769<simulation>
3770\end_layout
3771
3772\begin_layout Plain Layout
3773
3774        <context id="test">
3775\end_layout
3776
3777\begin_layout Plain Layout
3778
3779                <calendar type="Gregorian" timestep="1h" />
3780\end_layout
3781
3782\begin_layout Plain Layout
3783
3784\end_layout
3785
3786\begin_layout Plain Layout
3787
3788                <grid_definition>
3789\end_layout
3790
3791\begin_layout Plain Layout
3792
3793                        <grid id="grid_A"><!-- Definition ommited --></grid>
3794\end_layout
3795
3796\begin_layout Plain Layout
3797
3798                </grid_definition>
3799\end_layout
3800
3801\begin_layout Plain Layout
3802
3803\end_layout
3804
3805\begin_layout Plain Layout
3806
3807                <field_definition>
3808\end_layout
3809
3810\begin_layout Plain Layout
3811
3812                <field id="field_A" grid_ref="grid_A" operation="average" />
3813\end_layout
3814
3815\begin_layout Plain Layout
3816
3817                </field_definition>
3818\end_layout
3819
3820\begin_layout Plain Layout
3821
3822\end_layout
3823
3824\begin_layout Plain Layout
3825
3826                <file_definition>
3827\end_layout
3828
3829\begin_layout Plain Layout
3830
3831                        <file name="output" output_freq="1d">
3832\end_layout
3833
3834\begin_layout Plain Layout
3835
3836                        <field id="field_B" field_ref="field_A">field_A + 273.15</field>
3837\end_layout
3838
3839\begin_layout Plain Layout
3840
3841                        <field id="field_C" field_ref="field_A">log10(field_B)</field>
3842\end_layout
3843
3844\begin_layout Plain Layout
3845
3846                        </file>
3847\end_layout
3848
3849\begin_layout Plain Layout
3850
3851                </file_definition>
3852\end_layout
3853
3854\begin_layout Plain Layout
3855
3856        </context>
3857\end_layout
3858
3859\begin_layout Plain Layout
3860
3861</simulation>
3862\end_layout
3863
3864\end_inset
3865
3866With this configuration, only one call to
3867\begin_inset Flex Code
3868status open
3869
3870\begin_layout Plain Layout
3871xios_send_field(
3872\begin_inset Quotes eld
3873\end_inset
3874
3875field_A
3876\begin_inset Quotes erd
3877\end_inset
3878
3879, field_A)
3880\end_layout
3881
3882\end_inset
3883
3884 is needed.
3885 In this example
3886\series bold
3887field_ref
3888\series default
3889 is used only to inherit the attributes from
3890\begin_inset Quotes eld
3891\end_inset
3892
3893field_A
3894\begin_inset Quotes erd
3895\end_inset
3896
3897, the instant values are not inherited since an expression has been given
3898 for
3899\begin_inset Quotes eld
3900\end_inset
3901
3902field_B
3903\begin_inset Quotes erd
3904\end_inset
3905
3906 and
3907\begin_inset Quotes eld
3908\end_inset
3909
3910field_C
3911\begin_inset Quotes erd
3912\end_inset
3913
3914.
3915 Note that it is possible to use fields obtained from an expression in another
3916 expression, thus the expression of
3917\begin_inset Quotes eld
3918\end_inset
3919
3920field_C
3921\begin_inset Quotes erd
3922\end_inset
3923
3924 is equivalent to
3925\begin_inset Flex Code
3926status open
3927
3928\begin_layout Plain Layout
3929log10(field_A + 273.15)
3930\end_layout
3931
3932\end_inset
3933
3934.
3935\begin_inset Newline newline
3936\end_inset
3937
3938
3939\begin_inset Newline newline
3940\end_inset
3941
3942The special keyword
3943\series bold
3944this
3945\series default
3946 can be used in an expression to refer to the instant data received from
3947 the model by the current field.
3948 For example, the previous configuration file could be rewritten as follow:
3949\begin_inset listings
3950lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
3951inline false
3952status open
3953
3954\begin_layout Plain Layout
3955
3956<?xml version="1.0"?>
3957\end_layout
3958
3959\begin_layout Plain Layout
3960
3961<simulation>
3962\end_layout
3963
3964\begin_layout Plain Layout
3965
3966        <context id="test">
3967\end_layout
3968
3969\begin_layout Plain Layout
3970
3971                <calendar type="Gregorian" timestep="1h" />
3972\end_layout
3973
3974\begin_layout Plain Layout
3975
3976\end_layout
3977
3978\begin_layout Plain Layout
3979
3980                <grid_definition>
3981\end_layout
3982
3983\begin_layout Plain Layout
3984
3985                        <grid id="grid_A"><!-- Definition ommited --></grid>
3986\end_layout
3987
3988\begin_layout Plain Layout
3989
3990                </grid_definition>
3991\end_layout
3992
3993\begin_layout Plain Layout
3994
3995\end_layout
3996
3997\begin_layout Plain Layout
3998
3999                <file_definition>
4000\end_layout
4001
4002\begin_layout Plain Layout
4003
4004                        <file name="output" output_freq="1d">
4005\end_layout
4006
4007\begin_layout Plain Layout
4008
4009                        <field id="field_B" grid_ref="grid_A" operation="average">this
4010 + 273.15</field>
4011\end_layout
4012
4013\begin_layout Plain Layout
4014
4015                        <field id="field_C" field_ref="field_B">log10(field_B)</field>
4016\end_layout
4017
4018\begin_layout Plain Layout
4019
4020                        </file>
4021\end_layout
4022
4023\begin_layout Plain Layout
4024
4025                </file_definition>
4026\end_layout
4027
4028\begin_layout Plain Layout
4029
4030        </context>
4031\end_layout
4032
4033\begin_layout Plain Layout
4034
4035</simulation>
4036\end_layout
4037
4038\end_inset
4039
4040and the Fortran call would be replaced by
4041\begin_inset Flex Code
4042status open
4043
4044\begin_layout Plain Layout
4045xios_send_field(
4046\begin_inset Quotes eld
4047\end_inset
4048
4049field_B
4050\begin_inset Quotes erd
4051\end_inset
4052
4053, field_A)
4054\end_layout
4055
4056\end_inset
4057
4058.
4059\end_layout
4060
4061\begin_layout Section
4062How to chain multiple temporal operations
4063\end_layout
4064
4065\begin_layout Standard
4066By default, all field names appearing in an expression refer to the instant
4067 data of those fields.
4068 To refer to the result of a temporal operation, the field name must be
4069 prefixed with
4070\begin_inset Quotes eld
4071\end_inset
4072
4073@
4074\begin_inset Quotes erd
4075\end_inset
4076
4077.
4078\begin_inset Newline newline
4079\end_inset
4080
4081
4082\begin_inset Newline newline
4083\end_inset
4084
4085This feature allows to chain multiple temporal operations as illustrated
4086 bellow:
4087\end_layout
4088
4089\begin_layout Standard
4090\begin_inset listings
4091lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4092inline false
4093status open
4094
4095\begin_layout Plain Layout
4096
4097<?xml version="1.0"?>
4098\end_layout
4099
4100\begin_layout Plain Layout
4101
4102<simulation>
4103\end_layout
4104
4105\begin_layout Plain Layout
4106
4107        <context id="test">
4108\end_layout
4109
4110\begin_layout Plain Layout
4111
4112                <calendar type="Gregorian" timestep="1h" />
4113\end_layout
4114
4115\begin_layout Plain Layout
4116
4117\end_layout
4118
4119\begin_layout Plain Layout
4120
4121                <grid_definition>
4122\end_layout
4123
4124\begin_layout Plain Layout
4125
4126                        <grid id="grid_A"><!-- Definition ommited --></grid>
4127\end_layout
4128
4129\begin_layout Plain Layout
4130
4131                </grid_definition>
4132\end_layout
4133
4134\begin_layout Plain Layout
4135
4136\end_layout
4137
4138\begin_layout Plain Layout
4139
4140                <field_definition>
4141\end_layout
4142
4143\begin_layout Plain Layout
4144
4145                <field id="field_A" grid_ref="grid_A" operation="average" />
4146\end_layout
4147
4148\begin_layout Plain Layout
4149
4150                </field_definition>
4151\end_layout
4152
4153\begin_layout Plain Layout
4154
4155\end_layout
4156
4157\begin_layout Plain Layout
4158
4159                <file_definition>
4160\end_layout
4161
4162\begin_layout Plain Layout
4163
4164                        <file name="output" output_freq="7d">
4165\end_layout
4166
4167\begin_layout Plain Layout
4168
4169                        <field name="field_A_min_of_average" grid_ref="grid_A" operation="min"
4170 freq_op="1d">@field_A</field>
4171\end_layout
4172
4173\begin_layout Plain Layout
4174
4175                        </file>
4176\end_layout
4177
4178\begin_layout Plain Layout
4179
4180                </file_definition>
4181\end_layout
4182
4183\begin_layout Plain Layout
4184
4185        </context>
4186\end_layout
4187
4188\begin_layout Plain Layout
4189
4190</simulation>
4191\end_layout
4192
4193\end_inset
4194
4195This example shows how to compute the minimum on 7 days of the daily average
4196 of
4197\begin_inset Quotes eld
4198\end_inset
4199
4200field_A
4201\begin_inset Quotes erd
4202\end_inset
4203
4204.
4205 In this context, the
4206\series bold
4207freq_op
4208\series default
4209 attribute defines the period of the temporal operation for all fields pointed
4210 with the
4211\begin_inset Quotes eld
4212\end_inset
4213
4214@
4215\begin_inset Quotes erd
4216\end_inset
4217
4218 operator in the expression.
4219\begin_inset Newline newline
4220\end_inset
4221
4222
4223\begin_inset Newline newline
4224\end_inset
4225
4226Another use of this feature is to do arithmetic operations on the result
4227 of temporal operations.
4228  The following configuration file for example shows how to output the standard
4229 deviation for a field on a one day period:
4230\begin_inset listings
4231lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4232inline false
4233status open
4234
4235\begin_layout Plain Layout
4236
4237<?xml version="1.0"?>
4238\end_layout
4239
4240\begin_layout Plain Layout
4241
4242<simulation>
4243\end_layout
4244
4245\begin_layout Plain Layout
4246
4247        <context id="test">
4248\end_layout
4249
4250\begin_layout Plain Layout
4251
4252                <calendar type="Gregorian" timestep="1h" />
4253\end_layout
4254
4255\begin_layout Plain Layout
4256
4257\end_layout
4258
4259\begin_layout Plain Layout
4260
4261                <grid_definition>
4262\end_layout
4263
4264\begin_layout Plain Layout
4265
4266                        <grid id="grid_A"><!-- Definition ommited --></grid>
4267\end_layout
4268
4269\begin_layout Plain Layout
4270
4271                </grid_definition>
4272\end_layout
4273
4274\begin_layout Plain Layout
4275
4276\end_layout
4277
4278\begin_layout Plain Layout
4279
4280                <field_definition>
4281\end_layout
4282
4283\begin_layout Plain Layout
4284
4285                <field id="field_A" grid_ref="grid_A" operation="average" />
4286\end_layout
4287
4288\begin_layout Plain Layout
4289
4290                <field id="field_A_square" field_ref="grid_A">field_A * field_A</field>
4291\end_layout
4292
4293\begin_layout Plain Layout
4294
4295                </field_definition>
4296\end_layout
4297
4298\begin_layout Plain Layout
4299
4300\end_layout
4301
4302\begin_layout Plain Layout
4303
4304                <file_definition>
4305\end_layout
4306
4307\begin_layout Plain Layout
4308
4309                        <file name="output" output_freq="1d">
4310\end_layout
4311
4312\begin_layout Plain Layout
4313
4314                        <field name="field_A_std_dev" grid_ref="grid_A" operation="instant"
4315 freq_op="1d">sqrt(@field_A_square - @field_A^2)</field>
4316\end_layout
4317
4318\begin_layout Plain Layout
4319
4320                        </file>
4321\end_layout
4322
4323\begin_layout Plain Layout
4324
4325                </file_definition>
4326\end_layout
4327
4328\begin_layout Plain Layout
4329
4330        </context>
4331\end_layout
4332
4333\begin_layout Plain Layout
4334
4335</simulation>
4336\end_layout
4337
4338\end_inset
4339
4340Note that since an
4341\series bold
4342\emph on
4343
4344\begin_inset Quotes eld
4345\end_inset
4346
4347instant
4348\begin_inset Quotes erd
4349\end_inset
4350
4351
4352\series default
4353 
4354\emph default
4355operation is used,
4356\series bold
4357freq_op
4358\series default
4359 and
4360\series bold
4361output_freq
4362\series default
4363 are identical in this scenario.
4364\end_layout
4365
4366\begin_layout Section
4367How to access the data of a field
4368\end_layout
4369
4370\begin_layout Standard
4371In order not to waste memory, the instant data of a field can be read from
4372 the model only if:
4373\end_layout
4374
4375\begin_layout Itemize
4376it is part of a file whose attribute
4377\series bold
4378mode
4379\series default
4380 is
4381\series bold
4382\emph on
4383
4384\begin_inset Quotes eld
4385\end_inset
4386
4387read
4388\begin_inset Quotes erd
4389\end_inset
4390
4391
4392\end_layout
4393
4394\begin_layout Itemize
4395or its attribute
4396\series bold
4397read_access
4398\series default
4399 is set to
4400\series bold
4401\emph on
4402
4403\begin_inset Quotes eld
4404\end_inset
4405
4406true
4407\begin_inset Quotes erd
4408\end_inset
4409
4410
4411\series default
4412\emph default
4413.
4414\end_layout
4415
4416\begin_layout Standard
4417In any other case, trying to access the field data would cause an error.
4418\begin_inset Newline newline
4419\end_inset
4420
4421
4422\begin_inset Newline newline
4423\end_inset
4424
4425The following configuration file:
4426\begin_inset listings
4427lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4428inline false
4429status open
4430
4431\begin_layout Plain Layout
4432
4433<?xml version="1.0"?>
4434\end_layout
4435
4436\begin_layout Plain Layout
4437
4438<simulation>
4439\end_layout
4440
4441\begin_layout Plain Layout
4442
4443        <context id="test">
4444\end_layout
4445
4446\begin_layout Plain Layout
4447
4448                <calendar type="Gregorian" timestep="1h" />
4449\end_layout
4450
4451\begin_layout Plain Layout
4452
4453\end_layout
4454
4455\begin_layout Plain Layout
4456
4457                <grid_definition>
4458\end_layout
4459
4460\begin_layout Plain Layout
4461
4462                        <grid id="grid_A"><!-- Definition ommited --></grid>
4463\end_layout
4464
4465\begin_layout Plain Layout
4466
4467                </grid_definition>
4468\end_layout
4469
4470\begin_layout Plain Layout
4471
4472\end_layout
4473
4474\begin_layout Plain Layout
4475
4476                <file_definition>
4477\end_layout
4478
4479\begin_layout Plain Layout
4480
4481                        <file name="input" output_freq="1ts">
4482\end_layout
4483
4484\begin_layout Plain Layout
4485
4486                        <field id="field_A" grid_ref="grid_A" operation="instant" />
4487\end_layout
4488
4489\begin_layout Plain Layout
4490
4491                        </file>
4492\end_layout
4493
4494\begin_layout Plain Layout
4495
4496                </file_definition>
4497\end_layout
4498
4499\begin_layout Plain Layout
4500
4501        </context>
4502\end_layout
4503
4504\begin_layout Plain Layout
4505
4506</simulation>
4507\end_layout
4508
4509\end_inset
4510
4511can be used with this Fortran code:
4512\end_layout
4513
4514\begin_layout Standard
4515\begin_inset listings
4516lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4517inline false
4518status open
4519
4520\begin_layout Plain Layout
4521
4522DO ts=1,numberOfTimestep
4523\end_layout
4524
4525\begin_layout Plain Layout
4526
4527        ! Get field_A for current timestep
4528\end_layout
4529
4530\begin_layout Plain Layout
4531
4532        CALL xios_recv_field("field_A", field_A) ! field_A must be an allocated
4533 array with the right size
4534\end_layout
4535
4536\begin_layout Plain Layout
4537
4538        ! Do useful things...
4539\end_layout
4540
4541\begin_layout Plain Layout
4542
4543        ! Inform XIOS of the current timestep
4544\end_layout
4545
4546\begin_layout Plain Layout
4547
4548        CALL xios_update_calendar(ts)
4549\end_layout
4550
4551\begin_layout Plain Layout
4552
4553ENDDO
4554\end_layout
4555
4556\end_inset
4557
4558The call to
4559\begin_inset Flex Code
4560status open
4561
4562\begin_layout Plain Layout
4563xios_recv_field
4564\end_layout
4565
4566\end_inset
4567
4568 might block for a while if the data was not yet received from the server(s)
4569 but it should not happen too often thanks to the prefetching done by XIOS.
4570\begin_inset Newline newline
4571\end_inset
4572
4573
4574\begin_inset Newline newline
4575\end_inset
4576
4577Since the
4578\series bold
4579read_access
4580\series default
4581 attribute allows to the access fields which depend directly on data from
4582 the model, you must be very careful with the order of the
4583\begin_inset Flex Code
4584status open
4585
4586\begin_layout Plain Layout
4587xios_send_field
4588\end_layout
4589
4590\end_inset
4591
4592 and
4593\begin_inset Flex Code
4594status open
4595
4596\begin_layout Plain Layout
4597xios_recv_field
4598\end_layout
4599
4600\end_inset
4601
4602 calls.
4603 For example, consider the following configuration file (just a simple example
4604 as in practice it does not make much sense to use it):
4605\begin_inset listings
4606lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4607inline false
4608status open
4609
4610\begin_layout Plain Layout
4611
4612<?xml version="1.0"?>
4613\end_layout
4614
4615\begin_layout Plain Layout
4616
4617<simulation>
4618\end_layout
4619
4620\begin_layout Plain Layout
4621
4622        <context id="test">
4623\end_layout
4624
4625\begin_layout Plain Layout
4626
4627                <calendar type="Gregorian" timestep="1h" />
4628\end_layout
4629
4630\begin_layout Plain Layout
4631
4632\end_layout
4633
4634\begin_layout Plain Layout
4635
4636                <grid_definition>
4637\end_layout
4638
4639\begin_layout Plain Layout
4640
4641                        <grid id="grid_A"><!-- Definition ommited --></grid>
4642\end_layout
4643
4644\begin_layout Plain Layout
4645
4646                </grid_definition>
4647\end_layout
4648
4649\begin_layout Plain Layout
4650
4651\end_layout
4652
4653\begin_layout Plain Layout
4654
4655                <field_definition>
4656\end_layout
4657
4658\begin_layout Plain Layout
4659
4660                <field id="field_A" grid_ref="grid_A" operation="instant" />
4661\end_layout
4662
4663\begin_layout Plain Layout
4664
4665                </field_definition>
4666\end_layout
4667
4668\begin_layout Plain Layout
4669
4670\end_layout
4671
4672\begin_layout Plain Layout
4673
4674                <file_definition>
4675\end_layout
4676
4677\begin_layout Plain Layout
4678
4679                        <file name="output" output_freq="1ts">
4680\end_layout
4681
4682\begin_layout Plain Layout
4683
4684                        <field id="field_B" grid_ref="grid_A" operation="instant" read_access=
4685"true">field_A / 42</field>
4686\end_layout
4687
4688\begin_layout Plain Layout
4689
4690                        </file>
4691\end_layout
4692
4693\begin_layout Plain Layout
4694
4695                </file_definition>
4696\end_layout
4697
4698\begin_layout Plain Layout
4699
4700        </context>
4701\end_layout
4702
4703\begin_layout Plain Layout
4704
4705</simulation>
4706\end_layout
4707
4708\end_inset
4709
4710If you call
4711\begin_inset Flex Code
4712status open
4713
4714\begin_layout Plain Layout
4715xios_recv_field(
4716\begin_inset Quotes eld
4717\end_inset
4718
4719field_B
4720\begin_inset Quotes erd
4721\end_inset
4722
4723, field_B)
4724\end_layout
4725
4726\end_inset
4727
4728 before
4729\begin_inset Flex Code
4730status open
4731
4732\begin_layout Plain Layout
4733xios_send_field(
4734\begin_inset Quotes eld
4735\end_inset
4736
4737field_A
4738\begin_inset Quotes erd
4739\end_inset
4740
4741, field_A)
4742\end_layout
4743
4744\end_inset
4745
4746, the requested data will never be available and a deadlock could occur.
4747 In practice, XIOS will detect the problem and throw an error.
4748\end_layout
4749
4750\begin_layout Section
4751How to reduce the size of an output file
4752\end_layout
4753
4754\begin_layout Standard
4755The size of the output files can sometimes become a problem.
4756 XIOS provides some features which may help to reduce the size of the output
4757 files losslessly.
4758\begin_inset Newline newline
4759\end_inset
4760
4761
4762\begin_inset Newline newline
4763\end_inset
4764
4765The first solution is to use the compression feature provided by HDF5 which
4766 allows a field to be compressed using gzip.
4767 Since it depends directly on HDF5, this feature works only when the NetCDF-4
4768 format is used.
4769 Since HDF5 does not (yet) support compression for parallel output, one
4770 has to use two server-level functionality (see Sec.
4771 
4772\begin_inset CommandInset ref
4773LatexCommand ref
4774reference "sec:Launching-secondary-server"
4775
4776\end_inset
4777
4778) or to engage the
4779\series bold
4780\emph on
4781
4782\begin_inset Quotes eld
4783\end_inset
4784
4785multiple_file
4786\begin_inset Quotes erd
4787\end_inset
4788
4789
4790\series default
4791\emph default
4792 mode.
4793\begin_inset Newline newline
4794\end_inset
4795
4796
4797\begin_inset Newline newline
4798\end_inset
4799
4800To enable the gzip compression of a field, you need to set the
4801\series bold
4802compression_level
4803\series default
4804 attribute to any integer between 1 and 9 (by default this attribute is
4805 set to 0 which means that compression is disabled).
4806 Using an higher compression level should improve the compression ratio
4807 at the cost of using more processing power.
4808 Generally using a compression level of 2 should be a good trade-off.
4809\begin_inset Newline newline
4810\end_inset
4811
4812
4813\begin_inset Newline newline
4814\end_inset
4815
4816The following example illustrates the use of the gzip compression:
4817\begin_inset listings
4818lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4819inline false
4820status open
4821
4822\begin_layout Plain Layout
4823
4824<?xml version="1.0"?>
4825\end_layout
4826
4827\begin_layout Plain Layout
4828
4829<simulation>
4830\end_layout
4831
4832\begin_layout Plain Layout
4833
4834        <context id="test">
4835\end_layout
4836
4837\begin_layout Plain Layout
4838
4839                <calendar type="Gregorian" timestep="1h" />
4840\end_layout
4841
4842\begin_layout Plain Layout
4843
4844\end_layout
4845
4846\begin_layout Plain Layout
4847
4848                <grid_definition>
4849\end_layout
4850
4851\begin_layout Plain Layout
4852
4853                        <grid id="grid_A"><!-- Definition ommited --></grid>
4854\end_layout
4855
4856\begin_layout Plain Layout
4857
4858                </grid_definition>
4859\end_layout
4860
4861\begin_layout Plain Layout
4862
4863\end_layout
4864
4865\begin_layout Plain Layout
4866
4867                <file_definition>
4868\end_layout
4869
4870\begin_layout Plain Layout
4871
4872                        <file name="output" output_freq="1ts" compression_level="2">
4873\end_layout
4874
4875\begin_layout Plain Layout
4876
4877                        <field id="field_A" grid_ref="grid_A" operation="average" compression_
4878level="4" />
4879\end_layout
4880
4881\begin_layout Plain Layout
4882
4883                        <field id="field_B" grid_ref="grid_A" operation="average" compression_
4884level="0" />
4885\end_layout
4886
4887\begin_layout Plain Layout
4888
4889                        <field id="field_C" grid_ref="grid_A" operation="average" />
4890\end_layout
4891
4892\begin_layout Plain Layout
4893
4894                        </file>
4895\end_layout
4896
4897\begin_layout Plain Layout
4898
4899                </file_definition>
4900\end_layout
4901
4902\begin_layout Plain Layout
4903
4904        </context>
4905\end_layout
4906
4907\begin_layout Plain Layout
4908
4909</simulation>
4910\end_layout
4911
4912\end_inset
4913
4914Note that the
4915\series bold
4916compression_level
4917\series default
4918 attribute can also be set at a file level, in this case it is inherited
4919 by all fields of the file unless they explicitly override the attribute.
4920\begin_inset Newline newline
4921\end_inset
4922
4923
4924\begin_inset Newline newline
4925\end_inset
4926
4927The second solution is available only if you are using a grid with masked
4928 values.
4929 In this case, you can choose to output the indexed grid instead of the
4930 full grid by setting the
4931\series bold
4932indexed_output
4933\series default
4934 attribute to
4935\series bold
4936\emph on
4937
4938\begin_inset Quotes eld
4939\end_inset
4940
4941true
4942\begin_inset Quotes erd
4943\end_inset
4944
4945
4946\series default
4947\emph default
4948.
4949 Missing values are then omitted and extra arrays are outputted so that
4950 the translation from the
4951\begin_inset Quotes eld
4952\end_inset
4953
4954compressed
4955\begin_inset Quotes erd
4956\end_inset
4957
4958 indexes to the true indexes can be done.
4959 Due to those arrays of indexes, indexed output should be considered only
4960 if there is enough masked values.
4961 For more details about this feature, please refer to section 8.2
4962\begin_inset Quotes eld
4963\end_inset
4964
4965Compression by Gathering
4966\begin_inset Quotes erd
4967\end_inset
4968
4969 of the Climate and Forecast (CF) Convention.
4970\end_layout
4971
4972\begin_layout Standard
4973\begin_inset CommandInset include
4974LatexCommand include
4975filename "inputs/user/Grid.lyx"
4976
4977\end_inset
4978
4979
4980\end_layout
4981
4982\begin_layout Standard
4983\begin_inset CommandInset include
4984LatexCommand include
4985filename "inputs/user/Domain.lyx"
4986
4987\end_inset
4988
4989
4990\end_layout
4991
4992\begin_layout Standard
4993\begin_inset CommandInset include
4994LatexCommand include
4995filename "inputs/user/Axis.lyx"
4996
4997\end_inset
4998
4999
5000\end_layout
5001
5002\begin_layout Chapter
5003XIOS parameterization
5004\end_layout
5005
5006\begin_layout Standard
5007Some of XIOS behaviors can be configured using options.
5008 Those options must be expressed as variables in a specific context whose
5009 
5010\series bold
5011id
5012\series default
5013 must be
5014\series bold
5015\emph on
5016
5017\begin_inset Quotes eld
5018\end_inset
5019
5020xios
5021\begin_inset Quotes erd
5022\end_inset
5023
5024
5025\series default
5026\emph default
5027 as shown below.
5028\end_layout
5029
5030\begin_layout Standard
5031\begin_inset listings
5032lstparams "breaklines=true,frame=tb,language=XML,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}},tabsize=2"
5033inline false
5034status open
5035
5036\begin_layout Plain Layout
5037
5038<?xml version="1.0"?>
5039\end_layout
5040
5041\begin_layout Plain Layout
5042
5043<simulation>
5044\end_layout
5045
5046\begin_layout Plain Layout
5047
5048        <!-- Actual context(s) used by the simulation ommited -->
5049\end_layout
5050
5051\begin_layout Plain Layout
5052
5053\end_layout
5054
5055\begin_layout Plain Layout
5056
5057        <context id="xios">
5058\end_layout
5059
5060\begin_layout Plain Layout
5061
5062                <variable_definition>
5063\end_layout
5064
5065\begin_layout Plain Layout
5066
5067                        <variable id="option_name" type="option_type">option_value</variable>
5068\end_layout
5069
5070\begin_layout Plain Layout
5071
5072                </variable_definition>
5073\end_layout
5074
5075\begin_layout Plain Layout
5076
5077        </context>
5078\end_layout
5079
5080\begin_layout Plain Layout
5081
5082</simulation>
5083\end_layout
5084
5085\end_inset
5086
5087
5088\end_layout
5089
5090\begin_layout Section
5091Launching secondary server
5092\begin_inset CommandInset label
5093LatexCommand label
5094name "sec:Launching-secondary-server"
5095
5096\end_inset
5097
5098
5099\end_layout
5100
5101\begin_layout Standard
5102To improve I/O performance and to be able to use HDF5 compression with the
5103 
5104\series bold
5105\emph on
5106
5107\begin_inset Quotes eld
5108\end_inset
5109
5110multiple_file
5111\begin_inset Quotes erd
5112\end_inset
5113
5114
5115\series default
5116\emph default
5117 mode, it is possible to separate servers into two levels: intermediaries
5118 (level one) and writers (level two).
5119 A single MPI communicator will be created for the intermediaries, while
5120 multiple communicators will be created for the writers according to the
5121 number of
5122\begin_inset Quotes eld
5123\end_inset
5124
5125pools
5126\begin_inset Quotes erd
5127\end_inset
5128
5129 which can be set by a user.
5130 Level-one servers will receive data from clients and will redistribute
5131 it to be sent to pools of level-two servers whilst level-two servers will
5132 do the I/O (important: for now level-two servers only do writing data).
5133 Secondary servers can be launched by means of three parameters:
5134\end_layout
5135
5136\begin_layout Itemize
5137
5138\series bold
5139using_server2
5140\series default
5141 (type:
5142\series bold
5143bool
5144\series default
5145) activates the secondary server
5146\end_layout
5147
5148\begin_layout Itemize
5149
5150\series bold
5151ratio_server2
5152\series default
5153 (type:
5154\series bold
5155int
5156\series default
5157) defines the percentage of servers that will be dedicated to level two.
5158 The parameter can take value from 0 to 100 with the default value of 50%.
5159 In case if the requested number of level-two servers is not valid (for
5160 example, zero or equal to the total number of servers), XIOS will run in
5161 its classical server mode with one server level.
5162\end_layout
5163
5164\begin_layout Itemize
5165
5166\series bold
5167number_pools_server2
5168\series default
5169(type:
5170\series bold
5171int
5172\series default
5173) sets the number of server-two pools (i.e.
5174 MPI communicators on level two).
5175 By default the number of pools is equal to the number of level-two servers,
5176 thus permitting one process per communicator.
5177\end_layout
5178
5179\begin_layout Standard
5180Shown in Fig.
5181 
5182\begin_inset CommandInset ref
5183LatexCommand ref
5184reference "Fig:server2"
5185
5186\end_inset
5187
5188 is the two-level server structure for the following definitions:
5189\end_layout
5190
5191\begin_layout Standard
5192\begin_inset listings
5193lstparams "breaklines=true,frame=tb,language=XML,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}},tabsize=2"
5194inline false
5195status open
5196
5197\begin_layout Plain Layout
5198
5199<context id="xios">    
5200\end_layout
5201
5202\begin_layout Plain Layout
5203
5204...
5205       
5206\end_layout
5207
5208\begin_layout Plain Layout
5209
5210        <variable id="using_server2" type="bool">true</variable>
5211\end_layout
5212
5213\begin_layout Plain Layout
5214
5215        <variable id="ratio_server2" type="int">75</variable>         
5216\end_layout
5217
5218\begin_layout Plain Layout
5219
5220        <variable id="number_pools_server2" type="int">3</variable>         
5221\end_layout
5222
5223\begin_layout Plain Layout
5224
5225...
5226\end_layout
5227
5228\begin_layout Plain Layout
5229
5230</context>
5231\end_layout
5232
5233\end_inset
5234
5235
5236\end_layout
5237
5238\begin_layout Standard
5239\begin_inset Float figure
5240placement H
5241wide false
5242sideways false
5243status open
5244
5245\begin_layout Plain Layout
5246\begin_inset Graphics
5247        filename inputs/images/Server2.pdf
5248
5249\end_inset
5250
5251
5252\end_layout
5253
5254\begin_layout Plain Layout
5255\begin_inset Caption Standard
5256
5257\begin_layout Plain Layout
5258Two levels of servers for the total number of servers of 8 and ratio_server2=75%.
5259 The number of level-two servers is
5260\begin_inset Formula $8\times\text{ratio\_server2}=6$
5261\end_inset
5262
5263 and, thus, the remaining 2 servers are of level one.
5264 
5265\end_layout
5266
5267\end_inset
5268
5269
5270\begin_inset CommandInset label
5271LatexCommand label
5272name "Fig:server2"
5273
5274\end_inset
5275
5276
5277\end_layout
5278
5279\end_inset
5280
5281
5282\end_layout
5283
5284\begin_layout Standard
5285Note that with one server per pool, the I/O is actually sequential and thus
5286 the use of HDF5 compression is possible.
5287 
5288\end_layout
5289
5290\begin_layout Standard
5291By default file distribution among server-two pools is optimized for bandwidth.
5292 An alternative way of distributing files is possible in order to minimize
5293 memory consumption by level-two servers.
5294 For this, two additional parameters should be specified:
5295\end_layout
5296
5297\begin_layout Itemize
5298
5299\series bold
5300server2_dist_file_memory
5301\series default
5302 (type:
5303\series bold
5304bool
5305\series default
5306) activates memory optimization.
5307\end_layout
5308
5309\begin_layout Itemize
5310
5311\series bold
5312server2_dist_file_memory_ratio
5313\series default
5314 (type:
5315\series bold
5316double
5317\series default
5318) (optional) takes value from 0 (memory optimization) to 1 (bandwidth optimizati
5319on).
5320 The default value is 0.5.
5321\end_layout
5322
5323\begin_layout Section
5324Buffer related options
5325\end_layout
5326
5327\begin_layout Standard
5328By default, XIOS tries to guess the required buffers sizes to ensure efficient
5329 client-server communications.
5330 However it might sometimes be useful to tweak the buffers sizes so XIOS
5331 provides the following options:
5332\end_layout
5333
5334\begin_layout Itemize
5335
5336\series bold
5337optimal_buffer_size
5338\series default
5339 (type:
5340\series bold
5341string
5342\series default
5343) can be either
5344\series bold
5345\emph on
5346
5347\begin_inset Quotes eld
5348\end_inset
5349
5350memory
5351\begin_inset Quotes erd
5352\end_inset
5353
5354
5355\series default
5356\emph default
5357 or
5358\series bold
5359\emph on
5360
5361\begin_inset Quotes erd
5362\end_inset
5363
5364performance
5365\begin_inset Quotes erd
5366\end_inset
5367
5368
5369\series default
5370\emph default
5371.
5372 When using the
5373\series bold
5374\emph on
5375
5376\begin_inset Quotes eld
5377\end_inset
5378
5379memory
5380\begin_inset Quotes erd
5381\end_inset
5382
5383
5384\series default
5385\emph default
5386 mode, XIOS will try to use buffers as small as possible while still ensuring
5387 that the bigger message will fit.
5388 When using the
5389\series bold
5390\emph on
5391
5392\begin_inset Quotes erd
5393\end_inset
5394
5395performance
5396\begin_inset Quotes erd
5397\end_inset
5398
5399
5400\series default
5401\emph default
5402 mode, XIOS will ensure that all active fields can be buffered without having
5403 to flush the buffers.
5404 This mode is used by default since it allows more asynchronism and thus
5405 better performance at the cost of being quite memory hungry.
5406\end_layout
5407
5408\begin_layout Itemize
5409
5410\series bold
5411minimum_buffer_size
5412\series default
5413 (type:
5414\series bold
5415int
5416\series default
5417) defines the minimum buffer size in bytes (8192 by default).
5418 This value will be used by XIOS only for buffers whose detected size is
5419 smaller than the user defined minimum size.
5420\end_layout
5421
5422\begin_layout Itemize
5423
5424\series bold
5425buffer_size_factor
5426\series default
5427(type:
5428\series bold
5429int
5430\series default
5431) allows to modify the buffers sizes by multiplying the detected sizes by
5432 an user defined factor (
5433\begin_inset Formula $1.0$
5434\end_inset
5435
5436 by default).
5437 For each allocated buffers, the used size is defined as
5438\begin_inset Formula
5439\[
5440{\scriptstyle used\_size\;=\;\min\left(minimum\_buffer\_size,\; detected\_size\;\times\; buffer\_size\_factor\right)}
5441\]
5442
5443\end_inset
5444
5445
5446\end_layout
5447
5448\end_body
5449\end_document
Note: See TracBrowser for help on using the repository browser.