source: XIOS/dev/dev_trunk_omp/doc/XIOS_testcase_user_guide.tex @ 1742

Last change on this file since 1742 was 1742, checked in by yushan, 2 years ago

Doc updated

File size: 10.2 KB
Line 
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
118The XIOS generic testcase is a set of unit tests that test functionalities of
119XIOS. It is reserved for XIOS developers and it is designed to ensure that the
120XIOS does not introduce errors after each code modification.
121
122\section{Organization of the testcase}
123The XIOS generic testcase is located in the \verb|GENERIC_TESTCASE| folder inside
124the XIOS directory. Inside the \verb|GENERIC_TESTCASE| folder, we have for the moment
1255 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}
141At 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
155The default values of all 7 configuration variables can be found and modified in
156the file \verb|default_param.py| located in the root folder \verb|GENERIC_TESTCASE|.
157
158Besides of the default value, one can also set a temporal value for the configuration variables in the file \verb|user_params.def|.
159In this file, each variable can have multiple values separated by a semicolon. For example, \verb|NumberServers=2,4,6|.
160From 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}
164The 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.
166It will not be necessary to compare all output files for this will slow down the whole test execution.
167To specify the output files to compare with the reference, one can modify the \verb|checkfile.def| file.
168If 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}
171For the sake of simplicity, we suppose in the following context that the computing resource
172is Juliot-Curie from the TGCC computing center\footnote{\url{http://www-hpc.cea.fr/en/complexe/tgcc-JoliotCurie.htm}}.
173
174Inside the \verb|GENERIC_TESTCASE| folder, we have a sob submission script \verb|job_irene.sh|.
175This script will execute all the unit tests in all the 5 test folders. We also prepared
176job 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|
178script inside the \verb|test_domain_algo| folder.
179
180\section{Output of XIOS testcase}
181An example of the XIOS testcase output is as follows:
182\begin{lstlisting}[frame=single]
183-- Configuring done
184-- Generating done
185Test 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
19414/16 Test #14: test_axis_algo_config1 ...........   Passed    2.31 sec
195      Start 15: test_grid_algo_config0
19615/16 Test #15: test_grid_algo_config0 ...........   Passed    2.23 sec
197      Start 16: test_grid_algo_config1
19816/16 Test #16: test_grid_algo_config1 ...........   Passed    2.24 sec
199
200100% tests passed, 0 tests failed out of 16
201
202Total Test time (real) =  39.63 sec
203Built target report
204\end{lstlisting}
205
206This CTest style summary report shows the overall execution status of all unit tests.
207Besides of this console output, we also have \verb|report.html| which can be viewed
208by any web browser.
209
210We also generate job submission script for each configuration in each tet folder.
211These 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
219If no reference results exist for a given configuration, the output \verb|NetCDF| files along with
220the 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
235These results are considered to be temporal. Once the results are confirmed, one can
236store these results elsewhere for later use. We provide the \verb|copy_to_reference.py|
237script for storing the confirmed reference results in the \verb|$WORK| directory of the
238Juliot-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}
Note: See TracBrowser for help on using the repository browser.