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

% !TEX TS-program = pdflatex
% !TEX encoding = UTF-8 Unicode
% This is a simple template for a LaTeX document using the "article" class.
% See "book", "report", "letter" for other types of document.

\documentclass[11pt]{article} % use larger type; default would be 10pt

\usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX)

%%% Examples of Article customizations
% These packages are optional, depending whether you want the features they provide.
% See the LaTeX Companion or other references for full information.

%%% PAGE DIMENSIONS
\usepackage{geometry} % to change the page dimensions
\geometry{a4paper} % or letterpaper (US) or a5paper or....
% \geometry{margin=2in} % for example, change the margins to 2 inches all round
% \geometry{landscape} % set up the page for landscape
%   read geometry.pdf for detailed page layout information

\usepackage{graphicx} % support the \includegraphics command and options

% \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent

%%% PACKAGES
\usepackage{booktabs} % for much better looking tables
\usepackage{array} % for better arrays (eg matrices) in maths
\usepackage{paralist} % very flexible & customisable lists (eg. enumerate/itemize, etc.)
\usepackage{verbatim} % adds environment for commenting out blocks of text & for better verbatim
\usepackage{subfig} % make it possible to include more than one captioned figure/table in a single float
% These packages are all incorporated in the memoir class to one degree or another...

%%% HEADERS & FOOTERS
\usepackage{fancyhdr} % This should be set AFTER setting up the page geometry
\pagestyle{fancy} % options: empty , plain , fancy
\renewcommand{\headrulewidth}{0pt} % customise the layout...
\lhead{}\chead{}\rhead{}
\lfoot{}\cfoot{\thepage}\rfoot{}

%%% SECTION TITLE APPEARANCE
\usepackage{sectsty}
\allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
% (This matches ConTeXt defaults)

%%% ToC (table of contents) APPEARANCE
\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!

\usepackage{listings}

\usepackage{color}

\definecolor{gray}{rgb}{0.4,0.4,0.4}
\definecolor{darkblue}{rgb}{0.0,0.0,0.6}
\definecolor{cyan}{rgb}{0.0,0.6,0.6}

\lstset{
  basicstyle=\ttfamily,
  columns=fullflexible,
  showstringspaces=false,
  commentstyle=\color{gray}\upshape
}

\lstdefinelanguage{XML}
{
  morestring=[b]",
  moredelim=[s][\bfseries\color{Maroon}]{<}{\ },
  moredelim=[s][\bfseries\color{Maroon}]{</}{>},
  moredelim=[l][\bfseries\color{Maroon}]{/>},
  moredelim=[l][\bfseries\color{Maroon}]{>},
  morecomment=[s]{<?}{?>},
  morecomment=[s]{<!--}{-->},
  commentstyle=\color{DarkOliveGreen},
  stringstyle=\color{blue},
  identifierstyle=\color{red},
  keywordstyle=\color{brown},
  morekeywords={xmlns,version,type, grid, field_ref, grid_ref, id, 
  build_workflow_graph, build_workflow_graph_begin, build_workflow_graph_end}% list your attributes here
  }
