%-----------------------------------------------------------------------
%
%     This file is part of the Code_Saturne Kernel, element of the
%     Code_Saturne CFD tool.
%
%     Copyright (C) 1998-2008 EDF S.A., France
%
%     contact: saturne-support@edf.fr
%
%     The Code_Saturne Kernel is free software; you can redistribute it
%     and/or modify it under the terms of the GNU General Public License
%     as published by the Free Software Foundation; either version 2 of
%     the License, or (at your option) any later version.
%
%     The Code_Saturne Kernel is distributed in the hope that it will be
%     useful, but WITHOUT ANY WARRANTY; without even the implied warranty
%     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%     GNU General Public License for more details.
%
%     You should have received a copy of the GNU General Public License
%     along with the Code_Saturne Kernel; if not, write to the
%     Free Software Foundation, Inc.,
%     51 Franklin St, Fifth Floor,
%     Boston, MA  02110-1301  USA
%
%-----------------------------------------------------------------------
%==================================
%==================================
\section{Appendix 1 : automatic validation procedure}
%==================================
%==================================
\label{prg_autovalid}
%=====================
\subsection{Introduction}
%=====================

This document is the practical user guide for the autovalidation
procedure associated with \CS version \verscs.
The aim of this document is to guide the user through all the steps
necessary for the running and the user-understanding of the autovalidation
procedure.
The guide describes the selected test cases, the modifiable settings
and the procedure to add a case in the reference base.

The procedure is written in python language and a XML file containing the
data settings is necessary.

%================================================
\subsection{Practical informations on the procedure}
%================================================

This procedure aims to run automatically all the selected cases and to
compare the obtained results with those of the reference base. All the
comparisons are summarized in a report file.
If the discrepancies between the reference and the test overpass a
determined tolerance, the procedure creates an EnSight part containing
the variable differences.

For each test cases, the detailed actions are the following:
\begin{list}{$\bullet$}{}
\item preparation of the study with the {\tt code\_saturne~create} command,
\item copy of all the necessary files (meshes, XML data file, user
      fortran files) from the reference base,
\item execution of the case with the {\tt runcase} utility,
\item comparison between the reference results and the test results,
\item update of the report file.
\end{list}

First, an empty directory named BASETEST is generated by the user.
In this directory, the command to launch the script is the following:
\begin{center}
{\tt autovalid -f [xml file name] [-d [tmp directory]] }
\end{center}
where {\it xml file name} is the data file containing the settings
necessary to the autovalidation. The reference base has to be easily
updatable. The user has to copy this file, initially associated to the
directory BASEREF, in the directory BASETEST in order to modify it (for
example, if the user doesn't want to execute all the tests or if he
wants to compare only some variables).


%==================================
\subsection{Directories architecture}
%==================================

The typical architecture is given in the following section:

\begin{list}{$\bullet$}{}
\item a directory BASEREF containing all the reference studies
      (five elementary tests GRADIENT and LAPLACIEN) and the XML data
      file {\tt autovalid.xml},
\item the user has to create a directory BASETEST and to copy
      the XML data file {\tt autovalid.xml} in this directory before
      launching the script,
\item a directory Autovalid containing all the python source files.
\end{list}



%==================================
\subsection{Validation base}
%==================================

The selected cases in the reference directory are:
\begin{list}{$\bullet$}{}
\item GRADIENT : elementary tests of gradient calculation using the
      different methods proposed by \CS,
\item LAPLACIEN : resolution of a laplacian equation.
\end{list}

%==================================
\subsubsection{Elementary tests : gradient calculations}
%==================================
The elementary tests are performed on a cubical mesh composed by
hexahedrons and tetrahedrons with non-conforming merging. The mesh is
generated using Simail-6.4 mesher (file with extension {\it .des}).

All the tests are contained in the fortran file {\tt testel.f90} called by
the fortran file {\tt caltri.f90}. To activate the elementary tests,
we use the existing parameter {\tt iverif} in the main program {\tt cs\_solver.c};
{\tt iverif} is initialised to -1 (no action).

A new keyword ARG\_CS\_VERIF refering to {\tt iverif} is added in the
universal launch script {\tt runcase}, so that the command line is:
{\tt cs\_solver \$ARG\_CS\_VERIF}.

The test case consists in calculating the gradient of $sin(x+2y+3z)$
with the different methods implemented in \CS (boundary conditions
are treated with Dirichlet condition). We compare the result to the
reference solution (not to the exact solution).


