source: XIOS/trunk/doc/XIOS_user_guide.lyx

Last change on this file was 1623, checked in by oabramkina, 3 years ago

Updating reference guide.

File size: 96.6 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_B)
4054\end_layout
4055
4056\end_inset
4057
4058.
4059\end_layout
4060
4061\begin_layout Standard
4062XIOS also provides the means to define an expression in a Fortran code via
4063 the field attribute
4064\begin_inset Quotes eld
4065\end_inset
4066
4067expr
4068\begin_inset Quotes erd
4069\end_inset
4070
4071.
4072 The example above can rewritten as
4073\begin_inset listings
4074lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4075inline false
4076status open
4077
4078\begin_layout Plain Layout
4079
4080<?xml version="1.0"?>
4081\end_layout
4082
4083\begin_layout Plain Layout
4084
4085<simulation>
4086\end_layout
4087
4088\begin_layout Plain Layout
4089
4090        <context id="test">
4091\end_layout
4092
4093\begin_layout Plain Layout
4094
4095                <calendar type="Gregorian" timestep="1h" />
4096\end_layout
4097
4098\begin_layout Plain Layout
4099
4100\end_layout
4101
4102\begin_layout Plain Layout
4103
4104                <grid_definition>
4105\end_layout
4106
4107\begin_layout Plain Layout
4108
4109                        <grid id="grid_A"><!-- Definition ommited --></grid>
4110\end_layout
4111
4112\begin_layout Plain Layout
4113
4114                </grid_definition>
4115\end_layout
4116
4117\begin_layout Plain Layout
4118
4119\end_layout
4120
4121\begin_layout Plain Layout
4122
4123                <file_definition>
4124\end_layout
4125
4126\begin_layout Plain Layout
4127
4128                        <file name="output" output_freq="1d">
4129\end_layout
4130
4131\begin_layout Plain Layout
4132
4133                        <field id="field_B" grid_ref="grid_A" operation="average">
4134\end_layout
4135
4136\begin_layout Plain Layout
4137
4138                        <field id="field_C" field_ref="field_B">
4139\end_layout
4140
4141\begin_layout Plain Layout
4142
4143                        </file>
4144\end_layout
4145
4146\begin_layout Plain Layout
4147
4148                </file_definition>
4149\end_layout
4150
4151\begin_layout Plain Layout
4152
4153        </context>
4154\end_layout
4155
4156\begin_layout Plain Layout
4157
4158</simulation>
4159\end_layout
4160
4161\end_inset
4162
4163
4164\end_layout
4165
4166\begin_layout Standard
4167while the two expressions can be specified with the following calls:
4168\begin_inset Flex Code
4169status open
4170
4171\begin_layout Plain Layout
4172xios_set_field_attr(
4173\begin_inset Quotes eld
4174\end_inset
4175
4176field_B
4177\begin_inset Quotes erd
4178\end_inset
4179
4180, expr=
4181\begin_inset Quotes erd
4182\end_inset
4183
4184@this + 273.15
4185\begin_inset Quotes erd
4186\end_inset
4187
4188
4189\end_layout
4190
4191\end_inset
4192
4193 and
4194\begin_inset Flex Code
4195status open
4196
4197\begin_layout Plain Layout
4198xios_set_field_attr(
4199\begin_inset Quotes eld
4200\end_inset
4201
4202field_C
4203\begin_inset Quotes erd
4204\end_inset
4205
4206, expr=
4207\begin_inset Quotes erd
4208\end_inset
4209
4210log10(field_B)
4211\begin_inset Quotes erd
4212\end_inset
4213
4214
4215\end_layout
4216
4217\end_inset
4218
4219.
4220 
4221\end_layout
4222
4223\begin_layout Section
4224How to chain multiple temporal operations
4225\end_layout
4226
4227\begin_layout Standard
4228By default, all field names appearing in an expression refer to the instant
4229 data of those fields.
4230 To refer to the result of a temporal operation, the field name must be
4231 prefixed with
4232\begin_inset Quotes eld
4233\end_inset
4234
4235@
4236\begin_inset Quotes erd
4237\end_inset
4238
4239.
4240\begin_inset Newline newline
4241\end_inset
4242
4243
4244\begin_inset Newline newline
4245\end_inset
4246
4247This feature allows to chain multiple temporal operations as illustrated
4248 bellow:
4249\end_layout
4250
4251\begin_layout Standard
4252\begin_inset listings
4253lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4254inline false
4255status open
4256
4257\begin_layout Plain Layout
4258
4259<?xml version="1.0"?>
4260\end_layout
4261
4262\begin_layout Plain Layout
4263
4264<simulation>
4265\end_layout
4266
4267\begin_layout Plain Layout
4268
4269        <context id="test">
4270\end_layout
4271
4272\begin_layout Plain Layout
4273
4274                <calendar type="Gregorian" timestep="1h" />
4275\end_layout
4276
4277\begin_layout Plain Layout
4278
4279\end_layout
4280
4281\begin_layout Plain Layout
4282
4283                <grid_definition>
4284\end_layout
4285
4286\begin_layout Plain Layout
4287
4288                        <grid id="grid_A"><!-- Definition ommited --></grid>
4289\end_layout
4290
4291\begin_layout Plain Layout
4292
4293                </grid_definition>
4294\end_layout
4295
4296\begin_layout Plain Layout
4297
4298\end_layout
4299
4300\begin_layout Plain Layout
4301
4302                <field_definition>
4303\end_layout
4304
4305\begin_layout Plain Layout
4306
4307                <field id="field_A" grid_ref="grid_A" operation="average" />
4308\end_layout
4309
4310\begin_layout Plain Layout
4311
4312                </field_definition>
4313\end_layout
4314
4315\begin_layout Plain Layout
4316
4317\end_layout
4318
4319\begin_layout Plain Layout
4320
4321                <file_definition>
4322\end_layout
4323
4324\begin_layout Plain Layout
4325
4326                        <file name="output" output_freq="7d">
4327\end_layout
4328
4329\begin_layout Plain Layout
4330
4331                        <field name="field_A_min_of_average" grid_ref="grid_A" operation="min"
4332 freq_op="1d">@field_A</field>
4333\end_layout
4334
4335\begin_layout Plain Layout
4336
4337                        </file>
4338\end_layout
4339
4340\begin_layout Plain Layout
4341
4342                </file_definition>
4343\end_layout
4344
4345\begin_layout Plain Layout
4346
4347        </context>
4348\end_layout
4349
4350\begin_layout Plain Layout
4351
4352</simulation>
4353\end_layout
4354
4355\end_inset
4356
4357This example shows how to compute the minimum on 7 days of the daily average
4358 of
4359\begin_inset Quotes eld
4360\end_inset
4361
4362field_A
4363\begin_inset Quotes erd
4364\end_inset
4365
4366.
4367 In this context, the
4368\series bold
4369freq_op
4370\series default
4371 attribute defines the period of the temporal operation for all fields pointed
4372 with the
4373\begin_inset Quotes eld
4374\end_inset
4375
4376@
4377\begin_inset Quotes erd
4378\end_inset
4379
4380 operator in the expression.
4381\begin_inset Newline newline
4382\end_inset
4383
4384
4385\begin_inset Newline newline
4386\end_inset
4387
4388Another use of this feature is to do arithmetic operations on the result
4389 of temporal operations.
4390  The following configuration file for example shows how to output the standard
4391 deviation for a field on a one day period:
4392\begin_inset listings
4393lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4394inline false
4395status open
4396
4397\begin_layout Plain Layout
4398
4399<?xml version="1.0"?>
4400\end_layout
4401
4402\begin_layout Plain Layout
4403
4404<simulation>
4405\end_layout
4406
4407\begin_layout Plain Layout
4408
4409        <context id="test">
4410\end_layout
4411
4412\begin_layout Plain Layout
4413
4414                <calendar type="Gregorian" timestep="1h" />
4415\end_layout
4416
4417\begin_layout Plain Layout
4418
4419\end_layout
4420
4421\begin_layout Plain Layout
4422
4423                <grid_definition>
4424\end_layout
4425
4426\begin_layout Plain Layout
4427
4428                        <grid id="grid_A"><!-- Definition ommited --></grid>
4429\end_layout
4430
4431\begin_layout Plain Layout
4432
4433                </grid_definition>
4434\end_layout
4435
4436\begin_layout Plain Layout
4437
4438\end_layout
4439
4440\begin_layout Plain Layout
4441
4442                <field_definition>
4443\end_layout
4444
4445\begin_layout Plain Layout
4446
4447                <field id="field_A" grid_ref="grid_A" operation="average" />
4448\end_layout
4449
4450\begin_layout Plain Layout
4451
4452                <field id="field_A_square" field_ref="grid_A">field_A * field_A</field>
4453\end_layout
4454
4455\begin_layout Plain Layout
4456
4457                </field_definition>
4458\end_layout
4459
4460\begin_layout Plain Layout
4461
4462\end_layout
4463
4464\begin_layout Plain Layout
4465
4466                <file_definition>
4467\end_layout
4468
4469\begin_layout Plain Layout
4470
4471                        <file name="output" output_freq="1d">
4472\end_layout
4473
4474\begin_layout Plain Layout
4475
4476                        <field name="field_A_std_dev" grid_ref="grid_A" operation="instant"
4477 freq_op="1d">sqrt(@field_A_square - @field_A^2)</field>
4478\end_layout
4479
4480\begin_layout Plain Layout
4481
4482                        </file>
4483\end_layout
4484
4485\begin_layout Plain Layout
4486
4487                </file_definition>
4488\end_layout
4489
4490\begin_layout Plain Layout
4491
4492        </context>
4493\end_layout
4494
4495\begin_layout Plain Layout
4496
4497</simulation>
4498\end_layout
4499
4500\end_inset
4501
4502Note that since an
4503\series bold
4504\emph on
4505
4506\begin_inset Quotes eld
4507\end_inset
4508
4509instant
4510\begin_inset Quotes erd
4511\end_inset
4512
4513
4514\series default
4515 
4516\emph default
4517operation is used,
4518\series bold
4519freq_op
4520\series default
4521 and
4522\series bold
4523output_freq
4524\series default
4525 are identical in this scenario.
4526\end_layout
4527
4528\begin_layout Section
4529How to access the data of a field
4530\end_layout
4531
4532\begin_layout Standard
4533In order not to waste memory, the instant data of a field can be read from
4534 the model only if:
4535\end_layout
4536
4537\begin_layout Itemize
4538it is part of a file whose attribute
4539\series bold
4540mode
4541\series default
4542 is
4543\series bold
4544\emph on
4545
4546\begin_inset Quotes eld
4547\end_inset
4548
4549read
4550\begin_inset Quotes erd
4551\end_inset
4552
4553
4554\end_layout
4555
4556\begin_layout Itemize
4557or its attribute
4558\series bold
4559read_access
4560\series default
4561 is set to
4562\series bold
4563\emph on
4564
4565\begin_inset Quotes eld
4566\end_inset
4567
4568true
4569\begin_inset Quotes erd
4570\end_inset
4571
4572
4573\series default
4574\emph default
4575.
4576\end_layout
4577
4578\begin_layout Standard
4579In any other case, trying to access the field data would cause an error.
4580\begin_inset Newline newline
4581\end_inset
4582
4583
4584\begin_inset Newline newline
4585\end_inset
4586
4587The following configuration file:
4588\begin_inset listings
4589lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4590inline false
4591status open
4592
4593\begin_layout Plain Layout
4594
4595<?xml version="1.0"?>
4596\end_layout
4597
4598\begin_layout Plain Layout
4599
4600<simulation>
4601\end_layout
4602
4603\begin_layout Plain Layout
4604
4605        <context id="test">
4606\end_layout
4607
4608\begin_layout Plain Layout
4609
4610                <calendar type="Gregorian" timestep="1h" />
4611\end_layout
4612
4613\begin_layout Plain Layout
4614
4615\end_layout
4616
4617\begin_layout Plain Layout
4618
4619                <grid_definition>
4620\end_layout
4621
4622\begin_layout Plain Layout
4623
4624                        <grid id="grid_A"><!-- Definition ommited --></grid>
4625\end_layout
4626
4627\begin_layout Plain Layout
4628
4629                </grid_definition>
4630\end_layout
4631
4632\begin_layout Plain Layout
4633
4634\end_layout
4635
4636\begin_layout Plain Layout
4637
4638                <file_definition>
4639\end_layout
4640
4641\begin_layout Plain Layout
4642
4643                        <file name="input" output_freq="1ts">
4644\end_layout
4645
4646\begin_layout Plain Layout
4647
4648                        <field id="field_A" grid_ref="grid_A" operation="instant" />
4649\end_layout
4650
4651\begin_layout Plain Layout
4652
4653                        </file>
4654\end_layout
4655
4656\begin_layout Plain Layout
4657
4658                </file_definition>
4659\end_layout
4660
4661\begin_layout Plain Layout
4662
4663        </context>
4664\end_layout
4665
4666\begin_layout Plain Layout
4667
4668</simulation>
4669\end_layout
4670
4671\end_inset
4672
4673can be used with this Fortran code:
4674\end_layout
4675
4676\begin_layout Standard
4677\begin_inset listings
4678lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4679inline false
4680status open
4681
4682\begin_layout Plain Layout
4683
4684DO ts=1,numberOfTimestep
4685\end_layout
4686
4687\begin_layout Plain Layout
4688
4689        ! Get field_A for current timestep
4690\end_layout
4691
4692\begin_layout Plain Layout
4693
4694        CALL xios_recv_field("field_A", field_A) ! field_A must be an allocated
4695 array with the right size
4696\end_layout
4697
4698\begin_layout Plain Layout
4699
4700        ! Do useful things...
4701\end_layout
4702
4703\begin_layout Plain Layout
4704
4705        ! Inform XIOS of the current timestep
4706\end_layout
4707
4708\begin_layout Plain Layout
4709
4710        CALL xios_update_calendar(ts)
4711\end_layout
4712
4713\begin_layout Plain Layout
4714
4715ENDDO
4716\end_layout
4717
4718\end_inset
4719
4720The call to
4721\begin_inset Flex Code
4722status open
4723
4724\begin_layout Plain Layout
4725xios_recv_field
4726\end_layout
4727
4728\end_inset
4729
4730 might block for a while if the data was not yet received from the server(s)
4731 but it should not happen too often thanks to the prefetching done by XIOS.
4732\begin_inset Newline newline
4733\end_inset
4734
4735
4736\begin_inset Newline newline
4737\end_inset
4738
4739Since the
4740\series bold
4741read_access
4742\series default
4743 attribute allows to the access fields which depend directly on data from
4744 the model, you must be very careful with the order of the
4745\begin_inset Flex Code
4746status open
4747
4748\begin_layout Plain Layout
4749xios_send_field
4750\end_layout
4751
4752\end_inset
4753
4754 and
4755\begin_inset Flex Code
4756status open
4757
4758\begin_layout Plain Layout
4759xios_recv_field
4760\end_layout
4761
4762\end_inset
4763
4764 calls.
4765 For example, consider the following configuration file (just a simple example
4766 as in practice it does not make much sense to use it):
4767\begin_inset listings
4768lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4769inline false
4770status open
4771
4772\begin_layout Plain Layout
4773
4774<?xml version="1.0"?>
4775\end_layout
4776
4777\begin_layout Plain Layout
4778
4779<simulation>
4780\end_layout
4781
4782\begin_layout Plain Layout
4783
4784        <context id="test">
4785\end_layout
4786
4787\begin_layout Plain Layout
4788
4789                <calendar type="Gregorian" timestep="1h" />
4790\end_layout
4791
4792\begin_layout Plain Layout
4793
4794\end_layout
4795
4796\begin_layout Plain Layout
4797
4798                <grid_definition>
4799\end_layout
4800
4801\begin_layout Plain Layout
4802
4803                        <grid id="grid_A"><!-- Definition ommited --></grid>
4804\end_layout
4805
4806\begin_layout Plain Layout
4807
4808                </grid_definition>
4809\end_layout
4810
4811\begin_layout Plain Layout
4812
4813\end_layout
4814
4815\begin_layout Plain Layout
4816
4817                <field_definition>
4818\end_layout
4819
4820\begin_layout Plain Layout
4821
4822                <field id="field_A" grid_ref="grid_A" operation="instant" />
4823\end_layout
4824
4825\begin_layout Plain Layout
4826
4827                </field_definition>
4828\end_layout
4829
4830\begin_layout Plain Layout
4831
4832\end_layout
4833
4834\begin_layout Plain Layout
4835
4836                <file_definition>
4837\end_layout
4838
4839\begin_layout Plain Layout
4840
4841                        <file name="output" output_freq="1ts">
4842\end_layout
4843
4844\begin_layout Plain Layout
4845
4846                        <field id="field_B" grid_ref="grid_A" operation="instant" read_access=
4847"true">field_A / 42</field>
4848\end_layout
4849
4850\begin_layout Plain Layout
4851
4852                        </file>
4853\end_layout
4854
4855\begin_layout Plain Layout
4856
4857                </file_definition>
4858\end_layout
4859
4860\begin_layout Plain Layout
4861
4862        </context>
4863\end_layout
4864
4865\begin_layout Plain Layout
4866
4867</simulation>
4868\end_layout
4869
4870\end_inset
4871
4872If you call
4873\begin_inset Flex Code
4874status open
4875
4876\begin_layout Plain Layout
4877xios_recv_field(
4878\begin_inset Quotes eld
4879\end_inset
4880
4881field_B
4882\begin_inset Quotes erd
4883\end_inset
4884
4885, field_B)
4886\end_layout
4887
4888\end_inset
4889
4890 before
4891\begin_inset Flex Code
4892status open
4893
4894\begin_layout Plain Layout
4895xios_send_field(
4896\begin_inset Quotes eld
4897\end_inset
4898
4899field_A
4900\begin_inset Quotes erd
4901\end_inset
4902
4903, field_A)
4904\end_layout
4905
4906\end_inset
4907
4908, the requested data will never be available and a deadlock could occur.
4909 In practice, XIOS will detect the problem and throw an error.
4910\end_layout
4911
4912\begin_layout Section
4913How to reduce the size of an output file
4914\end_layout
4915
4916\begin_layout Standard
4917The size of the output files can sometimes become a problem.
4918 XIOS provides some features which may help to reduce the size of the output
4919 files losslessly.
4920\begin_inset Newline newline
4921\end_inset
4922
4923
4924\begin_inset Newline newline
4925\end_inset
4926
4927The first solution is to use the compression feature provided by HDF5 which
4928 allows a field to be compressed using gzip.
4929 Since it depends directly on HDF5, this feature works only when the NetCDF-4
4930 format is used.
4931 Since HDF5 does not (yet) support compression for parallel output, one
4932 has to use two server-level functionality (see Sec.
4933 
4934\begin_inset CommandInset ref
4935LatexCommand ref
4936reference "sec:Launching-secondary-server"
4937
4938\end_inset
4939
4940) or to engage the
4941\series bold
4942\emph on
4943
4944\begin_inset Quotes eld
4945\end_inset
4946
4947multiple_file
4948\begin_inset Quotes erd
4949\end_inset
4950
4951
4952\series default
4953\emph default
4954 mode.
4955\begin_inset Newline newline
4956\end_inset
4957
4958
4959\begin_inset Newline newline
4960\end_inset
4961
4962To enable the gzip compression of a field, you need to set the
4963\series bold
4964compression_level
4965\series default
4966 attribute to any integer between 1 and 9 (by default this attribute is
4967 set to 0 which means that compression is disabled).
4968 Using an higher compression level should improve the compression ratio
4969 at the cost of using more processing power.
4970 Generally using a compression level of 2 should be a good trade-off.
4971\begin_inset Newline newline
4972\end_inset
4973
4974
4975\begin_inset Newline newline
4976\end_inset
4977
4978The following example illustrates the use of the gzip compression:
4979\begin_inset listings
4980lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}"
4981inline false
4982status open
4983
4984\begin_layout Plain Layout
4985
4986<?xml version="1.0"?>
4987\end_layout
4988
4989\begin_layout Plain Layout
4990
4991<simulation>
4992\end_layout
4993
4994\begin_layout Plain Layout
4995
4996        <context id="test">
4997\end_layout
4998
4999\begin_layout Plain Layout
5000
5001                <calendar type="Gregorian" timestep="1h" />
5002\end_layout
5003
5004\begin_layout Plain Layout
5005
5006\end_layout
5007
5008\begin_layout Plain Layout
5009
5010                <grid_definition>
5011\end_layout
5012
5013\begin_layout Plain Layout
5014
5015                        <grid id="grid_A"><!-- Definition ommited --></grid>
5016\end_layout
5017
5018\begin_layout Plain Layout
5019
5020                </grid_definition>
5021\end_layout
5022
5023\begin_layout Plain Layout
5024
5025\end_layout
5026
5027\begin_layout Plain Layout
5028
5029                <file_definition>
5030\end_layout
5031
5032\begin_layout Plain Layout
5033
5034                        <file name="output" output_freq="1ts" compression_level="2">
5035\end_layout
5036
5037\begin_layout Plain Layout
5038
5039                        <field id="field_A" grid_ref="grid_A" operation="average" compression_
5040level="4" />
5041\end_layout
5042
5043\begin_layout Plain Layout
5044
5045                        <field id="field_B" grid_ref="grid_A" operation="average" compression_
5046level="0" />
5047\end_layout
5048
5049\begin_layout Plain Layout
5050
5051                        <field id="field_C" grid_ref="grid_A" operation="average" />
5052\end_layout
5053
5054\begin_layout Plain Layout
5055
5056                        </file>
5057\end_layout
5058
5059\begin_layout Plain Layout
5060
5061                </file_definition>
5062\end_layout
5063
5064\begin_layout Plain Layout
5065
5066        </context>
5067\end_layout
5068
5069\begin_layout Plain Layout
5070
5071</simulation>
5072\end_layout
5073
5074\end_inset
5075
5076Note that the
5077\series bold
5078compression_level
5079\series default
5080 attribute can also be set at a file level, in this case it is inherited
5081 by all fields of the file unless they explicitly override the attribute.
5082\begin_inset Newline newline
5083\end_inset
5084
5085
5086\begin_inset Newline newline
5087\end_inset
5088
5089The second solution is available only if you are using a grid with masked
5090 values.
5091 In this case, you can choose to output the indexed grid instead of the
5092 full grid by setting the
5093\series bold
5094indexed_output
5095\series default
5096 attribute to
5097\series bold
5098\emph on
5099
5100\begin_inset Quotes eld
5101\end_inset
5102
5103true
5104\begin_inset Quotes erd
5105\end_inset
5106
5107
5108\series default
5109\emph default
5110.
5111 Missing values are then omitted and extra arrays are outputted so that
5112 the translation from the
5113\begin_inset Quotes eld
5114\end_inset
5115
5116compressed
5117\begin_inset Quotes erd
5118\end_inset
5119
5120 indexes to the true indexes can be done.
5121 Due to those arrays of indexes, indexed output should be considered only
5122 if there is enough masked values.
5123 For more details about this feature, please refer to section 8.2
5124\begin_inset Quotes eld
5125\end_inset
5126
5127Compression by Gathering
5128\begin_inset Quotes erd
5129\end_inset
5130
5131 of the Climate and Forecast (CF) Convention.
5132\end_layout
5133
5134\begin_layout Standard
5135\begin_inset CommandInset include
5136LatexCommand include
5137filename "inputs/user/Grid.lyx"
5138
5139\end_inset
5140
5141
5142\end_layout
5143
5144\begin_layout Standard
5145\begin_inset CommandInset include
5146LatexCommand include
5147filename "inputs/user/Domain.lyx"
5148
5149\end_inset
5150
5151
5152\end_layout
5153
5154\begin_layout Standard
5155\begin_inset CommandInset include
5156LatexCommand include
5157filename "inputs/user/Axis.lyx"
5158
5159\end_inset
5160
5161
5162\end_layout
5163
5164\begin_layout Chapter
5165XIOS parameterization
5166\end_layout
5167
5168\begin_layout Standard
5169Some of XIOS behaviors can be configured using options.
5170 Those options must be exprhessed as variables in a specific context whose
5171 
5172\series bold
5173id
5174\series default
5175 must be
5176\series bold
5177\emph on
5178
5179\begin_inset Quotes eld
5180\end_inset
5181
5182xios
5183\begin_inset Quotes erd
5184\end_inset
5185
5186
5187\series default
5188\emph default
5189 as shown below.
5190\end_layout
5191
5192\begin_layout Standard
5193\begin_inset listings
5194lstparams "breaklines=true,frame=tb,language=XML,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}},tabsize=2"
5195inline false
5196status open
5197
5198\begin_layout Plain Layout
5199
5200<?xml version="1.0"?>
5201\end_layout
5202
5203\begin_layout Plain Layout
5204
5205<simulation>
5206\end_layout
5207
5208\begin_layout Plain Layout
5209
5210        <!-- Actual context(s) used by the simulation ommited -->
5211\end_layout
5212
5213\begin_layout Plain Layout
5214
5215\end_layout
5216
5217\begin_layout Plain Layout
5218
5219        <context id="xios">
5220\end_layout
5221
5222\begin_layout Plain Layout
5223
5224                <variable_definition>
5225\end_layout
5226
5227\begin_layout Plain Layout
5228
5229                        <variable id="option_name" type="option_type">option_value</variable>
5230\end_layout
5231
5232\begin_layout Plain Layout
5233
5234                </variable_definition>
5235\end_layout
5236
5237\begin_layout Plain Layout
5238
5239        </context>
5240\end_layout
5241
5242\begin_layout Plain Layout
5243
5244</simulation>
5245\end_layout
5246
5247\end_inset
5248
5249
5250\end_layout
5251
5252\begin_layout Section
5253Launching secondary server
5254\begin_inset CommandInset label
5255LatexCommand label
5256name "sec:Launching-secondary-server"
5257
5258\end_inset
5259
5260
5261\end_layout
5262
5263\begin_layout Standard
5264To improve I/O performance, it is possible to separate servers into two
5265 levels: intermediaries (level one) and writers (level two).
5266 Level-one servers will receive data from clients and will redistribute
5267 and send the data to subsets of level-two servers (called “pools”), whilst
5268 level-two servers will do the I/O.
5269 Each file is written by only one pool.
5270 If one process is assigned per pool (which is the default option), the
5271 I/O is sequential and HDF5 compression can be used even in the “multiple_file”
5272 mode.
5273 Level-two servers can be launched and controlled by means of three parameters:
5274\end_layout
5275
5276\begin_layout Itemize
5277
5278\series bold
5279using_server2
5280\series default
5281 (type:
5282\series bold
5283bool
5284\series default
5285) activates the secondary server
5286\end_layout
5287
5288\begin_layout Itemize
5289
5290\series bold
5291ratio_server2
5292\series default
5293 (type:
5294\series bold
5295int
5296\series default
5297) defines the percentage of servers that will be dedicated to level two.
5298 The parameter can take value from 0 to 100 with the default value of 50%.
5299 In case if the requested number of level-two servers is not valid (for
5300 example, zero or equal to the total number of servers), XIOS will run in
5301 its classical server mode with one server level.
5302\end_layout
5303
5304\begin_layout Itemize
5305
5306\series bold
5307number_pools_server2
5308\series default
5309(type:
5310\series bold
5311int
5312\series default
5313) sets the number of server-two pools (i.e.
5314 MPI communicators on level two).
5315 By default the number of pools is equal to the number of level-two servers,
5316 thus permitting one process per communicator.
5317\end_layout
5318
5319\begin_layout Standard
5320Shown in Fig.
5321 
5322\begin_inset CommandInset ref
5323LatexCommand ref
5324reference "Fig:server2"
5325
5326\end_inset
5327
5328 is the two-level server structure for the following definitions:
5329\end_layout
5330
5331\begin_layout Standard
5332\begin_inset listings
5333lstparams "breaklines=true,frame=tb,language=XML,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}},tabsize=2"
5334inline false
5335status open
5336
5337\begin_layout Plain Layout
5338
5339<context id="xios">    
5340\end_layout
5341
5342\begin_layout Plain Layout
5343
5344...
5345       
5346\end_layout
5347
5348\begin_layout Plain Layout
5349
5350        <variable id="using_server2" type="bool">true</variable>
5351\end_layout
5352
5353\begin_layout Plain Layout
5354
5355        <variable id="ratio_server2" type="int">75</variable>         
5356\end_layout
5357
5358\begin_layout Plain Layout
5359
5360        <variable id="number_pools_server2" type="int">3</variable>         
5361\end_layout
5362
5363\begin_layout Plain Layout
5364
5365...
5366\end_layout
5367
5368\begin_layout Plain Layout
5369
5370</context>
5371\end_layout
5372
5373\end_inset
5374
5375
5376\end_layout
5377
5378\begin_layout Standard
5379\begin_inset Float figure
5380placement H
5381wide false
5382sideways false
5383status open
5384
5385\begin_layout Plain Layout
5386\begin_inset Graphics
5387        filename inputs/images/Server2.pdf
5388
5389\end_inset
5390
5391
5392\end_layout
5393
5394\begin_layout Plain Layout
5395\begin_inset Caption Standard
5396
5397\begin_layout Plain Layout
5398Two levels of servers for the total number of servers of 8 and ratio_server2=75%.
5399 The number of level-two servers is
5400\begin_inset Formula $8\times\text{ratio\_server2}=6$
5401\end_inset
5402
5403 and, thus, the remaining 2 servers are of level one.
5404 
5405\end_layout
5406
5407\end_inset
5408
5409
5410\begin_inset CommandInset label
5411LatexCommand label
5412name "Fig:server2"
5413
5414\end_inset
5415
5416
5417\end_layout
5418
5419\end_inset
5420
5421
5422\end_layout
5423
5424\begin_layout Standard
5425By default file distribution among server-two pools is optimized for bandwidth.
5426 An alternative way of distributing files is possible in order to minimize
5427 memory consumption by level-two servers.
5428 For this, two additional parameters should be specified:
5429\end_layout
5430
5431\begin_layout Itemize
5432
5433\series bold
5434server2_dist_file_memory
5435\series default
5436 (type:
5437\series bold
5438bool
5439\series default
5440) activates memory optimization.
5441\end_layout
5442
5443\begin_layout Itemize
5444
5445\series bold
5446server2_dist_file_memory_ratio
5447\series default
5448 (type:
5449\series bold
5450double
5451\series default
5452) (optional) takes value from 0 (memory optimization) to 1 (bandwidth optimizati
5453on).
5454 The default value is 0.5.
5455\end_layout
5456
5457\begin_layout Section
5458Buffer related options
5459\end_layout
5460
5461\begin_layout Standard
5462By default, XIOS tries to guess the required buffers sizes to ensure efficient
5463 client-server communications.
5464 However it might sometimes be useful to tweak the buffers sizes so XIOS
5465 provides the following options:
5466\end_layout
5467
5468\begin_layout Itemize
5469
5470\series bold
5471optimal_buffer_size
5472\series default
5473 (type:
5474\series bold
5475string
5476\series default
5477) can be either
5478\series bold
5479\emph on
5480
5481\begin_inset Quotes eld
5482\end_inset
5483
5484memory
5485\begin_inset Quotes erd
5486\end_inset
5487
5488
5489\series default
5490\emph default
5491 or
5492\series bold
5493\emph on
5494
5495\begin_inset Quotes erd
5496\end_inset
5497
5498performance
5499\begin_inset Quotes erd
5500\end_inset
5501
5502
5503\series default
5504\emph default
5505.
5506 When using the
5507\series bold
5508\emph on
5509
5510\begin_inset Quotes eld
5511\end_inset
5512
5513memory
5514\begin_inset Quotes erd
5515\end_inset
5516
5517
5518\series default
5519\emph default
5520 mode, XIOS will try to use buffers as small as possible while still ensuring
5521 that the bigger message will fit.
5522 When using the
5523\series bold
5524\emph on
5525
5526\begin_inset Quotes erd
5527\end_inset
5528
5529performance
5530\begin_inset Quotes erd
5531\end_inset
5532
5533
5534\series default
5535\emph default
5536 mode, XIOS will ensure that all active fields can be buffered without having
5537 to flush the buffers.
5538 This mode is used by default since it allows more asynchronism and thus
5539 better performance at the cost of being quite memory hungry.
5540\end_layout
5541
5542\begin_layout Itemize
5543
5544\series bold
5545minimum_buffer_size
5546\series default
5547 (type:
5548\series bold
5549int
5550\series default
5551) defines the minimum buffer size in bytes (8192 by default).
5552 This value will be used by XIOS only for buffers whose detected size is
5553 smaller than the user defined minimum size.
5554\end_layout
5555
5556\begin_layout Itemize
5557
5558\series bold
5559buffer_size_factor
5560\series default
5561(type:
5562\series bold
5563int
5564\series default
5565) allows to modify the buffers sizes by multiplying the detected sizes by
5566 an user defined factor (
5567\begin_inset Formula $1.0$
5568\end_inset
5569
5570 by default).
5571 For each allocated buffers, the used size is defined as
5572\begin_inset Formula
5573\[
5574{\scriptstyle used\_size\;=\;\min\left(minimum\_buffer\_size,\;detected\_size\;\times\;buffer\_size\_factor\right)}
5575\]
5576
5577\end_inset
5578
5579
5580\end_layout
5581
5582\end_body
5583\end_document
Note: See TracBrowser for help on using the repository browser.