[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 | |
---|
| 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 & customisable 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} % customise 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 | |
---|
| 55 | \definecolor{gray}{rgb}{0.4,0.4,0.4} |
---|
| 56 | \definecolor{darkblue}{rgb}{0.0,0.0,0.6} |
---|
| 57 | \definecolor{cyan}{rgb}{0.0,0.6,0.6} |
---|
| 58 | |
---|
| 59 | \lstset{ |
---|
| 60 | basicstyle=\ttfamily, |
---|
| 61 | columns=fullflexible, |
---|
| 62 | showstringspaces=false, |
---|
| 63 | commentstyle=\color{gray}\upshape |
---|
| 64 | } |
---|
| 65 | |
---|
| 66 | \lstdefinelanguage{XML} |
---|
| 67 | { |
---|
| 68 | morestring=[b]", |
---|
| 69 | moredelim=[s][\bfseries\color{Maroon}]{<}{\ }, |
---|
| 70 | moredelim=[s][\bfseries\color{Maroon}]{</}{>}, |
---|
| 71 | moredelim=[l][\bfseries\color{Maroon}]{/>}, |
---|
| 72 | moredelim=[l][\bfseries\color{Maroon}]{>}, |
---|
| 73 | morecomment=[s]{<?}{?>}, |
---|
| 74 | morecomment=[s]{<!--}{-->}, |
---|
| 75 | commentstyle=\color{DarkOliveGreen}, |
---|
| 76 | stringstyle=\color{blue}, |
---|
| 77 | identifierstyle=\color{red}, |
---|
| 78 | keywordstyle=\color{brown}, |
---|
| 79 | morekeywords={xmlns,version,type, grid, field_ref, grid_ref, id, |
---|
| 80 | build_workflow_graph, build_workflow_graph_begin, build_workflow_graph_end}% list your attributes here |
---|
| 81 | } |
---|
| 82 | \newcommand{\quotes}[1]{``#1''} |
---|
| 83 | \usepackage[dvipsnames]{xcolor} |
---|
| 84 | \newcommand{\visbutton}[1]{\colorbox[RGB]{92,184,92}{\color{white}{#1}}} |
---|
[1742] | 85 | |
---|
| 86 | \usepackage{float} |
---|
[1741] | 87 | %%% END Article customizations |
---|
| 88 | |
---|
| 89 | %%% The "real" document content comes below... |
---|
| 90 | |
---|
| 91 | \title{User Guide for XIOS workflow Graph} |
---|
| 92 | \author{Yushan Wang} |
---|
| 93 | %\date{} % Activate to display a given date or no date (if empty), |
---|
| 94 | % otherwise the current date is printed |
---|
| 95 | \makeatletter |
---|
| 96 | \def\@maketitle{ |
---|
| 97 | \raggedright |
---|
| 98 | %\flushleft\includegraphics[height = 30mm]{inputs/images/logo_IPSL} |
---|
| 99 | %\flushright\includegraphics[height = 30mm]{inputs/images/logo_LSCE}\\[10ex] |
---|
| 100 | \begin{minipage}[l]{0.45\textwidth} |
---|
| 101 | \flushleft\includegraphics[height = 30mm]{inputs/images/logo_IPSL} |
---|
| 102 | \end{minipage} |
---|
| 103 | \begin{minipage}[r]{0.45\textwidth} |
---|
| 104 | \flushright\includegraphics[height = 30mm]{inputs/images/logo_LSCE} |
---|
| 105 | \end{minipage} |
---|
| 106 | \\[10ex] |
---|
| 107 | \begin{center} |
---|
| 108 | {\Huge \bfseries \sffamily \@title }\\[4ex] |
---|
| 109 | {\Large \@author}\\[4ex] |
---|
| 110 | \@date\\[8ex] |
---|
| 111 | \end{center}} |
---|
| 112 | \makeatother |
---|
| 113 | |
---|
| 114 | |
---|
| 115 | \begin{document} |
---|
| 116 | \maketitle |
---|
| 117 | |
---|
| 118 | |
---|
| 119 | \section{What is the workflow graph} |
---|
| 120 | |
---|
| 121 | The workflow graph generated by XIOS shows the path of the data flux in the XIOS context. |
---|
| 122 | It can give user an overall presentation of how the field is generated and which operations are applied. |
---|
| 123 | 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. |
---|
| 124 | |
---|
| 125 | \begin{figure}[ht] |
---|
| 126 | \centering |
---|
| 127 | \includegraphics[scale=0.2]{inputs/images/graph.png} |
---|
| 128 | \end{figure} |
---|
| 129 | \subsection{Node} |
---|
| 130 | In the workflow graph, a node represents a XIOS filter. We have 7 categories of filters: |
---|
| 131 | \begin{itemize} |
---|
[1742] | 132 | \item source filter: when the field data is received from model or read from NetCDF file |
---|
[1741] | 133 | \item pass through filter: when having a field reference |
---|
| 134 | \item arithmetic filter: when arithmetic operations are performed on the field |
---|
| 135 | \item temporal filter: when the field has a temporal operation (\textit{e.g.} average, maximum, minimum, ...) |
---|
| 136 | \item spatial transform filter: when the field has a spatial transform applied upon (\textit{e.g.} zoom, interpolate, ...) |
---|
[1742] | 137 | \item file write filter: when the field data is written to a NetCDF file |
---|
[1741] | 138 | \item store filter: when the field data is send back to model |
---|
| 139 | \end{itemize} |
---|
| 140 | |
---|
| 141 | \subsection{Edge} |
---|
| 142 | Edge in the workflow graph represents the field after the filter is applied. |
---|
| 143 | |
---|
| 144 | |
---|
| 145 | |
---|
| 146 | \section{Enable the workflow graph} |
---|
| 147 | |
---|
| 148 | The field attribute \verb|build_workflow_graph| is used to control the workflow graph. |
---|
| 149 | |
---|
| 150 | \begin{lstlisting}[language=XML] |
---|
| 151 | <field id="field" grid_ref="grid" build_workflow_graph="true" /> |
---|
| 152 | \end{lstlisting} |
---|
| 153 | |
---|
[1742] | 154 | \subsection{Heritage by field referencing} |
---|
[1741] | 155 | |
---|
| 156 | \begin{lstlisting}[language=XML] |
---|
| 157 | <field id="field_A" grid="grid" build_workflow_graph="true" /> |
---|
| 158 | <field id="field_B" field_ref="field_A" /> |
---|
| 159 | \end{lstlisting} |
---|
| 160 | |
---|
| 161 | \subsection{Heritage by arithmetic operations} |
---|
| 162 | |
---|
| 163 | \begin{lstlisting}[language=XML] |
---|
| 164 | <field id="field_A" grid="grid" build_workflow_graph="true" /> |
---|
| 165 | <field id="field_B" field_ref="field_A" > field_A*2 </field> |
---|
| 166 | \end{lstlisting} |
---|
| 167 | |
---|
| 168 | |
---|
| 169 | |
---|
| 170 | |
---|
| 171 | \section{Visualization of workflow graph} |
---|
| 172 | |
---|
[1742] | 173 | |
---|
| 174 | \subsection{Example of XIOS workflow graph output} |
---|
| 175 | |
---|
| 176 | \begin{figure}[H] |
---|
| 177 | \centering |
---|
| 178 | \includegraphics[scale=0.45]{inputs/images/workflow_graph} |
---|
[1741] | 179 | \end{figure} |
---|
| 180 | |
---|
[1742] | 181 | From this graph, we can gather several information directly: |
---|
| 182 | \begin{itemize} |
---|
| 183 | \item the workflow has 3 inputs fields and one output field; |
---|
| 184 | \item \verb|filed_D = field_A + field_B + field_C|; |
---|
| 185 | \item \verb|field_D| is outputted every time step (instant temporal filter); |
---|
| 186 | \item the output NetCDF file is named \verb|output.nc|; |
---|
| 187 | \item the date label of the time step is 2012-03-01 at 21 o'clock. |
---|
| 188 | \end{itemize} |
---|
| 189 | |
---|
| 190 | This graph shows how XIOS interprets the \verb|xml| inputs. Users can easily check if it corresponds to |
---|
| 191 | their designed input configurations. |
---|
| 192 | |
---|
| 193 | The workflow graph is viewed through the \verb|graph.html| script located in the XIOS |
---|
[1741] | 194 | folder. The graph file \verb|graph_data.json| is stored in the same folder as the \verb|iodef.xml| file |
---|
| 195 | which is used for configure the simulation. |
---|
[1742] | 196 | Choose the graph file to start the Visualization by clicking the button \colorbox[RGB]{66,139,202}{\color{white}{Load a JSON XIOS file}}. |
---|
[1741] | 197 | Several buttons are set to allow user to visualize the graph interactively. |
---|
| 198 | |
---|
[1742] | 199 | \begin{figure}[H] |
---|
| 200 | \centering |
---|
| 201 | \includegraphics[scale=0.4]{inputs/images/graph_init} |
---|
| 202 | \caption{Start state of the Visualization} |
---|
| 203 | \end{figure} |
---|
| 204 | |
---|
[1741] | 205 | \subsection{Enable/Disable all} |
---|
| 206 | 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 |
---|
| 207 | |
---|
| 208 | \subsection{Show/Hide node} |
---|
| 209 | 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 |
---|
| 210 | to show the node and its edges by the \visbutton{Show node} button. |
---|
| 211 | |
---|
| 212 | \subsection{Enable parents/children} |
---|
| 213 | These buttons can show the direct parents or children of a given node. |
---|
| 214 | |
---|
| 215 | \subsection{Enable/Disable all parents} |
---|
| 216 | These buttons are used to show/hide all parent nodes and edges of a given node. |
---|
| 217 | |
---|
| 218 | \subsection{Enable/Disable all children} |
---|
| 219 | These buttons are used to show/hide all child nodes and edges of a given node. |
---|
| 220 | |
---|
| 221 | \subsection{Enable input} |
---|
| 222 | \visbutton{Enable input} shows all input nodes of the graph. The input nodes are |
---|
| 223 | often, if not always, the source filters: data received from the model or read |
---|
[1742] | 224 | from a NetCDF file. |
---|
[1741] | 225 | |
---|
| 226 | \subsection{Enable output} |
---|
| 227 | \visbutton{Enable output} shows all output nodes of the graph. The output nodes |
---|
[1742] | 228 | are either the file writer filter: data written to a NetCDF file; either the store |
---|
[1741] | 229 | filter: data send back to model. |
---|
| 230 | |
---|
| 231 | \subsection{Enable last temporal input} |
---|
| 232 | Very often, a field is generated after many iterations. Showing all these iterations |
---|
| 233 | can be redundant and slow down the browser. That's why the \visbutton{Enable last |
---|
| 234 | temporal input} button is useful because it can show us only the last iteration before |
---|
| 235 | the flux gets to the current filter node. |
---|
| 236 | |
---|
| 237 | \subsection{Show subgraph} |
---|
| 238 | \visbutton{Show subgraph} button is very useful because it can focus on a given node |
---|
| 239 | and show all its parents and children nodes and edges, and at the same time hide all |
---|
| 240 | irrelevant elements to the given node. |
---|
| 241 | |
---|
| 242 | |
---|
| 243 | \section{Hover message in the workflow graph} |
---|
| 244 | A hover message is shown for each filter and field. For example, the hover message for |
---|
| 245 | a file writer filter gives all attributes of the output file and the written field. |
---|
| 246 | |
---|
| 247 | |
---|
| 248 | \section{Time control of workflow graph} |
---|
| 249 | |
---|
| 250 | |
---|
| 251 | Attributes \verb|build_workflow_graph_start| and \verb|build_workflow_graph_end| are |
---|
| 252 | used to control the starting and end time of the workflow graph. |
---|
| 253 | |
---|
| 254 | \begin{lstlisting}[language=XML] |
---|
| 255 | <field id="field" grid_ref="grid" build_workflow_graph="true" |
---|
| 256 | build_workflow_graph_begin="3ts" |
---|
| 257 | build_workflow_graph_end="5ts" /> |
---|
| 258 | \end{lstlisting} |
---|
| 259 | |
---|
[1742] | 260 | In this example, the graph will only include information between the 3rd and 5th time step. |
---|
| 261 | These attributes are not mandatory. If \verb|build_workflow_graph_start| is not define, the graph will start to record from the first iteration. |
---|
| 262 | Similarly, the default value of \verb|build_workflow_graph_end| is the last iteration of the simulation. |
---|
[1741] | 263 | |
---|
| 264 | In case that two values of the same attribute are defined, we take the largest range. |
---|
| 265 | \begin{lstlisting}[language=XML] |
---|
| 266 | <field id="field_A" build_workflow_graph="true" |
---|
| 267 | build_workflow_graph_begin="3ts" |
---|
| 268 | build_workflow_graph_end="5ts" /> |
---|
| 269 | |
---|
| 270 | <field id="field_B" field_ref="field_A" build_workflow_graph="true" |
---|
| 271 | build_workflow_graph_end="4ts" /> |
---|
| 272 | \end{lstlisting} |
---|
| 273 | |
---|
| 274 | In this example, \verb|field_B| will have attributes \verb|build_workflow_graph_start="1ts"| and \verb|build_workflow_graph_end="5ts"| |
---|
| 275 | \end{document} |
---|