1 | % !TEX TS-program = pdflatex |
---|
2 | % !TEX encoding = UTF-8 Unicode |
---|
3 | % This is a simple template for a LaTeX document using the "article" class. |
---|
4 | % See "book", "report", "letter" for other types of document. |
---|
5 | |
---|
6 | \documentclass[11pt]{article} % use larger type; default would be 10pt |
---|
7 | |
---|
8 | \usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX) |
---|
9 | |
---|
10 | %%% Examples of Article customizations |
---|
11 | % These packages are optional, depending whether you want the features they provide. |
---|
12 | % See the LaTeX Companion or other references for full information. |
---|
13 | |
---|
14 | %%% PAGE DIMENSIONS |
---|
15 | \usepackage{geometry} % to change the page dimensions |
---|
16 | \geometry{a4paper} % or letterpaper (US) or a5paper or.... |
---|
17 | % \geometry{margin=2in} % for example, change the margins to 2 inches all round |
---|
18 | % \geometry{landscape} % set up the page for landscape |
---|
19 | % read geometry.pdf for detailed page layout information |
---|
20 | |
---|
21 | \usepackage{graphicx} % support the \includegraphics command and options |
---|
22 | |
---|
23 | % \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent |
---|
24 | |
---|
25 | %%% PACKAGES |
---|
26 | \usepackage{booktabs} % for much better looking tables |
---|
27 | \usepackage{array} % for better arrays (eg matrices) in maths |
---|
28 | \usepackage{paralist} % very flexible & customizable lists (eg. enumerate/itemize, etc.) |
---|
29 | \usepackage{verbatim} % adds environment for commenting out blocks of text & for better verbatim |
---|
30 | \usepackage{subfig} % make it possible to include more than one captioned figure/table in a single float |
---|
31 | % These packages are all incorporated in the memoir class to one degree or another... |
---|
32 | |
---|
33 | %%% HEADERS & FOOTERS |
---|
34 | \usepackage{fancyhdr} % This should be set AFTER setting up the page geometry |
---|
35 | \pagestyle{fancy} % options: empty , plain , fancy |
---|
36 | \renewcommand{\headrulewidth}{0pt} % customize the layout... |
---|
37 | \lhead{}\chead{}\rhead{} |
---|
38 | \lfoot{}\cfoot{\thepage}\rfoot{} |
---|
39 | |
---|
40 | %%% SECTION TITLE APPEARANCE |
---|
41 | \usepackage{sectsty} |
---|
42 | \allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help) |
---|
43 | % (This matches ConTeXt defaults) |
---|
44 | |
---|
45 | %%% ToC (table of contents) APPEARANCE |
---|
46 | \usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC |
---|
47 | \usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents |
---|
48 | \renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape} |
---|
49 | \renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold! |
---|
50 | |
---|
51 | \usepackage{listings} |
---|
52 | |
---|
53 | \usepackage{color} |
---|
54 | \usepackage{hyperref} |
---|
55 | |
---|
56 | \definecolor{gray}{rgb}{0.4,0.4,0.4} |
---|
57 | \definecolor{darkblue}{rgb}{0.0,0.0,0.6} |
---|
58 | \definecolor{cyan}{rgb}{0.0,0.6,0.6} |
---|
59 | |
---|
60 | \lstset{ |
---|
61 | basicstyle=\ttfamily, |
---|
62 | columns=fullflexible, |
---|
63 | showstringspaces=false, |
---|
64 | commentstyle=\color{gray}\upshape |
---|
65 | } |
---|
66 | |
---|
67 | \lstdefinelanguage{XML} |
---|
68 | { |
---|
69 | morestring=[b]", |
---|
70 | moredelim=[s][\bfseries\color{Maroon}]{<}{\ }, |
---|
71 | moredelim=[s][\bfseries\color{Maroon}]{</}{>}, |
---|
72 | moredelim=[l][\bfseries\color{Maroon}]{/>}, |
---|
73 | moredelim=[l][\bfseries\color{Maroon}]{>}, |
---|
74 | morecomment=[s]{<?}{?>}, |
---|
75 | morecomment=[s]{<!--}{-->}, |
---|
76 | commentstyle=\color{DarkOliveGreen}, |
---|
77 | stringstyle=\color{blue}, |
---|
78 | identifierstyle=\color{red}, |
---|
79 | keywordstyle=\color{brown}, |
---|
80 | morekeywords={xmlns,version,type, grid, field_ref, grid_ref, id, |
---|
81 | build_workflow_graph, build_workflow_graph_begin, build_workflow_graph_end}% list your attributes here |
---|
82 | } |
---|
83 | \newcommand{\quotes}[1]{``#1''} |
---|
84 | \usepackage[dvipsnames]{xcolor} |
---|
85 | \newcommand{\visbutton}[1]{\colorbox[RGB]{92,184,92}{\color{white}{#1}}} |
---|
86 | %%% END Article customizations |
---|
87 | |
---|
88 | %%% The "real" document content comes below... |
---|
89 | |
---|
90 | \title{User Guide for XIOS testcase} |
---|
91 | \author{Yushan Wang} |
---|
92 | %\date{} % Activate to display a given date or no date (if empty), |
---|
93 | % otherwise the current date is printed |
---|
94 | \makeatletter |
---|
95 | \def\@maketitle{ |
---|
96 | \raggedright |
---|
97 | \begin{minipage}[l]{0.45\textwidth} |
---|
98 | \flushleft\includegraphics[height = 30mm]{inputs/images/logo_IPSL} |
---|
99 | \end{minipage} |
---|
100 | \begin{minipage}[r]{0.45\textwidth} |
---|
101 | \flushright\includegraphics[height = 30mm]{inputs/images/logo_LSCE} |
---|
102 | \end{minipage} |
---|
103 | \\[10ex] |
---|
104 | \begin{center} |
---|
105 | {\Huge \bfseries \sffamily \@title }\\[4ex] |
---|
106 | {\Large \@author}\\[4ex] |
---|
107 | \@date\\[8ex] |
---|
108 | \end{center}} |
---|
109 | \makeatother |
---|
110 | |
---|
111 | |
---|
112 | \begin{document} |
---|
113 | \maketitle |
---|
114 | |
---|
115 | |
---|
116 | \section{What is the XIOS testcase} |
---|
117 | |
---|
118 | The XIOS generic testcase is a set of unit tests that test functionalities of |
---|
119 | XIOS. It is reserved for XIOS developers and it is designed to ensure that the |
---|
120 | XIOS does not introduce errors after each code modification. |
---|
121 | |
---|
122 | \section{Organization of the testcase} |
---|
123 | The XIOS generic testcase is located in the \verb|GENERIC_TESTCASE| folder inside |
---|
124 | the XIOS directory. Inside the \verb|GENERIC_TESTCASE| folder, we have for the moment |
---|
125 | 5 folders for testing specific XIOS functionalities. {\color{red}{Under construction}} |
---|
126 | \begin{itemize} |
---|
127 | \item \verb|test_function|: test the temporal reduce functionalities (accumulate, |
---|
128 | maximum, minimum, average, ...) |
---|
129 | \item \verb|test_scalar_algo|: test the scalar algorithms (extract, reduce, |
---|
130 | transformation, ...) |
---|
131 | \item \verb|test_axis_algo|: test the axis algorithms (duplicate, extract, |
---|
132 | interpolate, inverse, transformation, ...) |
---|
133 | \item \verb|test_domain_algo|: test the domain algorithms (connectivity, expand, extract, |
---|
134 | interpolate, reorder, transformation, ...) |
---|
135 | \item \verb|test_grid_algo|: test the grid algorithms (transformation, ...) |
---|
136 | \end{itemize} |
---|
137 | |
---|
138 | \section{How to configure XIOS testcase} |
---|
139 | |
---|
140 | \subsection{Define the configuration variables} |
---|
141 | At the moment, we provide 7 configuration variables with default values. |
---|
142 | \begin{itemize} |
---|
143 | \item \verb|UsingServer2|: when set to \verb|true|, the two-level server mode is enabled. |
---|
144 | Otherwise, the classic one-level server mode is used. |
---|
145 | \item \verb|RatioServer2|: the ratio of the second level servers. Significant only when |
---|
146 | two-lever server mode enabled. |
---|
147 | \item \verb|NumberPoolsServer2|: number of the pools of the second level servers. |
---|
148 | Significant only when two-lever server mode enabled. |
---|
149 | \item \verb|NumberClients|: number of client processes. |
---|
150 | \item \verb|NumberServers|: number of servers. |
---|
151 | \item \verb|Duration|: duration of the simulation. |
---|
152 | \item \verb|ATMdomain|: type of the domain used in the simulation. |
---|
153 | \end{itemize} |
---|
154 | |
---|
155 | The default values of all 7 configuration variables can be found and modified in |
---|
156 | the file \verb|default_param.py| located in the root folder \verb|GENERIC_TESTCASE|. |
---|
157 | |
---|
158 | Besides of the default value, one can also set a temporal value for the configuration variables in the file \verb|user_params.def|. |
---|
159 | In this file, each variable can have multiple values separated by a semicolon. For example, \verb|NumberServers=2,4,6|. |
---|
160 | From such definition, the testcase will generate 3 different configurations and tests will be run for each configuration. |
---|
161 | |
---|
162 | |
---|
163 | \subsection{Define the output file check list} |
---|
164 | The validation of the testcase is ensured by the comparison between the newly generated output |
---|
165 | \verb|NetCDF| files and the pre-stored reference results. In some cases, one maybe interested in only one or several output files. |
---|
166 | It will not be necessary to compare all output files for this will slow down the whole test execution. |
---|
167 | To specify the output files to compare with the reference, one can modify the \verb|checkfile.def| file. |
---|
168 | If nothing is set in this file, or \verb|all| is set, then all output files will be examined. |
---|
169 | |
---|
170 | \section{How to launch XIOS testcase} |
---|
171 | For the sake of simplicity, we suppose in the following context that the computing resource |
---|
172 | is Juliot-Curie from the TGCC computing center\footnote{\url{http://www-hpc.cea.fr/en/complexe/tgcc-JoliotCurie.htm}}. |
---|
173 | |
---|
174 | In the \verb|GENERIC_TESTCASE| folder, we have a job submission script \verb|job_irene.sh|. |
---|
175 | This script will execute all the unit tests in all 5 test folders. We also prepared |
---|
176 | job scripts for each test folder. If one want to run unit tests for a specific folder, |
---|
177 | \textit{e.g.} \verb|test_domain_algo|, it is sufficient to launch the \verb|job_irene.sh| |
---|
178 | script inside the folder \verb|test_domain_algo|. |
---|
179 | |
---|
180 | \section{Output of XIOS testcase} |
---|
181 | An example of the XIOS testcase output is as follows: |
---|
182 | \begin{lstlisting}[frame=single] |
---|
183 | -- Configuring done |
---|
184 | -- Generating done |
---|
185 | Test project /GENERIC_TESTCASE |
---|
186 | Start 1: test_domain_algo_config0 |
---|
187 | 1/16 Test #1: test_domain_algo_config0 ......... Passed 3.51 sec |
---|
188 | Start 2: test_domain_algo_config1 |
---|
189 | 2/16 Test #2: test_domain_algo_config1 ......... Passed 3.70 sec |
---|
190 | Start 3: test_domain_algo_config2 |
---|
191 | 3/16 Test #3: test_domain_algo_config2 ......... Passed 2.68 sec |
---|
192 | ... |
---|
193 | Start 14: test_axis_algo_config1 |
---|
194 | 14/16 Test #14: test_axis_algo_config1 ........... Passed 2.31 sec |
---|
195 | Start 15: test_grid_algo_config0 |
---|
196 | 15/16 Test #15: test_grid_algo_config0 ........... Passed 2.23 sec |
---|
197 | Start 16: test_grid_algo_config1 |
---|
198 | 16/16 Test #16: test_grid_algo_config1 ........... Passed 2.24 sec |
---|
199 | |
---|
200 | 100% tests passed, 0 tests failed out of 16 |
---|
201 | |
---|
202 | Total Test time (real) = 39.63 sec |
---|
203 | Built target report |
---|
204 | \end{lstlisting} |
---|
205 | |
---|
206 | This CTest style summary report shows the overall execution status of all unit tests. |
---|
207 | Besides of this console output, we also have \verb|report.html| which can be viewed |
---|
208 | by any web browser. |
---|
209 | |
---|
210 | We also generate job submission script for each configuration in each tet folder. |
---|
211 | These configuration specified job scripts allow one to focus on one configuration of the given test. |
---|
212 | \begin{verbatim} |
---|
213 | /GENERIC_TESTCASE/test_axis_algo/ |
---|
214 | irene_job_config_UsingSrv2=true_NbServers=2_ATMdomain=lmdz.sh |
---|
215 | \end{verbatim} |
---|
216 | |
---|
217 | \section{References results of XIOS testcase} |
---|
218 | |
---|
219 | If no reference results exist for a given configuration, the output \verb|NetCDF| files along with |
---|
220 | the setup files will be stored in the configuration folder of the test. |
---|
221 | \begin{verbatim} |
---|
222 | GENERIC_TESTCASE/test_axis_algo/ |
---|
223 | config_UsingSrv2=true_NbServers=2_ATMdomain=lmdz/ |
---|
224 | tmp_reference/ |
---|
225 | setup/ |
---|
226 | xios_output/ |
---|
227 | config_UsingSrv2=true_NbServers=4_ATMdomain=lmdz/ |
---|
228 | tmp_reference/ |
---|
229 | setup/ |
---|
230 | xios_output/ |
---|
231 | GENERIC_TESTCASE/test_domain_algo/ |
---|
232 | ... |
---|
233 | \end{verbatim} |
---|
234 | |
---|
235 | These results are considered to be temporal. Once the results are confirmed, one can |
---|
236 | store these results elsewhere for later use. We provide the \verb|copy_to_reference.py| |
---|
237 | script for storing the confirmed reference results in the \verb|$WORK| directory of the |
---|
238 | Juliot-Curie supercomputer. Similarly, we can retrieve the reference results from the |
---|
239 | \verb|$WORK| folder to the test folder by using the \verb|copy_from_reference.py| script. |
---|
240 | |
---|
241 | \end{document} |
---|