%==================================
\subsubsection{Laplacien calculation}
%==================================

The mesh is the same as for the previous elementary tests.

The case consists in the resolution of a stationary equation without
convection terms for a passive scalar. The source term and Dirichlet
boundary conditions are specified so that the solution is $sin(x+2y+3z)$.
The source term is imposed in the fortran file {\tt ustssc.f90}.
We compare the result with the reference solution (not with the exact
solution).



%==================================
\subsection{Architecture description}
%==================================

In the directory Autovalid, the user finds all the python source
files necessary to the execution of the procedure. The main file
{\tt autovalid} runs the autovalidation and manages the general
printouts.


%==================================
\subsubsection{Python files in the modules directory}
%==================================

All the python files are listed here:

\begin{list}{$\bullet$}{}
\item {\tt Common.py}: this file contains the global variables (XML
      file name, reference version, reference path, temporary directory
      and local directory),
\item {\tt CommandLine.py}: this file manages the command line usage,
\item {\tt Parser.py}: this file defines the parser class which loads
      and reads the XML data file,
\item {\tt Study.py}: this file defines the study class which contains
      case objects,
\item {\tt Case.py}: this file defines the case class which contains
      the launch script and the listing and chrono comparisons,
\item {\tt Listing.py}: this file defines the listing class which
      contains minima/maxima variables and clippings,
\item {\tt Chrono.py}: this file defines the chrono class which
      contains a list of values and creates, if necessary, a part
      EnSight (if tolerance $>$ specified value).
\end{list}


%================================
\subsubsection{XML file description}
%================================

The XML file contains all the data to run the different cases.
It is important to note the definitions of the following attributes:
\begin{list}{$\bullet$}{}
\item {\it label} refers to the name of the study, the name of the case,
the name of the variable or the name of the post-treatment script,
\item {\it status} is 'on' or 'off' to activate or not the action,
\item {\it compute} is 'on' or 'off' to run or not the calculation,
\item {\it tolerance} is the maximum allowed value for the norm of the
      variable X defined by
      $$\frac{\vert{X_{Ref}-X_{Test}}\vert}{\vert{X_{max_{Ref}}-X_{min_{Ref}}}+\varepsilon\vert}$$ .
\end{list}

An example of XML data file is given below:

\begin{alltt}
\input{autovalid.xml}
\end{alltt}

Note : If {\it status} is 'on' and {\it compute} is 'off', we compare
listing files and chrono files but if there isn't result available,
{\it compute} becomes 'on'.


%==============================
\subsubsection{To add a new study}
%==============================

To add a new study in the reference base, the user has to create and run
a calculation in the directory BASEREF. He also has to add the following
typical section in the XML data file:
\begin{alltt}
\input{addstudy.xml}
\end{alltt}
For example, this previous sequence means that the user wants to run
(compute is 'on') and compare the variable 'gradient' with a tolerance
0.1 for the case CAS1 of the study GRADIENT.


%========================
\subsubsection{Report files}
%========================

There are three kinds of report file :
\begin{list}{$\bullet$}{}
\item {\tt report.txt}: this general file contains just OK, NOK,
      'Execution error' or 'Compilation error' for each case of
      each study,
\item {\tt STUDY\_listing.report}: this file depends on the study
      and contains the listing files comparison for each selected
      variable at the last time step (min/max values, min/max norms,
      min/max clippings),
      $$Norm_{X_{max}}=\frac{\vert{X_{max_{Ref}}-X_{max_{Test}}}\vert}{\vert{X_{max_{Ref}}-X_{min_{Ref}}}+\varepsilon\vert}$$
      $$Norm_{X_{min}}=\frac{\vert{X_{min_{Ref}}-X_{min_{Test}}}\vert}{\vert{X_{max_{Ref}}-X_{min_{Ref}}}+\varepsilon\vert}$$
\item {\tt STUDY\_chrono.report}: this file depends on the study
      and contains the chrono files comparison for each selected
      variable at the last time step (maximum difference, mean
      difference and norm),
      $$\delta_{max}= max \vert{X_{Ref}-X_{Test}\vert}$$
      $$\delta_{mean}= \frac{\sum \vert{X_{Ref}-X_{Test}}\vert}{Nb_{values}} $$
      $$Norm = \frac{\delta_{max}}{\vert{X_{max_{Ref}}-X_{min_{Ref}}}+\varepsilon\vert}$$

\end{list}
