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}}} |
---|
85 | |
---|
86 | \usepackage{float} |
---|
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} |
---|
132 | \item source filter: when the field data is received from model or read from NetCDF file |
---|
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, ...) |
---|
137 | \item file write filter: when the field data is written to a NetCDF file |
---|
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 | |
---|
154 | \subsection{Heritage by field referencing} |
---|
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 | |
---|
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} |
---|
179 | \end{figure} |
---|
180 | |
---|
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 |
---|
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. |
---|
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}}. |
---|
197 | Several buttons are set to allow user to visualize the graph interactively. |
---|
198 | |
---|
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 | |
---|
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 |
---|
224 | from a NetCDF file. |
---|
225 | |
---|
226 | \subsection{Enable output} |
---|
227 | \visbutton{Enable output} shows all output nodes of the graph. The output nodes |
---|
228 | are either the file writer filter: data written to a NetCDF file; either the store |
---|
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 | |
---|
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. |
---|
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} |
---|