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

Last change on this file since 1205 was 1182, checked in by rlacroix, 7 years ago

Update the documentation.

Document the "xios_field_is_active" function and the "check_if_active" field attribute.

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