[1741] | 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 | |
---|
[1742] | 21 | \usepackage{graphicx} % support the \includegraphics command and options |
---|
[1741] | 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 |
---|
[1742] | 28 | \usepackage{paralist} % very flexible & customizable lists (eg. enumerate/itemize, etc.) |
---|
[1741] | 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 |
---|
[1742] | 36 | \renewcommand{\headrulewidth}{0pt} % customize the layout... |
---|
[1741] | 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 |
---|
[1742] | 119 | XIOS. It is reserved for XIOS developers and it is designed to ensure that the |
---|
[1741] | 120 | XIOS does not introduce errors after each code modification. |
---|
| 121 | |
---|
[1742] | 122 | \section{Organization of the testcase} |
---|
[1741] | 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|. |
---|
[1742] | 159 | In this file, each variable can have multiple values separated by a semicolon. For example, \verb|NumberServers=2,4,6|. |
---|
[1741] | 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} |
---|
[1742] | 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. |
---|
[1741] | 167 | To specify the output files to compare with the reference, one can modify the \verb|checkfile.def| file. |
---|
[1742] | 168 | If nothing is set in this file, or \verb|all| is set, then all output files will be examined. |
---|
[1741] | 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 | |
---|
[1779] | 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 |
---|
[1741] | 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| |
---|
[1779] | 178 | script inside the folder \verb|test_domain_algo|. |
---|
[1741] | 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 | |
---|
[1742] | 206 | This CTest style summary report shows the overall execution status of all unit tests. |
---|
[1741] | 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} |
---|