\newcommand{\quotes}[1]{``#1''}
\usepackage[dvipsnames]{xcolor}
\newcommand{\visbutton}[1]{\colorbox[RGB]{92,184,92}{\color{white}{#1}}}

\usepackage{float}
%%% END Article customizations

%%% The "real" document content comes below...

\title{User Guide for XIOS workflow Graph}
\author{Yushan Wang}
%\date{} % Activate to display a given date or no date (if empty),
         % otherwise the current date is printed 
\makeatletter         
\def\@maketitle{
\raggedright
%\flushleft\includegraphics[height = 30mm]{inputs/images/logo_IPSL}
%\flushright\includegraphics[height = 30mm]{inputs/images/logo_LSCE}\\[10ex]
\begin{minipage}[l]{0.45\textwidth}
\flushleft\includegraphics[height = 30mm]{inputs/images/logo_IPSL}
\end{minipage}
\begin{minipage}[r]{0.45\textwidth}
\flushright\includegraphics[height = 30mm]{inputs/images/logo_LSCE}
\end{minipage}
\\[10ex]
\begin{center}
{\Huge \bfseries \sffamily \@title }\\[4ex] 
{\Large  \@author}\\[4ex] 
\@date\\[8ex]
\end{center}}
\makeatother


\begin{document}
\maketitle


\section{What is the workflow graph}

The workflow graph generated by XIOS shows the path of the data flux in the XIOS context.  
It can give user an overall presentation of how the field is generated and which operations are applied.
It is often not easy to track the data dependency from the \verb|xml| file. That's why a graphic representation is more user-friendly.

\begin{figure}[ht]
\centering
\includegraphics[scale=0.2]{inputs/images/graph.png}
\end{figure}
\subsection{Node}
In the workflow graph, a node represents a XIOS filter. We have 7 categories of filters:
\begin{itemize}
    \item source filter: when the field data is received from model or read from NetCDF file
    \item pass through filter: when having a field reference
    \item arithmetic filter: when arithmetic operations are performed on the field
    \item temporal filter: when the field has a temporal operation (\textit{e.g.} average, maximum, minimum, ...)
    \item spatial transform filter: when the field has a spatial transform applied upon (\textit{e.g.} zoom, interpolate, ...)
    \item file write filter: when the field data is written to a NetCDF file
    \item store filter: when the field data is send back to model
\end{itemize}

\subsection{Edge}
Edge in the workflow graph represents the field after the filter is applied.



\section{Enable the workflow graph}

The field attribute \verb|build_workflow_graph| is used to control the workflow graph.

\begin{lstlisting}[language=XML]
    <field id="field" grid_ref="grid" build_workflow_graph="true" />
\end{lstlisting}

\subsection{Heritage by field referencing}

\begin{lstlisting}[language=XML]
    <field id="field_A" grid="grid" build_workflow_graph="true" />
    <field id="field_B" field_ref="field_A" />
\end{lstlisting}

\subsection{Heritage by arithmetic operations}

\begin{lstlisting}[language=XML]
    <field id="field_A" grid="grid" build_workflow_graph="true" />
    <field id="field_B" field_ref="field_A" > field_A*2 </field>
\end{lstlisting}




\section{Visualization of workflow graph}


\subsection{Example of XIOS workflow graph output}

\begin{figure}[H]
    \centering
    \includegraphics[scale=0.45]{inputs/images/workflow_graph}
\end{figure}

From this graph, we can gather several information directly:
\begin{itemize}
    \item the workflow has 3 inputs fields and one output field;
    \item \verb|filed_D = field_A + field_B + field_C|;
    \item \verb|field_D| is outputted every time step (instant temporal filter);
    \item the output NetCDF file is named \verb|output.nc|;
    \item the date label of the time step is 2012-03-01 at 21 o'clock.
\end{itemize}

This graph shows how XIOS interprets the \verb|xml| inputs. Users can easily check if it corresponds to 
their designed input configurations. 

The workflow graph is viewed through the \verb|graph.html| script located in the XIOS 
folder. The graph file \verb|graph_data.json| is stored in the same folder as the \verb|iodef.xml| file
which is used for configure the simulation.
Choose the graph file to start the Visualization by clicking the button \colorbox[RGB]{66,139,202}{\color{white}{Load a JSON XIOS file}}.
Several buttons are set to allow user to visualize the graph interactively. 

\begin{figure}[H]
    \centering
    \includegraphics[scale=0.4]{inputs/images/graph_init}
    \caption{Start state of the Visualization}
\end{figure}

\subsection{Enable/Disable all}
The graph is hidden at the beginning. \visbutton{Enable all} will show the whole graph and \visbutton{Disable all} is used to hide the whole graph 

\subsection{Show/Hide node}
The \visbutton{Hide node} buttons allow user to temporarily hide a node and its edges. The node's position is kept and user can still click on it 
to show the node and its edges by the \visbutton{Show node} button.

\subsection{Enable parents/children}
These buttons can show the direct parents or children of a given node.

\subsection{Enable/Disable all parents}
These buttons are used to show/hide all parent nodes and edges of a given node. 

\subsection{Enable/Disable all children}
These buttons are used to show/hide all child nodes and edges of a given node.

\subsection{Enable input}
\visbutton{Enable input} shows all input nodes of the graph. The input nodes are
often, if not always, the source filters: data received from the model or read 
from a NetCDF file.

\subsection{Enable output}
\visbutton{Enable output} shows all output nodes of the graph. The output nodes 
are either the file writer filter: data written to a NetCDF file; either the store 
filter: data send back to model.

\subsection{Enable last temporal input}
Very often, a field is generated after many iterations. Showing all these iterations 
can be redundant and slow down the browser. That's why the \visbutton{Enable last 
temporal input} button is useful because it can show us only the last iteration before 
the flux gets to the current filter node.

\subsection{Show subgraph}
\visbutton{Show subgraph} button is very useful because it can focus on a given node 
and show all its parents and children nodes and edges, and at the same time hide all 
irrelevant elements to the given node.


\section{Hover message in the workflow graph}
A hover message is shown for each filter and field. For example, the hover message for 
a file writer filter gives all attributes of the output file and the written field.


\section{Time control of workflow graph}


Attributes \verb|build_workflow_graph_start| and \verb|build_workflow_graph_end| are 
used to control the starting and end time of the workflow graph.

\begin{lstlisting}[language=XML]
    <field id="field" grid_ref="grid" build_workflow_graph="true"
                                      build_workflow_graph_begin="3ts"
                                      build_workflow_graph_end="5ts" />
\end{lstlisting}

In this example, the graph will only include information between the 3rd and 5th time step.
These attributes are not mandatory. If \verb|build_workflow_graph_start| is not define, the graph will start to record from the first iteration.
Similarly, the default value of \verb|build_workflow_graph_end| is the last iteration of the simulation.

In case that two values of the same attribute are defined, we take the largest range.
\begin{lstlisting}[language=XML]
    <field id="field_A"  build_workflow_graph="true"
                         build_workflow_graph_begin="3ts"
                         build_workflow_graph_end="5ts" />

    <field id="field_B"  field_ref="field_A" build_workflow_graph="true"
                         build_workflow_graph_end="4ts" />
\end{lstlisting} 

In this example, \verb|field_B| will have attributes \verb|build_workflow_graph_start="1ts"| and \verb|build_workflow_graph_end="5ts"| 
\end{document}